Implement Issue

You are the engineering-manager. Implement using the Cardo workflow.

Mode Detection

• •Single issue mode: /implement 75 → implements one issue on its own feature branch, creates a standalone PR
• •Sprint batch mode: /implement sprint → implements ALL pending sprint issues on a single release branch, creates one consolidated PR

If $ARGUMENTS is a number → single issue mode. If $ARGUMENTS is "sprint" → sprint batch mode.

Single Issue Mode

Pre-flight

1. •Read the issue: gh issue view $ARGUMENTS --json title,body,labels,milestone
2. •Verify issue is in the current sprint milestone
3. •Transition label from planned to in-progress:
   bash

   gh issue edit $ARGUMENTS --remove-label planned --add-label in-progress
   

4. •Read .claude/guides/commit-rules.md for commit conventions
5. •Read .claude/guides/session-management.md for checkpoint protocol
6. •Create feature branch: git checkout -b feature/$ARGUMENTS-<desc> main
7. •Run {{PKG_MGR}} install --frozen-lockfile if node_modules/ is missing

Phases 1-6: Same as Sprint Batch Mode (see below)

Run Phases 1 through 6 for the single issue.

Phase 7: Build & Verify

Skip if: backend-only, CI-only, or content-only changes (no {{APP_DIR}} files modified).

1. •Read the Verification Plan from the product spec (.product/specs/{{SPEC_PREFIX}}-XXX-*.md)
2. •Build the application for local testing
3. •Install on test device and execute each Verification Plan row:
   • •Perform the Action on device
   • •Confirm the Expected Result matches
   • •Capture evidence (screenshots, logs)
   • •Log pass/fail for each AC
4. •Run applicable {{E2E_TOOL}} E2E flows if they exist for this feature
5. •On failure:
   • •Fix the issue on the feature branch
   • •Quick re-review (code-reviewer checks only the fix)
   • •Incremental re-build and re-verify failing ACs only
6. •Circuit breaker: 3 failures on the same AC → escalate to user
7. •Output: Verification evidence (screenshots + pass/fail log) for PR body
8. •Acceptance Gate Evaluation — same as Sprint Batch Mode acceptance gate (see below)

Phase 8: Create PR

1. •Push the feature branch: git push -u origin feature/$ARGUMENTS-<desc>
2. •Create PR:
   bash

   gh pr create --title "{{SPEC_PREFIX}}-XXX: <title>" --body "$(cat <<'EOF'
   ## What Changed?
   <what changed and why>
   
   ## Why?
   <problem and rationale>
   
   Closes #$ARGUMENTS
   
   ## Breaking Changes?
   No breaking changes
   
   ## Implementation Summary
   
   ### AC Evidence
   | AC | Status | How Verified | Evidence |
   |----|--------|-------------|----------|
   | AC1 | PASS | Unit test | `file.test.ts:line` — "test name" |
   | AC2 | PASS | Unit test | `file.test.ts:line` — "test name" |
   
   ### Implementation Challenges
   <!-- If empty, write "None" -->
   | Challenge | Spec Requirement | What Happened | Decision | Decided By |
   |-----------|-----------------|---------------|----------|------------|
   | None | — | — | — | — |
   
   ### Scope Changes
   None
   
   ## Device Verification
   | AC | Result | Screenshot |
   |----|--------|------------|
   | AC1 | Pass/Fail | `verify-ac1.png` |
   | AC2 | Pass/Fail | `verify-ac2.png` |
   
   ## Test Plan
   - [ ] Unit tests pass
   - [ ] Manual verification on target platform(s)
   
   Generated with [Claude Code](https://claude.com/claude-code)
   EOF
   )"
   

3. •Comment on the issue with PR link

Phase 9: Merge Gate

1. •Verify CI passes: gh pr checks <pr-number>
2. •Notify user: "PR #NNN ready for review. Run /review <pr-number> or review on GitHub."
3. •Do NOT merge — user decides via /merge

Sprint Batch Mode

Orchestration Mode Selection

For sprint batch mode, prefer Agent Teams when available:

1. •

   Start team: Tell Claude to create an implementation team:

   "Create an agent team for Sprint N implementation. Spawn:

   • •Two engineer teammates for parallel issues
   • •A code-reviewer teammate for internal reviews
   • •An architect teammate for technical guidance Use delegate mode. Require plan approval for engineers."

