implementing-features

Files (58)

• SKILL.md
• evals.json · evals/
• feat-offline-queue-broken.md · evals/fixtures/phasewave/.opencode/plans/
• feat-offline-queue-rename.md · evals/fixtures/phasewave/.opencode/plans/
• feat-offline-queue.md · evals/fixtures/phasewave/.opencode/plans/
• AGENTS.md · evals/fixtures/phasewave/
• ROADMAP.md · evals/fixtures/phasewave/
• schema.sql · evals/fixtures/phasewave/db/
• timer.spec.ts · evals/fixtures/phasewave/e2e/
• package.json · evals/fixtures/phasewave/
• lint.js · evals/fixtures/phasewave/scripts/
• test.js · evals/fixtures/phasewave/scripts/
• type-check.js · evals/fixtures/phasewave/scripts/
• .gitkeep · evals/fixtures/phasewave/src/lib/
• focus-timer.ts · evals/fixtures/phasewave/src/stores/
• client.ts · evals/fixtures/phasewave/src/supabase/
• feat-clip-duration.md · evals/fixtures/phasewave/tdd-realgap/.opencode/plans/
• AGENTS.md · evals/fixtures/phasewave/tdd-realgap/
• package.json · evals/fixtures/phasewave/tdd-realgap/
• lint.js · evals/fixtures/phasewave/tdd-realgap/scripts/
• test.js · evals/fixtures/phasewave/tdd-realgap/scripts/
• type-check.js · evals/fixtures/phasewave/tdd-realgap/scripts/
• .gitkeep · evals/fixtures/phasewave/tdd-realgap/src/lib/
• clip.js · evals/fixtures/phasewave/tdd-realgap/src/stores/
• feat-audit-log-dedupe.md · evals/fixtures/phasewave/tdd-rebalance/.opencode/plans/
• AGENTS.md · evals/fixtures/phasewave/tdd-rebalance/
• package.json · evals/fixtures/phasewave/tdd-rebalance/
• lint.js · evals/fixtures/phasewave/tdd-rebalance/scripts/
• test.js · evals/fixtures/phasewave/tdd-rebalance/scripts/
• type-check.js · evals/fixtures/phasewave/tdd-rebalance/scripts/
• seed.js · evals/fixtures/phasewave/tdd-rebalance/
• audit-store.broken.js · evals/fixtures/phasewave/tdd-rebalance/src/stores/
• audit-store.js · evals/fixtures/phasewave/tdd-rebalance/src/stores/
• fake-client.js · evals/fixtures/phasewave/tdd-rebalance/src/supabase/
• feat-session-score.md · evals/fixtures/phasewave/tdd-redfirst/.opencode/plans/
• AGENTS.md · evals/fixtures/phasewave/tdd-redfirst/
• package.json · evals/fixtures/phasewave/tdd-redfirst/
• lint.js · evals/fixtures/phasewave/tdd-redfirst/scripts/
• test.js · evals/fixtures/phasewave/tdd-redfirst/scripts/
• type-check.js · evals/fixtures/phasewave/tdd-redfirst/scripts/
• .gitkeep · evals/fixtures/phasewave/tdd-redfirst/src/lib/
• focus-timer.js · evals/fixtures/phasewave/tdd-redfirst/src/stores/
• feat-session-score.md · evals/fixtures/phasewave/tdd-wrongreason/.opencode/plans/
• AGENTS.md · evals/fixtures/phasewave/tdd-wrongreason/
• package.json · evals/fixtures/phasewave/tdd-wrongreason/
• lint.js · evals/fixtures/phasewave/tdd-wrongreason/scripts/
• test.js · evals/fixtures/phasewave/tdd-wrongreason/scripts/
• type-check.js · evals/fixtures/phasewave/tdd-wrongreason/scripts/
• .gitkeep · evals/fixtures/phasewave/tdd-wrongreason/src/lib/
• focus-timer.js · evals/fixtures/phasewave/tdd-wrongreason/src/stores/
• make-session.js · evals/fixtures/phasewave/tdd-wrongreason/tests/helpers/
• database.types.ts · evals/fixtures/phasewave/types/
• coverage-gate.md · references/
• deviation-protocol.md · references/
• handoff-template.md · references/
• red-first.md · references/
• skills-library.md · references/stacks/
• vue-supabase.md · references/stacks/

SKILL.md (first lines)

# Implementing Features

Execute one approved plan artifact. The plan is a contract: implement what
`Files to Modify` + `Included` scope say, after a red-first test per
Acceptance Criterion (Step 5), a runtime validation of the changed flow
(Step 8), and a coverage-and-quality gate (Step 9); run the plan's
`Verification` until exit 0, append a `## History` entry, then **stop** at a
manual-validation handoff. Success is exit codes, never intent — and a
criterion that needs human eyes is never self-certified.

## The implement pass

Copy this checklist and check off items as you complete them.

