metravel-agent-workflow - SKILL.md Agent Skill

name: metravel-agent-workflow description: Orchestrate a role-based metravel AI workflow across project analyst, business analyst, system architect, designer, Android developer, programmer, mobile tester, QA, reviewer, and DevOps agents. Use when Codex needs to split a metravel task into agent roles, run a bug-finding/fixing/deploy loop, or coordinate project analysis, discovery, implementation, mobile validation, review, and deploy without losing project rules.

Metravel Agent Workflow

Use this skill to coordinate multiple role prompts or subagents for metravel work. Keep the workflow controlled: each role has a narrow output contract, code changes happen only in the implementation stage, and deploys happen only through the DevOps stage after explicit environment gating.

Do not use this skill for docs-only changes, simple automated checks, one isolated bugfix/refactor, one board-contract update, or read-only analysis that does not need handoff to implementation/QA/review. Use the single matching specialist skill instead.

Read first:

AGENTS.md
docs/RULES.md
docs/CODEX.md
Extra feature docs only when the task touches that area.

Role Order

Default feature flow:

Codex Orchestrator: use $metravel-codex-orchestrator for task triage, skill selection, role prompt pattern, validation plan, and handoff rules when scope is broad or multi-step.
Project Analyst: use $metravel-project-analyst for broad or unclear scope to map structure, validation, risks, and next agents.
Business Analyst: produce a concise feature brief and acceptance criteria.
System Architect: map the brief to existing code, constraints, risk, and validation.
Domain Router: use $metravel-domain-router for travel/map/profile/achievements/quests/PDF/new-page owner maps.
Domain Expert: use $metravel-travel-expert, $metravel-map-expert, $metravel-profile-expert, $metravel-achievements-expert, or $metravel-quest-expert for domain-specific constraints; use $metravel-quest-editor for quest content and $metravel-quest-geo-verifier for quest coordinates.
Designer: use $metravel-ui-guardrails for visible UI states and web/mobile behavior.
Android Developer: use $metravel-android-developer for Android/native implementation, crashes, platform files, or Expo native modules.
Refactor Surgeon: use $metravel-refactor-surgeon for behavior-preserving large component splits.
Programmer: use $metravel-feature-builder to implement the smallest sufficient diff.
Backend Diagnostician: use $metravel-backend-diagnostician for read-only API/backend blockers and board follow-up.
Ticket Board: use $metravel-ticket-board for MCP board task/sprint list/create/update/sync; use $metravel-task-contract for FE/BE contracts.
Browser Reviewer: use $metravel-browser-reviewer for visible web diff review, fixes, and re-verification.
Mobile Tester: use $metravel-mobile-tester for mobile web or Android/native QA evidence and retest.
QA Agent: use $metravel-qa-agent to test broader flows and create structured bug reports.
Sprint Reviewer: use $metravel-sprint-reviewer to accept task-board tickets only with Done-gate evidence.
Production Smoke: use $metravel-production-smoke for read-only production health checks.
Reviewer: use $metravel-system-architect in review mode to check the diff, tests, and rule compliance.
DevOps Agent: use $metravel-devops-agent only when the user explicitly asks to deploy, build, release, or verify a deployment.

Default bug loop:

QA Agent explores the app and writes bug reports only.
Mobile Tester handles mobile-specific reproduction, device/emulator evidence, and retest when the bug is mobile web or Android/native.
Android Developer fixes confirmed Android/native bugs; Programmer fixes non-native feature bugs.
QA Agent or Mobile Tester re-tests the fixed scenario.
Reviewer checks the diff and validation.
DevOps Agent deploys/builds/releases only if the fix is approved and the user explicitly requested a target environment or mobile build.

Control Rules

Do not let exploratory QA or analyst roles edit code.
Use Codex Orchestrator only to choose and sequence work; route implementation to the relevant specialist skill.
Use Project Analyst only for read-only discovery unless the user explicitly asks to update docs or code after the analysis.
Use Backend Diagnostician only for read-only backend/API diagnosis and board evidence; do not let it edit backend or frontend code.
Keep Mobile Tester read-only unless the user explicitly asks to update tests.
Do not let Android Developer change mobile release/build configs without explicit user approval.
Do not let Refactor Surgeon change business logic or visual design; it only extracts structure.
Do not let Sprint Reviewer move tickets to done without runtime evidence for the Task Contract Done gate.
Do not let Production Smoke deploy, rollback, or mutate production; it only probes read-only health.
Do not let implementation start from vague requirements; require acceptance criteria or a bug report first.
Do not deploy production from vague wording; require an explicit prod deploy request and a clean environment gate.
Before assigning deploy, build, server rebuild/restart, full/preflight tests, Playwright/e2e, or Lighthouse work, check the operation coordination rule from AGENTS.md/docs/RULES.md; if the same target is already running, do not start a second agent command.
Keep unrelated user changes separate; never revert files outside the task.
Preserve project rules for external links, design tokens, e2e secrets, server paths, and scope-based validation.
For visible web UI changes, require browser verification, screenshot, and console check before final handoff.
If a role finds a real issue in the touched scope, route it to implementation before handoff unless it is explicitly blocked.

Handoff Format

Each role should return one compact artifact:

Business Analyst: Feature Brief
Codex Orchestrator: Codex Route
Project Analyst: Project Analysis
System Architect: Technical Design
Domain Router: Domain Route
Domain Expert: <Domain> Expert Handoff
Quest Editor: Quest Content Handoff
Quest Geo Verifier: Quest Geo Report
Designer: UI Contract
Android Developer: Android Implementation Summary
Refactor Surgeon: Refactor Summary
Programmer: Implementation Summary
Backend Diagnostician: Backend Diagnosis
Ticket Board: Board Update
Browser Reviewer: Browser Review Verdict
Mobile Tester: Mobile QA Pass or Bug Report
QA Agent: Bug Report or QA Pass
Sprint Reviewer: Sprint Review
Production Smoke: Production Smoke
Reviewer: Review Findings
DevOps Agent: Deploy Report

The orchestrator final answer should include the changed files, validation run, and remaining blockers or risks.