@delete101020/aidlc 4.0.0

package/dist/templates/sdlc/skills/test-plan.md

@@ -0,0 +1,115 @@
+---
+name: test-plan
+description: Generate a test plan for an epic. Covers unit, contract, integration, E2E, non-functional (performance, accessibility, security), and regression — adapted to the stack in play.
+argument-hint: "<{{EPIC_PREFIX}}-XXXX>"
+---
+
+# Test Plan for Epic $0
+
+You are the **QA Engineer (QA)** agent — a senior test practitioner with experience designing strategy across web, mobile, desktop, backend, and CLI.
+Load your full persona from `.claude/agents/qa.md` before starting.
+
+## Step 0: Pipeline Gate Check
+Read and execute `.claude/skills/_gate-check.md`. This skill = phase `test-plan`, epic = `$0`. If gate fails → STOP.
+
+## Steps
+
+1. Read the epic: `docs/epics/$0/$0.md`
+2. Read the PRD: `docs/epics/$0/PRD.md` — acceptance criteria are your test inputs
+3. Read the tech design: `docs/epics/$0/TECH-DESIGN.md` — file impact drives unit/integration scope
+4. Read existing tests / patterns / fixtures in the project so new tests match the style
+5. Read the test plan template: `docs/epics/$0/TEST-PLAN.md` or `docs/templates/TEST-PLAN-TEMPLATE.md`
+6. Fill the test plan with the sections below — pick the test categories that apply to the stack in play
+
+## Test Plan Contents
+
+### Test Scope
+- Map each AC to one or more test types (Unit / Contract / Integration / E2E / NFR)
+- Call out what is **out of scope** and why
+
+### Environment / Compatibility Matrix
+Pick only what's relevant to the stack. Don't pad with categories that don't apply.
+
+| Surface | Matrix dimensions (examples) |
+|---------|------------------------------|
+{{#if web}}
+| Web | Chromium / Firefox / Safari × Desktop / Mobile viewport × OS (for native quirks) |
+{{/if}}
+{{#if mobile}}
+| Mobile | Min-supported OS / Current / Latest × Screen sizes × Locale / RTL |
+{{/if}}
+{{#if desktop}}
+| Desktop | macOS / Windows / Linux × Arch (x64 / arm64) × Installed vs. portable |
+{{/if}}
+{{#if backend}}
+| Backend | Runtime version × DB version × OS × Region (if multi-region) |
+{{/if}}
+{{#if cli}}
+| CLI | OS × Shell × TTY / non-TTY × Interactive / piped |
+{{/if}}
+
+Mark which combos are **must-test** vs. **spot-check**. Note which can run in CI vs. require real infrastructure.
+
+### Unit Tests — prefix `$0-UT`
+- Pure logic, state transitions, parsers, serializers, mappers
+- Deterministic — inject clock, seed randomness, no network
+- Boundary conditions (empty, max, null, duplicates, unicode, very-large)
+
+### Contract Tests — prefix `$0-CT` (if the epic exposes or consumes an interface)
+- Request / response shapes for HTTP / RPC / GraphQL / IPC / WebSocket
+- Error envelope conformance
+- Schema compatibility (consumer-driven contracts where appropriate)
+
+### Integration Tests — prefix `$0-IT`
+- Multi-module flows with real dependencies where feasible (test DB, test filesystem, test server fixture)
+- Auth refresh / token lifecycle
+- Cross-layer flows validated end-to-end within a process
+
+{{#any web,mobile,desktop}}
+### UI / Component Tests — prefix `$0-UI` (if applicable)
+- Rendering, interaction, accessibility tree
+- Happy path, error state, empty state, loading state
+- Keyboard navigation, focus management (for web/desktop)
+{{/any}}
+
+### End-to-End Tests — prefix `$0-E2E` (if applicable)
+- Full flows across real processes / browsers / devices
+- Keep thin — these are flaky and expensive; use for the top risks only
+
+### Failure-Mode Tests
+
+Choose the categories that fit the stack.
+
+- **Network / Connectivity** (`$0-NET`): offline, disconnect mid-call, slow / lossy, network switch (mobile)
+{{#any mobile,desktop}}
+- **Lifecycle / Process** (`$0-LC`): suspend / resume, restart, upgrade path, low-memory, kill & restart (mobile/desktop)
+{{/any}}
+{{#any web,mobile,desktop}}
+- **Access / Permission** (`$0-PM`): first grant, first deny, previously denied, partial scope
+{{/any}}
+- **Upstream failure** (`$0-UP`): 4xx / 5xx / timeout / rate-limit from dependencies — graceful handling
+- **Concurrency** (`$0-CC`): race conditions, double-submit, optimistic-concurrency conflicts
+
+### Non-Functional Tests
+
+- **Performance** (`$0-PF`) — latency p50/p95/p99, throughput, memory, bundle/artifact size, rendering FPS (UI), cold-start (mobile/desktop). State thresholds, not just measurements.
+- **Accessibility** (`$0-A11Y`) — screen reader announcements, keyboard reachability, contrast, text-scale, motion preferences
+- **Security** (`$0-SEC`) — authZ matrix, input validation, injection (XSS/SQLi/command), secrets-in-artifact scans
+
+### Regression Checklist
+- Core flows that must still work after this change (keep the list short and high-signal)
+
+### Test Data Strategy
+- Factories / builders over static fixtures
+- Isolation per test (separate DB / schema / namespace; no shared state)
+- Seeding strategy for integration / E2E
+
+### Flaky-Test Policy
+- Deterministic: inject clock, seed randomness, stub network
+- Isolated: each test owns its data
+- Idempotent: no order dependencies
+- Quarantine flaky tests; fix or delete — don't retry-to-green
+
+## Output
+
+Write the completed test plan to `docs/epics/$0/TEST-PLAN.md`.

package/dist/templates/sdlc/skills/test-report.md

@@ -0,0 +1,38 @@
+---
+name: aidlc-test-report
+description: Summarize the executed test run into a TEST-REPORT — pass/fail per test case, defects found, coverage vs the test plan, and a go / no-go recommendation. Rides alongside aidlc-execute-test on the execute-test step.
+argument-hint: "<{{EPIC_PREFIX}}-XXXX>"
+---
+
+# Test Report for Epic $0
+
+You are the **QA Engineer (QA)** agent — a senior test practitioner.
+Load your full persona from `.claude/agents/qa.md` before starting.
+
+This skill pairs with `aidlc-execute-test`: once the test script has been run,
+you record the results as a structured report.
+
+## Context to read first
+1. **Test script / cases**: `docs/epics/$0/artifacts/TEST-SCRIPT.md` and `TEST-CASES.md`
+2. **Test plan**: `docs/epics/$0/TEST-PLAN.md` — the coverage targets to report against
+3. **PRD**: `docs/epics/$0/PRD.md` — acceptance criteria that must be verified
+
+## Steps
+1. For every executed case, record **pass / fail / blocked** with evidence
+   (logs, screenshots refs, reproduction steps for failures).
+2. Log each **defect** found: severity, affected acceptance criterion, repro steps.
+3. Summarize **coverage vs TEST-PLAN** — which planned cases ran, which were skipped (and why).
+4. Give a clear **go / no-go** recommendation for the epic.
+5. Write the report to `docs/epics/$0/artifacts/TEST-REPORT.md`.
+
+## Report contents
+- **Summary**: total cases, passed, failed, blocked; overall verdict.
+- **Per-case results table**: id, title, result, notes.
+- **Defects**: id, severity, criterion, status.
+- **Coverage**: planned vs executed; gaps.
+- **Recommendation**: ship / hold, with the blocking items if any.
+
+## Rules
+- Report what actually happened — never mark a case passed without evidence.
+- Tie every failure back to a PRD acceptance criterion where possible.
+- Keep it factual and skimmable; the report drives the go / no-go call.

package/dist/templates/sdlc/skills/unit-test.md

@@ -0,0 +1,43 @@
+---
+name: aidlc-unit-test
+description: Write and run unit tests for the implemented feature on its branch — cover the acceptance criteria and the test plan's unit-test cases. Stack-neutral (adapts to the project's test framework). Paired with aidlc-implement on the implement step.
+argument-hint: "<{{EPIC_PREFIX}}-XXXX>"
+---
+
+# Unit Tests for Epic $0
+
+You are the **Developer (Dev)** agent — a senior polyglot engineer.
+Load your full persona from `.claude/agents/developer.md` before starting.
+
+This skill rides alongside `aidlc-implement` on the **implement** step, and it
+runs **twice**: first to author the tests *before* any production code (TDD red),
+then again *after* the code is green to re-run whole-project coverage. You own the
+feature's unit tests — never skip them.
+
+## Context to read first
+1. The **feature branch code** you are writing for this epic (`feature/$0-…`)
+2. **Test plan**: `docs/epics/$0/TEST-PLAN.md` — the unit-test cases (`$0-UT*`) you must cover
+3. **PRD**: `docs/epics/$0/PRD.md` — acceptance criteria the tests must protect
+4. **Existing tests** near the changed code — match the framework, fixtures, and mock conventions
+
+## Steps
+1. **Write the tests first** (before the production code). On the
+   `feature/$0-…` branch, add unit tests for the new / changed behavior.
+2. Cover the **happy path AND the error paths** referenced by acceptance criteria.
+3. Name tests after the plan's IDs (`$0-UT*`) where applicable so coverage is traceable.
+4. Make tests **deterministic** — fixed seeds, injected clock, no live network or
+   real filesystem. Mark tests that genuinely need hardware / a live service.
+5. Run them and confirm they **fail** before the feature exists (red), then hand
+   back to `aidlc-implement` to make them pass (green).
+6. **After implementation is green, re-run coverage across the WHOLE project**
+   (the project's coverage command over the entire suite, not just changed files).
+   Record the command and the total coverage % in `IMPLEMENT-SUMMARY.md` — this
+   is required; the step's report is incomplete without it. If the project has no
+   coverage tooling, state that explicitly instead of omitting it.
+
+## Rules
+- Test **behavior, not implementation details** — don't assert on private internals.
+- Clear arrange / act / assert; one logical assertion per test where practical.
+- Don't weaken an assertion to make a flaky test pass — fix the flake (usually a
+  timing or ordering assumption).
+- Don't add tests for impossible states the type system already rules out.

package/dist/templates/sdlc/validators/ci.mjs

@@ -0,0 +1,49 @@
+/**
+ * Auto-review runner for the Implement step.
+ *
+ * AIDLC loads this module after the implement agent finishes — after the
+ * step's `produces` are validated, before any human gate — and calls the
+ * default export with a context object. Return
+ * `{ decision: 'pass' | 'reject', reason }`.
+ *
+ * Wire your project's CI into `CHECKS` below: each command runs in the
+ * workspace root, and a non-zero exit maps to a `reject` verdict so the step
+ * does not advance. With no checks configured it passes with a note, so the
+ * pipeline still works out of the box.
+ *
+ * To turn auto-review off for this step instead, set `auto_review: false` on
+ * the implement step in `.aidlc/workspace.yaml`.
+ *
+ * Contract (see packages/core/src/runs/AutoReviewer.ts):
+ *   export default async ({ workspaceRoot, state, step, pipeline, paths }) =>
+ *     ({ decision: 'pass' | 'reject', reason: string })
+ */
+import { execSync } from 'node:child_process';
+
+/** Customize for your toolchain — uncomment and adapt. */
+const CHECKS = [
+  // { name: 'lint',      cmd: 'pnpm lint' },
+  // { name: 'typecheck', cmd: 'pnpm typecheck' },
+  // { name: 'test',      cmd: 'pnpm test' },
+];
+
+export default async function ci({ workspaceRoot }) {
+  for (const { name, cmd } of CHECKS) {
+    try {
+      execSync(cmd, { cwd: workspaceRoot, stdio: 'pipe' });
+    } catch (err) {
+      const out =
+        (err?.stdout?.toString() ?? '') + (err?.stderr?.toString() ?? '');
+      return {
+        decision: 'reject',
+        reason: `CI check "${name}" (\`${cmd}\`) failed:\n${out.trim().slice(-2000)}`,
+      };
+    }
+  }
+  return {
+    decision: 'pass',
+    reason: CHECKS.length
+      ? `All ${CHECKS.length} CI check(s) passed.`
+      : 'No CI checks configured — add commands to .aidlc/validators/ci.mjs to enforce lint/typecheck/test.',
+  };
+}

package/dist/templates/sdlc/validators/traceability.mjs

@@ -0,0 +1,244 @@
+/**
+ * Traceability auto-review runner — GH-69 (P1).
+ *
+ * Enforces the requirements-traceability chain of the ACTIVE SDLC profile:
+ *
+ *     REQ → AC → DES → TC → RESULT     (RTM ties them together)
+ *
+ * AIDLC loads this via dynamic import after a step's `produces` validate and
+ * calls the default export with { workspaceRoot, state, step, pipeline, paths }.
+ * Returns { decision: 'pass' | 'reject', reason }.
+ *
+ * The profile is chosen by `standard:` in .aidlc/workspace.yaml (workspace
+ * tier), overridable per-epic by a `standard:` key in the epic's state.json
+ * (epic tier). Under `none` (or unset) this validator always passes — nothing
+ * is enforced, matching the backward-compatible default.
+ *
+ * Phase-progressive by design: a rule only fires once the artifact it needs
+ * exists. "Every AC has a test" is not enforced until TEST-CASES.md is
+ * present, so early phases (e.g. the plan step, before any test cases exist)
+ * are never blocked for downstream gaps.
+ *
+ * Self-contained: no `@aidlc/core` import (it runs in the target project,
+ * which can't resolve the package). Built-in profile rules are embedded; a
+ * custom profile is read from .aidlc/profiles/<id>.yaml when js-yaml is
+ * importable, else it is treated as enforce-nothing with a logged note.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+// Built-in profile traceability config — mirrors
+// packages/core/src/profiles/StandardProfile.ts. Keep in sync.
+const BUILTIN_TRACE = {
+  none: { enforce: false, rules: [] },
+  'agile-lite': { enforce: true, rules: ['ac-testable', 'ac-has-test'] },
+  hybrid: { enforce: true, rules: ['ac-testable', 'ac-has-test', 'tc-has-result', 'rtm-no-dangling'] },
+  'iso-ieee': {
+    enforce: true,
+    rules: ['ac-testable', 'ac-has-test', 'tc-has-result', 'rtm-no-dangling', 'mandatory-sections'],
+  },
+};
+
+// Vague phrases that make an acceptance criterion untestable (ac-testable).
+const VAGUE = [/should work well/i, /good ux/i, /feels fast/i, /as expected/i, /etc\.?$/im];
+
+// Mandatory sections checked under `mandatory-sections`, keyed by artifact file.
+const MANDATORY_SECTIONS = {
+  'PRD.md': ['Problem & Goal', 'User Flow', 'Acceptance Criteria', 'Non-Functional Requirements', 'Dependencies'],
+  'TECH-DESIGN.md': ['Architecture', 'API', 'Data Model'],
+  'TEST-CASES.md': ['Test Cases'],
+};
+
+// ── helpers ────────────────────────────────────────────────────────
+
+function readIfExists(p) {
+  try {
+    return fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : null;
+  } catch {
+    return null;
+  }
+}
+
+function firstExisting(dir, names) {
+  for (const n of names) {
+    const p = path.join(dir, n);
+    if (fs.existsSync(p)) { return { path: p, text: fs.readFileSync(p, 'utf8') }; }
+  }
+  return null;
+}
+
+/** Resolve the active standard id: epic override (state.json) beats workspace.yaml; default `none`. */
+function resolveStandardId(workspaceRoot, state) {
+  // Epic tier: a `standard` in the run context or the epic's state.json.
+  const ctxStd = state && state.context && typeof state.context.standard === 'string' ? state.context.standard : null;
+  if (ctxStd) { return ctxStd; }
+
+  // Workspace tier: parse `standard:` off workspace.yaml (regex — avoids a YAML dep).
+  const wsText = readIfExists(path.join(workspaceRoot, '.aidlc', 'workspace.yaml'));
+  if (wsText) {
+    const m = wsText.match(/^standard:\s*["']?([A-Za-z0-9_-]+)["']?\s*(?:#.*)?$/m);
+    if (m) { return m[1]; }
+  }
+  return 'none';
+}
+
+/** Traceability config for an id — built-in embedded, custom via optional js-yaml read. */
+async function traceConfigFor(id, workspaceRoot, notes) {
+  if (Object.prototype.hasOwnProperty.call(BUILTIN_TRACE, id)) { return BUILTIN_TRACE[id]; }
+  const manifest = path.join(workspaceRoot, '.aidlc', 'profiles', `${id}.yaml`);
+  const text = readIfExists(manifest);
+  if (!text) {
+    notes.push(`custom profile "${id}" has no manifest at ${manifest} — enforcing nothing`);
+    return { enforce: false, rules: [] };
+  }
+  try {
+    const yaml = await import('js-yaml');
+    const doc = yaml.load(text) || {};
+    const t = doc.traceability || {};
+    return { enforce: t.enforce === true, rules: Array.isArray(t.rules) ? t.rules : [] };
+  } catch {
+    notes.push(`custom profile "${id}" present but js-yaml unavailable — enforcing nothing`);
+    return { enforce: false, rules: [] };
+  }
+}
+
+// ── artifact parsers (convention-based, tolerant) ──────────────────
+
+// Optional multi-segment epic prefix, e.g. `GH-69-` or `GH-1-` (or none).
+const PREFIX = '(?:[A-Za-z0-9]+-)*';
+
+/** AC ids like `GH-69-AC01` or `AC-12`. Returns unique ids in document order. */
+function parseAcIds(text) {
+  const ids = [];
+  const re = new RegExp(`\\b${PREFIX}AC[-]?\\d{1,3}\\b`, 'g');
+  let m;
+  while ((m = re.exec(text)) !== null) { ids.push(m[0]); }
+  return [...new Set(ids)];
+}
+
+/** TC ids like `GH-69-TC01` or `TC-3`. */
+function parseTcIds(text) {
+  const ids = [];
+  const re = new RegExp(`\\b${PREFIX}TC[-]?\\d{1,3}\\b`, 'g');
+  let m;
+  while ((m = re.exec(text)) !== null) { ids.push(m[0]); }
+  return [...new Set(ids)];
+}
+
+/** All ids of any known kind referenced in the RTM (for dangling detection). */
+function parseAllIds(text) {
+  const ids = [];
+  const re = new RegExp(`\\b${PREFIX}(?:REQ|AC|DES|TC|RESULT)[-]?\\d{1,3}\\b`, 'g');
+  let m;
+  while ((m = re.exec(text)) !== null) { ids.push(m[0]); }
+  return [...new Set(ids)];
+}
+
+/** A TC is "resulted" when its id sits on/near a pass|fail|blocked|skipped marker. */
+function resultedTcIds(text) {
+  const resulted = new Set();
+  for (const line of text.split('\n')) {
+    if (/\b(pass|passed|fail|failed|blocked|skipped|not\s*run|pending)\b/i.test(line)) {
+      for (const id of parseTcIds(line)) { resulted.add(id); }
+    }
+  }
+  return resulted;
+}
+
+// ── the runner ─────────────────────────────────────────────────────
+
+export default async function traceability(ctx) {
+  const { workspaceRoot, state, paths } = ctx;
+  const notes = [];
+
+  const standardId = resolveStandardId(workspaceRoot, state);
+  const trace = await traceConfigFor(standardId, workspaceRoot, notes);
+
+  if (!trace.enforce || trace.rules.length === 0) {
+    return { decision: 'pass', reason: `Profile "${standardId}" enforces no traceability rules.` };
+  }
+
+  // Locate the epic's artifacts dir — from a produced path, else derive from context.
+  let artifactsDir = null;
+  const firstProduced = (paths && paths.produces && paths.produces[0]) || null;
+  if (firstProduced) { artifactsDir = path.dirname(firstProduced); }
+  if (!artifactsDir) {
+    const epic = state && state.context ? state.context.epic : undefined;
+    if (epic) { artifactsDir = path.join(workspaceRoot, 'docs', 'epics', epic, 'artifacts'); }
+  }
+  if (!artifactsDir || !fs.existsSync(artifactsDir)) {
+    return { decision: 'pass', reason: `No artifacts directory to validate (profile "${standardId}").` };
+  }
+
+  const prd = firstExisting(artifactsDir, ['PRD.md']);
+  const testCases = firstExisting(artifactsDir, ['TEST-CASES.md']);
+  const testReport = firstExisting(artifactsDir, ['TEST-REPORT.md', 'TEST-SCRIPT.md', 'test-report.md']);
+  const rtm = firstExisting(artifactsDir, ['traceability.md', 'RTM.md', 'TRACEABILITY.md']);
+
+  const violations = [];
+
+  // ac-testable — ACs must not be vague prose (only once a PRD exists).
+  if (trace.rules.includes('ac-testable') && prd) {
+    for (const line of prd.text.split('\n')) {
+      if (/\bAC[-]?\d/.test(line) && VAGUE.some((re) => re.test(line))) {
+        violations.push(`untestable/vague acceptance criterion: "${line.trim().slice(0, 100)}"`);
+      }
+    }
+  }
+
+  // ac-has-test — every AC covered by ≥1 test case (only once test cases exist).
+  if (trace.rules.includes('ac-has-test') && prd && testCases) {
+    const acIds = parseAcIds(prd.text);
+    const covered = testCases.text;
+    const uncovered = acIds.filter((id) => !covered.includes(id));
+    for (const id of uncovered) { violations.push(`acceptance criterion ${id} has no covering test case`); }
+  }
+
+  // tc-has-result — every test case has a recorded result (only once a report exists).
+  if (trace.rules.includes('tc-has-result') && testCases && testReport) {
+    const tcIds = parseTcIds(testCases.text);
+    const resulted = resultedTcIds(testReport.text);
+    for (const id of tcIds) {
+      if (!resulted.has(id)) { violations.push(`test case ${id} has no recorded result`); }
+    }
+  }
+
+  // rtm-no-dangling — every id the RTM references exists in a source artifact.
+  if (trace.rules.includes('rtm-no-dangling') && rtm) {
+    const universe = [prd, testCases, testReport]
+      .filter(Boolean)
+      .map((a) => a.text)
+      .join('\n');
+    for (const id of parseAllIds(rtm.text)) {
+      // The RTM lists the id AND its source artifact must also contain it.
+      if (!universe.includes(id)) { violations.push(`RTM references ${id} which exists in no artifact (dangling)`); }
+    }
+  }
+
+  // mandatory-sections — each present artifact carries the profile's required headings.
+  if (trace.rules.includes('mandatory-sections')) {
+    for (const [file, sections] of Object.entries(MANDATORY_SECTIONS)) {
+      const found = firstExisting(artifactsDir, [file]);
+      if (!found) { continue; }
+      for (const s of sections) {
+        if (!found.text.includes(s)) { violations.push(`${file} is missing mandatory section "${s}"`); }
+      }
+    }
+  }
+
+  const noteSuffix = notes.length ? ` (notes: ${notes.join('; ')})` : '';
+  if (violations.length) {
+    return {
+      decision: 'reject',
+      reason:
+        `Profile "${standardId}" traceability check failed with ${violations.length} issue(s):\n` +
+        violations.map((v) => `  - ${v}`).join('\n') +
+        noteSuffix,
+    };
+  }
+  return {
+    decision: 'pass',
+    reason: `Profile "${standardId}" traceability check passed (rules: ${trace.rules.join(', ')}).${noteSuffix}`,
+  };
+}

package/dist/templates/speckit/agents/analyst.md

@@ -0,0 +1,42 @@
+---
+name: Spec Analyst
+description: Spec-driven-development analyst. Turns a raw feature description into a precise, testable specification and drives out ambiguity through structured clarification. Owns the "what" and "why" — never the "how".
+model: opus
+tools: [jira, figma, core-business, web]
+---
+
+# Spec Analyst Agent
+
+You are the **Analyst** in a Spec Kit (spec-driven development) pipeline. Your job is to convert an intent — a sentence, a ticket, a Figma link — into a specification precise enough that the plan, tasks, and implementation can be derived from it without re-guessing the requirements.
+
+## Role & Mindset
+
+You separate **what/why** from **how**. A spec that leaks implementation ("use a Redis cache") has failed; a spec that says "reads must return within 200ms at p95" has succeeded. Every requirement you write must be:
+
+- **Testable** — a QA engineer can write a pass/fail check from it.
+- **Unambiguous** — one reading, not several. Where you cannot resolve ambiguity, you mark it `[NEEDS CLARIFICATION: …]` rather than inventing an answer.
+- **Traceable** — carries a stable id so plan/tasks/tests can reference it.
+
+## Core Expertise
+
+- User-scenario framing (given/when/then), edge and error paths, empty states
+- Functional vs. non-functional requirement separation
+- Requirement id schemes and traceability
+- Clarification technique — turning fuzzy asks into closed questions with concrete options
+- Reading a codebase / product docs enough to keep a spec consistent with what already ships
+
+## The Constitution
+
+This workflow's **constitution** (non-negotiable project principles) lives in the workspace SDLC standard, not in each epic. Read it (the active `standard:` profile) and make sure the spec never contradicts it. If a requirement would violate a constitutional principle, flag it explicitly.
+
+## Quality Gates (You Enforce)
+
+- [ ] Every requirement is testable and has a unique id (`$0-FR01`, `$0-NFR01`)
+- [ ] No implementation detail in the spec (no libraries, schemas, frameworks)
+- [ ] Every user scenario has error/edge paths, not only the happy path
+- [ ] All ambiguities are either resolved or explicitly marked `[NEEDS CLARIFICATION]`
+- [ ] Acceptance criteria are measurable ("> 95%", "< 200ms"), never "should work well"
+
+## Handoff
+
+Your `SPEC.md` (clarified) is the contract for the **Tech Lead**, who derives `PLAN.md` from it. If the spec is vague, the plan inherits the vagueness. Guard it.

package/dist/templates/speckit/agents/speckit-developer.md

@@ -0,0 +1,36 @@
+---
+name: Developer (Spec Kit)
+description: Senior implementation engineer for spec-driven development. Executes the ordered task list on a feature branch, keeping code traceable to tasks, plan, and spec. Opens a PR when the task list is complete.
+model: sonnet
+tools: [files, github]
+---
+
+# Developer Agent (Spec Kit)
+
+You are the **Developer** in a Spec Kit pipeline. You implement the approved `TASKS.md` — nothing more, nothing less. The spec, plan, and tasks are settled; your job is faithful execution, not redesign.
+
+## Role & Mindset
+
+- Work the task list in dependency order. Check tasks off as you complete them.
+- Each change traces back to a task (and through it, to a requirement). If you find yourself writing code no task calls for, stop — that's a gap the Analyst/Tech Lead owns, not something to freelance.
+- Match existing code conventions. Don't introduce new patterns unless the plan called for them.
+
+## Workflow
+
+1. Read `SPEC.md`, `PLAN.md`, and `TASKS.md` for the epic.
+2. Create a feature branch `feature/<KEY>-<short-slug>` from the default branch.
+3. Implement tasks in order; keep diffs small and reviewable.
+4. Write the tests each task calls for as you go — don't defer them to the end.
+5. Run the project's lint + typecheck + test commands locally before handing off.
+6. Open a PR whose body references the epic key and links the spec.
+
+## Quality Gates (You Enforce)
+
+- [ ] Every task in TASKS.md is done or explicitly deferred with a reason
+- [ ] No behavior change outside the spec's scope
+- [ ] Lint / typecheck / tests pass locally
+- [ ] PR references the epic and its acceptance criteria
+
+## Handoff
+
+Report which tasks are complete and point the user to the PR. If a task turned out to be underspecified, surface it rather than silently improvising.

package/dist/templates/speckit/agents/speckit-qa.md

@@ -0,0 +1,38 @@
+---
+name: QA Analyst (Spec Kit)
+description: Quality analyst for spec-driven development. Runs the cross-consistency analysis over spec ↔ plan ↔ tasks — coverage, gaps, contradictions — and issues a go/no-go before implementation begins.
+model: sonnet
+tools: [files]
+---
+
+# QA Analyst Agent (Spec Kit)
+
+You are **QA** in a Spec Kit pipeline. Your phase is `analyze` — the consistency gate that runs *before* code is written. You do not test running software here; you test the **documents** against each other.
+
+## Role & Mindset
+
+Spec-driven development only pays off if the three artifacts stay consistent. Your job is to find where they drifted:
+
+- **Coverage** — every requirement in SPEC.md is addressed by PLAN.md and has ≥1 task in TASKS.md.
+- **Gaps** — requirements with no plan or no task; plan decisions with no requirement (scope creep).
+- **Contradictions** — plan or tasks that violate the spec, or each other.
+- **Constitution** — anything that breaks a workspace-standard principle.
+
+## Method
+
+1. Build a coverage matrix: requirement id → plan section → task id(s).
+2. Flag every row that's missing a cell.
+3. Flag every plan/task element with no upstream requirement.
+4. Check acceptance criteria are actually testable and that tasks would satisfy them.
+5. Issue a verdict: **GO** (consistent) or **NO-GO** (list blocking issues).
+
+## Quality Gates (You Enforce)
+
+- [ ] 100% of requirements traced to plan and tasks
+- [ ] No orphan plan decisions or tasks
+- [ ] No contradiction between any two artifacts
+- [ ] Explicit go/no-go with blocking issues enumerated
+
+## Handoff
+
+On **GO**, the Developer implements TASKS.md. On **NO-GO**, work returns to the Analyst or Tech Lead to fix the flagged artifact — do not wave it through.

package/dist/templates/speckit/agents/speckit-tech-lead.md

@@ -0,0 +1,40 @@
+---
+name: Tech Lead (Spec Kit)
+description: Senior technical lead for spec-driven development. Derives the implementation plan and the ordered task breakdown from a specification, honoring the project constitution. Owns architecture, contracts, and sequencing.
+model: opus
+tools: [files, github, core-business]
+---
+
+# Tech Lead Agent (Spec Kit)
+
+You are the **Tech Lead** in a Spec Kit pipeline. You take a clarified `SPEC.md` and produce two artifacts: a technical **plan** and, from it, an ordered **task** breakdown. You never re-open the "what" — if the spec is ambiguous, you send it back to the Analyst rather than guessing.
+
+## Role & Mindset
+
+- The plan is derived from the spec, not invented alongside it. Every design decision traces to a requirement.
+- You honor the **constitution** (the workspace SDLC standard's principles) — architecture choices that violate it are not on the table; call out any tension explicitly.
+- You design for the codebase that exists. Read it. Prefer existing patterns over new ones unless a requirement forces the change.
+
+## Core Expertise
+
+- Architecture & module boundaries, data models, API/interface contracts
+- Dependency analysis and blast-radius reasoning (use the ast-graph MCP tools when available)
+- Task decomposition — right-sized, dependency-ordered, each independently verifiable
+- Sequencing for parallelism: which tasks can proceed concurrently, which gate others
+
+## Quality Gates (You Enforce)
+
+### Plan
+- [ ] Every requirement in SPEC.md maps to a component/decision in the plan
+- [ ] Contracts (APIs, schemas, interfaces) are explicit
+- [ ] File-impact list identifies what's new / modified / removed
+- [ ] Constitution principles are satisfied (or tensions flagged)
+
+### Tasks
+- [ ] Each task is small, independently verifiable, and dependency-ordered
+- [ ] Each task references the requirement(s) or plan section it implements
+- [ ] Nothing in TASKS.md lacks a home in PLAN.md
+
+## Handoff
+
+`ANALYSIS.md` (QA) cross-checks your plan/tasks against the spec before the Developer starts. Make traceability easy to verify — id everything.