implement-feature

---
name: implement-feature
description: Use when implementing a feature or story, especially with acceptance criteria to verify. Triggers on /implement, build, create feature, add functionality.
---

# Implement Feature

**Plan sidecar:** `{output_dir}/*/plan.json` (searches all feature plans, updates story status in place)

Structured feature implementation workflow with test-driven development, acceptance criteria confirmation, and continuous lightweight review.

## Input

The user provides one or more of:
- A story ID (e.g., `EPIC-1-S1`) — looked up in the plan sidecar JSON
- A feature description
- A project management card URL or ID
- Context about constraints or approach

## When to Use

- User says "implement", "add", "build", or "create" a feature
- User references a story ID from the plan sidecar
- User provides a project management card URL/ID
- Multi-step implementation that benefits from planning before coding

**When NOT to use:**
- Bug fixes — use systematic-debugging instead
- Single-line changes or trivial edits
- Pure research or exploration tasks

## Step Skeleton

At startup, call execute-steps to register these steps. Execute them in order, updating status after each.

| Step | Action | Condition | Mandatory |
|------|--------|-----------|-----------|
| 0 | Devcontainer gate (skip if not in repo with `.devcontainer/`) | always | Yes |
| 1 | Load story from plan.json | skip if no plan context | No |
| 2 | Confirm acceptance criteria | always | Yes |
| 3 | Write failing test | always (TDD) | Yes |
| 4 | Implement to pass test | always | Yes |
| 5 | Per-step review | always | Yes |
| 6 | Commit + update AC status in plan.json | always | Yes |
| 7 | Repeat 3-6 for next AC | loop until all AC done | Yes |
| 8 | Update story status in plan.json | always | Yes |

## Phase 0: Devcontainer Gate

Before any other work, run the pre-flight gate to ensure `/implement` runs in the right place:

```bash
SHIELD_REPO=. python3 shield/scripts/devcontainer_gate.py
```

Behavior:
- Inside a devcontainer (`SHIELD_IN_DEVCONTAINER=true`): proceeds silently.
- Outside, but no `.devcontainer/` in the repo: proceeds silently (no devcontainer set up).
- Outside, with `.devcontainer/` present:
  - If `.shield.json` `devcontainer.required = true`: refuses to start; prints reopen instructions; exits.
  - If `false`: proceeds.
  - If `ask` (default): prompts `[y/n/always/never]`. `y`/`always` refuses + instructs reopen; `n`/`never` proceeds.
- Exit code 1 means refuse — `/implement` must not continue.

This is the same logic implemented in `shield/scripts/devcontainer_gate.py` (covered by `test_devcontainer_gate.py`).

**Per-AC tracking:** Step 6 updates each AC's status in `plan.json` immediately after commit — not just at the end (step 8). This means `plan.json` is the per-AC source of truth. On resume, the skill reads `plan.json` to determine which ACs are already done, then continues the loop from the next incomplete AC. `steps.json` tracks coarse workflow position; `plan.json` tracks per-AC completion.

## Workflow

```
1. Load context (sidecar, PM card, or user description)
2. Confirm acceptance criteria with user
3. Plan implementation steps
4. Get user approval
5. TDD: write failing tests, implement, per-step review
6. Final verification against acceptance criteria
```

## Phase 1: Load Context

### From plan sidecar (preferred)

If plan sidecars exist in `{output_dir}/*/plan.json`:
1. Read all plan files found
2. Search for the story by ID across all plans
3. Extract: name, description, tasks, acceptance criteria
4. Show the story details to the user

If no plans found in `{output_dir}/*/plan.json`, check for legacy `shield/docs/plans/<name>.json` and suggest migration.

### From project management card

If a PM card URL/ID is provided and a PM tool is configured:
1. Call `pm_get_capabilities` to verify the adapter is available
2. Fetch the card details
3. Extract: title, description, acceptance criteria, subtasks

### From user description

If no sidecar or PM card, gather requirements by asking:
- What should this feature do?
- What inputs/outputs?
- How do we know it's done?

## Phase 2: Confirm Acceptance Criteria

**ALWAYS confirm acceptance criteria before starting implementation.**

Present the criteria to the user:

