Implement

Implement Feature

Parallel subagent execution for feature implementation with scope control and reflection.

Quick Start

/ork:implement user authentication
/ork:implement --model=opus real-time notifications
/ork:implement dashboard analytics

Argument Resolution

FEATURE_DESC = "$ARGUMENTS"  # Full argument string, e.g., "user authentication"
# $ARGUMENTS[0] is the first token, $ARGUMENTS[1] second, etc. (CC 2.1.59)

# Model override detection (CC 2.1.72)
MODEL_OVERRIDE = None
for token in "$ARGUMENTS".split():
    if token.startswith("--model="):
        MODEL_OVERRIDE = token.split("=", 1)[1]  # "opus", "sonnet", "haiku", "fable"
        FEATURE_DESC = FEATURE_DESC.replace(token, "").strip()

Pass MODEL_OVERRIDE to all Agent() calls via model=MODEL_OVERRIDE when set. Accepts symbolic names (opus, sonnet, haiku, fable on harnesses whose Agent tool lists it; note fable is premium API spend after 2026-07-12) or full IDs (claude-opus-4-8) per CC 2.1.74.

Step -1: MCP Probe + Resume Check

Run BEFORE any other step. Detect available MCP servers and check for resumable state.

# Probe MCPs (parallel — all in ONE message):
# memory is alwaysLoad in .mcp.json (CC 2.1.121+, #1541) — probe below kept as fallback for older CC:
ToolSearch(query="select:mcp__memory__search_nodes")
ToolSearch(query="select:mcp__context7__resolve-library-id")

Write(".claude/chain/capabilities.json", JSON.stringify({
  "memory": <true if found>,
  "context7": <true if found>,
  "timestamp": now()
}))

# Resume check:
Read(".claude/chain/state.json")
# If exists and skill == "implement":
#   Read last handoff (e.g., 04-architecture.json)
#   Skip to current_phase
#   "Resuming from Phase {N} — architecture decided in previous session"
# If not: write initial state
Write(".claude/chain/state.json", JSON.stringify({
  "skill": "implement", "feature": FEATURE_DESC,
  "current_phase": 1, "completed_phases": [],
  "capabilities": capabilities,
  "budget_remaining_pct": 100  // advisory; see Budget Awareness below
}))

Batch Size Governance (large refactors)

For implementations touching >10 files, enforce max 5 files per agent batch, run tests between batches, commit green batches immediately, stop on red. Override via --batch-size N. Full rule: Read("rules/batch-governance.md").

Budget Awareness (Opus 5 task budgets, public beta)

Opus 5 exposes per-task token budgets. Until the CC side is GA, OrchestKit tracks an advisory budget_remaining_pct in state.json so long runs self-throttle. Update after each phase:

# At end of every phase, estimate remaining budget:
pct = tokensAsContextPct(tokensUsedSoFar)  # from lib/context-window.ts
remaining = max(0, 100 - pct)
state["budget_remaining_pct"] = remaining
Write(".claude/chain/state.json", JSON.stringify(state))

Thresholds influence behavior:

When CC's native task-budget API ships GA, replace the estimate with the real signal; the thresholds and behavior stay the same.

Load: Read("${CLAUDE_PLUGIN_ROOT}/skills/chain-patterns/references/checkpoint-resume.md")

Step -0.5: Assess Verdict Gate

If .claude/chain/assess-verdict.json exists with a feature matching this run and verdict == "fail" (composite < the 5.5 min_pass in ${CLAUDE_PLUGIN_ROOT}/skills/assess/rubric.json, or any dimension below its min_blocker), BLOCK Phase 1. Present each blockers[] entry (dimension, score, reason), then AskUserQuestion with plain label+description options (no preview):

1. Fix blockers first (Recommended) — address the blockers, re-run /ork:assess, then return here.
2. Override and implement — proceed anyway; record "assess_gate": "overridden" in state.json and carry the blockers into Phase 1 context.

Missing file or verdict == "pass" → no gate; continue to Step 0.

Step 0: Effort-Aware Phase Scaling (CC 2.1.76; xhigh added in 2.1.111)

Read the /effort setting to scale implementation depth. The effort-aware context budgeting hook detects effort level automatically — adapt the phase plan accordingly:

Override: Explicit user selection in Step 0 (e.g., "Plan first" or "Worktree") overrides /effort downscaling. If user requests full exploration, respect that regardless of effort level.

Step 0a: Project Context Discovery

BEFORE any work, detect the project tier. This becomes the complexity ceiling for all patterns.

Scan codebase signals and classify into tiers 1-6 (Interview through Open Source). Each tier sets an architecture ceiling and determines which phases/agents to use.

