@bonesofspring/ai-rules 0.2.15 → 0.2.17

package/presets/claude/android-kotlin/skills/technical-retro/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: technical-retro
+description: Facilitates technical retrospectives for tasks, sprints, incidents, releases, and agent-team pipelines. Use when the user asks for retro, postmortem, process review, or action items after delivery.
+---
+
+# Technical Retro
+
+## Inputs
+
+Ask for missing period, focus, task slug, participants, or format constraints. If a slug is provided, read `.claude/team/tasks/<slug>/` artifacts and local git status/diff. Do not invent facts not present in artifacts or the user's message.
+
+## Facilitation Principles
+
+- Focus on process and system behavior, not blame.
+- Separate facts, interpretations, and proposed actions.
+- Balance what worked with what slowed delivery.
+- Keep action items concrete, owned, and measurable.
+
+## Default Structure
+
+1. Goal and scope.
+2. Timeline or factual observations.
+3. What worked.
+4. What hurt quality, speed, or confidence.
+5. Root causes for the top one or two issues.
+6. Experiments and action items.
+
+## Agent Team Block
+
+For `/task` pipelines, include router, analyst, developer, **build-verifier** (./gradlew), reviewer, QA/Android instrumentation, hooks, and rules.
+
+## Wrong-turn taxonomy (optional)
+
+When artifacts or the user mention agent mistakes, tag incidents:
+
+| Kind | Signal |
+|------|--------|
+| `correction` | User pushback («no», «don't», «actually») |
+| `retry` | Same tool/approach 2+ times before success |
+| `waste` | Many searches before the right file |
+| `reversal` | Edit then revert / delete |
+| `dead-end` | Env/tool failure (missing binary, wrong path) |
+
+Severity: **high** (explicit correction / large waste) · **med** · **low**. Confidence 0–100 — be honest; low-confidence items are optional.
+
+## Preset feedback loop
+
+If the same issue appeared in **2+** tasks (or **3+** for packaging a new rule/skill — Rule of Three), add section **Preset updates**:
+
+- Proposed change to `.claude/rules/`, `.claude/agents/`, `.claude/skills/`, or **`.claude/team/conventions.md`** (prefer conventions for project gotchas)
+- One concrete snippet or file path
+- Whether it belongs in session-start vs `paths:` vs skill vs conventions (see `PRESET-CONTRIBUTION` → Building blocks)
+
+Do not apply preset or conventions changes without user approval.

package/presets/claude/android-kotlin/skills/unit-testing/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: unit-testing
+description: Plans, generates, and heals JUnit 4/5 (repo default) for mappers, use cases, and ViewModels using src/test and tests-unit rules. Use for unit test planning, generation, or fixing failing unit tests.
+---
+
+# Unit Testing (Android)
+
+## Project Layout
+
+- Unit targets: `src/test` (+ `androidTest` for instrumentation) colocated or parallel to Feature — **as in the Android Studio / AGP project**.
+- Framework: JUnit 4/5 (repo default) — MockK, Turbine, Truth/AssertJ as already configured.
+- Do **not** create Jest/Vitest `*.spec.ts` files.
+
+Follow `testing/unit.md` (Cursor `.mdc` / Claude `testing/unit.md` depending on preset).
+
+## Planner
+
+Write or update `.claude/team/tasks/<slug>/unit-test-plan.md`.
+
+Each scenario needs a Russian `test` / `@Test` title (capital letter after each sentence). Cover mappers, use cases, ViewModel state branches, and mocked client/repository behavior per AC.
+
+## Generator
+
+Implement tests from `unit-test-plan.md` into the correct `src/test` source set. Reuse shared fixtures and interface mocks / fakes (MockK). Do not change production code.
+
+## Healer
+
+Fix mocks, coroutine/dispatcher timing, and fixtures — preserve business assertions. Use `unit-test-plan.md` and `brief.md` as the behavior contract.
+
+## Validation
+
+Run affected unit tests via `./gradlew test` (`tooling-and-review/gradle-tooling.md`) when feasible. Report command, pass/fail, and remaining gaps vs plan.

package/presets/claude/android-kotlin/skills/write-adr/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: write-adr
+description: Author an Architecture Decision Record (ADR) with Context, Decision, Consequences, and Links. Use when capturing a durable technical choice for the team.
+---
+
+# Write ADR
+
+On-demand skill for durable architecture decisions. Stack-agnostic sections — fill with project-specific paths and links.
+
+## When to use
+
+- Choosing between non-trivial alternatives (storage, layering, library, API shape).
+- Recording a decision that future agents/humans should not silently reverse.
+- User asks for an ADR, decision log, or “why did we pick X”.
+
+## Template
+
+Create (or append) a short markdown ADR in the repo’s agreed location (e.g. `docs/adr/`, `.cursor/team/`, wiki). Suggested filename: `NNNN-short-title.md`.
+
+```markdown
+# ADR NNNN: <Title>
+
+## Context
+What problem / constraint / force requires a decision?
+
+## Decision
+What we chose (one clear option). Include rejected alternatives briefly if useful.
+
+## Consequences
+Positive and negative outcomes; follow-up work; what becomes harder.
+
+## Links
+Related PRs, issues, rules, prior ADRs, diagrams.
+```
+
+## Guidelines
+
+- Prefer one decision per ADR.
+- Keep Context factual; Decision imperative and short.
+- Link living gotchas to `team/conventions.md` when the decision becomes a recurring local pattern.
+- Do not put ADR bodies only in root `AGENTS.md` (overwrite on init).

package/presets/claude/android-kotlin/team/README.md

@@ -0,0 +1,54 @@
+# Agent team artifacts (android-kotlin)
+
+Artifact directory for the Android agent-team pipeline.
+
+## Layout
+
+```
+.claude/team/
+  active-task.json
+  fixtures/
+  tasks/<slug>/
+    pipeline.json
+    status.json
+    brief.md
+    decomposition.md
+    …
+```
+
+## Fixtures
+
+| Fixture | Notes |
+|---------|-------|
+| `feature-full.json` | Full profile; QA scope `e2e-only` = **Android instrumentation** |
+| `feature-light.json` | developer → build-verifier |
+| `bugfix-standard.json` | debugger → developer (skipIf) → verifier → reviewer |
+
+### `skipped[]` in fixtures
+
+`pipeline.json` / fixture `skipped` is **documentation of forbidden or non-applicable template stems** from other stacks (Playwright, XCUITest, JVM `integration-test-*`) — **not** agents that ran and were skipped at runtime, and **not** steps to schedule. Routers must never promote these stems into `steps[]`. For UI-test-only intents use `instrumentation-test-*`.
+
+**Never** schedule Playwright-only steps without skip rationale. Use `instrumentation-test-*` for UI-test-only intents.
+
+## Creating task dirs
+
+Bootstrap `tasks/<slug>/` by **writing** artifacts (Write tool), not Shell `mkdir`. Cursor sandbox → `Operation not permitted` otherwise (worse on Desktop/Documents).
+
+## Artifact manifest and receipts
+
+Each slug stores one context index at `.claude/team/tasks/<slug>/artifact-manifest.json`. Schema v1 is defined by shared core `agent-team/agent-artifact-contracts.md`: every entry declares its producer, status, authoritative paths, acceptance-criteria IDs, decomposition task IDs, timestamps, and a terminal completion receipt.
+
+Producer/consumer rules:
+
+- Read the manifest first and use only the authoritative inputs needed by the current step; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` when it is missing or stale, and report that gap.
+- Producers upsert only their stable entry IDs, preserve foreign entries, and finish with `completed`, `blocked`, `changes_requested`, or `validation_failed` receipt evidence.
+- The router owns `pipeline.json` and its routing entry; analyst, developer, verifier, and reviewer own their named outputs and receipts. Consumers do not edit another producer's receipt.
+- Agents do not mutate `status.json` or `metrics.json`. The orchestration runtime/hook is their single writer. Parallel receipt merges are serialized by the parent/orchestrator.
+
+## Local metrics ledger
+
+`metrics.json` is an append-only schema-v1 event ledger for one task run. It contains only allowlisted IDs, task dimensions, timestamps, outcomes, and attribution confidence—never prompts, secrets, file paths, or contents. The orchestration runtime writes `task_started` / `attempt_started`; the hook records host-clock completion and human-gate edges under a per-task lock with temp-and-rename.
+
+`status.json.activeAttempts` is a transient timing bridge keyed by `attemptId`; `lastCompletedAttempt` is diagnostic; `parallelOutcomes` holds per-agent outcomes for the current parallel join until the step advances. For parallel stops, the hook must use a stable payload identity or the sole active attempt. Otherwise an explicit `.metrics-receipts.json` receipt is fallback data marked `source: agent`, `attributionConfidence: fallback`; it must never guess from `currentAgent`.
+
+Aggregate with `node packages/ai-rules/scripts/aggregate-agent-task-metrics.mjs --team-root .claude/team`. It reports role/agent count, completed count, total/average duration, distinct completed run IDs, separate human-gate wait, and incomplete artifacts.

package/presets/claude/android-kotlin/team/conventions.md

@@ -0,0 +1,17 @@
+# Team conventions (consumer-local)
+
+After installing this preset, document **local** names and paths here. Do not put vendor/brand names into the shared preset packages.
+
+## Suggested entries
+
+| Concern | Local name / path |
+|---------|-------------------|
+| ViewModel base class | _(fill)_ |
+| Feature DI holder / component types | _(fill)_ |
+| Design-system package | _(fill)_ |
+| App shell module(s) under `applications/` | _(fill)_ |
+| Default product flavor / variant for local builds | _(fill)_ |
+| Instrumentation test base / robot pattern | _(fill)_ |
+| Documented Gradle wrapper (if not `./gradlew`) | _(fill)_ |
+
+Keep this file consumer-owned; `ai-rules init` may overwrite other preset files but conventions are meant to accumulate local decisions.

package/presets/claude/android-kotlin/team/fixtures/bugfix-standard.json

@@ -0,0 +1,47 @@
+{
+  "slug": "example-bugfix-standard",
+  "intent": "bugfix",
+  "profile": "standard",
+  "summary": "Bugfix with unit coverage and optional instrumentation",
+  "steps": [
+    {
+      "agent": "task-analyst",
+      "label": "Clarify repro and AC"
+    },
+    {
+      "agent": "debugger",
+      "label": "Reproduce and locate root cause"
+    },
+    {
+      "agent": "feature-developer",
+      "label": "Minimal fix + unit test",
+      "scope": "unit-in-dev"
+    },
+    {
+      "agent": "build-verifier",
+      "label": "Gradle compile + lint + unit smoke",
+      "model": "cheap"
+    },
+    {
+      "agent": "code-reviewer",
+      "label": "Code review",
+      "model": "cheap"
+    }
+  ],
+  "humanGates": [],
+  "autoChain": true,
+  "skipped": [
+    {
+      "agent": "playwright-test-planner",
+      "reason": "Android uses instrumentation-test-*"
+    },
+    {
+      "agent": "xcuitest-test-planner",
+      "reason": "iOS-only"
+    },
+    {
+      "agent": "instrumentation-test-planner",
+      "reason": "No UI AC \u2014 add if regression is UI-only"
+    }
+  ]
+}

package/presets/claude/android-kotlin/team/fixtures/feature-full.json

@@ -0,0 +1,97 @@
+{
+  "slug": "example-feature-full",
+  "intent": "feature",
+  "profile": "full",
+  "summary": "Multi-layer feature with Android instrumentation coverage",
+  "steps": [
+    {
+      "agent": "task-analyst",
+      "label": "Clarify and decompose"
+    },
+    {
+      "agent": "solution-architect",
+      "label": "Design boundaries",
+      "model": "strong"
+    },
+    {
+      "agent": "feature-developer",
+      "label": "Implement + unit tests",
+      "scope": "unit-in-dev"
+    },
+    {
+      "agent": "build-verifier",
+      "label": "Gradle compile + lint + unit smoke",
+      "model": "cheap"
+    },
+    {
+      "agent": "security-reviewer",
+      "label": "Security review",
+      "model": "strong"
+    },
+    {
+      "agent": "code-reviewer",
+      "label": "Code review",
+      "model": "cheap"
+    },
+    {
+      "agent": "accessibility-reviewer",
+      "label": "Compose a11y",
+      "model": "cheap"
+    },
+    {
+      "agent": "instrumentation-test-planner",
+      "label": "Plan instrumentation UI tests"
+    },
+    {
+      "agent": "instrumentation-test-generator",
+      "label": "Generate instrumentation tests"
+    },
+    {
+      "agent": "instrumentation-test-healer",
+      "label": "Heal flaky instrumentation",
+      "model": "cheap"
+    }
+  ],
+  "humanGates": [
+    "after:task-analyst"
+  ],
+  "autoChain": true,
+  "skipped": [
+    {
+      "agent": "playwright-test-planner",
+      "reason": "Android uses instrumentation-test-* \u2014 not Playwright"
+    },
+    {
+      "agent": "playwright-test-generator",
+      "reason": "Android uses instrumentation-test-*"
+    },
+    {
+      "agent": "playwright-test-healer",
+      "reason": "Android uses instrumentation-test-*"
+    },
+    {
+      "agent": "xcuitest-test-planner",
+      "reason": "iOS-only"
+    },
+    {
+      "agent": "xcuitest-test-generator",
+      "reason": "iOS-only"
+    },
+    {
+      "agent": "xcuitest-test-healer",
+      "reason": "iOS-only"
+    },
+    {
+      "agent": "integration-test-planner",
+      "reason": "JVM backend pattern \u2014 not Android UI"
+    },
+    {
+      "agent": "integration-test-generator",
+      "reason": "JVM backend pattern"
+    },
+    {
+      "agent": "integration-test-healer",
+      "reason": "JVM backend pattern"
+    }
+  ]
+}

package/presets/claude/android-kotlin/team/fixtures/feature-light.json

@@ -0,0 +1,38 @@
+{
+  "slug": "example-feature-light",
+  "intent": "feature",
+  "profile": "light",
+  "summary": "Trivial single-file change with explicit AC",
+  "steps": [
+    {
+      "agent": "feature-developer",
+      "label": "Implement",
+      "model": "cheap"
+    },
+    {
+      "agent": "build-verifier",
+      "label": "Gradle compile + lint + unit smoke",
+      "model": "cheap"
+    }
+  ],
+  "humanGates": [],
+  "autoChain": true,
+  "skipped": [
+    {
+      "agent": "task-analyst",
+      "reason": "Explicit AC and single-file scope"
+    },
+    {
+      "agent": "code-reviewer",
+      "reason": "Light profile \u2014 non-trivial app changes should use standard"
+    },
+    {
+      "agent": "instrumentation-test-planner",
+      "reason": "No UI AC"
+    },
+    {
+      "agent": "playwright-test-planner",
+      "reason": "Android uses instrumentation-test-*"
+    }
+  ]
+}

package/presets/claude/go/agents/build-verifier.md

@@ -40,3 +40,6 @@ Document PASS/FAIL in `validation-report.md`.
 - **Owned outputs:** `validation-report.md`; upsert only the manifest entry assigned by handoff (`artifactOutputId`; fallback `validation`) and preserve all foreign entries.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `validation_failed`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.
+
+13. **Product-specs assets (FAIL):** package must ship `presets/_shared/assets/docs-specs/INDEX.md`, `_templates/page.md`, `_templates/feature.md`. Cursor+Claude twins for `product-specs` and `product-specs-authoring` must embed matching shared-core markers; both stems **requestable** (`alwaysApply: false` / Claude `paths: docs/specs/**`) — never session-start.
+14. **Optional consumer check (WARN default):** `scripts/check-product-specs.sh` + schema stub may exist for opt-in consumer CI; **FAIL** only with `--strict` or AC that requires named specs — do not force consumer CI.

package/presets/claude/go/agents/code-reviewer.md

@@ -18,6 +18,8 @@ Apply skill `code-review` and `code-review-mr.mdc`. Weigh `architecture-boundari
 
 ## Review focus (Go hexagonal)
 
+- If the MR touches `docs/specs/**`, load **`product-specs`** (+ **`product-specs-authoring`** when new/changed specs): **WARN** code/spec drift; **FAIL** broken INDEX `path` link or missing required frontmatter keys/arrays on touched spec files; required body headings missing → **FAIL** on touched files. Do not invent missing product behavior.
+
 - **Layers:** domain has no HTTP/SQL/framework imports; application defines ports and has no concrete adapters; handlers map DTO↔domain at the edge only.
 - **DI:** composition root in `cmd/` / `internal/app` — no business logic in wiring.
 - **Errors / context:** `%w` wrapping; `context.Context` on I/O boundaries; no swallowed errors.

package/presets/claude/go/agents/feature-developer.md

@@ -46,6 +46,13 @@ Update `.claude/team/tasks/<slug>/implementation.md` and the owned implementatio
 
 - When writing or changing code, load / follow rule `anti-sycophancy-discipline`.
 
+## Product specs (docs/specs)
+
+When work touches a page/feature/route/alias: if `docs/specs/INDEX.md` exists (or brief lists approved specs), load **`product-specs`** and treat **approved** specs from brief/handoff as **behavior SoT**. Soft-fail on miss (`open_questions` + code / `.ai/context` fallback); **never invent** product behavior.
+
+Mechanical INDEX/frontmatter fixes only when implementation renames routes/ids. Substantive behavior edits → hand back to task-analyst (or tech-writer where present). If INDEX is absent and generation was not approved, treat specs as optional (greenfield).
+
+
 ## Artifact contract
 
 - **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for `brief.md`, `decomposition.md`, current scope, and applicable prior findings.

package/presets/claude/go/agents/task-analyst.md

@@ -24,6 +24,25 @@ Emit an analysis receipt; the runtime applies any configured human gate.
 
 - Optional: Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit — only when decomposing refactor/architecture tasks (not default).
 
+## Product specs (docs/specs)
+
+**Consume (default):** When work touches a page/feature/route/alias and `docs/specs/INDEX.md` exists, load **`product-specs`**, resolve the linked page/feature spec, and cite it under **Related specs** in `brief.md`. Soft-fail on miss (`open_questions` + code / `.ai/context` fallback); **never invent** product behavior. If INDEX is absent, treat specs as optional unless author mode applies.
+
+**Author mode (Generate / Bootstrap):** When the user runs `/spec-start`, router intent is `spec-gen` / bootstrap, or brief/AC requests generation: load **`product-specs`** + **`product-specs-authoring`** and skill **`spec-authoring`**. You are the **primary author** (INDEX bootstrap included). Follow frontmatter v1 + required headings; update INDEX in the **same change set**; default `status: draft`. Block handoff via `open_questions` until the authoring self-check passes.
+
+### Brief sections (when author mode or INDEX exists)
+
+Add to `brief.md`:
+
+```markdown
+## Related specs
+- path or id (or N/A)
+
+## Spec gaps / generation requested
+- [ ] none | generate | bootstrap — sources: …
+```
+
+
 ## Artifact contract
 
 - **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume `pipeline.json`, the manifest routing entry, user-approved decisions, and any authoritative architecture/approval entries.

package/presets/claude/go/agents/task-router.md

@@ -89,6 +89,17 @@ Write `.claude/team/tasks/<slug>/pipeline.json` and initialize the routing entry
 
 Intent + steps table + skipped + gates → invoke `steps[0].agent` (unless retro).
 
+## Spec generation intents
+
+Detect and set routing reasons when the user asks to **generate / bootstrap product specs**, mentions `docs/specs`, or runs `/spec-start`:
+
+| Signal | Intent | Steps |
+|--------|--------|-------|
+| `/spec-start`, "bootstrap docs/specs", "generate product spec" | `spec-gen` | task-analyst (**author mode**) → human gate → stop (or continue to feature-developer only if implement-after) |
+| Feature/task with AC "generate specs" / missing INDEX + bootstrap AC | `spec-gen` inside feature profile | task-analyst author mode first; **not** a separate agent step |
+
+Do **not** add a dedicated `spec-author` agent. Do not require solution-architect for routine spec authoring.
+
 ## Runtime initialization
 
 Return the routing receipt to the orchestrator. The orchestration runtime/hook exclusively initializes and updates `status.json`, `metrics.json`, attempt identities, and gate lifecycle; the router does not write those shared runtime files.

package/presets/claude/go/agents/tech-writer.md

@@ -13,3 +13,8 @@ Write documentation from task artifacts (brief, architecture, implementation, re
 - For ai-rules preset tasks: update PRESET-CONTRIBUTION / package README as scoped — docs only.
 
 Do not change production `.go` business logic.
+
+## Product specs (docs/specs)
+
+Post-delivery: when behavior or public docs changed and `docs/specs/` is in play, load **`product-specs`** (+ **`product-specs-authoring`** if updating specs). Sync page/feature specs + INDEX in the **same change set**. **Never invent** product behavior without AC/code source; label inferred lines `status: draft`. Soft-fail on miss; no-op if INDEX absent and sync not requested.
+

package/presets/claude/go/commands/feature-continue.md

@@ -37,6 +37,7 @@ Legacy command to continue after a human gate. For new pipelines with `pipeline.
 3. Call subagent **feature-developer** with context:
    - paths to `brief.md`, `decomposition.md`, `status.json`;
    - instruction to follow `rules/architecture/feature-delivery-workflow.md`.
+   - if `docs/specs/INDEX.md` exists: load **`product-specs`** and honor **Related specs** from `brief.md` (soft-fail on miss; never invent behavior).
 
 4. After the developer finishes, continue review → QA per `rules/tooling-and-review/agent-team-orchestrator.md`.
 

package/presets/claude/go/commands/feature-start.md

@@ -16,11 +16,19 @@ Starts the **analysis phase** for a new task. For new work, prefer `/task` becau
 5. Invoke subagent **task-analyst** with the full task description and artifact paths.
 6. Wait for the analyst to finish. **Do not invoke developer** at this stage.
 
+## Product specs (docs/specs)
+
+When invoking **task-analyst**: if `docs/specs/INDEX.md` exists, instruct consume via **`product-specs`** and cite **Related specs**. Soft-fail on miss; never invent behavior.
+
+If the user/AC requests generation or bootstrap, or INDEX is missing **with** bootstrap AC / `/spec-start` intent: instruct **author mode** inside the same analyst step — load **`product-specs-authoring`** + skill **`spec-authoring`**. Authoring is **not** a separate pipeline agent. Handoff must list created paths + INDEX diff; human gate must approve generated specs before feature-developer.
+
+
 ## Human gate
 
 After the analyst:
 
 - Show the user links to `brief.md` and `decomposition.md`.
+- Also ask them to check **Related specs** in `brief.md` when `docs/specs/INDEX.md` exists.
 - Ask them to review and approve or send edits.
 - To continue: `/feature-continue <slug>` or `/task-continue <slug>`.
 

package/presets/claude/go/commands/spec-start.md

@@ -0,0 +1,29 @@
+---
+name: spec-start
+description: Bootstrap or generate docs/specs (INDEX + page/feature) via task-analyst author mode. Optional docs-only path with human gate.
+---
+
+# Spec start — generate / bootstrap product specs
+
+Routes intent **`spec-gen`** (or bootstrap) → **task-analyst** in **author mode** → human gate (`after:task-analyst`) → stop, or continue to feature-developer if the user asked to implement after.
+
+## What to do
+
+1. Extract description from arguments after `/spec-start` (domain, page/feature ids, sources).
+2. Generate a **slug** (kebab-case, ≤48 chars), e.g. `spec-<domain>-<id>`.
+3. Ensure `.claude/team/tasks/<slug>/` exists (Write artifacts; not Shell mkdir).
+4. Write `.claude/team/active-task.json` → `{ "slug": "<slug>" }`.
+5. Write minimal `pipeline.json`: task-analyst → (optional stop) → feature-developer only if user asked implement-after. **No separate spec-author agent.**
+6. Invoke **task-analyst** with: author mode; load **`product-specs`** + **`product-specs-authoring`** + skill **`spec-authoring`**; Bootstrap if `docs/specs/` absent, else Generate.
+7. Wait for analyst. **Do not** invoke feature-developer until human gate passes.
+
+## Human gate
+
+- Show created/updated spec paths and INDEX diff.
+- Ask user to approve drafts (`status: draft` → promote) or send edits.
+- Continue: `/task-continue <slug>` only after approval when implementation follows; otherwise stop after docs.
+
+## Notes
+
+- Greenfield invent of INDEX is allowed **only** via this command, explicit ask, or AC bootstrap language.
+- mcp-ts: analyst-only author/sync (no tech-writer).

package/presets/claude/go/commands/task-continue.md

@@ -40,11 +40,14 @@ printf '%s\n' '{"status":"completed","action":"end_human_gate","activateNext":tr
 
 | Agent | Read |
 |-------|------|
-| feature-developer | brief.md, decomposition.md, validation-report.md (if retry), review.md (if retry), architecture.md |
+| feature-developer | brief.md (incl. **Related specs**), decomposition.md, validation-report.md (if retry), review.md (if retry), architecture.md; if `docs/specs/INDEX.md` exists → load **`product-specs`** |
 | build-verifier | git diff, decomposition.md |
 | code-reviewer | brief.md, validation-report.md, git diff |
 | qa-tester | brief.md, decomposition.md, scope from pipeline step |
 
-## Metrics
+## Product specs (docs/specs)
+
+When the next agent is **feature-developer** (or other implementer): if `docs/specs/INDEX.md` exists or brief lists approved specs, instruct them to load **`product-specs`** and honor **Related specs** / approved generated specs as behavior SoT. Soft-fail on miss; never invent product behavior.
+
+If analyst ran **author mode**, confirm human approved drafts before developer. Pass spec paths + INDEX diff in the handoff. No-op if INDEX is absent and no approved specs.
 
-On human-gate resume, the hook action above appends `human_gate_ended` under the per-task lock **before** any new `attempt_started`. Agents must not calculate durations.

package/presets/claude/go/rules/README.md

@@ -49,6 +49,8 @@ Claude topic `.md` files are **derived** from Cursor SoT `presets/cursor/go/rule
 | `preset-token-budget.mdc` | `tooling-and-review/preset-token-budget.md` |
 | `preset-twin-sync.mdc` | `tooling-and-review/preset-twin-sync.md` |
 | `reference-features.mdc` | `architecture/reference-features.md` |
+| `product-specs.mdc` | `architecture/product-specs.md` |
+| `product-specs-authoring.mdc` | `architecture/product-specs-authoring.md` | Generate/Bootstrap; requestable |
 | `security-go.mdc` | `tooling-and-review/security-go.md` |
 | `technical-retro.mdc` | `tooling-and-review/technical-retro.md` |
 | `tests-e2e.mdc` | `testing/e2e.md` |

package/presets/claude/go/rules/architecture/feature-delivery.md

@@ -49,3 +49,7 @@ flowchart LR
 - Framework types in domain; SQL in use cases; DI inside handlers; skipping port interfaces “for speed”.
 - **Ubiquitous language:** Domain names/boundaries reflect the feature domain — do not mix transport/framework terms into domain without need.
 - Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.
+
+## Related
+
+- Product behavior discovery: requestable **`product-specs`** (`docs/specs/INDEX.md`) — do not paste the discovery algorithm here.