Feature Implementation

Feature Implementation Workflow

End-to-end workflow for a feature-implementation tagged item — the feature container that holds the plan and holistic review. Child work items under this container use the feature-task tag with lighter gates (task-scope instead of the feature-level feature-summary, and no review phase by default — task-level review is opt-in via the needs-task-review trait, which adds a review-checklist note to that child). A second child-level trait, needs-test-author, is opt-in the same way (applied per the /implement Step 1 trigger rule) and adds its own gate-enforced notes.

Covers all three phases (queue → work → review) with gate-enforced notes at each transition.

Usage: /feature-implementation [item-uuid]

• If item-uuid is provided: load the existing item and resume from its current phase
• If omitted: create a new item and start from the beginning

Phase 0 — Setup

If an item UUID was provided, call:

get_context(itemId="<uuid>")

Check canAdvance and missingRequiredNotes to determine which phase the item is in, then jump to the appropriate phase below.

If no UUID was provided, create the item:

manage_items(
  operation="create",
  items=[{ title: "<feature title>", tags: "feature-implementation", priority: "medium" }]
)

Note the returned UUID and expectedNotes list. Confirm the item is in queue role, then continue to Phase 1.

Phase 1 — Queue: Define the Feature Summary

Goal: Fill the single required queue-phase note before advancing to work.

1a. Fill feature-summary

Use manage_notes to upsert the feature-summary note:

manage_notes(
  operation="upsert",
  notes=[{
    itemId: "<uuid>",
    key: "feature-summary",
    role: "queue",
    body: "<content>"
  }]
)

What to write: Keep this note lean (target under 2k chars) — it stays at the feature level, not the child-task level where the full spec-quality disciplines apply. Cover:

• Goal — the problem this solves and who benefits.
• Findings → tasks table — a table mapping each finding or requirement to the child task that will address it.
• Dependency edges — ordering constraints between child tasks, if any.
• Non-goals pointer — a reference to where non-goals are documented per child (each child's task-scope note carries its own alternatives/non-goals/blast-radius/risk/test strategy per the spec-quality framework); this note does not repeat that analysis.

1b. Enter plan mode

After filling the note, use EnterPlanMode to explore the codebase and produce a concrete implementation plan. The pre-plan hook will inject additional guidance.

When the plan is approved, post-plan hook fires — proceed directly to Phase 2 without pausing.

1c. Advance to work

advance_item(transitions=[{ itemId: "<uuid>", trigger: "start" }])

Gate check: feature-summary must be filled. If gate rejects, fill the missing note and retry. If instead the response has errorCode: "resource_unavailable" (errorKind: "transient"), this is resource-lease contention, not a note gate failure — see Quick Reference below.

Confirm newRole: "work" in the response before dispatching implementation subagents.

Phase 2 — Work: Implement and Document

Goal: Delegate implementation, then fill work-phase notes before advancing to review.

2a. Materialize any child items

If the feature has sub-tasks, create them now using create_work_tree with the feature UUID as parentId and the feature-task tag. Each child fills a task-scope queue note (the full spec-quality disciplines — alternatives, non-goals, blast radius, risk flags, test strategy — apply there, not in the feature-level feature-summary). Dispatch implementation subagents with each child item UUID.

Each subagent must:

• Call advance_item(trigger="start") on their item to enter work phase
• Fill work-phase notes following the JIT progression loop (the subagent-start hook provides guidance via guidancePointer and skillPointer)
• Return to the orchestrator — do NOT call advance_item again. The orchestrator handles all further transitions.

By default, feature-task items have no review phase — advance_item(trigger="start") from work goes straight to terminal. A child only gets a review phase if it (or its schema's default_traits) carries the needs-task-review trait, which adds the review-checklist note back in, or the needs-test-author trait, which adds test-independence-audit.