Load tier details, workflow mapping, and orchestration mode: Read("references/tier-classification.md")

Worktree Isolation (CC 2.1.49)

For features touching 5+ files, offer worktree isolation to prevent conflicts with the main working tree:

AskUserQuestion(questions=[{
  "question": "Isolate this feature in a git worktree?",
  "header": "Isolation",
  "options": [
    {"label": "Yes — worktree (Recommended)", "description": "Creates isolated branch via EnterWorktree, merges back on completion"},
    {"label": "No — work in-place", "description": "Edit files directly in current branch"},
    {"label": "Plan first", "description": "Research and design in plan mode before writing code"}
  ],
  "multiSelect": false
}])

If 'Plan first' selected:

# 1. Enter read-only plan mode
EnterPlanMode("Research and design: $ARGUMENTS")

# 2. Research phase — Read/Grep/Glob ONLY, no Write/Edit
#    - Read existing code in the target area
#    - Grep for related patterns, imports, dependencies
#    - Check tests, configs, and integration points
#    - If context7 available: query library docs

# 3. Design the plan — produce:
#    - File map: which files to create/modify
#    - Architecture decisions with rationale
#    - Task breakdown with acceptance criteria
#    - Risk assessment and edge cases

# 4. Exit plan mode — returns plan to user for approval
ExitPlanMode()

# 5. User reviews plan. If approved → continue to Phase 1 (Discovery)
#    with the plan as input. If rejected → revise or stop.

If worktree selected:

1. Call EnterWorktree(name: "feat-{slug}") to create isolated branch
2. All agents work in the worktree directory
3. On completion, merge back: git checkout {original-branch} && git merge feat-{slug}
4. If merge conflicts arise, present diff to user via AskUserQuestion

Load worktree details: Read("references/worktree-isolation-mode.md")

Step 0b: Blast-Radius Clarification (ask "what" before "how")

Before Phase 1, resolve the unknowns whose answers would change the architecture, in blast-radius order — schema/migration → auth → API contract → perf/scale → cosmetics (last). Grep first, then AskUserQuestion one at a time (highest first, cap ~5, skip the obvious). Each answer becomes a row in a Decisions table written to .claude/chain/decisions.json and the PR body, feeding Phase 4 (Architecture) as constraints. Do NOT start Phase 1 with an unresolved schema/auth question; skip in low effort. Full protocol: Read("references/blast-radius-clarification.md").

Task Management (MANDATORY)

BEFORE doing ANYTHING else, create tasks to track progress:

# 1. Create main task IMMEDIATELY
TaskCreate(
  subject="Implement: {feature}",
  description="Feature implementation with parallel subagents",
  activeForm="Implementing {feature}"
)

# 2. Create subtasks for each phase
TaskCreate(subject="Research best practices and docs", activeForm="Researching best practices")  # id=2
TaskCreate(subject="Micro-plan: scope, files, criteria", activeForm="Micro-planning")            # id=3
TaskCreate(subject="Architecture design (parallel agents)", activeForm="Designing architecture") # id=4
TaskCreate(subject="Implement and write tests", activeForm="Implementing code")                  # id=5
TaskCreate(subject="Integration verification", activeForm="Verifying integration")               # id=6
TaskCreate(subject="Scope creep check", activeForm="Checking scope creep")                       # id=7
TaskCreate(subject="E2E verification", activeForm="Running E2E verification")                    # id=8
TaskCreate(subject="Document and reflect", activeForm="Documenting decisions")                   # id=9

# 3. Set dependencies for sequential phases
TaskUpdate(taskId="3", addBlockedBy=["2"])  # Plan needs research
TaskUpdate(taskId="4", addBlockedBy=["3"])  # Architecture needs plan
TaskUpdate(taskId="5", addBlockedBy=["4"])  # Implementation needs architecture
TaskUpdate(taskId="6", addBlockedBy=["5"])  # Integration needs implementation
TaskUpdate(taskId="7", addBlockedBy=["6"])  # Scope creep needs integration
TaskUpdate(taskId="8", addBlockedBy=["7"])  # E2E needs scope check
TaskUpdate(taskId="9", addBlockedBy=["8"])  # Docs need E2E

# 4. Update status as you progress
TaskUpdate(taskId="2", status="in_progress")  # When starting
TaskUpdate(taskId="2", status="completed")    # When done — repeat for each subtask

Workflow (10 Phases)

Load agent prompts: Read("references/agent-phases.md")

For Agent Teams mode: Read("references/agent-teams-phases.md")

