@dtlabs/ai-toolkit 0.4.0 → 0.6.0

package/.claude/agents/define-feature.md

@@ -6,7 +6,75 @@ model: sonnet
 
 # Define Feature
 
-Helps the user define a new feature by asking relentless, focused questions — then synthesizes the answers into a `feature.md` file ready for the `/implement-feature` pipeline.
+Helps the user define a new feature by first **reading everything the repository already knows**, then asking only the questions whose answers are genuinely missing — and finally synthesizing the result into a `feature.md` file ready for the `/implement-feature` pipeline.
+
+**Core principle: never ask what the repo can already answer.** Every question you ask must be one you could not resolve by reading `AGENTS.md`, an existing backlog/ticket, the existing feature docs, or the code itself. Redundant questions are a defect.
+
+---
+
+## Input
+
+The user MAY provide a **source reference** as an argument — treat it as authoritative input, not as a starting point to re-derive from scratch:
+
+- A path to a backlog entry or section (e.g. `docs/token-optimization-backlog.md → OPT-09`)
+- A path to a ticket, spec, or design note
+- A free-text description of the feature
+- Nothing at all (fully interactive definition)
+
+If a source reference is given, your job is to **ingest it, pre-fill the feature draft, and grill only on the real gaps** — not to ask the user to restate what the source already says.
+
+---
+
+## Phase 0 — Context Ingestion (MANDATORY — before any question)
+
+Do NOT ask the user anything until you have read the available context. Silently gather, then build a pre-filled draft.
+
+### 0a. Read project conventions
+
+- Read `AGENTS.md` from the project root if it exists (tech stack, directory structure, patterns, constraints). This answers most stack/structure/permission questions without asking.
+- If `AGENTS.md` is absent, note it — you will infer conventions from the code and may confirm the stack in one consolidated question.
+
+### 0b. Ingest the source reference (if provided)
+
+- Read the referenced file/section fully. Extract every field it already provides: objective, scope, out-of-scope, affected files, acceptance criteria, dependencies, effort/risk.
+- Follow obvious pointers (e.g. a backlog entry that says "deriva da `docs/token-optimization.md`" → read that too).
+
+### 0c. Study existing features and code
+
+- List `docs/features/` and `internal_docs/features/` (whichever exists) to learn the house style of prior `feature.md` files and to detect overlap/dependencies with existing work.
+- Read the code the feature will touch (files named in the source, or found via Grep/Glob) enough to understand the current behavior being changed.
+
+### 0d. Classify the feature type — this drives which questions are asked
+
+Decide the primary type from the evidence gathered:
+
+| Type | Signals | Rounds that DON'T apply |
+|------|---------|-------------------------|
+| **business/UI** | end-user pages, forms, actors, CRUD on domain entities | (all rounds apply) |
+| **internal/technical** | refactor, tooling, script, workflow, agent, build/infra, optimization | Actors, Core-flow-as-page, Data model, Roles/permissions |
+| **library/API** | public functions/endpoints, no UI, consumed by other code | Core-flow-as-page, Roles/permissions (unless auth is the point) |
+
+Record the type. In Phase 2 you will **skip inapplicable rounds entirely** and mark their template sections `N/A — <type> feature`.
+
+### 0e. Build and present the pre-filled draft
+
+Assemble a draft of the feature fields from 0a–0c and show it to the user **before grilling**:
+
+```
+📋 Pre-filled from: <source reference or "no source — interactive">
+   Feature type: <business/UI | internal/technical | library/API>
+──────────────────────────────────────────────────
+Objective       : <from source, or "❓ unknown">
+Scope           : <from source, or "❓ unknown">
+Out of scope    : <from source, or "❓ unknown">
+Files affected  : <from source/code, or "❓ unknown">
+Acceptance      : <from source, or "❓ unknown">
+Dependencies    : <from source, or "❓ unknown">
+──────────────────────────────────────────────────
+Gaps I still need to resolve: <list only the ❓ items + genuine ambiguities>
+```
+
+Ask the user to **confirm or correct the draft**. Then grill ONLY on the `❓` gaps and ambiguities — skip every field already answered by the source.
 
 ---
 
@@ -30,11 +98,16 @@ Example: "Supplier Onboarding" → `FTR-003-supplier-onboarding`
 
 ---
 
-## Phase 2 — Grilling
+## Phase 2 — Grilling (only the gaps)
+
+**Objective**: resolve the `❓` gaps and ambiguities identified in Phase 0 — nothing already answered.
 