2. •

   Create tasks: One TaskCreate per issue with full context

3. •

   Engineer teammates claim tasks and present plans for approval

4. •

   Engineers message code-reviewer directly for internal review

5. •

   EM monitors TaskList, handles escalations, assigns unblocked work

Fallback: If team creation fails, use current subagent delegation with run_in_background: true (existing behavior below).

Pre-flight

1. •Read .claude/sprint/current.md to get the full issue list and sprint number
2. •Read .claude/guides/commit-rules.md for commit conventions
3. •Read .claude/guides/session-management.md for checkpoint protocol
4. •Identify all pending issues (not yet done/merged) from the sprint plan
5. •Exclude Human-type issues — only implement Agent-deliverable issues
6. •Sort by dependency order first, then RICE descending
7. •Create the release branch from main:
   bash

   git checkout -b release/sprint-<N> main
   

8. •Run {{PKG_MGR}} install --frozen-lockfile if node_modules/ is missing
9. •Create a sprint batch checkpoint at .claude/sprint/checkpoints/sprint-batch.md:
   markdown

   # Sprint Batch Implementation
   - Branch: release/sprint-<N>
   - Issues: #A, #B, #C, ...
   - Started: <timestamp>
   
   ## Progress
   | # | Issue | {{SPEC_PREFIX}}-ID | Status |
   |---|-------|-----|--------|
   | 1 | #75   | {{SPEC_PREFIX}}-032 | Pending |
   | 2 | #160  | {{SPEC_PREFIX}}-093 | Pending |
   ...
   

Issue Loop

For each issue in order, run Phases 1 through 6:

Phase 1: Intake

• •Read the issue: gh issue view <number> --json title,body,labels,milestone
• •Transition label from planned to in-progress:
  bash

  gh issue edit <number> --remove-label planned --add-label in-progress
  

• •Extract acceptance criteria from issue body
• •Identify the spec ID and read the product spec: .product/specs/{{SPEC_PREFIX}}-XXX-*.md
• •Check for existing tech documentation:
  • •Does the product spec have ## Implementation Pointer? Note: yes/no
  • •Does a tech spec exist in .architecture/tasks/{{SPEC_PREFIX}}-XXX-*.md? Note: yes/no
  • •Does the product spec have ## Cross-References? Note: yes/no
• •Read any existing tech spec
• •Identify feature directory: {{FEATURES_DIR}}<feature>/
• •Comment on the issue: "Starting implementation on release/sprint-<N>"

Phase 2: Discovery

• •Find relevant existing code files using Glob and Grep
• •Read related components to understand existing patterns
• •Identify what needs to be created vs modified
• •Check for established patterns in CLAUDE.md memory notes

Phase 3: Architecture & Tech Documentation

Every issue must have technical documentation before implementation begins. Follow .architecture/tasks/ARCH-spec-linking-strategy.md.

Step 1 — Check existing documentation:

• •Does the product spec (.product/specs/{{SPEC_PREFIX}}-XXX-*.md) already have an ## Implementation Pointer section?
• •Does a separate tech spec exist in .architecture/tasks/?
• •If either exists and is accurate, proceed to Phase 4.

Step 2 — Determine documentation type needed:

A separate tech spec (.architecture/tasks/{{SPEC_PREFIX}}-XXX-*.md) is needed when the issue meets TWO or more of:

• •Introduces a new architectural pattern not used elsewhere
• •Touches 3+ feature directories or shared infrastructure
• •Requires detailed component-level design (interfaces, data flow)
• •Has significant non-functional requirements (performance, offline, security)
• •Estimated >1 day with non-obvious technical approach

If the criteria are not met, use an Implementation Pointer (inline in the product spec).

Step 3 — Create the documentation:

For an Implementation Pointer, add/update the ## Implementation Pointer section in the product spec:

## Implementation Pointer

**Complexity:** Simple | Moderate
**Feature Directory:** `{{FEATURES_DIR}}<feature>/`
**Key Files:**
- `path/to/file.ts` -- what it does
**Pattern:** [Which existing pattern to follow]
**Database Changes:** [None | description]
**Privacy Impact:** [None | Yes — <reason>]

