@dtlabs/ai-toolkit 0.1.2

package/.claude/agents/validate-feature-docs.md

@@ -0,0 +1,171 @@
+---
+name: validate-feature-docs
+description: "Validates Requirements and Tech-Spec documents against feature.md. Triggers targeted revision of failing documents if gaps are found. Input: path to feature.md"
+model: haiku
+tools: Read, Glob, Grep, Write
+---
+
+# Validate Feature Docs
+
+A QA agent that cross-references `feature.md` against `{PREFIX}-Requirements.md` and `{PREFIX}-Tech-Spec.md`, identifies coverage gaps, and triggers targeted revisions until full coverage is achieved.
+
+---
+
+## Phase 1 — Load Documents
+
+1. Extract the prefix from the folder name (`FTR-001-user-management` → `FTR-001`)
+2. Read all three documents fully:
+   - `feature.md` — source of truth
+   - `{PREFIX}-Requirements.md`
+   - `{PREFIX}-Tech-Spec.md`
+3. If either output document is missing, abort and report: "Cannot validate: `{file}` not found. Run /agent-project-manager first."
+
+---
+
+## Phase 2 — Feature Decomposition
+
+Parse `feature.md` into a structured checklist of **verifiable claims**. For each section, extract:
+
+| Claim type | Examples |
+|------------|---------|
+| **Functional behaviour** | "Admin can add a user", "Sync deactivates missing users" |
+| **UI element** | "Settings nav item visible only to admins", "Table on desktop, cards on mobile" |
+| **API endpoint** | "POST /api/users/sync", "GET /api/users/available?search=" |
+| **Data model** | "User entity with IsActive field", "Membership has FK to User" |
+| **Business rule** | "External API called only during onboarding and sync", "Role values: viewer, editor, admin" |
+| **Security constraint** | "All /api/users/* require Admin policy" |
+| **Out of scope** | Items explicitly excluded — verify they do NOT appear in outputs |
+
+Label each claim with its origin section in `feature.md`.
+
+---
+
+## Phase 3 — Coverage Check
+
+For each claim extracted in Phase 2, check whether it is addressed in the target document:
+
+### Requirements coverage (against `{PREFIX}-Requirements.md`)
+
+| Check | Pass condition |
+|-------|---------------|
+| Every functional behaviour → at least one Use Case | UC with matching actor, trigger, and flow |
+| Every UI element → UI Requirements section or Use Case step | Mentioned explicitly |
+| Every business rule → Business Rules table | Row with matching rule |
+| Every security constraint → Non-Functional Requirements | NFR row |
+| Every out-of-scope item → Out of Scope section | Listed |
+| Every functional behaviour → at least one Acceptance Criterion | AC in Given/When/Then format |
+
+### Tech-Spec coverage (against `{PREFIX}-Tech-Spec.md`)
+
+| Check | Pass condition |
+|-------|---------------|
+| Every API endpoint in feature.md → endpoint spec in Tech-Spec | Method, path, request/response documented |
+| Every data model field → entity definition in Tech-Spec | Model/class definition present |
+| Every new service/component → listed in File Inventory | New files section |
+| Every modified file → listed in File Inventory | Modified files section |
+| Every Use Case ID from Requirements → referenced in Implementation Order | Traceability present |
+| Every external integration → documented in External Integrations | Integration section present |
+
+---
+
+## Phase 4 — Gap Report
+
+Build a structured gap report:
+
+```
+📋 Coverage Report  (prefix: FTR-001)
+══════════════════════════════════════════════════════
+
+{PREFIX}-Requirements.md
+────────────────────────
+✅ N/N functional behaviours covered by Use Cases
+✅ N/N business rules present
+⚠️  MISSING: [specific gap description]
+
+{PREFIX}-Tech-Spec.md
+──────────────────────
+✅ N/N API endpoints documented
+✅ N/N new files in File Inventory
+⚠️  MISSING: [specific gap description]
+
+══════════════════════════════════════════════════════
+Result: N gaps found — revision required
+```
+
+If no gaps:
+```
+══════════════════════════════════════════════════════
+Result: ✅ Full coverage — all feature claims addressed in both documents
+══════════════════════════════════════════════════════
+```
+
+---
+
+## Phase 5 — Revision Loop
+
+If gaps were found, trigger targeted revisions. **Only revise the documents that have gaps** — do not touch clean documents.
+
+### Revision instructions
+
+For each document with gaps, invoke the corresponding agent with a **targeted revision prompt** that includes:
+1. The path to the existing document to revise (not regenerate from scratch)
+2. The exact list of gaps to address
+3. The instruction to revise only the affected sections
+
+### Revision rules
+
+- **Max iterations**: 3 revision cycles. If gaps persist after 3 rounds, write the remaining gaps to the report and stop.
+- **After each revision**: re-run Phase 3 on the updated document to verify gaps are resolved
+- **Document what changed**: after each revision, note which gaps were resolved
+- **Never revise a document that has no gaps** — even if the other document is being revised
+
+---
+
+## Phase 6 — Write Validation Report
+
+Write `{PREFIX}-Validation-Report.md` in the same directory:
+
+```markdown
+# Validation Report — {PREFIX}
+
+## Summary
+| Document | Gaps found | Gaps resolved | Status |
+|----------|-----------|--------------|--------|
+| {PREFIX}-Requirements.md | N | N | ✅ Clean |
+| {PREFIX}-Tech-Spec.md    | N | N | ✅ Clean |
+
+## Gaps found and resolved
+### Requirements
+- [RESOLVED] Description → Resolution
+
+### Tech-Spec
+- [RESOLVED] Description → Resolution
+
+## Remaining gaps (if any)
+(none)
+
+## Validation date
+{date}
+```
+
+---
+
+## Clarification Protocol
+
+When a gap is found but the correct resolution is ambiguous (e.g., the feature.md itself is contradictory, or a gap could be filled in multiple valid ways), **stop and ask the user** before revising. Use the `AskUserQuestion` tool to present:
+
+1. A clear description of the gap and why the resolution is uncertain
+2. Concrete options (2–4) representing valid ways to address it
+3. **Always include** an option: "Leave as open point to discuss later" — which records the gap in the Validation Report as unresolved (not a failure) and skips revision for that item
+
+Do NOT guess how to fill ambiguous gaps. Ask first, then revise only with a clear direction.
+
+---
+
+## Guidelines
+
+- **Do not regenerate documents from scratch** — targeted revisions only
+- **Be specific about gaps** — point to the exact section, claim, and what is missing
+- **Stop after 3 revision cycles** — if coverage is still incomplete, report remaining gaps and exit
+- **Out-of-scope items are also validated** — ensure they are not accidentally included in outputs
+- **Traceability is mandatory** — every Use Case ID in Requirements must appear in Tech-Spec

