dev

name

dev

description

MUST BE LOADED for any coding task: implementing features, fixing bugs, writing code, refactoring, or making changes. This skill provides the mandatory step-by-step SDLC (Software Development Lifecycle) workflow for orchestrating development using specialized skills and sub-agents. Load this skill when the user asks to 'add', 'create', 'build', 'fix', 'update', 'change', 'implement', or 'refactor' anything.

Dev — SDLC Workflow Skill

This skill defines the mandatory workflow for all coding tasks. Follow these steps IN ORDER. Skipping steps is FORBIDDEN.

CRITICAL RULES

YOU MUST USE THE AGENT TOOL TO LAUNCH SUB-AGENTS FOR ALL WORK. Each sub-agent loads the appropriate skill via the Skill tool.

How to Launch Sub-Agents with Skills

Skills are NOT agent types. Launch a general-purpose sub-agent and instruct it to load the skill:

Agent tool:
  prompt: "Load the [skill-name] skill (Skill tool: skill='[skill-name]'), then:
           [task details]"
  description: "[3-5 word summary]"

Do NOT use subagent_type for skills. The subagent_type parameter is reserved for built-in agent types (Explore, Plan, etc.). Skills are loaded inside the sub-agent via the Skill tool.

Coder Task Reporting (Sub-Agent Restriction)

Sub-agents MUST NEVER send "idle" or "complete" states via mcp__coder__coder_report_task. Only the main agent session (root conversation) is allowed to report "idle" or "complete". Sub-agents spawned via the Agent tool may only report "state": "working". This prevents sub-agents from overwriting the coordinator's dashboard status and falsely signaling task completion.

• ❌ NEVER write code yourself
• ❌ NEVER create files yourself
• ❌ NEVER make commits yourself
• ❌ NEVER skip steps
• ❌ NEVER skip tests (test.skip, it.skip, describe.skip are FORBIDDEN)
• ❌ NEVER use subagent_type for skills — use Skill tool inside the sub-agent
• ✅ ALWAYS launch sub-agents via the Agent tool
• ✅ ALWAYS instruct sub-agents to load skills via the Skill tool
• ✅ ALWAYS verify each step before proceeding
• ✅ ALWAYS fix, replace, refactor, or remove tests - never skip them

FAILURE TO USE SUB-AGENTS = WORKFLOW FAILURE

Test Policy

⛔ NEVER skip tests. If a test cannot pass:

• Fix it - Update assertions to match correct behavior
• Replace it - Write a new test that properly validates the behavior
• Refactor it - Restructure to test what's actually testable
• Remove it - Delete entirely if it tests something that no longer exists

If tests require infrastructure (auth, database, external services), SET UP that infrastructure. Do not skip tests because setup is hard.

---

MANDATORY STEPS (Execute in Order)

STEP 0: GitHub Authentication

Execute FIRST before anything else.

gh auth status

If fails: STOP. Tell user to run gh auth login. Do NOT proceed.

---

STEP 1: Workspace Preparation

Create clean feature branch BEFORE any implementation.

1.1 Check for uncommitted changes

git status

If uncommitted changes exist:

• Ask user: "Uncommitted changes found. Stash them or abort?"
• If stash: git stash push -m "SDLC auto-stash"
• If abort: STOP

1.2 Sync and create branch

git fetch origin
git checkout main
git pull origin main
git checkout -b <type>/<short-description>

Branch types: feat, fix, refactor, docs, test, chore

⛔ DO NOT PROCEED until branch is created

---

STEP 2: Requirements Analysis

MANDATORY: Launch a sub-agent that loads the requirements-analyzer skill.

Agent tool:
  prompt: "Load the requirements-analyzer skill (Skill tool: skill='fx-dev:requirements-analyzer'), then:

           Analyze requirements for: [TASK DESCRIPTION]

           - Analyze task/issue/error to understand requirements
           - Use WebSearch to research technologies
           - Use WebFetch for referenced URLs
           - Use AskUserQuestion for ambiguities
           - Analyze codebase for patterns

           Output: Complete requirements with acceptance criteria"
  description: "Analyze requirements"

For GitHub issues, fetch first:

gh issue view [NUMBER] --json title,body,labels,comments

⛔ DO NOT PROCEED until requirements are complete

---

STEP 2.5: Freeze the Implementation Contract and Open the Finding Ledger