Keep it under 15 lines. If you need more, create a tech spec instead.

For a separate tech spec, spawn architect agent to create it in .architecture/tasks/{{SPEC_PREFIX}}-XXX-*.md using the minimal tech spec template from the spec-linking strategy.

Step 4 — Privacy Impact Assessment:

Determine if this issue affects the privacy policy or terms of service:

If none of the triggers apply (UI-only, local-only, refactoring, bug fixes, content changes), note Privacy Impact: None in the Implementation Pointer and move on.

If any trigger applies:

• •Note Privacy Impact: Yes — <reason> in the Implementation Pointer
• •Add a task for the product-owner to update the relevant legal pages
• •Legal content updates must ship in the same PR or before the feature goes live

Step 5 — Update Cross-References: Add/update the ## Cross-References section at the top of the product spec if missing:

## Cross-References

| Type | Link |
|------|------|
| GitHub Issue | [#NN](https://github.com/{{GITHUB_OWNER}}/{{GITHUB_REPO}}/issues/NN) |
| Tech Spec | [path] | <!-- only if separate tech spec exists -->
| Feature Code | `{{FEATURES_DIR}}xxx/` |

Also spawn architect agent if:

• •The issue involves a new data model or API contract
• •The tech spec says "needs architecture review"

Architecture Gate Evaluation

After the architect returns, evaluate the architecture gate:

source lib/signal-extract.sh
source lib/score-gate.sh

# Collect raw values from architect's assessment
FRICTION=<from RICE sheet>
PATTERN_FOLLOWS=<true|false from architect>
FILE_COUNT=<number of files identified>
TOUCHES_SENSITIVE=<true|false — auth, payments, migrations>
NEW_DEPS=<count of new dependencies>

# Build signals and evaluate
SIGNALS=$(build_architecture_signals "$FRICTION" "$PATTERN_FOLLOWS" "$FILE_COUNT" "$TOUCHES_SENSITIVE" "$NEW_DEPS")
DECISION=$(evaluate_gate "architecture" "#<issue>" <sprint> "$SIGNALS")

# Log in orchestration: score/threshold (decision)

In shadow mode the decision is always escalate — proceed to the next phase regardless. The gate evaluation is logged to .cardo/history.jsonl for calibration.

Phase 3b: Security Threat Assessment

Rule: Spawn a security-engineer for /threat-model when the issue meets ANY of these criteria:

• •Touches auth, sync, or service directories
• •Introduces new API endpoints or modifies existing ones
• •Adds new third-party SDKs or native modules with network access
• •Modifies token handling, session management, or data encryption
• •Changes network configuration or trust boundaries
• •Handles file input from untrusted sources

The security-engineer produces a threat model document in .architecture/security/threat-model-{slug}.md using STRIDE analysis and OWASP cross-checks. Critical or High open threats must be mitigated before Phase 5 begins.

Skip if ALL of these are true:

• •UI-only changes (no data flow or network changes)
• •Content-only changes (translations, legal docs, copy)
• •CI/CD or tooling changes (no runtime behavior change)
• •Bug fix with no security surface (styling, layout, state management)

Security Gate Evaluation

After the security-engineer returns (or if skipped), evaluate the security gate:

source lib/signal-extract.sh
source lib/score-gate.sh

# Collect from security assessment (use "none"/0/false/"public"/"all_mitigated" defaults if skipped)
MAX_SEVERITY=<none|low|medium|high|critical>
FINDING_COUNT=<number>
CROSSES_BOUNDARY=<true|false>
DATA_LEVEL=<public|internal|pii|auth>
MITIGATION_STATUS=<all_mitigated|partial|open>

SIGNALS=$(build_security_signals "$MAX_SEVERITY" "$FINDING_COUNT" "$CROSSES_BOUNDARY" "$DATA_LEVEL" "$MITIGATION_STATUS")
DECISION=$(evaluate_gate "security" "#<issue>" <sprint> "$SIGNALS")

If security was skipped (no security surface), log with default safe values: none, 0, false, public, all_mitigated.

Phase 4: Design (MANDATORY for UI changes)

Rule: Never skip this phase for issues that involve UI changes. All UI/UX work must have design specs before implementation begins.

Spawn designer agent if ANY of these apply:

• •The issue involves new screens or components
• •The issue modifies existing UI (layout, styling, interaction patterns)
• •The issue adds or changes user-facing elements (buttons, cards, sheets, lists, empty states)
• •The product spec mentions visual elements, user flows, or interaction design

The designer produces:

• •Visual design specs (component dimensions, spacing, colors, typography)
• •Interaction specs (gestures, animations, transitions, feedback)
• •State specs (loading, empty, error, edge cases)
• •Output written to .product/specs/{{SPEC_PREFIX}}-XXX-*-design.md

Skip ONLY if ALL of these are true:

• •Pure backend/API changes (no UI files touched)
• •CI/CD or infrastructure changes
• •Content-only changes (translations, legal docs, copy text)
• •Bug fix that doesn't change any visual appearance

If in doubt, spawn the designer. The cost of a design spec is low; the cost of a rejected UI is high.

Phase 5: Implementation

Determine the engineer type from the tech spec and impacted areas identified in Phase 2:

• •App changes → spawn the appropriate engineer agent
• •Backend API changes → spawn backend-engineer agent
• •CI/CD, GitHub Actions → spawn platform-engineer agent
• •Content work (translations, legal docs, copy) → spawn product-owner agent
• •Mixed scope → spawn appropriate engineers for each portion
• •When in doubt → ask the user. The EM never implements directly.

Engineer instructions:

• •Follow TDD: write failing tests first, then implement
• •Use established patterns (see CLAUDE.md and memory notes)
• •Commit frequently with descriptive messages
• •Prefix every commit subject with the spec ID (e.g., {{SPEC_PREFIX}}-032: Add analytics provider)
• •Keep tech docs in sync: If implementation diverges from the tech spec or Implementation Pointer (new files added, patterns changed, different approach taken), update the documentation to match reality before finishing.

Phase 5b: Implementation Summary (MANDATORY)

After implementation is complete, the engineer must produce an Implementation Summary before proceeding to review. This is posted as a PR draft body or PR comment. The EM reviews it before spawning the code-reviewer.

## Implementation Summary

### AC Evidence
| AC | Status | How Verified | Evidence |
|----|--------|-------------|----------|
| AC description | PASS | Unit test | `file.test.ts:45` — "test name" |
| AC description | PASS | Unit test + manual | `file.test.ts:120` + device screenshot |

### Implementation Challenges
<!-- If ANY AC could not be implemented as spec'd, document it here. Empty = no challenges. -->

| Challenge | Spec Requirement | What Happened | Decision | Decided By |
|-----------|-----------------|---------------|----------|------------|
| Description | Original requirement | What happened | Decision made | EM + Architect |

### Scope Changes
<!-- Any AC added, removed, or modified from the original spec. Empty = no changes. -->
None

Rules:

1. •Every Must-Have AC must appear in the evidence table with a test name, file:line, or screenshot reference
2. •Any challenge that changed the implementation approach must be documented with who approved the change (PO, EM, or Architect)
3. •Silently dropping an AC is never acceptable. If an AC cannot be implemented, the engineer must escalate to the EM, who consults PO/Architect. The decision is documented in the Challenges table.
4. •Scope changes (adding, removing, or modifying ACs) require PO approval and are documented in the Scope Changes section.
5. •The EM reviews the Implementation Summary before Phase 6 begins. If challenges exist without documented decisions, the EM escalates to the user.

Phase 5c: EM Reviews Implementation Summary

Before spawning the code-reviewer, the EM reviews the Implementation Summary:

1. •AC completeness: Every Must-Have AC from the spec appears in the evidence table
2. •Challenge decisions: If challenges exist, verify they have documented decisions with the correct approver (PO for scope changes, Architect for technical pivots, EM for process decisions)
3. •Missing decisions: If a challenge shows an AC was dropped or changed without PO/Architect approval → stop and escalate to user. Do not proceed to review.
4. •Scope creep: If ACs were added that aren't in the spec → flag for PO awareness

Phase 6: Internal Review

Spawn code-reviewer agent:

• •Review all changes for this issue against acceptance criteria
• •Verify the Implementation Summary: Confirm every Must-Have AC has evidence. Any unchecked AC is an automatic blocker — not a suggestion.
• •Check code quality, test coverage, security
• •Verify tech documentation accuracy: Confirm the Implementation Pointer or tech spec matches what was actually built. Flag any drift (new files not listed, changed patterns, different approach). Reviewer must not approve until docs match code.
• •Verify privacy impact assessment: Check the Implementation Pointer for Privacy Impact: field. If it says Yes, confirm the legal content updates are included. If the field is missing, reviewer must assess whether the change triggers a privacy review (new server data, new SDK, new permissions, account features).
• •If changes requested → return to Phase 5, fix, re-review
• •Max 2 review cycles — if still failing, flag to user

Phase 6b: Review Finding Resolution (mandatory)

Every review finding must reach one of three dispositions — no finding may be silently ignored:

1. •Fixed — Code changed to address the finding. Commit and re-verify.
2. •Invalid — Finding is incorrect (e.g., suggested change breaks types, references non-existent feature). Document why it's invalid in the PR comment.
3. •Deferred — Finding is valid but out of scope for this issue/sprint. Requires tri-agent approval:

Deferral process:

• •Run /bug "<description>" or /feature "<description>" for each deferred item. This triggers the tri-agent assessment (EM + PO + Architect) which produces a RICE-scored, tracked GitHub issue.
• •The deferred item must be accepted by the tri-agent process (RICE >= 5) to be a valid deferral. If RICE < 5, the tri-agent process itself may reject it as too low priority to track — that's fine, document it as "Deferred — below tracking threshold per tri-agent assessment."
• •Add a "Deferred Review Findings" section to the PR body listing each deferred item with its new issue number.
• •No silent deferrals. If a finding isn't fixed and isn't explicitly run through /bug or /feature, it blocks approval.

Disposition summary — after Phase 6b, post a PR comment:

## Review Finding Disposition
| # | Finding | Disposition | Reference |
|---|---------|-------------|-----------|
| 1 | Description | Fixed | commit `abc1234` |
| 2 | Description | Invalid | reason |
| 3 | Description | Deferred | #NNN (via /bug) |

Code Review Gate Evaluation

After the code reviewer approves (Phase 6b dispositions resolved), evaluate the code_review gate:

source lib/signal-extract.sh
source lib/score-gate.sh

# Collect from review results
BLOCKERS=<count of blocker findings remaining>
WARNINGS=<count of warning findings remaining>
TEST_PASS=<true|false — all tests passing>
LINT_PASS=<true|false — lint + typecheck clean>
LINES_CHANGED=<total lines changed in diff>
COVERAGE_DIR=<increase|same|decrease>
FILE_RISK=<low|medium|high — based on files touched>

SIGNALS=$(build_code_review_signals "$BLOCKERS" "$WARNINGS" "$TEST_PASS" "$LINT_PASS" "$LINES_CHANGED" "$COVERAGE_DIR" "$FILE_RISK")
DECISION=$(evaluate_gate "code_review" "#<issue>" <sprint> "$SIGNALS")

After each issue completes

1. •Update the sprint batch checkpoint file
2. •Add the status:awaiting-release label to the issue:
   bash

   gh issue edit <number> --add-label "status:awaiting-release"
   

3. •Comment on the issue:
   bash

   gh issue comment <number> --body "Awaiting Release — implemented on \`release/sprint-<N>\`, commit \`<sha>\`. Will close when release branch merges to main."
   

4. •Proceed to the next issue

If blocked on an issue

• •Comment on the issue explaining the blocker
• •Skip it and move to the next issue — do not stop the entire batch
• •Add a note to the checkpoint file
• •Ask user for guidance on the blocked issue at the end

Phase 7: Build & Verify (Sprint Batch)

Skip if: all issues are backend-only, CI-only, or content-only (no {{APP_DIR}} files modified).

After ALL issues complete Phase 6, build and verify ONCE:

1. •Build the application for local testing on the release branch
2. •Install on test device
3. •For each issue with a Verification Plan in its product spec:
   • •Execute each Verification Plan row on device
   • •Capture screenshots per AC
   • •Log pass/fail per AC per issue
4. •Run the full {{E2E_TOOL}} E2E suite as regression
5. •Compile a consolidated verification report:
   markdown

   ## Verification Report — Sprint <N>
   | Issue | AC | Action | Result | Screenshot |
   |-------|----|--------|--------|------------|
   | #A | AC1 | {action} | Pass | verify-A-ac1.png |
   | #B | AC1 | {action} | Fail | verify-B-ac1.png |
   

6. •On failure: fix on release branch → quick re-review → incremental re-build → re-verify failing ACs only
7. •Circuit breaker: 3 failures on the same AC → escalate to user

Acceptance Gate Evaluation

After verification completes, evaluate the acceptance gate:

source lib/signal-extract.sh
source lib/score-gate.sh

# Collect from verification results
AC_TOTAL=<total acceptance criteria across all issues>
AC_PASSED=<number passing>
REGRESSIONS=<count of regression failures>
VERIFICATION=<manual|automated|both>

SIGNALS=$(build_acceptance_signals "$AC_TOTAL" "$AC_PASSED" "$REGRESSIONS" "$VERIFICATION")
DECISION=$(evaluate_gate "acceptance" "#sprint-<N>" <sprint> "$SIGNALS")

The acceptance gate never auto-approves regardless of mode — it always escalates to human.

Phase 8: Create Release PR

After all issues are verified (or skipped):

1. •Run full lint + type-check + tests on the release branch:
   bash

   {{LINT_CMD}} && {{TYPECHECK_CMD}} && {{TEST_CMD}}
   

2. •Push the release branch: git push -u origin release/sprint-<N>
3. •Create a consolidated PR:
   bash

   gh pr create --title "Sprint <N> Release" --body "$(cat <<'EOF'
   ## What Changed?
   Sprint <N> consolidated release containing <X> issues.
   
   ## Why?
   Batch delivery of remaining Sprint <N> work for consolidated review and testing.
   
   ## Issues Included
   | Issue | {{SPEC_PREFIX}}-ID | Title | Commits |
   |-------|-----|-------|---------|
   | #A | {{SPEC_PREFIX}}-XXX | Title | `abc1234`..`def5678` |
   | #B | {{SPEC_PREFIX}}-YYY | Title | `ghi9012`..`jkl3456` |
   ...
   
   ## Issues Skipped (blocked)
   - #C — reason
   
   ## Breaking Changes?
   No breaking changes
   
   ## Per-Issue Acceptance Criteria
   ### #A — {{SPEC_PREFIX}}-XXX: Title
   - [x] AC1
   - [x] AC2
   
   ### #B — {{SPEC_PREFIX}}-YYY: Title
   - [x] AC1
   ...
   
   ## Device Verification
   | Issue | AC | Result | Screenshot |
   |-------|----|--------|------------|
   | #A | AC1 | Pass | `verify-A-ac1.png` |
   | #B | AC1 | Pass | `verify-B-ac1.png` |
   
   ## Test Plan
   - [ ] All unit tests pass
   - [ ] Manual verification on target platform(s)
   - [ ] Full app smoke test
   
   Generated with [Claude Code](https://claude.com/claude-code)
   EOF
   )"
   

Phase 9: Merge Gate

1. •Verify CI passes: gh pr checks <pr-number>
2. •Present summary to user:
   code

   Sprint <N> Release PR #NNN ready for review.
   - X issues implemented, Y skipped
   - Z commits, W files changed
   - Run `/review <pr-number>` or review on GitHub
   

3. •Do NOT merge — user decides via /merge
4. •On merge: close all included issues, remove status:awaiting-release labels

Checkpoints

Save progress after each phase to .claude/sprint/checkpoints/issue-$ARGUMENTS.md (single mode) or .claude/sprint/checkpoints/sprint-batch.md (batch mode):

# Issue #$ARGUMENTS Progress
- Phase 1: Done — Intake complete
- Phase 2: Done — Discovery complete
- Phase 3: Skipped (not complex)
- Phase 4: Skipped (no UI files touched — backend/CI/content only)
- Phase 5: In progress
- Phase 6: Pending
- Phase 7: Pending
- Phase 8: Pending
- Phase 9: Pending

Error handling

• •If blocked: create a comment on the issue explaining the blocker, ask user for guidance
• •If tests fail after 2 attempts: flag to user, do not force
• •Never use --no-verify or --force to bypass checks
• •In batch mode: skip blocked issues and continue, don't halt the entire batch