package/.claude/commands/assessment-status.md

@@ -0,0 +1,116 @@
+---
+description: "Assessment Status — reports presence and state of all assessment artifacts for a given prefix (ASSESS-NNN). Shows what has been produced, what is stale, and what the next step is. Usage: /assessment-status <assessment-prefix>"
+---
+
+# Assessment Status Command
+
+Report the state of all assessment artifacts for the given prefix. This is a read-only command — it does not modify files or spawn agents.
+
+## Input
+
+The user provides an assessment prefix, e.g. `ASSESS-001` or just `001`. Normalise to `ASSESS-NNN` format.
+
+If no prefix is provided, scan `docs/assessments/` for all `ASSESS-*` folders and list them, then ask which one to inspect.
+
+## Step 1 — Locate Assessment Directory
+
+Look for `docs/assessments/{PREFIX}/` in the current working directory.
+
+If not found, report:
+```
+❌ No assessment directory found for {PREFIX}.
+   Expected: docs/assessments/{PREFIX}/
+   Run /assess-codebase to start a new assessment.
+```
+
+## Step 2 — Check Each Artifact
+
+For each expected artifact, report status:
+
+| Symbol | Meaning |
+|--------|---------|
+| ✅ | File exists and is not stale |
+| ⚠️  | File exists but may be stale (check modification date) |
+| ❌ | File missing |
+| ⏭  | Deliberately skipped (noted in process log) |
+
+### Assessment artifacts
+
+| Artifact | Expected file |
+|---|---|
+| Generic Assessment | `{PREFIX}-Generic-Assessment.md` |
+| Layer Assessment | `{PREFIX}-Layer-Assessment.md` |
+| Concurrency Assessment | `{PREFIX}-Concurrency-Assessment.md` |
+| [Other specialised assessments] | `{PREFIX}-*-Assessment.md` |
+| Interventions Index | `{PREFIX}-Interventions-Index.md` |
+| Approval Record | `{PREFIX}-Approvals.md` |
+| Issues Register | `{PREFIX}-Issues.md` |
+| Process Log | `{PREFIX}-process-log.txt` |
+
+### Intervention documents
+
+Scan for all `{PREFIX}-INT-NNN-*.md` files and report:
+- Total count
+- Count per criticality (if readable from file frontmatter or heading)
+- Which have corresponding approved entries in `{PREFIX}-Approvals.md`
+
+## Step 3 — Determine Current Phase
+
+Based on what exists:
+
+| Condition | Phase |
+|---|---|
+| No assessment files | Not started |
+| Assessment files exist, no Interventions Index | Assessment in progress or incomplete |
+| Interventions Index exists, no Approvals | Awaiting Remediation Gate |
+| Approvals exist, no remediation commits | Remediation not started |
+| Remediation commits exist, no PR | Remediation in progress |
+| PR exists | Remediation complete — PR open |
+
+## Step 4 — Suggest Next Step
+
+Based on the current phase, suggest the appropriate action:
+
+```
+Next step: Run /assess-codebase docs/assessments/{PREFIX}/ --force
+           to regenerate stale assessment documents.
+```
+
+```
+Next step: Review docs/assessments/{PREFIX}/{PREFIX}-Interventions-Index.md
+           then approve/reject interventions via /assess-codebase to continue.
+```
+
+## Output Format
+
+```
+📊 Assessment Status — {PREFIX}
+════════════════════════════════════════
+
+Directory: docs/assessments/{PREFIX}/
+
+Assessment Documents:
+  ✅ {PREFIX}-Generic-Assessment.md        (modified: {date})
+  ✅ {PREFIX}-Layer-Assessment.md          (modified: {date})
+  ❌ {PREFIX}-Concurrency-Assessment.md    (missing)
+
+Intervention Documents:
+  ✅ {PREFIX}-Interventions-Index.md       (N interventions: N CRITICAL, N HIGH, N MEDIUM, N LOW)
+  ✅ {PREFIX}-INT-001-security-hardening.md
+  ✅ {PREFIX}-INT-002-god-class-decomposition.md
+  ❌ {PREFIX}-INT-003-di-refactoring.md    (missing)
+
+Approval Record:
+  ✅ {PREFIX}-Approvals.md                 (INT-001 ✅, INT-002 ✅, INT-003 ⏭ deferred)
+
+Issues Register:
+  ⚠️  {PREFIX}-Issues.md                   (N open, N fixed, N deferred)
+
+Process Log:
+  ✅ {PREFIX}-process-log.txt              (last entry: {timestamp})
+
+────────────────────────────────────────
+Current phase: Remediation in progress
+Next step:     Continue remediation or review open issues in {PREFIX}-Issues.md
+════════════════════════════════════════
+```