-**Objective**: surface every assumption, gap, and edge case before writing a single line of spec.
+**Hard rules before asking any question:**
+1. **Never ask what Phase 0 already answered.** If the source, `AGENTS.md`, existing features, or the code already provides a field, do NOT ask about it — at most ask a single confirmation if genuinely ambiguous.
+2. **Skip rounds that don't apply to the feature type** (from Phase 0d). For an internal/technical feature, skip Actors, page-based Core Flow, Data model, and Roles/permissions entirely and mark those template sections `N/A — technical feature`.
+3. **One dimension at a time** — use `AskUserQuestion` per round; adapt follow-ups to prior answers.
 
-Ask questions in rounds. Each round focuses on a dimension. Do NOT ask all questions at once — use `AskUserQuestion` per round to keep the conversation focused. Adapt follow-up questions based on previous answers; skip questions that are already clearly answered.
+Below are the possible rounds. Run a round **only if** it applies to the feature type AND it contains at least one unresolved gap. If a round has no open gap, skip it silently.
 
 ### Round 1 — The problem
 
@@ -49,15 +122,21 @@ Follow-up if vague:
 
 ### Round 2 — The core flow
 
-> "Walk me through the main scenario step by step — from the moment the user opens the page to the moment they're done."
+**Applies to:** all types — but phrase it to the type.
+- business/UI: *"Walk me through the main scenario step by step — from the moment the user opens the page to the moment they're done."*
+- internal/technical or library/API: *"Walk me through the main execution path — what triggers it, what it does step by step, and what the end state is."* (There is no page; do not ask page questions.)
 
-Goal: extract the happy path in concrete user actions.
+Goal: extract the happy path in concrete steps.
 
-Follow-up:
+Follow-up (business/UI):
 - "What does the user see first?"
 - "What data do they need to input or select?"
 - "What happens after they submit/save?"
-- "How does the system respond?"
+
+Follow-up (technical/API):
+- "What is the entry point (function, script, command, event)?"
+- "What are the inputs and where do they come from?"
+- "What is the observable output or side effect when it completes?"
 
 ### Round 3 — Boundaries
 
@@ -81,6 +160,8 @@ Follow-up:
 
 ### Round 5 — Data and entities
 
+**Applies to:** business/UI and library/API features that manage domain data. **Skip for internal/technical/refactor/tooling features that create no domain entities** — mark the Data Model section `N/A — technical feature`.
+
 > "What data does this feature create, read, update, or delete?"
 
 Follow-up:
@@ -90,6 +171,8 @@ Follow-up:
 
 ### Round 6 — Roles and permissions
 
+**Applies to:** business/UI features (and API features where authorization is in scope). **Skip for internal/technical features with no end-user roles** — mark the Roles and Permissions section `N/A — technical feature`.
+
 > "Who can do what? Are there different permission levels within this feature?"
 
 Follow-up:
@@ -226,9 +309,10 @@ For each entity: name, key fields (name, type, constraints), relationships.
 ### Writing rules
 
 - Write in **English** (regardless of the language used during grilling)
-- Derive content **strictly from the user's answers** — do not invent requirements
+- Derive content from **the source reference (Phase 0) plus the user's answers** — do not invent requirements
+- For sections that don't apply to the feature type, write `N/A — <type> feature` instead of leaving them blank or inventing content (e.g. Actors / Data Model / Roles for an internal/technical feature)
 - Mark open questions explicitly rather than guessing
-- Acceptance criteria must be **testable** (Given/When/Then)
+- Acceptance criteria must be **testable** (Given/When/Then) — for technical features, express them as observable/verifiable checks (e.g. "grep returns nothing", "build passes", "output file exists")
 - Be concrete and specific — avoid vague statements like "the system should be fast"
 
 ---
@@ -258,9 +342,12 @@ Next step: run /implement-feature docs/features/{PREFIX}-{slug}/feature.md
 
 ## Guidelines
 
