@dtlabs/ai-toolkit 0.17.5 → 0.19.0

package/src/claude/scripts/templates/gaia-tech-spec-index-template.md

@@ -0,0 +1,137 @@
+<!--
+TECH-SPEC INDEX TEMPLATE — spec/index.md
+
+Canonical structure for the Tech-Spec index (skeleton) in the split format (FTR-024). Holds every
+section genuinely feature-wide, PLUS the Section 9 Components index table — one row per file the
+feature creates or modifies. Each component's own Backend/Frontend/External-Integration/Testing
+detail is produced separately, one call per component (see gaia-component-template.md); this
+skeleton never contains that per-component content inline.
+
+This is the REAL, currently-implemented 12-section contract — authoritative source:
+`src/claude/agents/gaia-generate-tech-spec.md`'s own "Output Structure" section, and
+`src/claude/scripts/tech-spec-assembler.js`/`tech-spec-graph-checks.js`. An earlier FTR-020
+exploratory draft of this template used a completely different 6-section numbering (Baseline /
+Resolution of Open Questions / Components index / Traceability / feature-wide guarantees / Shared
+test fixtures) that predates the Tech-Spec split entirely and was never what generation actually
+shipped — this file reflects the real, current 12-section format, not that earlier draft.
+
+Fill in every placeholder (angle brackets) and delete every HTML comment block (including this
+one) before treating the file as finished.
+-->
+
+# Technical Specification — {Feature Title}
+
+## Document Info
+| Field | Value |
+|-------|-------|
+| Feature | {PREFIX and title} |
+| Version | 1.0 |
+| Date | {today} |
+| Status | Draft |
+
+## 1. Overview
+
+<prose: brief technical summary — what is being built, which systems are affected>
+
+## 2. Architecture
+
+### 2.1 System Context
+
+<prose: where this feature sits in the overall architecture>
+
+### 2.2 Component Diagram
+
+<!-- Text-based diagram showing components and their interactions. -->
+
+```
+[Component A] --(protocol)--> [Component B]
+```
+
+### 2.3 Sequence Diagrams
+
+<!-- For key flows, show the sequence of calls between components (text-based or Mermaid). -->
+
+## 3. Backend
+
+_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
+
+_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
+
+_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
+
+<!-- Authentication & authorization requirements, input validation boundaries, sensitive data
+     handling, CORS implications (if applicable). -->
+
+<prose / bullet list>
+
+## 7. Database Changes
+
+<!-- New tables/columns, indexes recommended, seed data, migration strategy. -->
+
+<prose / bullet list>
+
+## 8. Configuration
+
+<!-- New environment variables, app settings changes, feature flags (if applicable). -->
+
+<prose / bullet list>
+
+## 9. File Inventory
+
+Complete list of files to create or modify:
+
+### New files
+| Path | Purpose | Addresses | Domain | Spec |
+|------|---------|-----------|--------|------|
+| {real file path} | {purpose} | {AC-IDs, comma-separated, or —} | {BE \| FE \| DB \| DevOps \| INFRA \| TEST} | [components/{fileSlug}](components/{fileSlug}) |
+
+### Modified files
+| Path | Change description | Addresses | Domain | Spec |
+|------|-------------------|-----------|--------|------|
+| {real file path} | {change description} | {AC-IDs, comma-separated, or —} | {BE \| FE \| DB \| DevOps \| INFRA \| TEST} | [components/{fileSlug}](components/{fileSlug}) |
+
+<!--
+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, positional parser reads from, 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. `Spec` is a provisional link to this file's own
+design file — `components/{the file's own basename, with its extension kept}.md` — the host may
+rewrite this link if two files share a basename, so treat it as provisional, not final.
+-->
+
+## 10. Testing Strategy
+
+_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
+
+<!-- Numbered, dependency-aware sequence of components/tasks. -->
+
+1. {component/task} — depends on: nothing
+2. {component/task} — depends on: 1
+
+## 12. Risks & Mitigations
+
+| Risk | Impact | Mitigation |
+|------|--------|-----------|
+| {risk} | {impact} | {mitigation} |
+
+<!--
+PARSING CONTRACT — tech-spec-assembler.js's tech-spec-graph-checks.js's parsers require exactly
+these 12 numbered `## N. ` headings, in order, to exist (assertCompleteSections's truncation guard
+in pm-phase1.js checks the same 12 headings), plus Section 9's two subtables in the exact column
+order above. Sections 3/4/5/10 must keep their heading even though their real content is deferred
+to per-component generation — the assembler's spliceSectionBody requires the heading to already
+exist to splice into.
+-->

package/src/claude/scripts/templates/gaia-use-case-template.md