package/.claude/commands/check-docs.md

@@ -0,0 +1,18 @@
+---
+description: "Check Docs — quick consistency check between feature.md, requirements, and tech-spec. Reports only inconsistencies. Usage: /check-docs <feature-slug>"
+argument-hint: <feature-slug>
+allowed-tools: Read, Glob, Grep, Agent
+---
+
+Run a terse consistency check on the feature documents for `$ARGUMENTS`.
+
+Approach:
+1. Locate the feature folder under `docs/features/` (match by slug or FTR id).
+2. Spawn the `validate-feature-docs` agent and pass the feature.md path as input.
+3. From the agent's report, extract ONLY the inconsistencies. Skip the OK items, summaries, and recommendations.
+4. Render the inconsistencies as a bullet list with this exact format:
+   - `<doc>:<section>` — <one-line description of the gap>
+
+If there are no inconsistencies, output a single line: `✅ Docs are consistent.`
+
+Do not propose fixes. This command is a diagnostic, not a corrective.

package/.claude/commands/feature-status.md

@@ -0,0 +1,20 @@
+---
+description: "Feature Status — reports presence and state of all feature artifacts (feature.md, requirements, tech-spec, work breakdown, implementation). Usage: /feature-status <feature-slug>"
+argument-hint: <feature-slug>
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+Report the status of feature `$ARGUMENTS`.
+
+Steps:
+1. Locate the feature folder under `docs/features/`. Match by slug or FTR id (e.g. `FTR-001-user-login` matches both `001` and `user-login`).
+2. For each of the following artifacts, check presence and basic completeness:
+   - `feature.md` — the source brief
+   - `{PREFIX}-Requirements.md` — functional requirements
+   - `{PREFIX}-Tech-Spec.md` — technical specification
+   - `{PREFIX}-Work-Breakdown.md` — user stories + tasks
+   - Implementation status: cross-check tasks in the work breakdown against the codebase. For each task, report `done` / `partial` / `not started` based on whether the referenced files/symbols exist.
+3. Output a single markdown table with columns: `Artifact | Status | Notes`. Status uses ✅ / ⚠️ / ❌. Keep notes under 80 chars.
+4. After the table, list the next 1–3 actionable items in priority order.
+
+Do not spawn subagents. Do not modify files. Read-only operation.

package/.claude/commands/next-task.md