Nested delegation (CC 2.1.172+): Phase 4-6 specialist agents MAY be instructed to delegate a bounded sub-problem to their own declared sub-agents (e.g. backend-system-architect → database-engineer for schema design) instead of doing everything inline. Keep chains ≤ 3 levels deep; when sub-tasks are independent, flatten to parallel dispatch from this orchestrator. See chain-patterns Pattern 9 (CC 2.1.172+).

Phase Handoffs (CC 2.1.71)

Write handoff JSON after major phases. See chain-patterns skill for schema.

Progressive Output (CC 2.1.76+)

Output results incrementally after each phase — don't batch everything until the end.

Focus mode (CC 2.1.101): In focus mode (/focus), the user only sees your final message. Include a self-contained summary with all key results — don't assume they saw incremental outputs.

When agents run with run_in_background=true, output each agent's findings as soon as it returns — don't wait for all agents to finish. This gives users ~60% faster perceived feedback and enables early intervention if an agent's approach diverges from the plan.

Teammate background tasks survive turn-end (CC 2.1.183): A run_in_background task started by a teammate is no longer killed when that teammate finishes its turn. A parallel architecture/test teammate can launch a long build and let it outlive its own turn; the lead collects the result later. Pre-2.1.183 the lead had to own every background task to keep it alive.

Monitor Tool for Background Streaming (CC 2.1.98)

Use Monitor to stream real-time events from background build/test scripts instead of polling output files:

# Start a long-running build in background
Bash(command="npm run build 2>&1", run_in_background=true)
# Stream its output line-by-line as notifications (no polling)
Monitor(pid=build_task_id)

# For background agents with test suites:
Agent(subagent_type="ork:test-generator", run_in_background=true, ...)
# Monitor agent progress via task notifications (CC 2.1.98 partial progress)

Full pattern reference (when to use vs. TaskOutput, until-condition gates, partial-result salvage, anti-patterns): Read("${CLAUDE_PLUGIN_ROOT}/skills/chain-patterns/references/monitor-patterns.md").

Partial results (CC 2.1.98): if a worktree-isolated agent crashes mid-implementation, salvage its partial output — git diff --name-only in its worktree, commit what's usable, flag incomplete items — instead of re-spawning; escalate a BLOCKED agent to the user. Full salvage logic: the monitor-patterns reference above.

Worktree-Isolated Implementation

Spawn parallel implementation agents with Agent(isolation="worktree"). The subagent bypass of the worktree-isolation guard was fixed in CC 2.1.154 and completed in 2.1.203; ork's floor is >= 2.1.220, so every supported session gets real isolation. Full pattern, plus the 2.1.206 caveat that EnterWorktree now prompts for confirmation on ork's out-of-tree ../<repo>-<task> convention: Read("${CLAUDE_PLUGIN_ROOT}/skills/chain-patterns/references/worktree-agent-pattern.md")

Historical (CC <= 2.1.153 only): the param thrashed the primary worktree's HEAD and cut agents off at ~60 tool uses (Yonatan-HQ/platform#3224). The manual pre-create workaround that fixed it is superseded and kept only as a record: references/manual-worktree-pattern.md.

Post-Deploy Monitoring (CC 2.1.71)

After final PR, schedule health monitoring:

# Guard: Skip cron in headless/CI (CLAUDE_CODE_DISABLE_CRON)
# if env CLAUDE_CODE_DISABLE_CRON is set, run a single check instead
CronCreate(
  schedule="0 */6 * * *",
  prompt="Health check for {feature} in PR #{pr}:
    gh pr checks {pr} --repo {repo}.
    If healthy 24h → CronDelete. If errors → alert."
)

context7 with Detection

if capabilities.context7:
  mcp__context7__resolve-library-id({ libraryName: "next-auth" })
  mcp__context7__query-docs({ libraryId: "...", query: "..." })
else:
  WebFetch("https://docs.example.com/api")  # T1 fallback

Issue Tracking

If working on a GitHub issue, run the Start Work ceremony from issue-progress-tracking and post progress comments after major phases.

Feedback Loop

Maintain checkpoints after each task. Load triggers: Read("references/feedback-loop.md")

Test Requirements Matrix

Phase 5 test-generator MUST produce tests matching the change type. Each change type maps to specific required tests and testing rules.

Load test matrix, real-service detection, and phase 9 gate: Read("references/test-requirements-matrix.md")

Key Principles