```
Story: EPIC-1-S1 — IPAM Pool Hierarchy

Acceptance Criteria:
  1. Regional pools allocate /20 CIDRs
  2. No CIDR overlap across regions
  3. Rollback without data loss

Confirm before starting implementation:
  [a] Proceed as-is
  [b] Edit criteria (add/remove/modify)
  [c] Skip — implement without formal criteria
```

If the user edits criteria:
1. Update the plan sidecar JSON with the new criteria
2. Re-render the HTML plan document from the updated sidecar
3. Optionally sync changes to the PM card

**Do NOT skip this step.** The confirmed criteria are what `/review` will verify against.

## Phase 3: Plan Implementation Steps

Explore the codebase to understand existing patterns, then create a plan:

1. Files to create or modify
2. Steps in execution order
3. Test strategy for each step
4. Which steps can run in parallel

If superpowers is available, delegate to `superpowers:writing-plans` for the plan structure.

## Phase 4: Get User Approval

Show the plan summary. **NEVER proceed without explicit approval.**

## Phase 5: TDD Implementation

For each step:

### 5a. Write failing test
Write a test that captures the expected behavior. Run it — confirm it FAILS.

### 5b. Implement
Write the minimal code to make the test pass.

### 5c. Per-step lightweight review
After each step passes its test:
- Check for obvious issues (logic bugs, style, missing edge cases)
- For the changed file's domain, consult the relevant skill(s):
  - `*.tf` / `*.tfvars` → `shield/skills/terraform/*/SKILL.md`
  - `*.java` / `*.kt` / `*.py` / `*.ts` / `*.js` / `*.go` → `shield/skills/backend/*/SKILL.md`
  - `*.yaml` (K8s manifests) → `shield/skills/kubernetes/*/SKILL.md`
  - `.github/workflows/*.yml` → `shield/skills/github-actions/*/SKILL.md`
- Use the LLM's judgment to pick which skills are applicable to the file. Skip skills that don't apply (e.g., spring-security on a controller file).
- This is NOT a full agent review — keep it focused on what changed in this step. Don't run a comprehensive multi-skill audit; that happens at /review.
- If the file's domain has no matching skill, fall back to general code-quality judgment.

### 5d. Commit
Commit the step immediately:
```bash
git add <specific files>
git commit -m "feat(<feature-name>): step N — <description>"
```

### 5e. Update sidecar status
If implementing from a sidecar story, update the story status:
- When starting: `"status": "in-progress"`
- When complete: `"status": "in-review"`
Re-render HTML after status change.

### 5f. Update last_aligned_with on story close
When a story transitions to `"status": "done"` (or, in the in-review path, when
its acceptance criteria are all met and the PR merges), update the plan-level
`last_aligned_with` field to the current `HEAD` commit SHA:

```bash
last_aligned_with=$(git rev-parse HEAD)
# write into {plan_json}.last_aligned_with
```

This satisfies the schema 1.3 drift-accountability contract — `/plan-review`
and `/pm-sync` surface the value so reviewers can compare plan and code as of
the same commit. The field stays `null` until the first close.

### 5h. Promote feature-folder LLD drafts to canonical (milestone close)

After step 5f (`last_aligned_with` update), check whether the just-closed
story was the **last** open story in its milestone. If yes, walk the
milestone's `touches_lld[]` and promote each draft from
`docs/shield/{feature}/lld-{name}.md` to `docs/lld/{name}.md`.

This step has six sub-steps, executed in order per component:

1. **Look up registry entry.** Read `lld_components[]` for the entry where
   `name == <component>`. Extract `type` and `fork_blob_sha`.