If the task is sourced from, names, or discovers a relevant docs/changes/*.md file, read it and the spec sections it links. Confirm implementation approval from the conversation or the change's recorded workflow state; if approval is unclear, STOP and ask the user. Record the contract path and approval evidence in the working brief. The change document, its linked specs, and all mandatory project rules form the implementation contract: the plan and coder prompt MUST map work to that contract and MUST NOT infer adjacent product or architecture work.

The coordinator owns one in-memory finding ledger for the run; reviewer sub-agents return findings to the coordinator and MUST NOT mutate the ledger concurrently. Give every finding a stable fingerprint (category + file + line/range + normalized claim) and record its source, first-seen revision, classification, disposition, and verification evidence. Classify each finding exactly once as:

• required-by-contract — Necessary to satisfy the change document, its linked specs, or any mandatory project, security, privacy, test, or merge rule.
• regression-caused-by-change — A demonstrable correctness, security, privacy, or data-loss regression caused by this branch anywhere within its behavioral impact, including downstream consumers or integrations.
• follow-up/out-of-scope — A pre-existing issue, hardening, cleanup, product addition, architecture expansion, or improvement not required by either category above.

Fix only the first two classes. Deduplicate repeated or reworded findings by fingerprint and update the existing ledger entry. Record follow-up/out-of-scope findings for the PR or later tracking; do not implement them. When reviewer resolvers are invoked by /dev, their deferred-feedback paths MUST return follow-ups to the coordinator instead of modifying task trackers in the implementation PR. To implement out-of-scope product or architecture work, first amend the change document and obtain user approval.

---

STEP 3: Planning

MANDATORY: Launch a sub-agent that loads the planner skill.

Agent tool:
  prompt: "Load the planner skill (Skill tool: skill='fx-dev:planner'), then:

           Create implementation plan for:

           [REQUIREMENTS FROM STEP 2]

           - Break into atomic steps
           - Identify files to modify
           - Determine test requirements
           - Flag if multiple PRs needed
           - Treat the approved change document as the implementation contract
           - Do not include follow-up/out-of-scope work or expand product/architecture without an approved amendment

           Output: Numbered implementation steps"
  description: "Plan implementation"

For GitHub issues, also update issue:

Agent tool:
  prompt: "Load the issue-updater skill (Skill tool: skill='fx-dev:issue-updater'), then:

           Update issue #[NUMBER] with plan. Add label: in-progress"
  description: "Update issue"

⛔ DO NOT PROCEED until plan exists

---

STEP 4: Implementation

MANDATORY: Launch a sub-agent that loads the coder skill.

Agent tool:
  prompt: "Load the coder skill (Skill tool: skill='fx-dev:coder'), then:

           Implement this plan:

           [PLAN FROM STEP 3]

           Requirements:
           - Atomic commits (format: type(scope): message)
           - Follow existing patterns
           - Run tests
           - Treat the approved change document as the implementation contract
           - Do not implement follow-up/out-of-scope findings or expand product/architecture without an approved amendment
           - Do NOT create PR"
  description: "Implement changes"

Verify commits exist:

git log --oneline -5
git diff main --stat

⛔ DO NOT PROCEED until commits exist on feature branch

---

STEP 4.5: Pre-PR Self-Review (simplify → review → CodeRabbit → Codex)

MANDATORY: Run one complete local review matrix before creating the PR. Run each available pass once in order against the current HEAD, record the revision that each channel reviewed, and classify its findings before accepting fixes. If /simplify edits directly, retain only changes that satisfy the contract classification and record the resulting revision before starting the next pass.

1. /simplify — reuse, quality, efficiency cleanup:

Skill tool: skill="simplify"

Reviews changed code for reuse (duplicated logic), quality (copy-paste, leaky abstractions, nesting), and efficiency (redundant computation, missed concurrency).

2. /code-review — correctness bugs in the diff:

Skill tool: skill="code-review"

3. CodeRabbit (local, via cr) — independent local review:

Skill tool: skill="fx-dev:coderabbit-review"

If cr is unavailable, fall back to the PR-level CodeRabbit review in Step 6.3. If cr is installed but not authenticated, STOP and report to the user — NEVER run cr auth login. If CodeRabbit reports a rate/quota limit or cooldown, report it once, classify findings already received, mark the pass skipped (rate-limited), and continue immediately. Never wait or retry solely for a CodeRabbit cooldown.

4. Codex (local, via codex) — independent one-shot branch review:

Skill tool: skill="fx-dev:codex-review"

If the codex CLI is unavailable or not authenticated, report it once and proceed without this pass. NEVER run codex login.

Remediation and Delta Verification

Fix only findings classified required-by-contract or regression-caused-by-change. After a fix commit:

1. Rerun the reviewer or check that originated the blocking finding.
2. Rerun tests affected by the delta.
3. Rerun another reviewer only when the delta touches the risk area that reviewer covered or invalidates its recorded evidence.

Do not restart the full matrix merely because HEAD changed. Deduplicate repeated or reworded findings against the ledger; they do not start a new cycle. When /dev invokes reviewer subskills, this contract classification and bounded stopping policy takes precedence over generic instructions to resolve every actionable finding or rerun until clean.

PR-Ready Stopping Condition

Proceed to Step 5 when all of the following are true:

1. Every required-by-contract and regression-caused-by-change ledger entry is resolved with evidence.
2. Contract-required tests and tests affected by the latest delta pass.
3. Every available review channel completed its initial pass or has a documented permitted degradation.
4. One verification pass over the latest affected delta produces no new finding in either blocking class.

follow-up/out-of-scope entries and non-contract suggestions do not block PR creation. Limit each review channel to two remediation/delta-verification rounds after its initial pass, with four post-review fix rounds total. At the bound, create the PR if only follow-up/out-of-scope entries remain. If a blocking-class finding remains, STOP and report it to the user. A contract amendment may change product scope, but it cannot waive mandatory correctness, security, privacy, testing, or merge rules. Perfect local convergence is not required.

---

STEP 5: Pull Request Creation

MANDATORY: Launch a sub-agent that loads the pr-preparer skill. ALL PRs MUST be created READY FOR REVIEW — never as drafts.

⛔ NEVER use the --draft flag. NEVER create draft PRs. Draft PRs have repeatedly been used as an excuse to skip downstream steps (reviewer waits, CI monitoring, CodeRabbit/Copilot resolution). The SDLC ALWAYS executes the full review/CI cycle from PR creation onward — opening as draft defeats this. If the work isn't ready for review, don't open the PR yet.

Before creating the PR, identify related spec and change documents:

# Find related change documents (check if task was sourced from a change doc)
ls docs/changes/ 2>/dev/null
# Find related specs
ls docs/specs/ 2>/dev/null
cat docs/index.yml 2>/dev/null

If the work was driven by a specific change document or spec, note the paths for inclusion in the PR description.

Agent tool:
  prompt: "Load the pr-preparer skill (Skill tool: skill='fx-dev:pr-preparer'), then:

           Create PR (ready for review, NOT draft) for current branch.
           Task: [ORIGINAL TASK]
           Summary: [WHAT WAS IMPLEMENTED]

           Spec/Change context (include in PR body if applicable):
           - Spec: [SPEC_PATH or 'none']
           - Change: [CHANGE_DOC_PATH or 'none']

           CRITICAL: Do NOT pass --draft. The PR must be opened ready for review so
           CI, Copilot, and CodeRabbit run from the start.
           - Push branch if needed
           - Create PR with: gh pr create  (NO --draft flag)
           - Include links to related spec/change docs in the PR body
             (use relative paths from repo root, e.g. docs/specs/auth/ or docs/changes/0003-add-oauth.md)
           - Do NOT put spec/change references in the PR title — not as a number,
             slug, or path, even when the PR finalizes a change doc. Describe the
             work itself in the title; reference the doc by path in the body only.
           - ⛔ NEVER put '#<number>' in the PR title ('#4', '(#4)', '#123')
             unless N is a REAL existing PR/issue on the target repo that this PR
             references. On squash-merge the title becomes the commit subject,
             where '#N' auto-links to PR/issue #N. NEVER use '#N' for an
             implementation wave, phase, step, or change-doc number, and NEVER
             pre-add a '(#N)' suffix (GitHub appends the real PR number at squash
             merge). No waves/phases/steps in the title at all — those go in the
             body. See the fx-dev:github skill's '#<number> PR-Title Rule'.
           - Reference related issues
           - Do NOT include any 'this is a draft' / 'draft for review' language
             anywhere in the title or body
           - Return PR number and URL"
  description: "Create PR"

Capture the PR number for remaining steps.

⛔ DO NOT PROCEED until PR is created (as ready for review)

---

STEP 5.5: Test Plan Verification (MANDATORY)

This step is MANDATORY for every PR that has a test plan. It is NOT limited to web/UI changes. Backend changes, platform integrations, CLI tools, and infrastructure changes all have test plans that must be addressed.

5.5.1 Extract and Classify the Test Plan

Read the PR description and extract the Test Plan section:

gh pr view [PR_NUMBER] --json body --jq '.body'

Parse the ## Test plan section. Each - [ ] item is a verification target.

If the PR has no Test Plan section, construct one from the PR diff — identify what changed and create verification steps. Add them to the PR description before proceeding.

Classify each test plan item into one of three categories:

Category	Description	Action
Browser-verifiable	Can be tested via Playwright MCP (UI routes, visual changes, interactions)	Run verify-web-change (Step 5.5.2)
Programmatically verifiable	Can be tested via CLI, API calls, log inspection, or automated scripts	Run verification commands directly (Step 5.5.3)
Manual-only	Requires external systems, user accounts, or physical interaction (e.g., "send a Discord message", "check email")	Annotate for user and prompt them to verify (Step 5.5.4)

5.5.2 Browser Verification (for browser-verifiable items)

Skip this sub-step if no test plan items are browser-verifiable.

Detect if browser verification is possible:

WEB_FILES=$(git diff main --name-only | grep -E '\.(tsx|jsx|vue|svelte|html|css|scss|less)$' || true)

HAS_WEB_STACK=false
for cfg in vite.config.ts vite.config.js next.config.js next.config.ts next.config.mjs nuxt.config.ts svelte.config.js angular.json astro.config.mjs; do
    if [[ -f "$cfg" ]]; then
        HAS_WEB_STACK=true
        break
    fi
done

If web changes exist and browser-verifiable items are present, launch the verify-web-change sub-agent:

Agent tool:
  prompt: "Load the verify-web-change skill (Skill tool: skill='fx-dev:verify-web-change'), then:

           Verify the following Test Plan items for PR #[PR_NUMBER] using browser automation:

           [BROWSER-VERIFIABLE TEST PLAN ITEMS]

           For each item:
           1. Navigate to the relevant page/route
           2. Use Playwright MCP snapshots to verify the element/behavior exists
           3. Test any interactions described in the test plan item
           4. Check for console errors
           5. Report PASS/FAIL per item with evidence (what you observed)

           Output: A list of each test plan item with its result (PASS/FAIL/SKIPPED) and evidence."
  description: "Verify web changes in browser"

5.5.3 Programmatic Verification (for programmatically verifiable items)

Skip this sub-step if no test plan items are programmatically verifiable.

For items that can be verified via commands (API calls, log inspection, test runs, etc.), run the verification directly:

• Check test output: bun --bun run test — confirm relevant tests pass
• Inspect logs: Check dev server output for expected behavior
• Call APIs: Use curl or similar to verify endpoint behavior
• Check database state: Verify schema/data changes applied correctly

Record PASS/FAIL per item with evidence.

5.5.4 Manual Verification (for manual-only items)

⛔ NEVER silently skip manual-only test plan items.

For items that require manual interaction (external services, physical devices, user accounts), you MUST:

1. Tell the user which items require their manual verification
2. Explain what to test — be specific about the steps
3. Ask them to confirm each item passes or fails
4. Wait for their response before proceeding

Example:

The following test plan items require manual verification:
- [ ] Send a message to the Discord bot and verify the typing indicator appears immediately
- [ ] Confirm the typing indicator stays active for responses > 10 seconds

Please test these and let me know the results.

5.5.5 Update the Test Plan in the PR Description

MANDATORY: After all verification (automated + manual), update the PR description.

BODY=$(gh pr view [PR_NUMBER] --json body --jq '.body')

For each Test Plan item:

• Verified (pass): Change - [ ] to - [x]
• Verified (fail): Leave as - [ ] and append: — FAILED: [reason]
• Manual — confirmed by user: Change - [ ] to - [x] and append: (manually verified)
• Manual — not yet verified: Leave as - [ ] and append: — requires manual testing

Update the PR:

gh pr edit [PR_NUMBER] --body "$UPDATED_BODY"

⛔ DO NOT PROCEED to Step 6 until every test plan item has been addressed — either verified (pass/fail), confirmed by user, or explicitly annotated as requiring manual testing.

5.5.6 Handle Failures

If any Test Plan items failed verification:

1. Launch a sub-agent with the coder skill to fix:

   Agent tool:
     prompt: "Load the coder skill (Skill tool: skill='fx-dev:coder'), then:
   
              Fix these verification failures:
              [FAILURE DETAILS]
              Push fixes to the PR branch."
     description: "Fix verification failures"
   

2. After fixes are pushed, re-run the relevant verification step (5.5.2 or 5.5.3)
3. Maximum 2 fix iterations. If still failing after 2 attempts, proceed to Step 6 and note the unverified items in the PR description.

⛔ DO NOT PROCEED until verification passes or max iterations reached

---

STEP 6: Review & Quality

MANDATORY: Execute ALL sub-steps.

6.1 Self-Review

Agent tool:
  prompt: "Load the pr-reviewer skill (Skill tool: skill='fx-dev:pr-reviewer'), then:

           Review PR #[NUMBER] for:
           - Code quality
           - Test coverage
           - Security issues
           - Performance

           Output: Issues found (if any)"
  description: "Review PR"

The coordinator MUST classify and deduplicate these findings in the Step 2.5 ledger before invoking a coder. Do not pass follow-up/out-of-scope findings to implementation.

6.2 Fix Blocking Issues (if any found)

Agent tool:
  prompt: "Load the coder skill (Skill tool: skill='fx-dev:coder'), then:

           Fix only these blocking-class issues in PR #[NUMBER]:
           [REQUIRED-BY-CONTRACT OR REGRESSION-CAUSED-BY-CHANGE FINDINGS]

           Do not implement ledger entries classified follow-up/out-of-scope."
  description: "Fix review issues"

6.3 Automated Reviewer Wait (Copilot + CodeRabbit + future)

MANDATORY: Wait for and resolve EVERY automated reviewer configured on the repo. Copilot and CodeRabbit are the two we know about today; future integrations slot in here. Reviewers are independent feedback channels with different latencies (Copilot ≈30–90 s; CodeRabbit 2–10+ min and re-runs after every push).

CodeRabbit was attempted LOCALLY in Step 4.5 (cr review --agent). The PR-level handling here is a fallback for repos whose GitHub App auto-reviews PRs. Prefer a passing check and resolve received feedback; if either local or PR-level CodeRabbit rate-limits, record skipped (rate-limited) and continue without blocking.

Reviewer-by-reviewer skills

Reviewer	Skill	Notes
GitHub Copilot	fx-dev:copilot-review	Auto-reviews; we explicitly request via API as a defensive belt. Does NOT re-review on push by default.
CodeRabbit	fx-dev:coderabbit-review	Already run locally in Step 4.5 (cr). Here = fallback PR-level gate when the GitHub App auto-reviews PRs: re-reviews after pushes and exposes state via the CodeRabbit check. Classify new feedback in the shared ledger and settle its threads within the bounds below. Skip if not configured.

Pick the right execution mode for your context

⛔ CRITICAL: the right mode depends on whether YOU can spawn sub-agents right now.

• You ARE the root session / a standalone caller of fx-dev:dev → use mode A (parallel sub-agents).
• You are a fx-dev:team coordinator OR a sub-agent yourself → sub-agents CANNOT spawn sub-agents. Use mode B (sequential, with background wait scripts). Do NOT call the Agent tool here.

If unsure: assume mode B. It's strictly slower but always correct; mode A is an optimisation that requires you to be a top-level agent.

Mode A: parallel sub-agents (root session only)

In a single message, spawn one sub-agent per reviewer using the Agent tool. Both wait scripts run concurrently and each resolves its own reviewer.

Agent tool (spawn ALL reviewer sub-agents in the same message — parallel):

Agent 1:
  prompt: "Load the copilot-review skill (Skill tool: skill='fx-dev:copilot-review'),
           then wait for and inspect currently unresolved feedback for PR #[PR_NUMBER] at its
           current head SHA. Return findings and evidence only; do not edit, push, resolve threads,
           or modify task trackers. Report the reviewed SHA."
  description: "Inspect Copilot review"

Agent 2:
  prompt: "Load the coderabbit-review skill (Skill tool: skill='fx-dev:coderabbit-review'),
           then wait for and inspect currently unresolved feedback for PR #[PR_NUMBER] at its
           current head SHA. Return findings and evidence only; do not edit, push, resolve threads,
           or modify task trackers. Report the reviewed SHA."
  description: "Inspect CodeRabbit review"

Wait for all sub-agents to report completion. The coordinator then deduplicates and classifies their findings, dispatches blocking remediation serially, and settles all reviewer threads. Never let parallel reviewer agents push fixes before coordinator classification.

Mode B: sequential, with background wait scripts (team-coordinator / sub-agent)

You can't spawn sub-agents, so handle each reviewer's wait+resolve lifecycle yourself, sequentially. To recover some parallelism, kick off the slow waiter (CodeRabbit) in the background while you handle the fast one (Copilot) in the foreground. When Copilot is done, switch to CodeRabbit.

Concrete recipe:

1. Start the CodeRabbit waiter as a background bash process — its output streams to a file you can poll later:

   bash [SKILL_BASE_DIR]/skills/coderabbit-review/scripts/wait-for-coderabbit-review.sh [PR_NUMBER] \
        > /tmp/coderabbit-wait-[PR_NUMBER].log 2>&1
   

   Use Bash with run_in_background: true. Capture the task ID.
2. In the foreground, wait for Copilot using the bundled copilot-review waiter, then read its unresolved threads without invoking a resolver. Classify and deduplicate them in the coordinator-owned ledger.
3. Wait for the background CodeRabbit waiter to finish, then read its unresolved threads and classify them before invoking a resolver. Invoke each reviewer resolver only after classification, passing the blocking findings and instructing it to settle deferred findings without code or task-tracker changes.
4. After a resolver pushes, record the new SHA and inspect only feedback added or changed since the previous reviewed SHA. Classify and deduplicate it in the shared ledger. Rerun only the reviewer whose state or evidence the delta invalidated; do not restart every reviewer merely because HEAD changed.
5. Stop after one latest-delta pass produces no new required-by-contract or regression-caused-by-change finding and every required reviewer thread is settled.

If Bash run_in_background isn't available in your context, fall back to fully-serial: Copilot first, then CodeRabbit. Slower but correct.

Bounded delta review (both modes)

Fix only blocking-class findings. Record follow-up/out-of-scope feedback without implementing it, and settle its thread with an out-of-scope disposition when repository policy permits. Allow at most two remediation rounds per reviewer. At the bound, continue when only follow-up/out-of-scope findings remain; escalate any unresolved blocking-class finding to the user. Do not seek zero suggestions or restart unrelated review channels.

Skip rules

• If a reviewer is not configured for the repo (e.g. wait-for-coderabbit-review.sh exits 2 because no CodeRabbit check ever appears), report this once and proceed without that reviewer.
• If CodeRabbit reports a rate/quota limit or cooldown, report it once, mark CodeRabbit skipped (rate-limited), and proceed immediately. Do not raise timeouts, sleep, poll, or retry for CodeRabbit throttling.
• Do not apply this exception to Copilot or other reviewers. A merely slow CodeRabbit check with no rate-limit signal still follows the normal timeout behavior.

⛔ DO NOT PROCEED until every required reviewer has settled. CodeRabbit is satisfied by a passing result or an explicit skipped (rate-limited) degradation.

---

STEP 7: CI/CD Monitoring

MANDATORY: Execute ALL sub-steps. Maximum 3 fix iterations.

Because Step 5 opens the PR ready for review (NOT draft), CI workflows that trigger on pull_request start immediately. There is no draft → ready transition to manage in this workflow.

7.1 Wait for CI Checks to Start and Complete

Run the bundled CI check script in the FOREGROUND:

# CRITICAL: Run in FOREGROUND — do NOT use run_in_background
bash [SKILL_BASE_DIR]/skills/dev/scripts/wait-for-ci-checks.sh [PR_NUMBER]

⚠️ CRITICAL: Run this script in the FOREGROUND with timeout: 600000 (10 minutes) on the Bash tool call. Do NOT use run_in_background. Running in the background causes output to be lost and prevents the workflow from properly reacting to the results.

Script behavior:

• Phase 1: Waits for checks to appear (some repos have a startup delay)
• Phase 2: Polls every 30s until all checks complete (timeout: 900s / 15 minutes)
• Exit 0: All checks passed → proceed to Step 8
• Exit 1: One or more checks failed → proceed to Step 7.2
• Exit 2: Timeout waiting for checks → report to user, ask whether to continue waiting or proceed
• Exit 3: Invalid arguments or gh error

7.2 Handle CI Failures (LOOP — max 3 iterations)

If Step 7.1 exits with code 1 (failures detected):

Skill tool: skill="fx-dev:resolve-ci-failures"

Pass the failure details from the script output to the skill. The skill will:

1. Analyze failure logs and identify root causes
2. Delegate fixes to a sub-agent with the coder skill
3. Push the fixes

After the skill completes and fixes are pushed, GO BACK TO Step 7.1 — re-run the wait script to monitor the new check run. This creates a loop:

Step 7.1 (wait) → fail → Step 7.2 (fix) → Step 7.1 (wait) → ...

⚠️ Maximum 3 iterations. Track the current iteration count. If checks still fail after 3 fix attempts, STOP and report the persistent failures to the user with full details.

⛔ DO NOT PROCEED until all checks pass or max iterations reached

---

STEP 8: Finalization

8.1 Final Verification (MANDATORY MERGE GATES)

⛔ ALL of the following must be verified before ANY PR can be merged. No exceptions.

# 1. CI checks — ALL must be green (includes the CodeRabbit check)
gh pr checks [NUMBER]

# 2. Automated reviewers — MUST be settled and resolved (if not already done in Step 6.3)
# Reuse Step 6.3 evidence when it covers the current head SHA. Invoke a dedicated
# reviewer skill only when its check, threads, or reviewed SHA changed; do not restart
# a settled review loop solely because finalization was reached.
# Use the dedicated skills — NEVER raw gh api commands.

Skill tool: skill="fx-dev:copilot-review",     args="[NUMBER]"
Skill tool: skill="fx-dev:coderabbit-review",  args="[NUMBER]"

# 3. Unresolved review threads — MUST be 0 (across ALL reviewers)
gh pr view [NUMBER] --json reviewThreads \
  --jq '[.reviewThreads[] | select(.isResolved == false)] | length'

# 4. Codecov — patch and project checks must pass
gh pr checks [NUMBER]  # verify codecov/patch and codecov/project

Merge gate checklist (every item must pass):

• PR is open and mergeable
• PR title is a conventional-commit subject (type(scope): description) — verify gh pr view [NUMBER] --json title -q .title | grep -Eq '^(feat|fix|docs|refactor|chore|test|perf|build|ci|style|revert)(\(.+\))?!?: .+'; a plain prose title FAILS — rename with gh pr edit [NUMBER] --title "type(scope): …" BEFORE merging (squash bakes the title into main). Also no stray #<number>/wave/phase wording.
• ALL CI checks green
• Copilot review RECEIVED and ALL threads resolved (via fx-dev:copilot-review skill — NEVER raw gh api)
• CodeRabbit is passing with all received threads resolved, not configured, or explicitly recorded as skipped (rate-limited). CodeRabbit throttling is optional and never blocks merge.
• Zero unresolved required-by-contract or regression-caused-by-change findings; the latest affected delta is verified within the stopping bounds
• Codecov coverage passing with 0 missing lines
• No unresolved review threads from any reviewer (Copilot, CodeRabbit, human, or future automated reviewer); follow-up/out-of-scope threads are settled without expanding implementation

PR size is NEVER a reason to skip merge gates. A 1-line fix gets the same verification as a 1000-line feature.

The PR was opened ready-for-review in Step 5, so there is no draft → ready transition to perform here. Do NOT run gh pr ready — it is unnecessary and will fail on a non-draft PR.

8.2 Update Task Tracking Docs

MANDATORY: Mark completed tasks in the relevant change document or tasks file.

If a change document or task list was referenced in the original request (e.g., a docs/changes/NNNN-name.md or docs/tasks.md), use it directly. If none was provided, search for the relevant tracking doc:

# Look for change documents or tasks that reference the work being done
grep -rl "keyword from task" docs/changes/ docs/tasks.md 2>/dev/null || true

Once identified, update the doc to mark completed tasks:

• Check off completed items (e.g., - [ ] → - [x])
• Add the PR number: - [x] Task name (PR #N)
• Only mark items that are actually addressed by the changes in this PR
• If ALL tasks in a change document are now complete, update its Status to complete
• Commit the doc update to the PR branch

Agent tool:
  prompt: "Load the coder skill (Skill tool: skill='fx-dev:coder'), then:

           Update task tracking in [DOC_PATH]:
           - Read the doc and identify tasks completed by PR #[NUMBER]
           - Mark those tasks as done: - [x] Task name (PR #N)
           - Do NOT mark tasks that were not addressed
           - If all tasks in a change doc are done, update Status: complete
           - SYNC INDEXES: Update docs/index.yml (status field) and docs/index.md (table row) to match
           - Commit the change with: docs: mark completed tasks in [DOC_NAME]
           - Push to the PR branch"
  description: "Update task tracking"

If no relevant tracking doc is found, skip this step.

8.3 Update Issue (if applicable)

Agent tool:
  prompt: "Load the issue-updater skill (Skill tool: skill='fx-dev:issue-updater'), then:

           Update issue #[NUMBER]: Link PR, set label ready-for-review"
  description: "Update issue"

8.4 Report to User

✅ PR #[NUMBER] ready: [URL]

Changes:
- [summary bullets]

Awaiting your approval to merge.

⚠️ NEVER MERGE WITHOUT USER APPROVAL ⚠️ NEVER MERGE WITHOUT ALL MERGE GATES PASSING (Step 8.1) ⚠️ NEVER MERGE WITHOUT COPILOT REVIEW RECEIVED AND ADDRESSED

---

Workflow Variations

GitHub Issue URL

1. STEP 0: Auth check
2. STEP 1: Branch as fix/issue-123-description
3. Fetch issue: gh issue view [NUMBER] --json title,body,labels,comments
4. STEP 2-8: Standard (use issue-updater in Steps 3 and 8)

Quick Fix (fix:, error:, bug: prefix)

1. STEP 0: Auth check
2. STEP 1: Branch as fix/short-error-desc
3. STEP 2: Focus on error analysis, root cause
4. STEPS 3-8: Standard

Multi-PR Tasks

1. Complete STEPS 1-8 for first PR
2. STOP - Wait for user approval
3. Only after approval: Start next PR
4. Track with TodoWrite

NEVER have multiple PRs open simultaneously

---

Error Handling

Error	Action
Sub-agent fails	Retry once with adjusted params, then STOP and report
Git conflict	STOP, report to user, wait for resolution
Tests fail	coder sub-agent fixes, rerun until pass
Auth fails	STOP, request gh auth login

---

Sub-Agent Quick Reference

All sub-agents are launched via the Agent tool. Each loads its skill via the Skill tool inside the sub-agent.

Step	Skill to Load	Skill Name
2	Requirements Analyzer	fx-dev:requirements-analyzer
3	Planner	fx-dev:planner
3,8	Issue Updater	fx-dev:issue-updater
4,6.2,8.2	Coder	fx-dev:coder
4.5	Pre-PR Self-Review	simplify, then code-review, then fx-dev:coderabbit-review (local cr), then fx-dev:codex-review (local codex) — initial passes complete, blocking-class findings resolved, latest affected delta verified
5	PR Preparer	fx-dev:pr-preparer
5.5.2	Browser Verification	fx-dev:verify-web-change
6.1	PR Reviewer	fx-dev:pr-reviewer
6.3	Copilot Review	fx-dev:copilot-review (run in parallel with coderabbit-review)
6.3	CodeRabbit Review	fx-dev:coderabbit-review (run in parallel with copilot-review; classify/deduplicate feedback and verify only affected deltas within bounds)
6.3	PR Feedback Resolver	fx-dev:resolve-pr-feedback (meta — called by reviewer skills)
7.2	CI Failure Resolver	fx-dev:resolve-ci-failures

Pattern for every sub-agent call:

Agent tool:
  prompt: "Load the [skill-name] skill (Skill tool: skill='[full-skill-name]'), then: [task]"
  description: "[summary]"

---

Success Criteria

Workflow complete when ALL true:

• ✅ Feature branch created from main
• ✅ Requirements documented
• ✅ Plan created
• ✅ Code implemented with atomic commits
• ✅ Pre-PR review matrix completed (or permitted degradation documented), findings classified in the shared ledger, blocking-class findings resolved, and the latest affected delta verified within the stopping bounds
• ✅ PR created with description (including links to related specs/changes and test plan)
• ✅ ALL test plan items addressed: browser-verified, programmatically verified, or user-confirmed manual verification (NEVER silently skipped)
• ✅ PR test plan items checked off or annotated with verification results in the PR description
• ✅ Self-review done, issues fixed
• ✅ Automated review feedback classified and settled; blocking-class findings resolved and the latest affected delta verified without unrelated review restarts
• ✅ All CI/CD checks pass
• ✅ Task tracking docs updated (completed tasks marked in relevant change doc or tasks.md)
• ✅ User notified, awaiting merge approval