---
name: implement
license: MIT
compatibility: "Claude Code 2.1.277+. Requires memory MCP server, context7 MCP server, network access."
description: "Builds a new feature with parallel backend, frontend, test and security agents in worktrees, then verifies. Use when asked to build, add or scaffold a feature, endpoint or component. Not for fixing, reviewing or testing existing code."
argument-hint: "[feature-description]"
context: fork
# user-typed commands stay interactive; CC >= 2.1.218 backgrounds forks by default (#3093)
background: false
disable-model-invocation: false  # #3194: true also blocked USER-typed mid-turn invocations
user-invocable: true
allowed-tools: "SendMessage AskUserQuestion Bash Read Write Edit Grep Glob Agent TaskCreate TaskUpdate TaskStop ToolSearch WebFetch EnterWorktree ExitWorktree CronCreate CronDelete Monitor PushNotification mcp__context7__resolve-library-id mcp__context7__query-docs mcp__memory__search_nodes"
skills: [api-design, react-server-components-framework, testing-unit, testing-e2e, testing-integration, explore, verify, memory, scope-appropriate-architecture, chain-patterns]
model: sonnet
metadata:
  category: workflow-automation
  mcp-server: memory, context7
  version: "2.8.0"
  author: "OrchestKit"
  complexity: "medium"
  tags: "implementation, feature, full-stack, parallel-agents, reflection, worktree"
triggers:
  keywords: [implement, implment, build, create, add, make, scaffold, "set up", "file upload", "dark mode", "rate limiting"]
  examples:
    - "build a user authentication system with JWT"
    - "add dark mode support to the dashboard"
    - "implement the payment webhook handler"
  anti-triggers: [fix, debug, review, explore, test, assess, brainstorm]
paths:
  - "src/**/*.{ts,tsx,js,jsx}"
  - "package.json"
  - "tsconfig.json"
  - "CLAUDE.md"
---

# Implement Feature

Host-neutral workflow. Invoke by skill name (`implement`). Claude Code slash routing, YAML hook loaders, and `.claude/chain` live in `references/claude-code.md`.

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

## Quick Start

```bash
implement user authentication
implement --model=opus real-time notifications
implement dashboard analytics
```

---

## Argument Resolution

**Check the target first, before any other step.** This skill forks and cannot see the conversation. Load `Read("../../shared/rules/target-resolution.md")`: if the target, flags stripped, is a bare pronoun or deictic (`this`, `them`, `that one`) or empty, return exactly `TARGET_UNRESOLVED: <word>` and stop. The caller resolves it and re-invokes.

```python
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-5-5`) 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.

```python
# 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.5 task budgets, public beta)

Opus 5.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:

```python
# 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:

| Remaining | Behavior |
|---|---|
| `> 50%` | Normal — all optional depth (devil's advocate, visual capture, deep exploration). |
| `20-50%` | Efficient — skip optional depth; keep core phases. Warn user once. |
| `< 20%` | Conservation — finish current phase, emit a handoff with next steps, do not start new work. |

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("../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 `../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 `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:

| Effort Level | Phases Run | Agents | Token Budget |
|-------------|------------|--------|--------------|
| **low** | 1 (Discovery) → 5 (Implement) → 10 (Reflect) | 2 max | ~50K |
| **medium** | 1 → 2 → 5 → 7 (Scope Creep) → 10 | 3 max | ~150K |
| **high** | All 10 phases | 4-7 | ~400K |
| **xhigh** (Opus 5, CC 2.1.111+) | All 10 phases + one additional healing iteration on test failures before escalating | 4-7 | ~550K |

> **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. `low` is right only for spec-complete, mechanical work, and a low run always hands off to `/ork:verify` at high: `Read("references/effort-ladder.md")`.

## 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")`

**Load project context.** A fork skill never runs frontmatter hooks (#4683), so run the loader yourself and keep its `additionalContext` in mind:

```bash
echo '{"tool_name":"Bash","tool_input":{}}' | node "${CLAUDE_PLUGIN_ROOT}/hooks/bin/run-hook.mjs" skill/project-convention-loader
echo '{"tool_name":"Bash","tool_input":{}}' | node "${CLAUDE_PLUGIN_ROOT}/hooks/bin/run-hook.mjs" skill/implement-standards-loader
git rev-parse HEAD  # note it as the start sha for the Phase 6 pattern check
```

### Worktree Isolation (CC 2.1.49)

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

```python
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:**

```python
# 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")`.

---

**Finish line.** Done means: every planned file is written, the new and existing tests pass, the scope-creep check found nothing unplanned, and E2E verification ran. Follow `Read("../../shared/rules/long-run-protocol.md")`: keep going when a step needs no input from the user, stop and ask only when you can't continue without them or before anything destructive, check each subagent's evidence before accepting it, and mark anything you couldn't confirm with where you looked.

## Task Management (MANDATORY)

**BEFORE doing ANYTHING else, create tasks to track progress:**

```python
# 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)

| Phase | Activities | Agents |
|-------|------------|--------|
| **1. Discovery** | Research best practices, Context7 docs, break into tasks | — |
| **2. Micro-Planning** | Detailed plan per task (load `references/micro-planning-guide.md`) | — |
| **3. Worktree** | Isolate in git worktree for 5+ file features (load `references/worktree-workflow.md`) | — |
| **4. Architecture** | 4 parallel background agents (+ event-driven-architect when event/CQRS/queue-shaped) | workflow-architect, backend-system-architect, frontend-ui-developer, llm-integrator |
| **5. Implementation + Tests** | Parallel agents, single-pass artifacts with mandatory tests | backend-system-architect, frontend-ui-developer, llm-integrator, test-generator |
| **6. Integration Verification** | Code review + real-service integration tests | backend, frontend, code-quality-reviewer, security-auditor |
| **7. Scope Creep** | Compare planned vs actual (load `references/scope-creep-detection.md`) | workflow-architect |
| **8. E2E Verification** | Browser + API E2E testing (load `references/e2e-verification.md`) | — |
| **9. Documentation** | Save decisions to memory graph | — |
| **10. Reflection** | Lessons learned, estimation accuracy | workflow-architect |

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

**Phase 6 pattern check.** The fork cannot run the enforcer per Write/Edit (#4683); pipe each changed file into `node "${CLAUDE_PLUGIN_ROOT}/hooks/bin/run-hook.mjs" skill/pattern-consistency-enforcer` once, as `Read("references/phase-6-pattern-check.md")` shows.

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.

| After Phase | Handoff File | Key Outputs |
|-------------|-------------|-------------|
| 1. Discovery | `01-discovery.json` | Best practices, library docs, task breakdown |
| 2. Micro-Plan | `02-plan.json` | File map, acceptance criteria per task |
| 4. Architecture | `04-architecture.json` | Decisions, patterns chosen, agent results |
| 5. Implementation | `05-implementation.json` | Files created/modified, test results |
| 7. Scope Creep | `07-scope.json` | Planned vs actual, PR split recommendation |

### 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.

| After Phase | Show User |
|-------------|-----------|
| 1. Discovery | Key findings, library recommendations, task breakdown |
| 4. Architecture | Each agent's design decisions as they return |
| 5. Implementation | Files created/modified per agent, test results |
| 7. Scope Creep | Planned vs actual delta, PR split recommendation |

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:

```python
# 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, isolation="worktree", ...)
# 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("../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("../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:

```python
# 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

```python
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 checkpoint