@@ -0,0 +1,56 @@
+<!--
+USE CASE TEMPLATE — req/use-cases/{UC-ID}.md
+
+Canonical structure for one Use Case file in the split Requirements format. Every UC file has
+exactly three parts, in this order: (1) the heading + field table, (2) the flow/description
+body, (3) cross-references back to the index (Business Rules and Acceptance Criteria that apply
+to this UC). Fill in every placeholder (angle brackets) and delete every HTML comment block
+(including this one) before treating the file as finished.
+-->
+
+### {UC-ID}: <Title — short, matches the Title column in index.md's Use Cases table exactly>
+
+| Field | Value |
+|---|---|
+| Actor | <who/what initiates or participates in this use case> |
+| Priority | <Must \| Should \| Could> |
+| Preconditions | <what must already be true before this use case can start> |
+| Trigger | <the event that starts this use case> |
+
+> **Legend:** **Actor** — who/what initiates or participates in this use case. **Priority** —
+> MoSCoW (Must/Should/Could). **Preconditions** — what must already be true before this use case
+> can start. **Trigger** — the event that starts it.
+
+<!--
+The body: describe the actual flow. For a technical/internal feature (most of this toolkit's
+own features), this is usually a numbered or prose description of what happens, in enough detail
+that someone reading ONLY this file — not the whole Requirements document — understands exactly
+what this use case requires, without having to infer it from the Tech-Spec or the Work Breakdown.
+Length target: proportional to the use case's real complexity, not padded — a one-paragraph UC is
+fine if that's genuinely all there is to say; a multi-step UC can run longer, but if it's
+sprawling across unrelated concerns, that's a sign it should be two UCs, not one file trying to
+cover both (same atomicity instinct as a Work Breakdown task, just at a coarser grain).
+-->
+
+<prose describing the flow>
+
+**Related Business Rules:** <comma-separated BR-IDs that apply to this UC, derived from the
+`Applies to` column in [index.md](../index.md#3-business-rules) — include any `All UCs` rule
+too, or `—` if none>
+
+**Related Acceptance Criteria:** <comma-separated AC-IDs whose `Related UC` column includes this
+UC (always include any `All UCs` AC too), derived from
+[index.md](../index.md#6-acceptance-criteria). `—` is only valid if index.md's AC table
+genuinely has no AC referencing this UC yet — treat that as a flag worth double-checking, not a
+normal/expected state: per the feature.md<->req<->spec bidirectional traceability check (see
+[index.md](../index.md#traceability)), every UC should normally trace to at least one AC, or
+nothing downstream can verify this UC's Work Breakdown tasks actually satisfy it.
+
+<!--
+Both cross-reference lines above are DERIVED data — they must match what index.md's tables
+actually say. Don't invent a BR/AC reference here that doesn't exist in the index, and don't let
+this line go stale if the index changes later (whatever generates/maintains this file is
+responsible for keeping it in sync — this is the same "which side is authoritative" question the
+Work Breakdown's skeleton/detail split had to answer: here, index.md's tables are authoritative,
+this line is a convenience projection of them, not a second source of truth).
+-->

package/src/claude/scripts/templates/gaia-user-story-template.md

@@ -0,0 +1,61 @@
+<!--
+PHASE / USER-STORY DETAIL TEMPLATE — wbs/user-stories/{PHASE_ID}.md
+
+Canonical structure for a phase file (the INFRA phase and every US-NN phase both use this same
+template — INFRA is not a user story, but lives in the same directory and format; see "Type"
+below). Every phase file has exactly four parts, in this order: (1) the field block,
+(2) Context, (3) Tasks in this phase, (4) Depends on phases. Fill in every placeholder (angle
+brackets) and delete every HTML comment block (including this one) before treating the file as
+finished.
+-->
+<a id="phase-{PHASE_ID}"></a>
+### {PHASE_ID}
+
+- **Phase ID:** {PHASE_ID}
+- **Type:** <infrastructure | user-story>
+- **Source UC:** <comma-separated UC-ID(s) this phase's tasks realize, or `—` for a phase with no
+  single originating UC (e.g. shared infrastructure). Restated here for human readability from
+  `index.json`'s own `sourceUC` array, which is authoritative — this line is a display-only
+  projection, not parsed back out by `parsePhaseDetailBlock` (same convention as `Phase ID`/
+  `Type` above, which are also restated but not re-extracted). Can be MORE than one UC (an
+  orchestration phase) — don't force a single value if that's not true; see Tech-Spec OQ-05.>
+- **Title:** <For `type: user-story`, use the standard form: "As a <role>, I want <capability>,
+  so that <benefit>" — derived directly from this phase's source Use Case(s). For `type:
+  infrastructure` (the one INFRA phase), there is no user-story grammar — use a short descriptive
+  label of what shared setup this phase provides.>
+- **Commit type:** <conventional-commit type, usually `feat`>
+- **Commit scope:** <optional, or `—`>
+- **Commit subject:** <imperative, concise — e.g. "implement {PHASE_ID} <short description>" —
+  the renderer prepends `type(scope): ` automatically, do not include it here>
+
+**Context:**
+
+<!--
+2–4 sentences, no more. Answer: why does this phase exist (which Use Case / need does it map
+to)? How do its own tasks relate to each other? Is there a dependency or sequencing reason other
+phases or tasks need to know about before opening this phase's individual task files? Do NOT
+restate the Title — add information the title doesn't already give.
+-->
+
+<prose>
+
+**Tasks in this phase:**
+
+<!--
+One bullet per task, in the same order as `index.json`'s `taskIds` for this phase. The summary is
+a few words of what the task DOES, not a copy of its full Title (that's one click away via the
+task ID link/filename).
+-->
+
+- `{TASK_ID}` — <one-line summary>
+
+**Depends on phases:** <comma-separated phase IDs this phase's tasks have a `dependsOn` reference
+into, or `none` if this phase has no cross-phase dependency>
+
+<!--
+PARSING CONTRACT — read by wbs-assembler.js's parsePhaseDetailBlock: field values are read from
+the CONTIGUOUS RUN of `- **Label:** value` lines starting immediately after the `### {PHASE_ID}`
+heading, stopping at the first non-matching line. Same rule and same rationale as the task
+template — see task-template.md's parsing-contract note for the full explanation and the real
+bug it fixes.
+-->