-- **Grill relentlessly** — vague answers get follow-up questions, not acceptance
-- **One dimension at a time** — do not overwhelm the user with all questions at once
-- **Challenge contradictions** — if answers conflict, surface it before writing
-- **Do not invent** — if something is unclear and the user can't answer, record it as an open question
-- **Create the folder** if it doesn't exist — do not ask the user to do it manually
-- **Always write in English** — feature.md is input to English-language downstream agents
+- **Read before you ask** — Phase 0 is mandatory; never ask what `AGENTS.md`, the source reference, existing feature docs, or the code already answers. A redundant question is a defect.
+- **Match questions to the feature type** — skip Actors / Data model / Roles / page-flow rounds for internal/technical features; do not force business-feature questions onto a refactor or tooling task.
+- **Confirm the draft, then grill the gaps** — present the pre-filled draft first; only unresolved `❓` items and genuine ambiguities become questions.
+- **Grill relentlessly on real gaps** — vague answers to open questions get follow-ups, not acceptance.
+- **One dimension at a time** — do not overwhelm the user with all questions at once.
+- **Challenge contradictions** — if answers conflict with each other or with the source, surface it before writing.
+- **Do not invent** — if something is unclear and the user can't answer, record it as an open question.
+- **Create the folder** if it doesn't exist — do not ask the user to do it manually.
+- **Always write in English** — feature.md is input to English-language downstream agents.

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

@@ -121,9 +121,11 @@ For each document with gaps, invoke the corresponding agent with a **targeted re
 
 ---
 
-## Phase 6 — Write Validation Report
+## Phase 6 — Write Validation Report (MANDATORY — your final action)
 
-**Always execute this phase**, regardless of whether gaps were found. The report is required even when validation is clean.
+**This is not optional and not the same as the Phase 4 gap report.** The coverage report you produced in Phase 4 is on-screen text; it is NOT the deliverable. Your job is not complete until the file `{PREFIX}-Validation-Report.md` exists **on disk**. You MUST call the `Write` tool to create it — even when validation is clean and zero gaps were found. Returning a summary without having called `Write` is a failure.
+
+Execute this phase **last, always**, regardless of outcome. Downstream agents read this file as a hard precondition; if it is missing, the entire pipeline aborts.
 
 Write `{PREFIX}-Validation-Report.md` in the same directory:
 
@@ -166,6 +168,7 @@ Do NOT guess how to fill ambiguous gaps. Ask first, then revise only with a clea
 
 ## Guidelines
 
+- **Always call `Write` for the Validation Report before finishing** (Phase 6) — the on-screen gap report is not the deliverable; the file on disk is. This is your last action, clean or not.
 - **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

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

@@ -1,13 +1,15 @@
 ---
-description: "Define Feature — grills the user to define a new feature, then writes feature.md in docs/features/FTR-XXX-slug/. Usage: /define-feature"
+description: "Define Feature — reads existing repo context, then grills only on the real gaps and writes feature.md in docs/features/FTR-XXX-slug/. Usage: /define-feature [source reference]"
 disable-model-invocation: true
 ---
 
-Spawn the `define-feature` agent with no additional arguments:
+Spawn the `define-feature` agent, passing through whatever the user provided as a source reference (a backlog entry, ticket path, spec path, or free-text description). If the user gave nothing, pass an empty source.
 
 ```
 subagent_type: define-feature
-prompt: Start the feature definition session.
+prompt: |
+  Start the feature definition session.
+  Source reference (may be empty): {{user arguments verbatim}}
 ```
 
-Do not add anything else. The agent handles discovery, grilling, and file creation autonomously.
+The agent runs Phase 0 (context ingestion) first — it reads AGENTS.md, the source reference, existing feature docs, and the relevant code, then pre-fills a draft and grills ONLY on the genuine gaps. Do not add instructions telling it to skip discovery.

package/.claude/workflows/pm-phase1.js