• Verification gate (terminal, mandatory) — before declaring ANY task done you MUST Read("${CLAUDE_PLUGIN_ROOT}/shared/rules/verification-gate.md") and satisfy EVERY check: every changed file verified, tests green, scope-creep scored. A partial pass is NOT done; "should work now" is not evidence.
• Agent status protocol — all subagents report DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT per Read("${CLAUDE_PLUGIN_ROOT}/shared/status-protocol.md")
• Tests are NOT optional — each task includes its tests, matched to change type (see matrix above)
• Parallel when independent — use run_in_background: true, launch all agents in ONE message
• Output limits (CC 2.1.77+): the Opus tier defaults to 64k output tokens (128k upper bound). Generate complete artifacts in a single pass when possible; chunk across turns if output exceeds the limit
• Micro-plan before implementing — scope boundaries, file list, acceptance criteria
• Detect scope creep (phase 7) — score 0-10, split PR if significant
• Real services when available — if docker-compose/testcontainers exist, use them in Phase 6
• Reflect and capture lessons (phase 10) — persist to memory graph
• Clean up agents — teammates wind down at turn end (CC 2.1.178+ implicit team); press Ctrl+F twice to stop lingering background agents. Note: /clear (CC 2.1.72+) preserves background agents
• Exit worktrees — call ExitWorktree(action: "keep") in Phase 10 if worktree was entered in Step 0; never leave orphaned worktrees

Next Steps (suggest to user after implementation)

/ork:verify {FEATURE}              # Grade the implementation
/ork:cover {FEATURE}               # Generate test suite
/ork:commit                        # Commit changes
/loop 10m npm test                 # Watch tests while iterating
/loop 30m /ork:verify {FEATURE}    # Periodic quality gate

PushNotification on Completion (CC 2.1.110+)

/ork:implement runs commonly take 10–30 min with parallel agents. At the final synthesis step, after the PR is opened and tests are green, call PushNotification — the user has almost certainly context-switched.

PushNotification(
  message=f"ork:implement complete — {FEATURE}: {tests_passing}/{tests_total} tests · PR #{pr_num} opened · ready for /ork:verify",
  status="proactive"
)

Full rule (when to fire, body content limits, graceful fallback for users without Remote Control): load Read("${CLAUDE_PLUGIN_ROOT}/skills/chain-patterns/rules/push-notification-on-completion.md").

Agent Coordination

Dispatch envelope (CC 2.1.142+ flags — M146-6 / #1849)

When dispatching subagents — whether via the in-session Agent tool or a headless claude -p --bare from a wrapper script — set explicit --permission-mode and --effort per agent role so behaviour is deterministic across interactive vs CI runs:

In-session Agent tool calls inherit the parent session's permission mode; the table is the policy for what those defaults should be. For genuinely headless invocations (cron, CI), pass the flags explicitly to claude -p --bare:

claude -p --bare \
  --permission-mode dontAsk \
  --effort low \
  --max-turns 8 \
  "<prompt>"

Context Passing

All spawned agents receive: changed files list, project tier, architectural constraints, and decisions from prior phases (discovery, plan). Pass via the agent prompt, not just "implement X".

SendMessage (Active Coordination)

Cross-session replies land in the parent (CC 2.1.248): when a subagent sends SendMessage to another session, the reply is delivered to the parent session's conversation, never to the subagent; a subagent sends and moves on, the parent reads the answer. Cross-session SendMessage / ListAgents also work on Bedrock, Vertex and Foundry and with telemetry disabled (CC 2.1.248).

When backend and frontend agents need to align on API contracts:

SendMessage(to="frontend-ui-developer", message="API endpoint is POST /api/auth with {token, refreshToken} response shape")
SendMessage(to="test-generator", message="Backend uses JWT — mock auth middleware in test fixtures")

Skill Chain

After implementation completes, chain to verification:

TaskCreate(subject="Verify implementation", activeForm="Verifying changes")
TaskUpdate(taskId=verify_id, addBlockedBy=[impl_task_id])
# Then: /ork:verify {feature}

Session recovery (CC 2.1.108+): After idle periods or interruptions, use /recap to restore conversational context. Combined with .claude/chain/state.json checkpoint-resume, this enables full recovery of multi-phase implement sessions. Enabled by default since CC 2.1.110 (even with telemetry disabled).

Quality Bar

Done means all of these hold:

• every changed file verified per the terminal verification gate — never "should work"
• each Phase 5 task ships its tests matched to change type; the suite ran green with the summary line cited
• scope creep scored 0-10 in Phase 7; PR split when the delta is significant
• worktrees entered in Step 0 are exited via ExitWorktree — no orphans

Related Skills

• ork:explore: Explore codebase before implementing
• ork:verify: Verify implementations work correctly
• ork:issue-progress-tracking: Auto-updates GitHub issues with commit progress

References

Load on demand with Read("references/<file>"):