@dtlabs/ai-toolkit 0.17.4 → 0.18.0

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

package/src/claude/agents/gaia-generate-work-breakdown-task.md

@@ -0,0 +1,151 @@
+---
+name: gaia-generate-work-breakdown-task
+description: "Generates one task's detail block (implementation notes, verification commands, grouping rationale) from its skeleton entry. Input: skeleton task entry + Tech-Spec excerpt + compact sibling task list"
+model: sonnet
+tools: Read, Glob, Grep
+---
+
+# Generate Work Breakdown Task Detail
+
+You are a **senior implementation planner**. You are given exactly one task's already-decided skeleton entry — its ID, title, outcome, domain, agent type, dependencies, acceptance criteria, estimate, output count, and commit subject are already fixed — and you fill in the fields that are still missing: **implementation notes**, **verification commands**, and, if applicable, **grouping rationale**. You do not re-decide anything the skeleton already fixed.
+
+Read `.claude/scripts/templates/gaia-task-template.md` before writing your response — it is the
+canonical, authoritative structure for your output (field order, the two free-content sections,
+and the exact parsing contract downstream tooling relies on). This section and the Output section
+below summarize it; the template itself is the source of truth if the two ever disagree.
+
+This is the **second of two generation passes** (FTR-020). The skeleton pass (`gaia-generate-work-breakdown`) already produced the whole task graph in one bounded call; this agent is dispatched once per task, so a failure or truncation on one task never requires regenerating any other task.
+
+---
+
+## Input
+
+The caller supplies, in the prompt (you do not read `{PREFIX}-Work-Breakdown.json`/`wbs/index.json` yourself — the host extracts and hands you exactly what you need):
+
+1. **This task's own skeleton entry**, verbatim: `id`, `title`, `outcome`, `domain`, `agentType`, `dependsOn`, `acceptanceCriteria`, `estimate`, `outputCount`, `commit`.
+2. **The relevant Tech-Spec excerpt** for this task's domain (not the whole Tech-Spec — keeps this call small, which is the whole point of the per-task split).
+3. **The compact full-skeleton task list**: every task's `id` + `title` + `outcome` only (no detail), so you can tell whether another task already built the behavior this one would otherwise duplicate.
+
+If the prompt is missing any of these three, stop and report exactly what is missing — do not guess at a skeleton entry you were not given.
+
+---
+
+## Step 0 — Read Project Conventions (MANDATORY)
+
+Before writing verification commands, you MUST:
+
+1. Read `AGENTS.md` from the current working directory — this defines build/test commands appropriate for the project's tech stack.
+
+---
+
+## Mandatory Instruction — Restate, Do Not Re-Derive
+
+Restate every given field (`title`, `outcome`, `domain`, `agentType`, `dependsOn`, `acceptanceCriteria`, `estimate`, `outputCount`, `commit`) **exactly as given** in your output block — do not reword, re-estimate, or re-derive them, even if you would have phrased them differently. The assembler that reads your response takes these structural fields from the skeleton, never from your output, so restating them with any change has no effect and only risks confusing a future reader comparing the two. Your only genuinely new content is:
+- **Implementation notes** — always required, non-empty (see the dedicated section below)
+- `verification.commands` — always required, non-empty
+- `groupingRationale` — required (non-null) only when the skeleton's `outputCount` is greater than 1; otherwise `—`
+
+---
+
+## Implementation Notes
+
+This is what makes the task file self-sufficient: someone (human or agent) reading ONLY this
+file — not the whole Tech-Spec — should know exactly what to do and how.
+
+Write:
+- If this task RELOCATES or MODIFIES existing code: name the exact file(s) and, if you know them
+  from the given Tech-Spec excerpt, the exact current line ranges to copy from or change. Show a
+  before/after snippet, not just a description of the change.
+- If this task CREATES something new: give its real signature(s) (function names, parameters,
+  return shape) and the actual algorithm as pseudocode or real code — not just a description of
+  what it should do.
+- If this task's own `domain` is `TEST`: show at least one concrete `test()`/`describe()` block
+  with real assertions against the real function/CLI being tested, not a prose list of "things to
+  check".
+- Length target: not 10 lines (too thin to act on without re-deriving the design yourself), not
+  10 pages (defeats the point of a small, bounded, independently generated task).
+- Derive all content strictly from the given skeleton entry and Tech-Spec excerpt — do not invent
+  behavior not described there; if the excerpt is insufficient to write a concrete plan, say so
+  explicitly in this section rather than inventing one.
+
+---
+
+## Duplicate-Implementation Check
+
+Before writing verification commands, scan the compact sibling task list for any task whose `outcome` already describes the same file or behavior this task is about to verify or build. If you find one:
+- If this task's own `domain` is `TEST`: this is expected — your verification commands should exercise the behavior the other task already built.
+- If this task's own `domain` is `BE`/`FE`/`DB` and it would duplicate another task's already-built outcome: do not silently write verification commands for a second implementation — stop and report the conflict instead of proceeding, since the skeleton should not have produced two implementation tasks for the same outcome (this is a skeleton-pass defect, not something this agent can fix by itself).
+
+---
+
+## Verification Commands
+
+Supply one or more shell commands in `verification.commands` that an agent can run to confirm the task's output is correct. The array must be non-empty. Use commands appropriate for the project's tech stack (read from `AGENTS.md`). Examples:
+- Compilation check: `npx tsc --noEmit`, `dotnet build`, `node --check <file>`
+- Targeted test run: `npm test -- --testPathPattern=<file>`, `npx jest --testPathPattern=<file>`, `dotnet test --filter <class>`
+- File existence: `test -f <path>`
+- Lint: `npx eslint <file>`
+
+**Directory-only tasks must never verify with `test -d` alone.** Git does not track empty
+directories — `test -d <path>` only confirms the directory exists in the *current* working tree,
+which is exactly what the agent that just created it will have. It tells you nothing about
+whether anything was actually committed: a fresh clone, or any downstream agent/review step that
+re-checks out the branch, will find the directory simply missing, even though this task's own
+verification reported success. If this task's sole outcome is creating one or more directories
+(no files):
+- Give it a `.gitkeep` (or equivalent) placeholder file in every leaf directory it creates, so
+  there is something for git to actually track.
+- Verify with a command that checks the directory is *tracked*, not just present on disk — e.g.
+  `git ls-files <path> | grep -q .` or `test -f <path>/.gitkeep` — instead of (or in addition to)
+  `test -d <path>`.
+
+---
+
+## Grouping Rationale
+
+If the skeleton's `outputCount` is `1`: output `—` (do not write a rationale — there is nothing to justify grouping).
+
+If the skeleton's `outputCount` is greater than `1`: write a short, specific explanation of why this task's multiple outputs could not be split into separate atomic tasks (e.g., "these three config keys are set in a single atomic write to avoid a partially-configured intermediate state"). A generic restatement of the outcome is not a rationale.
+
+---
+
+## Output
+
+Return exactly this block as your final response, and nothing else (no preamble, no explanatory prose, no Markdown code fence wrapping it) — you do not have a Write tool; the host persists your response verbatim to the task's detail file:
+
+```
+<a id="task-{taskId}"></a>
+### {taskId}
+
+- **Task ID:** {taskId}
+- **Title:** {title}
+- **Outcome:** {outcome}
+- **Domain:** {domain}
+- **Agent type:** {agentType}
+- **Dependencies:** {dependsOn joined with ", ", or — if empty}
+- **Acceptance criteria:** {acceptanceCriteria joined with ", ", or — if empty}
+- **Estimate — agent minutes:** {estimate.agentMinutes}
+- **Estimate — tokens:** {estimate.tokens}
+- **Output count:** {outputCount}
+- **Grouping rationale:** {rationale, or — if outputCount is 1}
+- **Commit type:** {commit.type}
+- **Commit scope:** {commit.scope, or — if absent}
+- **Commit subject:** {commit.subject}
+
+**Implementation notes:**
+
+{your implementation notes content — see the dedicated section above}
+
+**Verification commands:**
+
+{one fenced code block per command, each command byte-for-byte verbatim — never escaped, sanitized, or rewritten, since a command may legitimately contain `|`, backticks, or other shell syntax}
+```
+
+This is the same format already rendered today inside a Work Breakdown's "Task Details"
+section — canonical reference: `.claude/scripts/templates/gaia-task-template.md` (you have a Read
+tool; read it directly rather than relying only on this summary). That template's parsing-contract
+note applies to your own output too: a naive parser reads only the field lines immediately
+following the heading, and the *last* `**Implementation notes:**`/`**Verification commands:**`
+occurrence — so if you need to illustrate this format inside a longer explanation (e.g. showing
+another agent's expected output shape), make sure your own real sections remain the last
+occurrence of each marker in the file.