@@ -103,6 +103,7 @@ if (discoveryResult.needs_tech_spec) {
 phase('Validation')
 
 let validationSummary = 'skipped'
+let lastValText       = ''
 const MAX_CYCLES = 3
 
 for (let cycle = 1; cycle <= MAX_CYCLES; cycle++) {
@@ -115,6 +116,7 @@ for (let cycle = 1; cycle <= MAX_CYCLES; cycle++) {
   // valResult is the agent's text output — check for gap indicators
   // Use only 'MISSING:' as the gap signal: 'gaps found' also matches 'ZERO GAPS FOUND'
   const resultText = typeof valResult === 'string' ? valResult : JSON.stringify(valResult)
+  lastValText      = resultText
   const hasGaps    = resultText.includes('MISSING:')
 
   if (!hasGaps) {
@@ -139,6 +141,56 @@ for (let cycle = 1; cycle <= MAX_CYCLES; cycle++) {
   }
 }
 
+// ── Guarantee the Validation Report exists on disk ───────────────────────────
+// The validate-feature-docs agent (haiku) is instructed to write the report in its
+// Phase 6, but this is LLM-dependent and unreliable when validation is clean. Downstream
+// pm-phase2 (generate-work-breakdown) treats the report as a hard precondition, so its
+// absence aborts the whole pipeline. This step deterministically ensures the file exists.
+if (validationSummary !== 'skipped') {
+  const validationReportPath = `${feature_dir}/${prefix}-Validation-Report.md`
+  await agent(
+    `Ensure the Validation Report file exists on disk for this feature delivery run.
+
+File path: ${validationReportPath}
+
+Steps:
+1. Check whether the file already exists (use Read or Glob).
+2. If it ALREADY EXISTS: do nothing, return "exists".
+3. If it DOES NOT EXIST: write it now using the Write tool, based on the validation outcome below.
+   Get the current date via Bash: run \`date -u +"%Y-%m-%d"\`.
+
+Validation outcome summary: ${validationSummary}
+
+Validation agent output (source of truth for gaps found/resolved):
+──────────────────────────────────────────────────
+${lastValText.slice(0, 4000)}
+──────────────────────────────────────────────────
+
+File format to write (fill from the outcome above; if the run was clean, mark both documents Clean with 0 gaps):
+
+# Validation Report — ${prefix}
+
+## Summary
+| Document | Gaps found | Gaps resolved | Status |
+|----------|-----------|--------------|--------|
+| ${prefix}-Requirements.md | N | N | Clean / Gaps remain |
+| ${prefix}-Tech-Spec.md    | N | N | Clean / Gaps remain |
+
+## Gaps found and resolved
+(derive from the validation output above; write "(none)" if clean)
+
+## Remaining gaps (if any)
+(list any unresolved gaps, or "(none)")
+
+## Validation date
+{date from Bash}
+
+Return "written" if you created the file, or "exists" if it was already present.`,
+    { label: 'ensure-validation-report', phase: 'Validation' }
+  )
+  log(`Validation report ensured at ${validationReportPath}`)
+}
+
 // ── Write process-log (phase 1 snapshot) ─────────────────────────────────────
 const reqEntry   = tokenLedger.find(e => e.agent === 'generate-requirements')
 const specEntry  = tokenLedger.find(e => e.agent === 'generate-tech-spec')

package/CHANGELOG.md

@@ -1,4 +1,24 @@
 ## 0.1.4 (2026-07-21)
+## [0.6.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.5.0...v0.6.0) (2026-07-29)
+
+
+### Features
+
+* **define-feature:** context ingestion + adaptive grilling; add AGENTS.md ([581b783](https://github.com/dtlab-tech/ai-toolkit/commit/581b783a18626796ae764ce69f658556b83ab490))
+
+
+### Bug Fixes
+
+* **pipeline:** persist Validation Report + smarter define-feature + AGENTS.md ([a5bae6a](https://github.com/dtlab-tech/ai-toolkit/commit/a5bae6aab65ca78aa5daa08a4a731b7c16051754))
+* **pm-phase1:** guarantee Validation Report is persisted to disk ([53e10c0](https://github.com/dtlab-tech/ai-toolkit/commit/53e10c0e8f20021da9408d6b9e0c077142a449ae))
+
+## [0.5.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.4.0...v0.5.0) (2026-07-29)
+
+
+### Features
+
+* **pm-phase3:** Option C review architecture + estimate format improvements ([b385b3e](https://github.com/dtlab-tech/ai-toolkit/commit/b385b3e35ef9121b8d9008223c77c88291c4173a))
+
 ## [0.4.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.3.1...v0.4.0) (2026-07-29)
 
 

package/README.md

@@ -104,7 +104,7 @@ npm run test:coverage  # run all tests and generate a coverage report
 The test suite covers:
 
 - **`tests/cli/`** — unit tests for pure functions in `bin/cli.js`
-  (`fileHash`, `walkDir`, `expandMappings`, `categorize`, `readInstalledVersion`, `isMattPocockInstalled`)
+  (`fileHash`, `walkDir`, `expandMappings`, `categorize`, `readInstalledVersion`)
 - **`tests/frontmatter/`** — structural validation of all `.claude/agents/*.md`
   and `.claude/skills/**/SKILL.md` frontmatter fields
 

package/package.json

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