new-feature
Orchestrates the feature pipeline — one use case per run, 5 design skills → spec.md for the executor, and implements an already-approved spec on the same argument
SKILL.md.claude/skills/new-feature/SKILL.md
GitHub/new-feature — Feature design orchestrator
Why this is Form 2 (manual skill)
Axis 2 (manual trigger) + axis 5 (procedural) + axis 8 (both). Form 1 rejected — user requested manual invocation. Subagent rejected — none of the three reasons apply (context, tools, model). A fixed-order procedure rules out a rule and CLAUDE.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 opus: consolidating the partials and settling their divergences is design, and the executor it chains declares its own model (@.claude/decisions/0081-skill-model-required-per-class.md).
Contract
Class: orchestrator — the territory is skill_classes.orchestrator in
@.claude/schemas/extensions.json and ArchHook.java guard enforces it. A run writes under
docs/ only, and ArchHook.java guard also refuses a Skill call to a build-class skill
while this run is open: a design run does not materialize files, it records what is missing.
Ownership: Feature zero→spec orchestrator. Owns the sequence, the input table, the
spec lifecycle (status:), and the final output (UC-NNN-spec.md). Does not own the
use case number or slug — use-case-design does.
Reads:
pom.xml,.claude/forbidden-imports.txt, and this project's domain package, discovered and never assumed — validates the generated projectdocs/use-cases/UC-*/— folder existence and each spec'sstatus:line, by commanddocs/use-cases/UC-NNN-<slug>/*.md— the partials of the case being run
Writes (indirectly via layer skills):
docs/use-cases/UC-NNN-<slug>/00-use-case.mdanddocs/use-cases/BACKLOG.md— viause-case-designdocs/use-cases/UC-NNN-<slug>/10-domain.md— viadomain-modelingdocs/use-cases/UC-NNN-<slug>/20-persistence.md— viapersistence-architect, migration SQL included as a code block, never as a file undersrc/docs/use-cases/UC-NNN-<slug>/25-messaging.md— viamessaging-architect, only if10-domain.md's Events block names external (Kafka) deliverydocs/use-cases/UC-NNN-<slug>/35-jobs.md— viajobs-architect, only if25-messaging.mdchose Form B or00-use-case.md's trigger is a scheduledocs/use-cases/UC-NNN-<slug>/30-rest.md— viarest-api-architect, unless00-use-case.md'sTriggernamesinbound GraphQL adapteralone (step 3)docs/use-cases/UC-NNN-<slug>/31-graphql.md— viagraphql-api-architect, only if theTriggernamesinbound GraphQL adapterorinbound REST and GraphQL adapters(step 3g)docs/use-cases/UC-NNN-<slug>/32-security.md— viasecurity-architect, only if00-use-case.md'sAccessasks for something the project's filter chain does not already give (step 3b)docs/use-cases/UC-NNN-<slug>/28-http-client.md— viahttp-client-architect, only if10-domain.md§ Ports declares a port of kindexternal HTTP(step 3c)docs/use-cases/UC-NNN-<slug>/29-ai.md— viaai-architect, only if10-domain.md§ Ports declares a port of kindLLMorvector store(step 3d)docs/use-cases/UC-NNN-<slug>/23-search.md— viasearch-architect, only if00-use-case.md'sSearch indexrow names a projection (step 3e)docs/use-cases/UC-NNN-<slug>/22-cache.md— viacache-architect, only if00-use-case.md'sFreshnessrow states a tolerance (step 5b)docs/use-cases/UC-NNN-<slug>/40-tests.md— viatest-architect
Writes outside docs/: none. A run is docs-only, and that is enforced, not promised:
ArchHook.java guard refuses a Skill call to a build-class skill — docker-architect
included — while this orchestrator's phase is open, and refuses a write outside
skill_classes.orchestrator's territory. A partial that needs a service the compose file
doesn't declare asks whether to add it, and records the answer in its ## Compose services
(persistence-architect step 9, messaging-architect step 9); the consolidated spec carries
the list in ## Infrastructure, and /new-feature-implement adds every materialize row
after the code is green — never this run. Why: a design run once hand-wrote a schema-registry block
into docker-compose.yml, with no template, no tag verification and no healthcheck
(lessons-learned-012.md §§ 4, 12, 13), and the review was of a spec nobody read that file
through. Record: @.claude/decisions/0058-skill-classes-territory-schema.md
Writes (directly):
docs/use-cases/UC-NNN-<slug>/UC-NNN-spec.md— implementation plan (executor-ready), including itsstatus:line (draft→approved)
Never writes under src/. Neither does any skill it chains. Every file under src/
— migrations included — belongs to java-spring-boot-developer, delegated by
/new-feature-implement, which also owns the one-time setup pre-flight
(@.claude/skills/new-feature-implement/SKILL.md).
Never runs git add, git commit, or git push. Neither does any skill it chains.
Git happens only through git-publish, behind its two confirmations, at the end steps
below. No end of this flow is left without an explicit git instruction.
Integrates with (sequence ordered by depends-on):
use-case-design— invoked for a new case; skipped on resume when00-use-case.mdexistsdomain-modeling— invoked if10-domain.mdis missing (depends on 1)rest-api-architect— invoked if30-rest.mdis missing (depends on 2). Skipped when00-use-case.md'sTriggernamesinbound GraphQL adapteralone 3g.graphql-api-architect— invoked if theTriggernamesinbound GraphQL adapterorinbound REST and GraphQL adaptersand31-graphql.mdis missing (depends on 1, 2; reads 3 when present). Skipped when the case has no GraphQL trigger 3b.security-architect— invoked per step 3b's table when32-security.mdis missing (depends on 1, 2, 3). Skipped whenAccessis public in a project with no filter chain, or authenticated in one whose chain already denies by default 3c.http-client-architect— invoked if10-domain.md§ Ports declares a port of kindexternal HTTPand28-http-client.mdis missing (depends on 1, 2; reads 3 and 3b when present). Skipped when the case calls no other system over HTTP 3d.ai-architect— invoked if10-domain.md§ Ports declares a port of kindLLMorvector storeand29-ai.mdis missing (depends on 1, 2; reads 3, 3b and 3c when present). Skipped when the case asks no model and searches no store 3e.search-architect— invoked if00-use-case.md'sSearch indexrow names a projection and23-search.mdis missing (depends on 1, 2). Skipped when the row readsnone, or the case predates itmessaging-architect— invoked if10-domain.md's Events block names external (Kafka) delivery and25-messaging.mdis missing (depends on 2). Skipped entirely when the event, if any, stays in-process — not every use case needs itjobs-architect— invoked if25-messaging.mdchose Form B, the trigger is a schedule,28-http-client.md§ 10 asks for a reconciliation pass, or29-ai.md§ 9 asks for an ingestion or re-index job, or23-search.md§ 8 asks for a rebuild job, or theAuditrow nameshistorywith no history prune job in the project yet, and35-jobs.mdis missing (depends on 1, 3c, 3d, 3e, 4). Skipped otherwisepersistence-architect— invoked if20-persistence.mdis missing (depends on 2, 3, 3b, 3c, 3d, 3e, 4, 5) 6b.cache-architect— invoked if00-use-case.md'sFreshnessrow states a tolerance and22-cache.mdis missing (depends on 1, 2, 6; reads 3c, 3e and 5 when present). Skipped when the row readsnone— every case that only writes, and every read that must see the last writetest-architect— invoked if40-tests.mdis missing (depends on 2,3,3b,3c,3d,3e,4,5,6,6b)
Why REST and messaging both run before persistence. The order follows who generates
requirements for whom. REST generates schema requirements — Idempotency-Key on a
creation POST needs the shared key table — and persistence generates none for REST.
With persistence first, the table was discovered after the partial was written, and
persistence ran twice.
Messaging is the same shape and was learned the same way: a transactional outbox needs the
shared outbox_events table, a consumer needs the shared dedupe table, and neither is
visible from the domain partial alone. With messaging after persistence, 20-persistence.md was
written without the relay's retry columns and its partial index, and persistence ran twice
again. Messaging depends only on step 2, so running it before persistence costs nothing —
and persistence then reads both requirement lists, 30-rest.md block 4 and
25-messaging.md § 6, in its first pass.
Jobs sits between them for the same reason. The scheduling technology it picks brings tables
(shedlock, QRTZ_*, BATCH_*), the relay's claim depends on how many instances run the
pass, and the prune job needs a bounded delete — three schema facts invisible to persistence
until 35-jobs.md § 3 and § 6 exist. Jobs itself needs only the use case and messaging's
publication form, so it costs nothing to run first
(@.claude/decisions/0087-jobs-architect-skill.md).
GraphQL runs right after REST and before security, the REST step's pair. Both shape the same input
ports, and when the trigger names both adapters the GraphQL partial reads the REST one, so each
operation names its counterpart. It generates requirements for the steps after it: a batch port the
domain did not declare, the batch statement and an index for persistence, and an access row per
root field and per sensitive field for security — none visible before 31-graphql.md § 9 exists
(@.claude/decisions/0146-graphql-api-architect-skill.md).
Security runs right after REST and GraphQL, for the same two reasons in opposite directions. It needs the
endpoints 30-rest.md fixed — access rules written before them protect a guess — and it can
generate schema requirements: users owned by the application need a credentials store, an
API key needs a key store, both invisible to persistence until 32-security.md § 7 exists.
Ownership is not one of them: it is an invariant domain-modeling already modeled from the
Access row (@.claude/decisions/0112-security-architect-skill.md).
The HTTP client runs right after security and before messaging, for the same reason in one
direction: it generates requirements for the steps after it. A non-idempotent write to another
system needs its idempotency key persisted with the operation, and an unknown outcome needs a
reconciliation pass — a column persistence cannot see and a job scheduling cannot see until
28-http-client.md § 10 exists. It reads the trigger's deadline from 30-rest.md and whether a
filter chain exists from 32-security.md, so it waits for both
(@.claude/decisions/0121-http-client-architect-skill.md).
The AI ports run right after the HTTP client and before messaging, for the same reason: a vector
store needs its table and extensions created by a migration, and the records it mirrors need a
re-index on every change and a first fill — a schema fact for persistence and a trigger for
messaging or jobs, invisible to all three until 29-ai.md § 9 exists. It reads the trigger's
deadline from 30-rest.md, so it waits for REST, and it needs nothing messaging, jobs or
persistence decide (@.claude/decisions/0145-ai-architect-skill.md).
The search projection runs right after the AI ports, before messaging, for the same reason: an
index is fed by the source's change events, rebuilt by a job and keyed on the source's version —
a consumer for messaging, a rebuild for jobs, a version field and an outbox event for persistence,
invisible to all three until 23-search.md § 8 exists. Whether the case has a search index, and on
which engine, is 00-use-case.md's row; this orchestrator never decides it
(@.claude/decisions/0147-document-storage-and-search-architect.md).
The cache runs after persistence, the one step here that generates no requirement for anyone
before it: a cache adds no table and no column. It wraps an outbound port, so it waits for the
adapters behind it — 20-persistence.md's query and 28-http-client.md's call — and it
lists every writer of the data it holds, which only the finished partials name. Tests run
after it, because a cached read owes three tests no other layer asks for
(@.claude/decisions/0144-cache-architect-skill.md).
Design order isn't implementation order. GraphQL is block 4.1, implemented by the conditional
Block G right after Block 3 and before Block S — its resolvers call the same ports as the REST
controllers, and Block S's annotations go on both. Messaging is designed fourth and implemented
sixth: UC-NNN-spec.md keeps messaging as block 6, and the executor's conditional Block M
still runs between REST and Tests. Jobs is block 7, implemented by the conditional Block J
right after Block M — a trigger compiles against the inbound port it calls, so it comes last
among the production blocks. Outbound HTTP is block 3.3, implemented by the conditional Block H
right after Block 2 — an adapter compiles against the outbound port and the domain types, and
nothing upstream compiles against it. AI is block 3.7, implemented by the conditional Block A
right after Block H, for the same reason. Security is block 4.5, implemented by the conditional Block S
right after Block 3 — its annotations and the actor resolution go on the controllers Block 3
just wrote. Cache is block 3.4, implemented by the conditional Block C last among the production
blocks, after Block J — a decorator compiles against the port and needs its delegate, and every
writer that must go through it already exists. The pipeline orders by who needs whose requirements;
the spec orders by what compiles against what.
8. git-publish — invoked at § Approval, per § End of flow, to commit the approved spec
The executor, java-spring-boot-developer, is not a step of this skill: /new-feature-implement
delegates to it over an approved spec, in a clean session.
gof-design-patterns is not a pipeline step, and this orchestrator never invokes it — a
design run cannot reach a build-class skill. Its catalog is still applied at design
time: each design skill above runs its § Design-time use for its own layer and writes a
## Design patterns section into its partial, so the classes a pattern creates are in the
spec the user approves, not chosen by the executor afterwards. The executor implements
those rows, and applies the catalog on its own only for a symptom already on disk
(@.claude/decisions/0089-design-patterns-decided-at-design-time.md, superseding the
executor-side trigger of 0077).
Spec lifecycle
UC-NNN-spec.md opens with a frontmatter carrying one field:
status: |
Written by | When |
|---|---|---|
draft |
this skill | at consolidation |
approved |
this skill | only after the user's explicit approval, § End of flow |
implemented |
java-spring-boot-developer |
with a green build |
implemented-blocked |
java-spring-boot-developer |
with a green build, when the run left an approved use case unreachable end to end — the code is on disk and verified, and a Satisfied by the spec named is not there yet |
A use case folder is open when it has no UC-NNN-spec.md yet, or its spec is draft.
implemented-blocked is not open: a case whose code is on disk, green and committed is not
work in progress, and its satisfier is usually a backlog row nobody is holding this run for.
One /new-feature produces one use case. The next one only starts once the previous
is approved, implemented or implemented-blocked.
An approved spec is immutable. Later cases read approved specs as a read-only
contract and reuse the aggregate already modeled. A change a new case needs in an
approved one goes into the ## Impact on approved use cases section of the new
spec; the executor applies it in code. Don't edit the old spec — write the line in the
altered case's own CHANGELOG.md instead (consolidation step 2).
A case can be nothing but changes. Every component CHANGE, no new use-case class:
it still gets its own UC-NNN, and its slug names the capability added rather than the
trigger, which already belongs to the case being changed
(@.claude/rules/naming.md § Use case identifier).
Decide what the current case needs. Don't defer or anticipate a decision "for the future case" — the future case decides it, in its own impact section.
Entry guardrail
Runs before any skill invocation, any write, and any question. Every check is a command;
the model doesn't interpret the input. Read references/entry-guardrail.md first — the
survey and classification commands, the error rule, and §§ 2–4 (worktree, project, disk) live
there, shared with /new-feature-implement. This section holds only what is this skill's own:
the history check and the input table.
1 · Input table — closed
Run the survey of references/entry-guardrail.md § 1.
The disk is not the history. A folder deleted from the working tree is invisible to
find and still in HEAD, so the next number looks free when it isn't:
git ls-tree -d --name-only HEAD docs/use-cases 2>/dev/null
A UC-NNN that HEAD has and the disk doesn't → stop and report it, before any
skill call. Two things can be true, and only the user knows which: the number was
recycled (the repository would end up with two different UC-NNN, and this run's commit
would delete one while adding the other), or approved work was deleted without being
committed. Name the folder, say which of the two it looks like, and ask. Don't infer the
next free number from the disk alone.
Same comparison for the backlog, and for the same reason — the entry of a deleted case disappears with its folder, and a run that recreates it from scratch writes different text nobody compares:
git diff --stat HEAD -- docs/use-cases/BACKLOG.md 2>/dev/null
Non-empty when a UC-NNN is missing from the disk → show the diff before
use-case-design writes a new entry.
Classify the argument with the commands of references/entry-guardrail.md § 1, then
evaluate in order and stop at the first row that matches:
| # | Input | Result |
|---|---|---|
| 1 | empty | ✅ list the survey above — each case with its status — and stop |
| 2 | EXACT, FOLDER, status draft or (no spec) |
✅ resume: skip use-case-design, generate only the missing partials, then consolidation |
| 3 | EXACT, FOLDER, status approved |
❌ <UC-NNN-slug> is approved — implement it in a clean session — plus the two lines /clear and /new-feature-implement <UC-NNN-slug>. This skill designs; it cannot forward, since /new-feature-implement is manual |
| 4 | EXACT, FOLDER, status implemented or implemented-blocked |
❌ already implemented — describe the change as a new feature |
| 5 | no FOLDER, and the argument's UC-NNN resolves to exactly one folder on disk |
❌ <UC-NNN> is <real-slug>, status <status> — plus the exact command for it: /new-feature <real-slug> for an open case, /new-feature-implement <real-slug> for an approved one. The case exists; the argument named it wrongly |
| 6 | EXACT, no FOLDER, number resolving to zero or several folders |
❌ use case not found; to create one, describe the feature |
| 7 | UC_LIKE but not EXACT (slug plus context, malformed slug, two slugs, a path) |
❌ ambiguous argument |
| 8 | free text, and the survey shows an open case | ❌ <UC folder> is open — resume or approve it first |
| 9 | free text, and no open case | ✅ new: pass the description as is to use-case-design |
| — | anything else | ❌ unrecognized argument |
Row 3 used to implement on the same argument; it is an error row since the implement flow
became its own skill, and it points there instead of guessing
(@.claude/decisions/0135-new-feature-split-spec-and-implement.md). A user typing the old
command loses one line, not a run.
Row 5 is the near miss, and it is an error row, not a success one: it reports and stops.
/new-feature UC-003-spec once answered use case not found while
docs/use-cases/UC-003-initiate-kyc-verification/ sat on disk — literally true, since no folder
carries that name, and practically wrong, since the argument was the basename of the spec file
inside that folder (lessons-learned-014 § 12). The answer names the real slug and the status, so
the next attempt is one line away. It does not resolve the argument and carry on: the
argument was wrong, and guessing which case was meant is exactly what the guardrail forbids.
❌ /new-feature: <reason>.
Usage: /new-feature <feature description> → new use case
/new-feature UC-NNN-slug → resume a draft case
/new-feature → list
/new-feature-implement UC-NNN-slug → implement an approved case
Row 5 keeps that shape and adds the one line that makes it actionable:
❌ /new-feature: UC-003 is UC-003-initiate-kyc-verification, status approved.
Did you mean: /new-feature-implement UC-003-initiate-kyc-verification
Usage: …
2 · Worktree, project, disk
references/entry-guardrail.md §§ 2–4, in that order, before any question or write.
IGNORED and the list of pre-existing changes travel to git-publish at § Approval.
Procedure — 6 steps + consolidation
Execution discipline — the run's cost is turns × context size, not file size:
- No progress messages between steps or tools ("moving to step 3", "domain ok"). Each one is a turn that re-reads the whole conversation. The only report is § Final report.
- Independent writes in one turn — parallel tool calls, not one file per turn.
- Dependency versions come from the build file. Read
pom.xmlbefore resolving any version; no web search for a version the project already declares. - A step's "Output" below is a check the run makes, not a message it prints.
Step 1: Use case (new case only)
Invoke use-case-design via the Skill tool, with the user's description as is.
use-case-design owns the boundary, the number, and the slug. When the description
holds several use cases, it asks the user which one to design, designs that one, and
writes the rest to docs/use-cases/BACKLOG.md. This run continues with the one it
created — never with the others.
Output: docs/use-cases/UC-NNN-<slug>/00-use-case.md — its folder name is the
UC-NNN-<slug> every later step uses.
Short path — checked right after step 1
A trivial case doesn't need five partials. Check all nine against 00-use-case.md
and the approved specs:
| Criterion | Unmet when |
|---|---|
| Aggregate reused from an approved spec | the component table has a NEW aggregate or value object |
| No new table, column, or migration | the component table has a NEW or CHANGE migration or entity |
| No new exception | an error situation has no exception already named in an approved spec |
| No question asked to the user | use-case-design needed AskUserQuestion |
| No freshness tolerance | the Freshness row states a duration — a cache to design |
| No model and no semantic search | the case asks a model to classify, extract or moderate, or finds items by meaning — an AI port to design |
| No GraphQL operation | the Trigger names a GraphQL adapter — the short template has no GraphQL row |
| No search projection, no new document | the Search index row names a projection, or a document (MongoDB) aggregate gets a NEW or CHANGE document, collection or index — the short template has no row for either |
| No new audit level | the Audit row names stamps or history for an aggregate whose level is new or changes — stamps, history tables and the actor to design; the short template has no row for them |
All nine met → skip steps 2–6 and write UC-NNN-spec.md from
templates/feature-spec-short.md.example: every row names its source, an approved spec or
a rule. A row that needs judgment to fill means the case isn't trivial — discard the
short spec and take steps 2–6. One criterion unmet → steps 2–6.
Step 2: Domain (depends on 1)
If 10-domain.md is missing: invoke /domain-modeling UC-NNN.
If it exists: read, validate (four blocks: aggregate, VOs, invariants, ports).
Output: "✅ Domain ready" or a list of gaps.
Step 3: REST (depends on 1,2)
Read the closing phrase of 00-use-case.md's Trigger row. inbound GraphQL adapter alone →
skip this step. Any other phrase, or none (a case written before the phrase existed) → if
30-rest.md is missing: invoke /rest-api-architect UC-NNN.
If it exists: read, validate (eight blocks: resources, DTOs, errors, pagination, idempotency,
personal data, versioning, admission — none unless 00-use-case.md has an Admission row).
Output: "✅ REST ready", "— skipped (GraphQL only)", or gaps.
Step 3g: GraphQL (depends on 1, 2, conditional)
If the Trigger names inbound GraphQL adapter or inbound REST and GraphQL adapters and
31-graphql.md is missing: invoke /graphql-api-architect UC-NNN. No GraphQL adapter in the
phrase → skip this step. If 31-graphql.md exists: read, validate (thirteen blocks: operations,
schema, inputs and payloads, pagination, batch loads, project setup, error map, personal data,
requirements to other partials, contract test cases, declared dependencies, configuration,
deferred).
Every list that grows is a connection with a ceiling, every child field that costs I/O is a batch
load, and the project setup is decided or inherited — a § 6 with neither is a gap. § 9 is what steps
2 (a batch port, through consolidation), 3b and 5 read; § 11 is the only list that entitles the
executor to add the GraphQL starter to pom.xml; § 10 is what step 6 turns into tests.
Output: "✅ GraphQL ready", "— skipped (no GraphQL trigger)", or gaps.
Step 3b: Security (depends on 1, 2, 3, 3g, conditional)
Read 00-use-case.md's Access row, and whether the project already has a filter chain
(grep -rl "SecurityFilterChain" --include='*.java' src/main). If 32-security.md is missing,
invoke /security-architect UC-NNN when any holds:
Access |
Filter chain on disk | Why it runs |
|---|---|---|
| a role, a group, a scope, or the owner | any | this case's rules — and the setup when there is none |
| authenticated | none | first secured case: the project-wide setup |
| public | present | a permitAll needs its recorded reason |
Otherwise skip: public in an unsecured project, or authenticated behind a chain that already
denies by default — the spec's security block says which. A GraphQL trigger is not a skip when
31-graphql.md § 9 asks for a field-level row: a sensitive field narrower than its operation is
this case's rule whatever the Access row says. An 00-use-case.md with an HTTP
trigger and no Access row (written before the row existed) is not a skip: invoke it, it asks.
If 32-security.md exists: read, validate (eleven blocks: access per endpoint, mechanism,
authorities, project-wide setup, ownership, failure responses, schema requirements, declared
dependencies, configuration, contract test cases, deferred).
§ 7 is what step 5 reads; § 8 is the only list that entitles the executor to add a security
starter to pom.xml; § 10 is what step 6 turns into tests.
Output: "✅ Security ready", "— skipped (<which row>)", or gaps.
Step 3c: Outbound HTTP (depends on 1, 2, conditional)
Read 10-domain.md § Ports. If it declares a port of kind external HTTP and
28-http-client.md is missing: invoke /http-client-architect UC-NNN. No such port → skip
this step. An output port with no kind is not a skip: stop and ask domain-modeling for it —
a kind left out is how an external call reaches the executor with nobody having decided its
timeout. A port of that kind whose 00-use-case.md has no External calls row (written
before the row existed) is not a skip either: invoke it, it asks. If 28-http-client.md exists:
read, validate (eleven blocks: operations, client, engine and pool, outbound authentication,
retry and resilience, project-wide setup, configuration, declared dependencies, contract test
cases, requirements to other partials, deferred).
§ 10 is what steps 4b and 5 read — the stored idempotency key, a reconciliation pass, the
security impact of the OAuth2 client starter; § 8 is the only list that entitles the executor to
add a client, engine or resilience dependency to pom.xml; § 9 is what step 6 turns into tests.
Output: "✅ Outbound HTTP ready", "— skipped (no external HTTP port)", or gaps.
Step 3d: AI (depends on 1, 2, conditional)
Read 10-domain.md § Ports. If it declares a port of kind LLM or vector store and
29-ai.md is missing: invoke /ai-architect UC-NNN. No such port → skip this step. A port
of kind LLM whose return type has no "could not decide" value, or no review state it leads to,
is not a skip: stop and ask domain-modeling for it — the adapter would have nowhere to put an
answer it cannot use. If 29-ai.md exists: read, validate (twelve blocks: AI ports, provider and
models, prompts and output, data sent, vector store, failure and retry, observability, test
cases, requirements to other partials, declared dependencies, configuration, deferred).
Every timeout in § 6 is below the trigger's deadline, and every field of § 4 sent in clear names
its receiver. § 9 is what steps 4, 4b and 5 read — the store's migration, a re-index trigger, an
ingestion job; § 10 is the only list that entitles the executor to add a Spring AI dependency to
pom.xml; § 8 is what step 6 turns into tests.
Output: "✅ AI ready", "— skipped (no AI port)", or gaps.
Step 3e: Search (depends on 1, 2, conditional)
Read 00-use-case.md's Search index row. If it names a projection and its engine and
23-search.md is missing: invoke /search-architect UC-NNN. none, or a spec older than the
row → skip this step. A row that names a projection but no engine is not a skip: stop and send the
case back to use-case-design, which asks the one factual question — this orchestrator never picks
an engine. If 23-search.md exists: read, validate (eleven blocks: projection, index, queries,
writes, rebuild, lag, failure, requirements to other partials, declared dependencies,
configuration, deferred).
§ 6's lag is at most the case's Freshness; a larger one is a divergence, not a refresh to add.
§ 8 is what steps 4, 4b and 5 read — the indexer's consumer, the rebuild job, the source's version
and change event; § 9 is the only list that entitles the executor to add a search dependency to
pom.xml; § 3 and § 4 are what step 6 turns into tests.
Output: "✅ Search ready", "— skipped (no search index)", or gaps.
Step 4: Messaging (depends on 2, conditional)
Read 10-domain.md's Events block. If it names external (Kafka) delivery for the
event and 25-messaging.md is missing: invoke /messaging-architect UC-NNN. If
the event is absent or stays in-process, skip this step — not every use case needs it.
If 25-messaging.md exists: read, validate (nine blocks: topic and delivery, producer,
consumer and idempotency, retry/DLQ, configuration, schema requirements, declared
dependencies, personal data, deferred).
A missing § 6 is a gap, not an omission: it's the list step 5 reads. none is a valid
value there and means publication Form A with no consumer dedupe table to build. § 7 is
the same shape for build dependencies: it is the only list the executor may act on when it
writes pom.xml, so a missing one leaves a needed dependency with no owner
(lessons-learned-013 § 10). This step is not the only check on it — a run that reaches
consolidation without taking this step is exactly how two lists went missing and a spec was
approved anyway, so consolidation gates the same thing for every path.
Output: "✅ Messaging ready", "— skipped (no external delivery)", or gaps.
Step 4b: Jobs (depends on 1, 3d, 3e, 4, conditional)
Invoke /jobs-architect UC-NNN if 35-jobs.md is missing and at least one holds:
25-messaging.md § 2 chose Form B, 00-use-case.md's trigger is a schedule, a
recurring run, a batch or a background job, 28-http-client.md § 10 asks for a reconciliation
pass, 29-ai.md § 9 asks for an ingestion or re-index job, 23-search.md § 8 asks for a rebuild job, 00-use-case.md's Audit row names history and the project has no history prune job yet, or a partial's Deferred block names a scheduled job. None holds → skip this step. If 35-jobs.md exists: read, validate (nine blocks: jobs,
technology, coordination, execution guarantees, observability, schema requirements, declared
dependencies, configuration, deferred).
A Form B case with no 35-jobs.md is a gap, not a skip: the relay would have no schedule and
the outbox no prune — the exact state lessons-learned-014 § 9 found. § 3's replica count and
§ 6's requirements are what step 5 reads; § 7 is the only list that entitles the executor to
add a scheduling dependency to pom.xml.
Output: "✅ Jobs ready", "— skipped (no scheduled work)", or gaps.
Step 5: Persistence (depends on 1,2,3,3g,3b,3c,3d,3e,4,4b)
If 20-persistence.md is missing: invoke /persistence-architect UC-NNN. It reads
every schema requirement list in the same pass — 30-rest.md block 4 (the idempotency
table among them) when step 3 ran, when step 3g ran 31-graphql.md § 9 (one statement per batch
port, bounded by § 6's max batch, and the index each connection's order needs), when step 3b ran 32-security.md § 7 (a credentials or API-key store),
when step 3c ran 28-http-client.md § 10 (a stored idempotency key, an unknown-outcome state),
when step 3d ran 29-ai.md § 9 (a vector store's table, its extensions and its index),
when step 3e ran 23-search.md § 8 (the source's version and its change event in the outbox),
when step 4 ran 25-messaging.md § 6 (the shared outbox table, the
dedupe table), and when step 4b ran 35-jobs.md § 3 and § 6 (the replica count its claim
strategy must meet, the scheduling tables, the prune's bounded delete). If it exists: read, validate (seven blocks: schema, mapping, adapter and
ports, migrations, configuration, declared dependencies, deferred). § 6 is the persistence twin
of 25-messaging.md § 7,
and the same rule holds: it is the only list that entitles the executor to touch pom.xml —
and consolidation checks it again, for the paths that never take this step.
Output: "✅ Persistence ready" or gaps.
Step 5b: Cache (depends on 1, 2, 5, conditional)
Invoke /cache-architect UC-NNN if 22-cache.md is missing and 00-use-case.md's
Freshness row states a tolerance — a duration an answer may be old. The row reads none, or
the case predates the row → skip this step: no tolerance, no cache
(@.claude/rules/caching.md § Boundary). If 22-cache.md exists: read, validate (ten blocks:
cached reads, provider, expiry and size, invalidation, failure and load, serialization,
observability, declared dependencies, configuration, deferred).
Every expiry in § 3 is at most the tolerance it serves — minus 23-search.md § 6's lag when the
cached read is a search projection — and every writer of the cached data
has a § 4 row — a writer named in another approved case's Components table and missing from
§ 4 is a gap. § 8 is the only list that entitles the executor to add a cache dependency to
pom.xml; § 1 and § 4 are what step 6 turns into tests.
Output: "✅ Cache ready", "— skipped (no freshness tolerance)", or gaps.
Step 6: Tests (depends on 1,2,3,3g,3b,3c,3d,3e,4,5,5b)
If 40-tests.md is missing: invoke /test-architect UC-NNN (design mode).
If it exists: read, validate (five blocks: pyramid, cases, fixtures, coverage, test dependencies).
When step 3b ran, every case of 32-security.md § 10 has a test row — a missing one is a gap.
When step 3g ran, every case of 31-graphql.md § 10 has a test row at the level it names, and the
schema snapshot test exists — a missing one is a gap, and so is an access case placed in the
GraphQL slice, where no filter chain runs.
When step 3c ran, every case of 28-http-client.md § 9 has a test row — a missing one is a gap.
When step 3d ran, every case of 29-ai.md § 8 has a test row at the level it names — a missing
one is a gap, and so is any row that calls a real model.
When step 5b ran, every cached read of 22-cache.md § 1 has three test rows — a second read
not reaching the source, an eviction by every writer of § 4 that goes through the port, and
two callers never sharing an entry when the key names the caller (@.claude/rules/caching.md
§ Tests). A missing one is a gap.
Output: "✅ Tests ready" or gaps.
Consolidation (after 1,2,5,6 ✅, and 3 or 3g — steps 3, 3g, 3b, 3c, 3d, 3e, 4, 4b and 5b conditional)
If all specs that apply exist and validate (REST only when step 3 wasn't skipped, GraphQL only when step 3g wasn't, security only when step 3b wasn't skipped, outbound HTTP only when step 3c wasn't, AI only when step 3d wasn't, search only when step 3e wasn't, messaging only when step 4 wasn't, jobs only when step 4b wasn't, cache only when step 5b wasn't):
Resolve divergences before consolidating. The partials are written by different skills, and downstream corrects upstream:
30-rest.mdfixes the path and status that00-use-case.mdhad sketched,20-persistence.mdfixes the key that the domain described in prose. Stacking both versions and explaining in a note which one wins pushes the work onto the reader — and the note ends up two hundred lines away from where it matters.Walk through every partial in the folder and, for each fact that appears in more than one with different values, apply this precedence:
Fact Who wins HTTP path, verb, status, body shape 30-rest.md— except the 401 and 403 rows, belowGraphQL root fields and the port each calls, types, fields and nullability, inputs, payloads and userErrors, connections and their ceilings, batch loads, the GraphQL error map, the project's GraphQL limits31-graphql.md— except who may read each field, below. A batch port it asked for becomes10-domain.md's port by consolidation, with31-graphql.mdas who asked; the batch statement and its index are20-persistence.md'sWho may call each endpoint, GraphQL root field and sensitive field, the authentication mechanism, the claims-to-authorities mapping, the permitAlllist and its reasons, the 401 and 403 rows, CORS, OpenAPI and Actuator exposure, where the controller reads the actor from32-security.md. The actor field, the owner field and the ownership invariant stay10-domain.md's; an owner-onlyAccesswhose domain partial has no actor is not settled by precedence: stop and askTable, column, key, index, migration 20-persistence.md— including every table or column another partial asked for: the requirement is born in30-rest.mdblock 4 or25-messaging.md§ 6, the final form (name, type, nullability, index, migration) is always this one'sTopic, serialization, delivery guarantee, consumer retry and DLQ 25-messaging.mdOutbox table, its columns, the claim query, and the values the columns encode (batch size, backoff, attempt ceiling, retention window, the prune's statement) 20-persistence.md— the whole table is its territory.25-messaging.mddeclares the guarantee those values have to deliver, never the columns; a § 6 row naming columns is reported as a divergence and the guarantee is what carries overClient, engine and pool, timeouts, the retrying layer and its policy, breaker and bulkhead, outbound authentication, the failure table of each remote operation 28-http-client.md. The outbound port, its domain types, the idempotency key field and the unknown-outcome state stay10-domain.md's; the column and the reconciliation schedule are persistence's and jobs's, as for every requirementScheduling technology, a job's trigger and cadence (the relay's poll interval included), coordination across instances and the replica count, overlap and missed-run policy, on/off property, job metrics, the prune job 35-jobs.md. A claim strategy in20-persistence.mdthat does not meet35-jobs.md§ 3's replica count is not settled by precedence — it is a guarantee dropped by a shape decision: stop and askProvider and model of each AI port, its prompt resources and answer type, what each unusable answer becomes, the fields sent to the provider, the store and its embedding model, the timeout and retrying layer of each AI port 29-ai.md. The port, its "could not decide" value and the review state stay10-domain.md's; a timeout above the trigger's deadline, or a personal-data field sent in clear without a named receiver, is not settled by precedence: stop and askThe search document and its mapping, the index version and alias, the query and its cursor, the indexer's write rules, the rebuild's alias swap, the lag the projection consumes, the search dependency 23-search.md. Whether the case has a search index, its engine and the freshness tolerance stay00-use-case.md's; a lag larger than the tolerance is not settled by precedence: stop and askStorage family of each aggregate 00-use-case.md— never a design partial, and never this orchestrator. An aggregate the code already stores in the other family is not settled by precedence: stop and askAudit level of each aggregate 00-use-case.md— never a design partial. An aggregate the code already audits at a higher level than the row asks is not settled by precedence (a history cannot be switched off without losing it): stop and askWhich reads are cached, each cache key, the cache provider, expiry and size per cache, the writers that must evict, cache serialization and metrics 22-cache.md. The freshness tolerance stays00-use-case.md's; an expiry longer than it is not settled by precedence — it serves answers older than the business allowed: stop and askAggregate name, value object, port, event 10-domain.mdException class and errorCode10-domain.mdUse case boundary, invariants, error situations 00-use-case.mdName and level of each test 40-tests.mdA design pattern and the classes it creates The partial of the layer those classes live in. Two partials adopting different patterns for the same class is not settled by precedence: stop and ask UC-NNN-spec.mdcarries a single value per fact — the winner — across all blocks, including those that had inherited the old value. The discarded versions go into a## Resolved divergencessection at the end, one line each: fact, discarded value, adopted value, partial that decided. The executor reads one truth; the audit trail is still there.A divergence the table doesn't resolve — two facts from the same owner, or a business-rule contradiction — stops the pipeline and asks. Don't invent it or stack it.
A downstream partial never edits an upstream one's fact — it asks for it. A requirement born downstream and landing upstream —
20-persistence.mdbounding the producer's send time so the outbox lease outlives any send, a value25-messaging.mdowns — travels as a named requirement in the downstream partial, and this step resolves it like any other divergence: the owner's block inUC-NNN-spec.mdcarries the new value, and## Resolved divergencesrecords who asked. Carried silently into the owner's block, it is a fact with two authors and no record of the second.And one shape the table resolves only in appearance: a column decision that changes behaviour.
20-persistence.mdwins on the column, always — but when dropping a column also drops a guarantee25-messaging.mddeclared (nonext_attempt_at, so per-row exponential backoff becomes a fixed repoll), the winner is not the answer. That is a divergence the table doesn't resolve: stop and ask, and record which guarantee the chosen shape delivers. A precedence rule written for table shape must never be what settles a behaviour.Consolidate into a single file:
UC-NNN-spec.md, withstatus: draft, by reference- Each block holds only the final decisions — one value per fact — and the path of the partial that details it. Never copy a partial's tables, SQL, or code: a copied consolidation doubled the output of a real run and added nothing the partial lacked
- Structure: 5 blocks (use case, domain, persistence, REST, tests) —
## 4 RESTreadsnone — GraphQL onlywhen step 3 was skipped — plus## 4.1 GraphQLonly when step 3g ran,noneotherwise, plus a 6th (messaging) only when step 4 wasn't skipped, a 7th (jobs) only when step 4b wasn't, and the security block (## 4.5 Security) only when step 3b wasn't — when it was, that block readsnonewith the skip row of step 3b, so "covered by deny-by-default" is a recorded fact and not a missing block - The outbound HTTP block (
## 3.3 Outbound HTTP) only when step 3c ran;noneotherwise - The cache block (
## 3.4 Cache) only when step 5b ran;noneotherwise - The AI block (
## 3.7 AI) only when step 3d ran;noneotherwise - The search block (
## 3.8 Search) only when step 3e ran;noneotherwise ## Impact on approved use cases: every row from the same section of each partial — "none" when all are empty## Design patterns: every row from the same section of each partial, with the partial that decided it — "none" when all are empty. A partial that applies must carry the section, or consolidation stops: absence is notnone, the same test as the declared-dependency lists below. A row whose force is neither a spec line nor afile:lineis not consolidated — the pipeline stops and asks- A row that adds a precondition must name its satisfier, or consolidation stops. Any
row making an earlier case require a state it did not require before — a status, a flag, a
related record — carries the
Satisfied bycolumn00-use-case.mdalready asks for: an approvedUC-NNN, this case, or a backlog row by itsBL-NN. Missing or vague, the pipeline stops and asks; it is not filled in by inference. AUCnumber is not a valid answer for a backlog case — it has none until it is designed, and two reports of a real run inventedUC-004because the sentence needed a name andBACKLOG.mdhad none to give (lessons-learned-014 § 7). Where the satisfier is a backlog row, the consolidated spec says outright that the earlier case is unreachable end to end until that one ships, and the final report repeats it, citing the sameBL-NN— a use case that answers 422 on every real call is not a detail the reader should have to find in a test fixture (lessons-learned-013 § 5) - A partial that applies must carry its declared-dependency section, or consolidation
stops.
20-persistence.md§ 6 always;31-graphql.md§ 11 whenever step 3g ran;32-security.md§ 8 whenever step 3b ran;28-http-client.md§ 8 whenever step 3c ran;29-ai.md§ 10 whenever step 3d ran;23-search.md§ 9 whenever step 3e ran;25-messaging.md§ 7 whenever step 4 ran;35-jobs.md§ 7 whenever step 4b ran;22-cache.md§ 8 whenever step 5b ran;40-tests.md§ 5 always. The valuenoneis legitimate and common — most cases need no new dependency — but absence is notnone: one says the design skill decided nothing was needed, the other says nobody looked, and the executor cannot tell them apart. Steps 4 and 5 validate the same thing; they are conditional, and a spec once reachedapprovedwith both lists missing because its partials had been written in earlier runs (lessons-learned-014 § 6). The executor then added a dependency topom.xmlby inference — a defensible one, and precisely the decision this list reserves for the design skill. Consolidation is the block every run passes, which is why the check belongs here as well, exactly likeSatisfied byabove - A partial that needs a container must carry
## Compose services, or consolidation stops.20-persistence.mdalways;25-messaging.mdwhenever step 4 ran;22-cache.mdwhenever step 5b ran;29-ai.mdwhenever step 3d ran;23-search.mdwhenever step 3e ran.noneis valid (H2, no broker) and absence is not. Every row goes into the spec's## Infrastructurewith the partial that decided it, shaped by@.claude/skills/docker-architect/references/compose-service-decision.md. Without it the implement run, in a session that never saw this one's report, has nothing to add and nothing to name — the broker of issue #119 - A personal-data field crossing the process boundary in clear carries a recorded
decision, or consolidation stops.
25-messaging.md§ 8,30-rest.md§ 6,31-graphql.md§ 8 and29-ai.md§ 4 each list the fields of the payload, the response body and the GraphQL output types that match@.claude/rules/logging.md§ Masking candidates, with the form chosen. Afull valuerow without a named receiver and a reason is not consolidated: the pipeline stops and asks, and it is not filled in by inference.noneis a valid value and absence is not one. Until now this was a line in the final report — detection after the spec is approved, after the code is written and after the commit, and in the observed run it appeared there only because the executor volunteered it, for a CPF already published in clear on a topic (lessons-learned-014 § 8,@.claude/rules/personal-data.md§ In transit) - A deferred row leaves the run with an owner, or consolidation stops. Each partial's
Deferredblock carries what it decided not to do, the norm that requires it, and an intended owner.checklist→ add the item to this spec's checklist; the run implements it.backlog→ consolidation appends the row todocs/use-cases/BACKLOG.mdand assigns itsBL-NN, then writes that id into this spec's## Out of scopewith the consequence spelled out: what the project does not guarantee until that row ships. Consolidation is the only writer of a backlog row inside a feature run — two partials each computing "highest plus one" would issue the sameBL-NN. An item whose norm makes it mandatory and whose owner is missing or vague stops the pipeline and is not inferred: a real run decided a 7-day retention foroutbox_events, left a commentedDELETEin the migration, keptapp.outbox.prune-afterout ofapplication.ymlon purpose, and handed the job to nobody, over a table whose payload carries personal data (lessons-learned-014 § 9,@.claude/rules/personal-data.md§ At rest) - Every case named in that section gets a line in its own
CHANGELOG.md, atdocs/use-cases/UC-XXX-<slug>/CHANGELOG.md— created on the first change, appended afterwards. One line: date, theUC-NNNmaking the change, and what changed (2026-09-27 · UC-003 · RegisterCustomerUseCase now emits CustomerRegistered). The approved spec stays untouched, which is exactly why the log is a separate file (@.claude/rules/naming.md§ Use case identifier). Without it, nobody reading the altered case ever learns it changed — immutability keeps the text and loses the history - Order: implementation order (depends-on)
- Every
permitAllcarries its reason, or consolidation stops.32-security.md§ 1 lists the public paths of the project after this case, each with a reason; a public row with none, or a first secured case whose## Impact on approved use casesdoes not say what happens to the endpoints earlier cases published without a chain, is not consolidated — deny by default turns them into 401 on the next deploy, and nobody chose that (@.claude/rules/authorization.md§ Default access) - Recipient:
java-spring-boot-developeragent — a spec with § 4.1 runs the executor's conditional Block G (steps G1-G3, right after Block 3 and before Block S), which generates the schema file, the GraphQL controllers and records, and — the first time — the GraphQL setup from31-graphql.md; a spec with § 4.5 runs the executor's conditional Block S (steps S1-S3, right after REST), which generates the filter chain, the mechanism wiring, the method-security annotations and the actor resolution from32-security.md; a spec with § 3.3 runs the executor's conditional Block H (steps H1-H3, right after Block 2), which generates the outbound adapters, the shared translator and the engine configuration from28-http-client.md; a spec with § 6 runs the executor's conditional Block M (steps M1-M4, between REST and Tests), which generates the Kafka producer/consumer adapters from25-messaging.md; a spec with § 7 runs Block J (steps J1-J3, right after Block M), which generates the scheduling wiring and triggers from35-jobs.md; a spec with § 3.4 runs Block C (steps C1-C3, right after Block J), which generates the cache wiring and the port decorators from22-cache.md. None touches the fixed 19-item checklist
Check whether the architecture tests can now be turned on. The bootstrap doesn't install ArchUnit or the coverage gate by design: a
checkover an empty set proves nothing. After the first feature that condition no longer holds, and nothing in the pipeline was watching for it.grep -rl "ArchRule\|ArchTest" --include='*.java' src/test/ 2>/dev/null | head -1 find src/main/java -name '*.java' ! -name 'package-info.java' | head -1Second command with a result and the first without: the project now has business classes and still has no boundary enforcement outside the editor. In
single-modulethe compiler doesn't enforce anything either, so there's no verification at all. Propose runningtest-architectin setup mode — propose, don't run it: detection is mechanical, authorization is the user's.
End of flow
Every branch below ends in an explicit instruction. None of them runs git outside
git-publish.
Design and implementation never share a session. This skill designs; a run that
consolidated a spec ends at § Approval. An approved spec is implemented only by
/new-feature-implement UC-NNN-<slug>, typed after /clear. The executor never inherits the
conversation, but the orchestrator's thread does: every hand-back it receives, every group it
launches and the git-publish after them would otherwise run at the 250–370k context the
design phase leaves behind
(@.claude/decisions/0130-executor-split-by-block-group-implement-in-clean-session.md). The
second half of the pipeline lives in its own skill, so an implement run never loads this body
(@.claude/decisions/0135-new-feature-split-spec-and-implement.md).
Approval — asked on every run that consolidated a spec
AskUserQuestion: Approve UC-NNN-spec.md / Keep as draft.
Keep as draft → report the spec path and the resume command (
/new-feature UC-NNN-<slug>), and stop. No git: a draft isn't a deliverable.Approve → change the spec's line to
status: approved, then invokegit-publishvia theSkilltool, with contextdocs(UC-NNN-<slug>): approved specanddocs/use-cases/UC-NNN-<slug>/plusdocs/use-cases/BACKLOG.mdas the paths to stage. Nothing else: a design-only run writes nothing outsidedocs/, and the guard is what makes that true rather than intended. Then the final report, which ends with the two lines to type next:/clear /new-feature-implement UC-NNN-<slug>What used to be staged here —
docker-compose.ymlanddocker/init/**, when the pipeline chaineddocker-architect— is no longer written during the run at all. Every## Infrastructurerow goes into the final report: amaterializerow is added by/new-feature-implement, and apendingrow carries the/docker-architectinvocation the user runs. An unmentioned service is how akafkaservice went orphan once (lessons-learned-010.md§ 7), and the fix is naming it, not writing the file mid-design.
Final report
Last message of the run, and the only report: the spec path and status, the backlog
entries left for later (if any), every ## Infrastructure row of the spec — each
compose service with its decision: materialize (the implement run adds it), pending (with
the /docker-architect command that adds it), external (with its address), 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") — never a UC number, which a backlog row does not
have — every item a partial deferred, with the owner it left it to (a checklist item, or a
BL-NN, 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") — now a repeat of what § 8 and § 6 of the
partials already recorded, not the first time anyone asks — three findings a reader must not have to
reconstruct from a fixture comment or a Javadoc sentence — what git-publish
did, and the next commands. After § Approval those are /clear and
/new-feature-implement UC-NNN-<slug>; after Keep as draft, /new-feature UC-NNN-<slug>.
Template: UC-NNN-spec.md
Lives at .claude/skills/new-feature/templates/feature-spec.md.example; the short path
uses templates/feature-spec-short.md.example.
Structure (5 blocks, implementation order — plus outbound HTTP, cache, GraphQL, security, messaging and jobs when they apply):
- Frontmatter:
status: - Block 1: Use case
- Block 2: Domain model (aggregate, VOs, invariants, ports, events)
- Block 3: Persistence (JPA mapping, migrations, transactions)
- Block 3.3 (conditional): Outbound HTTP (client and engine per dependency, timeouts, retrying layer, authentication, project-wide setup NEW/REUSE) — present when step 3c ran; "none" otherwise. Implemented by the executor's Block H, right after Block 2
- Block 3.4 (conditional): Cache (cached reads and keys, provider, expiry per cache, writers that evict) — present only when step 5b ran; "none" otherwise. Implemented by the executor's Block C, last among the production blocks
- Block 3.5 (conditional): Messaging (producer/consumer, delivery semantics, retry/DLQ)
— present only when
10-domain.mdnamed external delivery for the event; "none" otherwise. See the known gap above — the executor doesn't consume this block yet - Block 3.6 (conditional): Jobs (technology, triggers, coordination, replica count) — present only when step 4b ran; "none" otherwise. Implemented by the executor's Block J
- Block 4: REST API (resources, DTOs, errors, pagination, idempotency) —
none — GraphQL onlywhen step 3 was skipped - Block 4.1 (conditional): GraphQL (root fields and ports, connections, batch loads, errors as data, project setup NEW/inherited) — present when step 3g ran; "none" otherwise. Implemented by the executor's Block G, right after Block 3
- Block 4.5 (conditional): Security (mechanism, access per endpoint,
permitAlllist, ownership, setup NEW/REUSE) — present when step 3b ran; otherwisenonewith the skip row. Implemented by the executor's Block S, right after Block 3 - Block 5: Tests (pyramid, critical cases, coverage, checklist)
- Impact on approved use cases ("none" when empty)
- Final section: Resolved divergences (empty when there were none)
See templates/feature-spec.md.example for the full shape.
References
- D14 — ordered pipeline: use-case → domain → persistence → REST → tests → executor. Order
of REST and persistence swapped by
0037. - D17 — pipeline skills without
disable-model-invocation(so/new-featurecan call them). - D20 —
/new-featuredeferred;java-spring-boot-developerexecutor; scope: both. - D22 —
/new-featuredesign (this record). @.claude/decisions/0032-messaging-architect-skill.md—messaging-architectchained as a conditional step, same pattern aspersistence-architect/rest-api-architect.@.claude/decisions/0144-cache-architect-skill.md—cache-architectchained as step 5b, after persistence, only when the use case states a freshness tolerance.@.claude/decisions/0146-graphql-api-architect-skill.md—graphql-api-architectchained as step 3g, the REST step's pair, when theTriggernames a GraphQL adapter; step 3 skipped when it names GraphQL alone.@.claude/decisions/0130-executor-split-by-block-group-implement-in-clean-session.mdand@.claude/decisions/0135-new-feature-split-spec-and-implement.md— design and implement never share a session; the implement flow is/new-feature-implement, a skill of its own.@.claude/decisions/0037-lessons-learned-005-remediation.md— closed input table, one use case per run, spec lifecycle, nosrc/and no git outsidegit-publish.- Invariant 2 (
@CLAUDE.md) — single owner. The orchestrator ownsUC-NNN-spec.md;use-case-designowns number and slug. - Invariant 8 (
@CLAUDE.md) — specs via skills; code via executor.
Entry into generated projects
Step 6.6 writes the skills into the project. /new-feature travels the same way — the user runs
/new-feature <feature description> to design a new feature.
No adaptation needed — skills already use relative paths.