```
Implement Progress:
- [ ] 1. Read the plan artifact (frontmatter status first)
- [ ] 2. Resolve scope contract: Files to Modify + Included + Excluded
- [ ] 3. Detect stack & load the matching stack reference
- [ ] 4. Reconcile plan vs the actual repo (deviation triage BEFORE edits)
- [ ] 5. RED — capture core behavior from Acceptance Criteria (one test per AC, before any edit; confirm red for the right reason)
- [ ] 6. Implement exactly Files to Modify (scope discipline)
- [ ] 7. Run the plan's Verification; fix + re-run until all exit 0
- [ ] 8. Runtime UI validation (invoke validating-ui; console net + UX review; bounded fix loop)
- [ ] 9. Coverage-and-quality gate (rebalance layer guesses; re-prove meaningfulness; expand only on a real gap)
- [ ] 10. Update the plan (History entry; status per the user's convention)
- [ ] 11. Completion handoff summary + MANUAL validation steps; STOP
```

### Step 1 — Read the plan artifact

The skill starts only when given a plan artifact path. Read it before touching
any source — the prompt alone is not the spec; the plan is.

Git setup first (per `reference/git-workflow.md`): confirm the working tree is
on the plan's branch — `<type>/<name>` derived from the slug (e.g.
`fix-activity-image-delete` → `fix/activity-image-delete`), created from a
current `main` if it does not exist. Never work on `main`; only PRs merge.

- **No plan path given**, work is multi-file or schema-touching → route to
  `designing-architecture` and stop. This skill does not reverse-engineer a
  plan from a prompt; skipping the design stage destroys the auditability.
- **No plan path given**, single-file trivial change → just edit it; a plan
  costs more than the change (see "When not to use").

Read the frontmatter `status:` next:

- `approved` → proceed.
- `draft` → not approved. **Stop and confirm with the user** before editing
  ("the plan at `<path>` is `status: draft` — treat as approved, or hand back
  to design?"). Do not silently treat a draft as approved.
- `superseded` → do not implement; follow the `related:` pointer to the
  superseding plan.

A plan missing `Files to Modify`, `Verification`, or `Scope` is a contract
defect — route back to `designing-architecture` rather than improvising.

### Step 2 — Resolve the scope contract

The scope contract is three lists, read together:

1. **Files to Modify** — the only files you may create or edit; a file not on
   the list is out of scope. Do not tidy, refactor, or fix a pre-existing bug
   in it on the way past.
2. **Scope → Included** — what the plan delivers; confirms intent when a
   per-file note is ambiguous.
3. **Scope → Excluded** — the boundary you cite when refusing scope creep
   (non-empty by plan-format contract).

Hold the three in working memory for the whole pass; every "should I do this
too?" is checked against them.

### Step 3 — Detect stack & load the matching stack reference

Identify the project stack from its rules file (`AGENTS.md` /
`.opencode/agents.md`). If a matching `references/stacks/<stack>.md` exists in
this skill's own directory (not the project's), read it now and apply its
implementation-time concerns. If none exists, proceed generically and flag the
gap in the handoff. The available stack references are listed under
**References**.

### Step 4 — Reconcile plan vs the actual repo (BEFORE editing)

Before editing, match every `Files to Modify` entry against what is on disk and
read each named file. Classify each mismatch immediately:

- **Mechanical** — the feature is unchanged; only a mechanical detail differs
  (file moved/renamed, import alias drift). Proceed at the corrected detail and
  record a dated `## History` note with the reason.
- **Contract-breaking** — the mismatch changes what is being built (a different
  feature, a schema differing from `Schema / Type Impacts`, an AC untestable as
  written). **STOP**. Do not edit source. Report the mismatch and route back to
  `designing-architecture`; the implementer never improvises a different design.

The dividing question is *does the difference change the feature being built?*
When in doubt, stop — a stop is recoverable, a built-wrong-feature is not. The
full classification table is in `references/deviation-protocol.md` (read it
when a mismatch is ambiguous).

### Step 5 — RED — capture core behavior from Acceptance Criteria

Before any source edit, author each testable AC as a failing test — one test
per AC, before the behaviour exists. Invoke the matching test-trio skill in its
**red-first, pre-implementation** mode (the right-layer table lives there).
**Run it: it must fail for the right reason** — the failure output names the
missing behaviour, not a fixture gap or a typo; fix the test's own setup until
it does. Record each AC → test file and the red evidence for the plan History
and the handoff at Step 11.

Honest stops: an AC whose verifier cannot produce a red-first test is
contract-breaking (Step 4); a red that never fails for the right reason is the
N-attempts stop (Step 7) — hand to `debugging-test-failures`. Do not proceed on
an unverified red; that silently turns red-first back into test-after.

Full contract, rationale, and the pre- vs post-implementation distinction:
`references/red-first.md`.

### Step 6 — Implement exactly Files to Modify (scope discipline)

From hierovision/ai-framework, MIT.

More from hierovision/ai-framework