@dtlabs/ai-toolkit 0.17.5 → 0.18.0

package/CHANGELOG.md

@@ -1,4 +1,25 @@
 ## 0.1.4 (2026-07-21)
+## [0.18.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.17.5...v0.18.0) (2026-10-19)
+
+
+### Features
+
+* **planning-pipeline:** split Work Breakdown and Requirements generation into skeleton+per-item passes ([f7e7b66](https://github.com/dtlab-tech/ai-toolkit/commit/f7e7b66efe94a860bbd867402a250c5d92d56f4a))
+* **pm-phase1/pm-phase2:** split-only document generation with on-demand assembly ([40d8700](https://github.com/dtlab-tech/ai-toolkit/commit/40d87007d2125789c7943348ee4000467bffc882))
+* **pm-phase1:** split Tech-Spec generation into skeleton+per-component passes ([a42a83c](https://github.com/dtlab-tech/ai-toolkit/commit/a42a83c9413275888c7e0fa5bfae80a165da3d71))
+* **pm-phase1:** tag Tech-Spec File Inventory with AC IDs and extend the traceability matrix ([4a15510](https://github.com/dtlab-tech/ai-toolkit/commit/4a15510c4d2da110445976d1b9586b6d45252c6f))
+* **pm-phase2:** render an AC-to-Task traceability matrix at Gate 2 ([d975942](https://github.com/dtlab-tech/ai-toolkit/commit/d9759423771454a8d677f747bc0d4fc1e00de375))
+* **templates:** move the FTR-020 doc templates into the toolkit and make generation use them ([de7ffca](https://github.com/dtlab-tech/ai-toolkit/commit/de7ffca19b42ae324d8c8f8460cc9aeda23d8298))
+* traceability matrix, template relocation, split-only doc generation (FTR-025) ([bf17caa](https://github.com/dtlab-tech/ai-toolkit/commit/bf17caa1517fa28a4f28b3efb44f7a327661e184))
+
+
+### Bug Fixes
+
+* **pm-phase1:** host-compute each use case's Related Business Rules/Acceptance Criteria ([507ecfa](https://github.com/dtlab-tech/ai-toolkit/commit/507ecfa94cb8094049a3543dbf44d47c2ea38f80))
+* **tech-spec-assembler:** make the component Change/Tests heading scan fence-aware ([90af9ca](https://github.com/dtlab-tech/ai-toolkit/commit/90af9ca0585d3280ee12a97d3f745bae7de5fe69))
+* **wb-graph-checks:** scope AC-task validation by a phase's own sourceUC, not its ID ([fab14cb](https://github.com/dtlab-tech/ai-toolkit/commit/fab14cbcb2f4fc180e5b2bb234dad25a5d7a2b61))
+* **wbs:** wire the FTR-020 phase-detail template into real WB generation; fix a second sourceUC-drop ([54ed68e](https://github.com/dtlab-tech/ai-toolkit/commit/54ed68e5921e271a8b6ba4c54b0db748303648b1))
+
 ## [0.17.5](https://github.com/dtlab-tech/ai-toolkit/compare/v0.17.4...v0.17.5) (2026-10-13)
 
 

package/lib/agent-registry.js

@@ -168,6 +168,19 @@ const CATALOG = [
     deprecationTarget:     null,
     platforms:             ['claude'],
   },
+  {
+    agentId:               'gaia.agent.planner.requirements-use-case',
+    nativeNames:           { claude: 'gaia-generate-requirements-use-case' },
+    relativeInstallPath:   '.claude/agents/gaia-generate-requirements-use-case.md',
+    role:                  'planner',
+    type:                  'requirements',
+    authorisedPhases:      ['planning'],
+    allowedPipelines:      ['implement-feature'],
+    minimumToolkitVersion: '0.13.0',
+    deprecated:            false,
+    deprecationTarget:     null,
+    platforms:             ['claude'],
+  },
   {
     agentId:               'gaia.agent.planner.tech-spec',
     nativeNames:           { claude: 'gaia-generate-tech-spec' },
@@ -181,6 +194,19 @@ const CATALOG = [
     deprecationTarget:     null,
     platforms:             ['claude'],
   },
+  {
+    agentId:               'gaia.agent.planner.tech-spec-component',
+    nativeNames:           { claude: 'gaia-generate-tech-spec-component' },
+    relativeInstallPath:   '.claude/agents/gaia-generate-tech-spec-component.md',
+    role:                  'planner',
+    type:                  'tech-spec',
+    authorisedPhases:      ['planning'],
+    allowedPipelines:      ['implement-feature'],
+    minimumToolkitVersion: '0.13.0',
+    deprecated:            false,
+    deprecationTarget:     null,
+    platforms:             ['claude'],
+  },
   {
     agentId:               'gaia.agent.planner.work-breakdown',
     nativeNames:           { claude: 'gaia-generate-work-breakdown' },
@@ -194,6 +220,19 @@ const CATALOG = [
     deprecationTarget:     null,
     platforms:             ['claude'],
   },
+  {
+    agentId:               'gaia.agent.planner.work-breakdown-task',
+    nativeNames:           { claude: 'gaia-generate-work-breakdown-task' },
+    relativeInstallPath:   '.claude/agents/gaia-generate-work-breakdown-task.md',
+    role:                  'planner',
+    type:                  'work-breakdown',
+    authorisedPhases:      ['planning'],
+    allowedPipelines:      ['implement-feature'],
+    minimumToolkitVersion: '0.13.0',
+    deprecated:            false,
+    deprecationTarget:     null,
+    platforms:             ['claude'],
+  },
   {
     agentId:               'gaia.agent.planner.validate-feature-docs',
     nativeNames:           { claude: 'gaia-validate-feature-docs' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtlabs/ai-toolkit",
-  "version": "0.17.5",
+  "version": "0.18.0",
   "description": "AI Toolkit — reusable agents and procedures for developers to build AI-powered applications.",
   "files": [
     "docs/",

package/src/claude/agents/gaia-generate-requirements-use-case.md

@@ -0,0 +1,97 @@
+---
+name: gaia-generate-requirements-use-case
+description: "Generates one use case's full detail (flows, postconditions) from its index-table row. Input: UC row + compact sibling index + feature.md"
+model: haiku
+tools: Read, Glob, Grep
+---
+
+# Generate One Use Case's Detail
+
+Given one use case's index-table row (ID, Title, Actor, Priority), the compact index of every
+other use case in this feature, and `feature.md`, produce that use case's full detail: the field
+table plus Main flow, Alternative flows, Error flows, and Postconditions — exactly the Section 2
+content `gaia-generate-requirements` produced inline before this feature (FTR-021) split it out
+into one bounded call per use case.
+
+## Input
+
+The host supplies, in the dispatch prompt:
+1. This use case's own index-table row, verbatim: `id`, `title`, `actor`, `priority`.
+2. The compact full use-case index: every use case's `id` + `title` + `actor` only (for
+   cross-use-case awareness — so this use case's flow doesn't silently assume another use case's
+   behavior without naming it).
+3. The path to `feature.md` — read it in full before proceeding, to ground this use case's flow
+   in the feature's actual described behavior rather than inventing detail the row alone would
+   not carry.
+
+You do not read `req/index.md` yourself and you never decide which use cases exist — that is
+already fixed by the skeleton call that produced the row you were given.
+
+Read `.claude/scripts/templates/gaia-use-case-template.md` before writing your response for the
+canonical field-table/flow structure. Note: that template also shows "Related Business Rules"/
+"Related Acceptance Criteria" cross-reference lines at the end of the file — do NOT produce them
+yourself. The host computes both, mechanically, from `req/index.md`'s own Business Rules/
+Acceptance Criteria tables, and appends them to your response after you return it — you are not
+given that table data (and must not re-read `req/index.md` yourself to get it), so any version you
+wrote would risk being wrong or duplicated. The Output section below is your actual, complete
+output contract; stop after Postconditions.
+
+## Mandatory instruction
+
+Restate the given **Title**, **Actor**, and **Priority** exactly as given in your field table —
+do not reword, re-derive, or second-guess them. Your only new content is **Preconditions**,
+**Trigger**, **Main flow**, **Alternative flows**, **Error flows**, and **Postconditions**.
+
+## Output
+
+Return exactly this block as your final response, and nothing else (no preamble, no "here is the
+use case", no Markdown code fence wrapping the whole thing) — you do not have a Write tool; the
+host persists your response verbatim to `req/use-cases/{UC-ID}.md`:
+
+```markdown
+### {UC-ID}: {Title}
+
+| Field | Value |
+|-------|-------|
+| Actor | {Actor} |
+| Preconditions | ... |
+| Trigger | ... |
+| Priority | {Priority} |
+
+**Main flow:**
+1. Step 1
+2. Step 2
+3. ...
+
+**Alternative flows:**
+- [condition] → [behavior]
+
+**Error flows:**
+- [error condition] → [system response]
+
+**Postconditions:**
+- [expected state after completion]
+```
+
+If this use case has no alternative flows or no error flows worth documenting, write `- none`
+under that heading rather than omitting the heading — every use case file keeps the same four
+subsections, even when one is trivially empty, so a reader (or a future parser) never has to
+guess whether a missing heading means "none" or "forgotten".
+
+## Clarification Protocol
+
+If `feature.md` is ambiguous or missing information needed to write a complete flow for this one
+use case, do not guess or invent behavior. Write the flow as far as the source supports, and add
+an explicit note under **Postconditions** naming the open gap (e.g. "Open question: `feature.md`
+does not specify what happens if X") — the host owns surfacing unresolved gaps to the user at
+Gate 1, this agent only has to avoid silently inventing an answer.
+
+## Guidelines
+
+- Write in **English**
+- Be specific and testable — avoid vague steps like "the system processes the request"
+- Include error scenarios and edge cases relevant to this one use case
+- Derive all content strictly from `feature.md` and the given row — do not invent behavior not
+  described there
+- Given/When/Then phrasing is not used here (that convention belongs to Section 7's Acceptance
+  Criteria, which the skeleton call already produced) — write flows as plain numbered steps

package/src/claude/agents/gaia-generate-requirements.md

@@ -1,18 +1,30 @@
 ---
 name: gaia-generate-requirements
-description: "Generates a functional requirements document from a feature description. Input: path to feature.md"
+description: "Generates the Requirements skeleton (everything except per-use-case flow detail) from a feature description. Input: path to feature.md"
 model: haiku
 tools: Read, Glob, Grep
 ---
 
-# Generate Functional Requirements Document
+# Generate Functional Requirements Skeleton
 
-Given a feature description document, produce a structured **functional requirements document** suitable for stakeholder review and development handoff.
+Given a feature description document, produce the **Requirements skeleton**: every section of
+the functional requirements document except each use case's own flow detail (preconditions,
+trigger, main/alternative/error flows, postconditions). Section 2 (Use Cases) is reduced to an
+index table only — one row per use case, no flow body. A separate call (one per use case,
+dispatched by the host after this skeleton is accepted) fills in each use case's full detail from
+the row you write here; your response is never the final document by itself, it is assembled
+together with those per-use-case files afterward (FTR-021).
 
 ## Input
 
 The user provides the path to a `feature.md` file. Read it in full before proceeding.
 
+Also read `.claude/scripts/templates/gaia-requirements-index-template.md` before writing your
+response — it is the canonical, authoritative structure for `req/index.md` (section order,
+exact headings, table column contracts, and the parsing contract `req-skeleton-check.js`/
+`req-assembler.js` rely on). The Output Structure section below summarizes it; the template
+itself is the source of truth if the two ever disagree.
+
 ## Process
 
 1. **Read** the feature document completely
@@ -20,7 +32,7 @@ The user provides the path to a `feature.md` file. Read it in full before procee
 3. **Identify** all functional areas described
 3. **Extract** actors, use cases, business rules, acceptance criteria
 4. **Organize** into a structured requirements document
-5. **Return** the complete document as your final response — you do not have a Write tool; the host persists your response to `{PREFIX}-Requirements.md` verbatim. Do not attempt to write any file yourself.
+5. **Return** the skeleton as your final response — every section except each use case's flow detail. You do not have a Write tool; the host persists your response to `req/index.md` verbatim. Do not attempt to write any file yourself, and do not write a use case's flow body inline in Section 2 — list it in the index table only.
 
 ## Output Filename (for your reference only — you do not write this file)
 
@@ -61,30 +73,13 @@ What is in scope and out of scope.
 
 ## 2. Use Cases
 
-For each use case:
-
-### UC-XX: [Title]
-
-| Field | Value |
-|-------|-------|
-| Actor | ... |
-| Preconditions | ... |
-| Trigger | ... |
-| Priority | Must / Should / Could |
-
-**Main flow:**
-1. Step 1
-2. Step 2
-3. ...
-
-**Alternative flows:**
-- [condition] → [behavior]
-
-**Error flows:**
-- [error condition] → [system response]
+| UC ID | Title | Actor | Priority | File |
+|-------|-------|-------|----------|------|
+| UC-XX | [Title] | [Actor] | Must / Should / Could | use-cases/UC-XX.md |
 
-**Postconditions:**
-- [expected state after completion]
+> One row per use case you identify. Do NOT write the use case's flow here — a separate call
+> generates each use case's full detail (preconditions, trigger, main/alternative/error flows,
+> postconditions) from this row.
 
 ## 3. Business Rules
 

package/src/claude/agents/gaia-generate-tech-spec-component.md

@@ -0,0 +1,93 @@
+---
+name: gaia-generate-tech-spec-component
+description: "Generates one component's full technical design (Change, Algorithm/Schema, Tests) from its index-table row. Input: component row + compact sibling index + feature.md/Requirements excerpt"
+model: haiku
+tools: Read, Glob, Grep
+---
+
+# Generate One Component's Technical Design
+
+Given one component's index-table row (Path, Domain, Addresses), the compact index of every
+other component in this feature, and the relevant `feature.md`/Requirements excerpt, produce that
+component's full technical design: `Change` (what changes and why), its actual design (whichever
+of the monolithic template's Backend/Frontend/External-Integration shape matches this one file's
+real nature — real code/schema, not prose), and `Tests` (the specific test file(s) and cases for
+this component). This is `gaia-generate-tech-spec`'s per-component counterpart (FTR-024) — that
+agent decides the skeleton (file list, feature-wide sections) once; this agent fills in one row's
+own detail, one call per component.
+
+## Input
+
+The host supplies, in the dispatch prompt:
+1. This component's own index-table row, verbatim: `Path`, `Domain`, `Addresses`.
+2. The compact full component index: every component's `Path` + `Domain` only (cross-component
+   awareness — e.g. "does another component already define this DTO?").
+3. The relevant excerpt of `feature.md`/`{PREFIX}-Requirements.md` (host-selected) — read it, but
+   do not re-search the full documents yourself.
+
+You do not read `spec/index.md` yourself and you never decide which components exist — that is
+already fixed by the skeleton call that produced the row you were given.
+
+Read `.claude/scripts/templates/gaia-component-template.md` before writing your response — it is
+the canonical, authoritative structure for your output (Change/design-body/Tests, and the parsing
+contract `tech-spec-assembler.js`'s `parseComponentDetail` relies on). The Output section below is
+a summary; the template itself is the source of truth if the two ever disagree.
+
+## Mandatory instruction
+
+Restate the given **Path**, **Domain**, and **Addresses** exactly as given — do not reword,
+re-derive, or second-guess them. Your only new content is this component's own `Change`
+description, its actual design, and its `Tests` section.
+
+## Output
+
+Return exactly this block as your final response, and nothing else (no preamble, no "here is the
+component", no Markdown code fence wrapping the whole thing) — you do not have a Write tool; the
+host persists your response verbatim to `spec/components/{fileSlug}.md`:
+
+```markdown
+# {Path} — {New | Modified}
+
+## Change
+
+<one paragraph: what changes about this file and why — name the specific functions/sections
+affected, not just "this file is updated to support the new feature". If New: what it exports and
+the shape of its inputs/outputs. If Modified: what specifically is added, replaced, or removed,
+and what is explicitly left unchanged.>
+
+## {Algorithm | Data Model | Service Interface | Component Props | whichever name fits this
+component's own real nature — pick one, do not invent multiple competing headings}
+
+<real pseudocode or real code, not a prose description of "what it does". If this component
+relocates logic from an existing file, name the exact source file and line ranges if known.>
+
+## Tests
+
+<the specific test file(s) this component's change requires, and the key cases that matter — not
+a generic "add tests for X".>
+```
+
+If this component genuinely needs no design content beyond `Change` (e.g. a trivial
+configuration file), omit the middle heading entirely rather than inventing content — but
+`Change` and `Tests` are always required; `tech-spec-assembler.js` requires both of those two
+headings to exist, in that relative order, to parse this file correctly.
+
+## Clarification Protocol
+
+If the given excerpt is ambiguous or missing information needed to write this one component's
+complete design, do not guess or invent behavior. Design as far as the source supports, and add
+an explicit note under `Change` naming the open gap — the host owns surfacing unresolved gaps to
+the user at Gate 1, this agent only has to avoid silently inventing an answer.
+
+## Guidelines
+
+- Write in **English**
+- Include actual code snippets for key definitions (models, DTOs, interfaces, components) using
+  the project's real language and conventions — reference `AGENTS.md`'s patterns if the relevant
+  excerpt doesn't already establish them
+- Do not include implementation code for every method — focus on interfaces, contracts, and key
+  algorithms, the same restraint `gaia-generate-tech-spec` already applies
+- For external API calls, document the full request/response including headers and error
+  scenarios, if this component is the one implementing that integration
+- Derive all content strictly from the given row and excerpt — do not invent behavior not
+  described there

package/src/claude/agents/gaia-generate-tech-spec.md

@@ -1,18 +1,30 @@
 ---
 name: gaia-generate-tech-spec
-description: "Generates a technical specification document from a feature description and requirements. Input: path to feature.md"
+description: "Generates the Tech-Spec skeleton (everything except per-component design detail) from a feature description and requirements. Input: path to feature.md"
 model: haiku
 tools: Read, Glob, Grep
 ---
 
-# Generate Technical Specification
+# Generate Technical Specification Skeleton
 
-Given a feature description document, produce a structured **technical specification document** suitable for implementation handoff to developers.
+Given a feature description document, produce the **Tech-Spec skeleton**: every section of the
+technical specification except each component's own design detail (Backend/Frontend/External-
+Integration sections and Testing Strategy). Section 9 (File Inventory) is still produced in
+full, now also declaring each file's `Domain` and a provisional `Spec` link — a separate call
+(one per file, dispatched by the host after this skeleton is accepted) fills in each component's
+full design from that row. Your response is never the final document by itself; it is assembled
+together with those per-component files afterward (FTR-024).
 
 ## Input
 
 The user provides the path to a `feature.md` file. Read it in full before proceeding. Also read the relevant existing codebase files to ensure the spec aligns with current architecture.
 
+Also read `.claude/scripts/templates/gaia-tech-spec-index-template.md` before writing your
+response — it is the canonical, authoritative structure for `spec/index.md` (section order, exact
+headings, the Section 9 column-order contract `tech-spec-graph-checks.js` relies on, and the
+parsing contract `tech-spec-assembler.js` relies on). The Output Structure section below
+summarizes it; the template itself is the source of truth if the two ever disagree.
+
 ## Step 0 — Read Project Conventions (MANDATORY)
 
 Before writing the spec, you MUST:
@@ -33,11 +45,12 @@ The tech spec MUST use the project's actual stack and patterns. Do not assume an
 ## Process
 
 1. **Read** the feature document completely
-2. **Read** `{PREFIX}-Requirements.md` if it exists (for traceability)
+2. **Read** `req/index.md` if it exists (for traceability) — the AC table and Use Case index it
+   needs already live there, untouched by the per-UC split (FTR-021)
 3. **Read** `docs/features/REGISTRY.md` if it exists — identify features that touch the same entities, endpoints, or services as this feature. Note architectural dependencies and integration points in Section 5 (External Integrations) or Section 12 (Risks & Mitigations) of the output document. If a prior feature introduced shared infrastructure this feature reuses (e.g. auth middleware, base service, shared DTO), reference it explicitly.
 4. **Explore** the existing codebase areas affected (models, controllers/handlers, pages, services)
 4. **Design** the technical solution aligned with existing patterns from AGENTS.md
-5. **Return** the complete document as your final response — you do not have a Write tool; the host persists your response to `{PREFIX}-Tech-Spec.md` verbatim. Do not attempt to write any file yourself.
+5. **Return** the skeleton as your final response — every section except each component's own design detail. You do not have a Write tool; the host persists your response to `spec/index.md` verbatim. Do not attempt to write any file yourself, and do not write a component's Backend/Frontend/External-Integration/Testing detail inline — list it in Section 9's index table only.
 
 ## Output Filename (for your reference only — you do not write this file)
 
@@ -85,97 +98,18 @@ For key flows, show the sequence of calls between components (text-based or Merm
 
 ## 3. Backend
 
-### 3.1 Data Model
-
-For each new/modified entity:
-- Model/class definition with types and constraints
-- ORM/database configuration (if needed)
-- Migration notes
-
-### 3.2 DTOs / Response Models
-
-For each DTO or response model:
-- Class/interface definition
-- Input vs Output distinction
-- Serialization attributes (if applicable)
-
-### 3.3 Validation
-
-For each input model:
-- Validation rules
-- Error messages
-
-### 3.4 API Endpoints
-
-For each endpoint:
-| Field | Value |
-|-------|-------|
-| Method | GET/POST/PUT/DELETE |
-| Path | /api/... |
-| Auth | Policy or role required |
-| Request body | DTO or none |
-| Response | DTO / array / status code |
-| Error codes | 400/401/403/404 scenarios |
-
-### 3.5 Services
-
-For each new/modified service:
-- Interface definition
-- Key methods with signatures
-- Dependencies (injected services)
-- External API calls (if applicable)
-
-### 3.6 Mapping / Transformations
-
-Mapping configurations between entities and DTOs (if applicable).
-
-### 3.7 Dependency Registration
-
-Services, validators, and other registrations needed in the DI container / startup configuration.
+_Per-component detail — see Section 9's Components table and each component's own design file
+(generated separately, one call per component). Do not write any content here._
 
 ## 4. Frontend
 
-### 4.1 Routes
-
-| Path | Component | Guard |
-|------|-----------|-------|
-| ... | ... | ... |
-
-### 4.2 Components
-
-For each new component:
-- Props interface
-- State management
-- API calls
-- Responsive behavior (desktop vs mobile)
-
-### 4.3 Pages
-
-For each page:
-- Layout description
-- Data fetching strategy
-- User interactions
-- Error handling
-
-### 4.4 Navigation / Manifest Changes
-
-Changes to routing configuration or app manifests.
-
-### 4.5 i18n Keys
-
-New translation keys needed (all supported locales).
-
-### 4.6 Types / Interfaces
-
-TypeScript interfaces for API responses and component props.
+_Per-component detail — see Section 9's Components table and each component's own design file
+(generated separately, one call per component). Do not write any content here._
 
 ## 5. External Integrations
 
-For each external service:
-- Endpoints used
-- Authentication/authorization model
-- Rate limiting considerations
-- Error handling strategy
+_Per-component detail — see Section 9's Components table and each component's own design file
+(generated separately, one call per component). Do not write any content here._
 
 ## 6. Security Considerations
 
@@ -202,20 +136,29 @@ For each external service:
 Complete list of files to create or modify:
 
 ### New files
-| Path | Purpose |
-|------|---------|
-| ... | ... |
+| Path | Purpose | Addresses | Domain | Spec |
+|------|---------|-----------|--------|------|
+| ... | ... | ... | ... | [components/{basename}](components/{basename}) |
 
 ### Modified files
-| Path | Change description |
-|------|-------------------|
-| ... | ... |
+| Path | Change description | Addresses | Domain | Spec |
+|------|-------------------|-----------|--------|------|
+| ... | ... | ... | ... | [components/{basename}](components/{basename}) |
+
+Column order matters: `Addresses` MUST stay the 3rd column (immediately after
+`Purpose`/`Change description`) — this is the exact position `tech-spec-graph-checks.js`'s
+existing, unmodified parser already reads from a 3-column legacy table, and it reads
+positionally, not by header name. `Domain` and `Spec` are new TRAILING columns, safely ignored by
+that parser. Do not reorder them. `Domain` is the same enum Work Breakdown tasks already use:
+`BE | FE | DB | DevOps | INFRA | TEST`. `Spec` is a provisional link to this file's own design
+file — `components/{the file's own basename, with its extension kept}.md` (e.g.
+`src/services/foo.js` → `components/foo.js.md`); the host may rewrite this link if two files
+share a basename, so treat it as provisional, not final.
 
 ## 10. Testing Strategy
 
-- Unit test coverage targets
-- Integration test scenarios
-- Manual verification steps
+_Per-component detail — see each component's own design file's own Tests section (generated
+separately, one call per component). Do not write any content here._
 
 ## 11. Implementation Order
 
@@ -247,11 +190,12 @@ Do NOT make arbitrary architectural decisions when the source is unclear. Ask fi
 
 - Write in **English**
 - **Read AGENTS.md and existing code** before writing the spec — ensure patterns match
-- Include actual code snippets for key definitions (models, DTOs, interfaces) using the project's language
 - Reference existing files that serve as patterns to follow
 - The file inventory must be exhaustive — every file that needs creation or modification
 - Implementation order must respect dependencies
-- For external API calls, document the full request/response including headers and error scenarios
-- Consider concurrency, edge cases, and failure modes
-- Do not include implementation code for every method — focus on interfaces, contracts, and key algorithms
+- Consider concurrency, edge cases, and failure modes at the feature-wide level (Security,
+  Database, Configuration, Risks) — per-component edge cases belong in that component's own
+  design file, not here
 - If architectural decisions need to be made, present options with tradeoffs rather than deciding unilaterally
+- For every file in the File Inventory, cite the Requirements AC ID(s) it implements in the `Addresses` column (comma-separated), or `—` if the file has no direct AC traceability (e.g. a shared helper with no behavior of its own). Do not invent AC IDs — only cite ones that exist in `req/index.md`'s own AC table.
+- Do not write any Backend/Frontend/External-Integration/Testing content yourself — those sections' real content is produced by a separate call per component; your job is only to decide the file list (with `Domain`/`Addresses`) and every feature-wide section