/new-feature-implement — Feature implement orchestrator

Why this is Form 2 (manual skill)

Axis 2 (manual trigger) + axis 5 (procedural) + axis 8 (both). It was input row 3 of /new-feature until the two flows of the pipeline became two pieces: an implement run loaded the whole design procedure — about 10k tokens of steps 1–6 and consolidation it never runs — on every main-thread turn, and it ran on the opus the design needs. A subagent was rejected: the executor is already the isolated part, and this thread only chains it (@.claude/decisions/0135-new-feature-split-spec-and-implement.md).

Manual only. disable-model-invocation: true hides this skill from the model: the Skill tool can't call it, and trying is blocked. When a conversation reaches the point of running it, print the exact command for the user to type — don't attempt the call.

Pinned to sonnet: this thread runs a detection, chains three Agent calls and copies their findings — no design. The executor declares its own model (@.claude/decisions/0081-skill-model-required-per-class.md). A skill's model holds for the turn it runs in; a background executor's hand-back opens a new turn, which may run on the session's model — measured in the run's audit report, not assumed.

Contract

Class: orchestrator — skill_classes.orchestrator in @.claude/schemas/extensions.json, with overrides.new-feature-implement.write_allow: []: this thread writes nothing. Every write of a run is a subagent's, judged by its own agent_classes entry — the executor's and the installers' — never by this phase (@.claude/decisions/0059-agent-classes-territory-schema.md). The class keeps design_phase: true, so ArchHook.java guard refuses a Skill call to a build-class skill while the run is open.

Ownership: Feature spec→code orchestrator. Owns the pre-flight, the group chain, the hand-off between groups, and the /git-publish line an implemented case ends with. Does not own the spec — /new-feature writes it and its status: up to approved; java-spring-boot-developer writes implemented or implemented-blocked (@.claude/skills/new-feature/SKILL.md § Spec lifecycle).

Reads:

• @.claude/skills/new-feature/references/entry-guardrail.md — survey, classification, error rule, worktree, project, disk; shared with /new-feature, owned there
• docs/use-cases/UC-*/ — folder existence and each spec's status: line, by command
• docs/use-cases/UC-NNN-<slug>/UC-NNN-spec.md — the checklist, to find where the chain starts, and ## Infrastructure, for the services the run adds and reports
• @.claude/skills/docker-architect/references/compose-service-decision.md — what each ## Infrastructure decision means, and who acts on it
• src/test/**, the build files, the root CLAUDE.md's **Mappers: paragraph — by command, for the pre-flight

Writes (indirectly):

• src/**, pom.xml and the spec's checklist and status: — via java-spring-boot-developer
• the ArchUnit tests and coverage gate — via test-architect setup mode → archunit-installer
• the logging/masking library dependency in the build file — via commons-logging-installer, at the version commons_logging of .claude/schemas/extensions.json pins
• the project's mapper mechanism — the **Mappers: paragraph, and for MapStruct the build wiring and every converted mapper — via mapstruct-installer, from this skill's templates/mapstruct/*.example
• docker-compose.yml and what a service needs next to it — via compose-service-installer, which runs docker-architect for every materialize row of the spec

Writes (directly): none.

Never runs git add, git commit, or git push, and never invokes git-publish. Git happens only through git-publish, which the person types after /clear, behind its two confirmations; the final report prints the command (@.claude/decisions/0182-git-publish-printed-not-chained-by-the-feature-flows.md). No end of this flow is left without an explicit git instruction.

Integrates with the agents and skills step 2's field lines name, phase by phase; when each runs is step 2's body.

git-publish is not an integration: § 4 prints its command.

Procedure

1 · Entry guardrail

Runs: self · Gate: stop

Stops when: no approved case given? · Says: prints the error and usage; or lists the cases (empty)

Runs before any skill invocation, any delegation, and any question. Read @.claude/skills/new-feature/references/entry-guardrail.md and run its § 1 (survey and classify), then evaluate this table in order and stop at the first row that matches:

Every error follows the rule of the reference's § 1 — fixed shape, ends the run, no side effect:

❌ /new-feature-implement: <reason>.
Usage: /new-feature-implement UC-NNN-slug    → implement an approved case
       /new-feature-implement                → list
       /new-feature <feature description>    → design a new case

Row 8 exists because free text is what /new-feature takes: a description typed here was meant there, and running the design from this skill would load the body this split exists to keep out.

Then the reference's §§ 2–4 (worktree, project, disk), in that order. IGNORED and the list of pre-existing changes travel into the /git-publish line § 4 prints. This run's own folder, docs/use-cases/UC-NNN-<slug>/, and docs/use-cases/BACKLOG.md are never pre-existing: an approved spec nobody committed yet is the run's input and goes in its feat commit.

2 · Implement

Runs: agent:mapstruct-installer? · Gate: ask, stop · Note: pre-flight, first and alone when it installs

Then runs: skill:test-architect>agent:archunit-installer?, agent:commons-logging-installer? · Note: pre-flight

Then runs: agent:java-spring-boot-developer · Note: three groups, chained: domain, adapters, tests

Stops when: a group fails? · Says: reports the failing group; the chain stops there

Then runs: agent:compose-service-installer>skill:docker-architect? · Note: only with a materialize row

1. One-time setup pre-flight, before delegating. The executor is about to write the first .java under src/ for this project run — the only point in the pipeline where "is the one-time infrastructure installed yet" actually matters. Detect what's missing, don't assume:

   grep -rl "ArchRule\|ArchTest" --include='*.java' src/test/ 2>/dev/null | head -1
   find . -path ./.claude -prune -o \( -name 'pom.xml' -o -name 'build.gradle' -o -name 'build.gradle.kts' \) -print 2>/dev/null | xargs grep -l 'spring-log-utils' 2>/dev/null | head -1
   find . -path ./.claude -prune -o -path '*/src/main/java/*' -name 'LogMask.java' -print 2>/dev/null | head -1
   grep -n '^\*\*Mappers:' CLAUDE.md 2>/dev/null

   First command empty → ArchUnit not installed yet (the same gap /new-feature's consolidation step 3 already flagged, if this use case is the first one). Second and third command empty → the logging library is not installed (commons_logging of .claude/schemas/extensions.json); a LogMask.java under src/ is a project from before the library, already installed. Fourth command empty → the project never chose its mapper mechanism (.claude/rules/mapping.md § One mechanism per project). Any gap found → AskUserQuestion, one question per gap found: Install now / Skip for this run for the first two; for the mappers, Keep manual mappers (recorded, never asked again) / Install MapStruct (converts every existing mapper; needs a clean src/).

   • ArchUnit, install now → invoke test-architect via the Skill tool with no argument at all (setup mode) — the route /new-feature's consolidation step 3 names; never invoke archunit-installer directly, it stays test-architect's alone.
   • Commons-logging, install now → invoke commons-logging-installer directly via the Agent tool. No owning per-feature skill to route through: this orchestrator is the trigger.
   • Mappers, either answer → invoke mapstruct-installer directly via the Agent tool, with the mode — manual or install — and the project root. It writes the **Mappers: paragraph either way, so the question is never asked twice. When its mode is install, run it first and alone, and wait for it before the other two: it refuses a source tree with uncommitted changes — so git restore can undo its conversion — and the other two installers write under src/. When the worktree check already listed pre-existing changes under src/ or in a build file, don't invoke it: say why, and the executor writes manual mappers this run — the next run asks again, and an install then converts them with the rest. A failure it reports (dirty src/, red baseline, red after conversion) leaves no paragraph: say so, show its one line, and proceed to the executor with the manual mechanism for this run — the next run asks again.
   • Both gaps found and both answered "Install now" → either order works, and the same turn is fine. This used to be the one place in the repo that could deadlock itself: Skill(test-architect) opened a design phase and Agent(commons-logging-installer) closed one, two PreToolUse hooks with no ordering guarantee between them, and the loser blocked every write the other agent made under src/ for the rest of the run — lessons-learned-006 § 1 is the run that hit it (138k tokens, zero files written, had to relaunch alone). agent_classes retired it: a subagent's write is judged by its own agent_type, so no phase reaches it and nothing closes a phase on an Agent call any more (@.claude/decisions/0059-agent-classes-territory-schema.md).
   • Either Skip of the first two → proceed to the executor anyway. A spec that doesn't cite @LogExecution/@MaskSensitiveData or ArchUnit doesn't need either installed to compile; skipping isn't a gate failure, it's the user's call.
   • No gap found → skip this pre-flight silently, no question asked.

2. Three delegations to java-spring-boot-developer, chained. Every turn of the executor rereads its whole context, so one run carrying Block 1 into Block 4 pays for it on every later turn — 427,889 tokens of context and 531,362 billable tokens in the run that reopened this (0130). Each group starts again from the spec and what is on disk:

   Group	Blocks	Checklist lines it ticks
   domain	1, 2	1-7, and 8-12 when the spec carries them
   adapters	H, A, I, 3, G, S, M, J, C — those the spec carries	13-15 when present, and each lettered line
   tests	4	16-19, then the status: line

   • No valid checklist, no chain. Before the first delegation run java -jar .claude/hooks/ArchHook.jar spec check <spec>. Exit 2 → stop, nothing delegated: ❌ <UC-NNN-slug> has no valid implementation checklist — followed by what the command printed and reopen it as draft and run /new-feature <UC-NNN-slug>. The executor's precondition 5 would abort the first group after the context was spent (issue #191)
   • Where the chain starts. At the first group with a checklist step neither ticked nor n/a. A group ticks its steps only when it ends green, so a run that failed in adapters starts there again, and a fresh spec starts at domain.
   • Each delegation sends the spec path, the group, and — from the second on — the Blocks lines and findings of every earlier group, copied from their reports. A decision a group took that is in neither the spec nor the disk reaches the next one only this way.
   • Launch the next group in the turn that receives the previous one's report, and ask nothing in between. The tests Stop gate defers while a writer subagent of the session runs; a turn that ends between two groups has none running, and the gate tests a half-built tree (@.claude/decisions/0116-tests-defers-while-a-writer-subagent-runs.md).
   • A group that fails stops the chain → report its failure, name the group, and stop. No git. /new-feature-implement UC-NNN-<slug> again resumes at that group.
   • Success — the tests group reports the checklist complete, the build green, and the spec at status: implemented (or implemented-blocked, which is a success too, with the case it blocks on named) → item 3 below, then § 4. No Skill call to git-publish.
3. Add the compose services the spec decided. Read the spec's ## Infrastructure. A materialize row → invoke compose-service-installer via the Agent tool, in the foreground and in the same turn as the tests report, with the use case folder and those rows. It runs docker-architect, which this thread cannot call: the class keeps design_phase, and the guard skips the Skill call of a classed agent instead (@.claude/decisions/0137-pending-compose-service-decided-at-design-materialized-at-implement.md). No materialize row, or no section → skip silently. The agent failing does not stop the run: the code is green, the row is reported with the /docker-architect command, and the /git-publish line is still printed.

git-publish's two confirmation gates decide whether anything is committed or pushed — the person types it, after /clear, so the commit runs at near-zero context and carries the whole audit trail of this run.

3 · Long-running background work

Runs: self · Gate: ask

Implementing a complete feature takes dozens of minutes. An executor launched in the background doesn't survive the machine sleeping: the watchdog cuts the stream and execution dies where it was. This happened three times in a row on the first real feature, with not a single file written, because all three died still in the reading phase.

Before delegating the first group in the background, warn once and offer both options: keep the machine awake for the whole chain (caffeinate -i on macOS), or implement on the main thread, which is resumable. The executor writes by checkpoint precisely so that an interruption leaves reusable progress — but no checkpoint helps if execution dies before the first Write. A chain cut between groups resumes at the first group with open steps (§ Procedure, step 2).

4 · Final report

Runs: self

Hands over: /clear, /git-publish, /new-feature

Last message of the run, and the only report: the spec path and its status:, the groups that ran and how each ended, every ## Infrastructure row of the spec, with what this run did to it — added or failed by the installer, already present, external with its address, or pending with the /docker-architect command (or "none") — every approved use case this run left unreachable end to end, with the backlog row that restores it named by its BL-NN (or "none"), every item deferred, with its owner (or "none"), every guarantee delegated to a consumer outside this project whose idempotency is assumed or unknown (or "none"), and every personal-data field that crosses a boundary in clear, with its receiver (or "none") — the findings come from the tests group's report, which carries every group's lines — and the next commands, in this order:

/clear
/git-publish feat(UC-NNN-<slug>): <one-line summary>[ — pre-existing: <paths>]
/new-feature <next feature description>

/clear comes first: the commit then runs on a clean context, and SessionEnd has closed this run, so its report and history.jsonl line are on disk and enter the same commit instead of staying staged behind it. — pre-existing: is present only when the guardrail's worktree step listed changes from before the run, with the list itself (directories past 20 paths). /git-publish is the person's call and may be skipped or typed later. A clean context per use case keeps cost measurable per case. A failed group's report instead names the group, its failure, and /new-feature-implement UC-NNN-<slug> to resume there — no /git-publish.

References

• @.claude/decisions/0130-executor-split-by-block-group-implement-in-clean-session.md — the three groups, the hand-off, launching in the same turn, the clean session.
• @.claude/decisions/0135-new-feature-split-spec-and-implement.md — why this flow is a skill of its own, its model and its empty territory.
• @.claude/decisions/0067-implement-entry-row.md — the single door to the implement half, input row 3 of /new-feature until 0135.
• @.claude/decisions/0116-tests-defers-while-a-writer-subagent-runs.md — why the next group launches in the turn that receives the previous one's report.
• @.claude/agents/commons-logging-installer.md — one-time logging/masking setup, triggered directly from the pre-flight; adds the published library to the build (@.claude/decisions/0200-commons-logging-from-spring-log-utils-library.md).
• @.claude/agents/mapstruct-installer.md — records the project's mapper mechanism once; for MapStruct, wires the build from this skill's templates/mapstruct/ and converts every existing mapper.
• @.claude/agents/compose-service-installer.md — adds the spec's materialize services through docker-architect, after the tests group and before the final report.
• references/blocks/ — owned by this skill: the executor's per-block procedure, read by java-spring-boot-developer one block at a time (@.claude/decisions/0199-executor-blocks-on-demand-read-discipline-archunit-translation.md).
• @.claude/decisions/0182-git-publish-printed-not-chained-by-the-feature-flows.md — why the report prints /git-publish instead of invoking it.
• @.claude/decisions/0137-pending-compose-service-decided-at-design-materialized-at-implement.md — why the service is decided at design time and added here, by an agent.

Entry into generated projects

Step 6.6 writes the skills into the project, this one included — the user runs /new-feature-implement UC-NNN-<slug> after /new-feature approves a spec.