2. **Locate the draft.** `draft_path = docs/shield/{feature}/lld-{name}.md`.
   - If the draft is missing, auto-heal by invoking lld-docs in `draft` mode
     just-in-time; print a loud audit-trail warning (see "Just-in-time
     auto-heal" below).

3. **Concurrency check.** If `docs/lld/{name}.md` exists AND
   `fork_blob_sha` is non-null:
   - Compute `current_sha = blob_sha(docs/lld/{name}.md)` via
     `shield/scripts/lld_blob_sha.py`.
   - If `current_sha != fork_blob_sha`: fork drift detected. Invoke
     lld-docs in `remerge` mode (canonical changed since /plan drafted;
     merge canonical changes into draft). On clean merge, refresh
     `fork_blob_sha = current_sha` in plan.json and proceed. On conflict
     markers in the merged output, **abort** this component's promotion
     and surface a clear remediation message.

4. **Append §14 Changelog row** to the draft:
   ```
   | <milestone_id> | <YYYY-MM-DD> | <milestone.name> | <story_ids touching this component> |
   ```
   Insert at the bottom of the §14 table; preserve all existing rows.

5. **Atomic promote.** `os.replace(draft_path, canonical_path)` (writes via
   `<canonical>.tmp` first, then rename — same atomic contract as lld-docs
   skill's own writes).

6. **Back-fill `design_refs[]` anchors.** Walk all stories in plan.json;
   for each `design_refs[]` entry where `doc == "lld"` AND
   `component == <this component>` AND `anchor_url is null`:
   - Use `shield/scripts/lld_anchor_heuristic.py select_anchor()` with the
     story name and the template's slug allow-list (loaded from
     `shield/schema/lld-sections-<type>.yaml`).
   - Set `anchor_url = "lld-{name}.md#{slug}"`.
   - Update `label = "§{n} {title}"` (look up the slug's number+title from
     the schema).
   - Write the updated plan.json back atomically.

### Just-in-time auto-heal for missing drafts

If step 5h sub-step 2 finds no draft for a component listed in
`touches_lld[]`, just-in-time invoke the lld-docs skill to draft. Print a
loud multi-line warning to the run log AND include it in the run summary:

```
⚠️  DRAFT AUTO-GENERATED AT PROMOTION
    Component: <name>
    The /plan run did not produce docs/shield/{feature}/lld-{name}.md.
    /implement just-in-time-drafted the LLD; the design bypassed human review
    before promotion. Review docs/lld/{name}.md for content quality before
    next /plan-review.
```

Proceed with steps 3 through 6 normally.

### Milestone-close detection

A milestone is closed iff every story whose `milestone_id == <M>` has
`status == "done"`. The just-closed story is the trigger; step 5h runs
when its closure tips the milestone over to all-done.

If multiple stories close in the same /implement session (e.g. batch),
step 5h runs after the LAST one, not after each — the implementation can
short-circuit by checking the milestone state once per session-end.

### Summary output

`/implement` prints one block per promoted LLD:

```
LLD promoted: <component> (<type>)
  Source draft:    docs/shield/{feature}/lld-{component}.md
  Canonical:       docs/lld/{component}.md
  Fork drift:      none | auto-healed | aborted
  Changelog row:   | <M> | <date> | <milestone name> | <story_ids> |
  Anchor backfill: <count> entries updated (<exact-match: X, heuristic: Y, fallback: Z>)
```

### Failure modes

| Failure | Behavior |
|---|---|
| Draft missing AND auto-heal lld-docs invocation fails | Abort this component's promotion; continue with remaining `touches_lld[]` entries; surface as run-end error. |
| Concurrency check produces conflict markers | Abort this component's promotion; print `re-run /plan to refresh fork` and the conflicting section IDs; continue with remaining entries. |
| Atomic rename fails | Abort this component's promotion; the draft and the canonical both remain in their pre-step state (the `.tmp` is cleaned up); surface error. |
| Anchor back-fill: plan.json write-back fails | Roll back the changelog row append (re-read draft from prior state) is NOT attempted — the promotion already happened. Surface "promotion succeeded but design_refs[] back-fill failed; re-run /implement to retry back-fill." |

## Phase 6: Verify Against Acceptance Criteria

After all steps complete:

1. **Run all tests** — every test must pass
2. **Run linters/formatters** — code must be clean
3. **Check each acceptance criterion** against the implementation:

   | Criteria | Status | Evidence |
   |----------|--------|----------|
   | Regional pools allocate /20 CIDRs | Met | main.tf:42 — netmask_length = 20 |
   | No CIDR overlap | Met | tests/overlap.tftest.hcl |

4. **Update sidecar** — mark story as `"in-review"` if all criteria met
5. **Invoke `shield:summarize`** — produce an implementation summary

## Phase 7: Offer Next Steps

- `/review` — run full agent-based code review with AC verification
- `/pm-sync` — update story status in the PM tool

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Skipping AC confirmation | Always confirm before implementing |
| Implementing before tests | Write test first, confirm it fails |
| No per-step review | Check each step before committing |
| Not updating sidecar | Update status and re-render HTML |
| Giant end-of-feature commit | Commit after each step |
| Skipping verification | Check every AC before claiming done |