@@ -0,0 +1,37 @@
+---
+description: "Next Task — finds the next unblocked task in the active work breakdown and suggests which developer agent should handle it. Usage: /next-task [feature-slug]"
+argument-hint: "[feature-slug]"
+allowed-tools: Read, Glob, Grep
+---
+
+Identify the next unblocked task to work on.
+
+Steps:
+1. If `$ARGUMENTS` is provided, target that feature. Otherwise, list all feature folders under `docs/features/` and select the most recently modified one (use `git log -1 --format=%cd <path>` or filesystem mtime).
+2. Read `{PREFIX}-Work-Breakdown.md` in the chosen feature folder (where `{PREFIX}` matches the folder name pattern, e.g. `FTR-001`).
+3. Parse the task list. Identify the FIRST task that meets ALL these criteria, in order:
+   - Status is `pending` / `todo` / `not started` (not `done`, `in progress`, `blocked`)
+   - All listed dependencies (other task IDs) are marked `done`
+   - Not flagged as `BLOCKED` or `BLOCKED BY`
+4. Output a structured block:
+
+   ```
+   Feature: <slug>
+   Task ID: <id>
+   Domain: <DB | BE | FE | INFRA | TEST>
+   Title: <task title>
+
+   Suggested agent: <subagent_type>
+   Suggested invocation:
+     subagent_type: <developer-backend | developer-frontend | developer-testing>
+     prompt: <feature-md-path> <task-id>
+   ```
+
+   Domain → agent mapping:
+   - `DB`, `BE`, `INFRA` → `developer-backend`
+   - `FE` → `developer-frontend`
+   - `TEST` → `developer-testing`
+
+5. If no unblocked task remains, output: `✅ All tasks are either done, in progress, or blocked. Check blockers.`
+
+Do not spawn the agent automatically. Just suggest the invocation — the user decides when to delegate.

package/.claude/commands/pr-description.md

@@ -0,0 +1,34 @@
+---
+description: "PR Description — generates a pull request description from current branch commits and the linked feature.md. Usage: /pr-description"
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+Generate a pull request description for the current branch.
+
+Steps:
+1. Determine the current branch name: `git rev-parse --abbrev-ref HEAD`.
+2. Extract a feature identifier from the branch name (look for `FTR-XXX` or a slug pattern).
+3. Find the matching feature folder under `docs/features/`. If multiple match, ask the user.
+4. Read `feature.md` (and `{PREFIX}-Requirements.md` if present) for context.
+5. Collect the commits on this branch: `git log --no-merges $(git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD origin/master)..HEAD --pretty=format:"%h %s"`. If neither `main` nor `master` exists, ask the user for the base branch.
+6. Produce the PR description using this exact template:
+
+   ```markdown
+   ## Summary
+   <2–4 bullet points: what changed and why, framed from the feature.md goal>
+
+   ## Changes
+   <bullet list grouped by area: Backend / Frontend / DB / Tests / Docs — only include groups that have actual changes>
+
+   ## Test plan
+   - [ ] <concrete test step 1>
+   - [ ] <concrete test step 2>
+   - [ ] <concrete test step 3>
+
+   ## Linked feature
+   `docs/features/<folder>/feature.md`
+   ```
+
+7. Output ONLY the markdown above (no preamble, no postscript). The user will copy-paste it into the PR.
+
+If you cannot find a matching feature folder, fall back to generating the description from commits alone and note this in a single line above the output.

package/.claude/skills/assess-codebase/SKILL.md

@@ -0,0 +1,16 @@
+---
+description: "Assess Codebase — starts the full codebase assessment pipeline (parallel assessment → findings consolidation → intervention documents → approval gate → remediation → review → PR). Usage: /assess-codebase [path] [--scope=architecture,security,quality,concurrency,devops] [--force]"
+argument-hint: "[path] [--scope=architecture,security,quality,concurrency,devops] [--force]"
+disable-model-invocation: true
+---
+
+Spawn the `assessment-manager` agent with the arguments provided by the user:
+
+```
+subagent_type: assessment-manager
+prompt: <path> [--scope=...] [--force]
+```
+
+If no path is provided, use `.` (current working directory).
+
+Pass the exact arguments the user typed after `/assess-codebase` as the prompt to the agent. Do not add anything else.

package/.claude/skills/define-feature/SKILL.md

@@ -0,0 +1,13 @@
+---
+description: "Define Feature — grills the user to define a new feature, then writes feature.md in docs/features/FTR-XXX-slug/. Usage: /define-feature"
+disable-model-invocation: true
+---
+
+Spawn the `define-feature` agent with no additional arguments:
+
+```
+subagent_type: define-feature
+prompt: Start the feature definition session.
+```
+
+Do not add anything else. The agent handles discovery, grilling, and file creation autonomously.