From 30697e90ad5b1b4a97bfe88e6229d30733db0a61 Mon Sep 17 00:00:00 2001 From: Chris Pezza <153260989+chrispezza@users.noreply.github.com> Date: Mon, 12 Oct 2026 13:59:49 -0400 Subject: [PATCH] chore(checks): graduate twelve checks to block and correct stale records ADR 0012's graduation rule (7+ consecutive clean days) had been met since late July and never executed, so no finding could fail CI or reach an agent through the Stop-gate. - Flip twelve structural checks warn -> block; keep manifest, word-limit and self-containment at warn with reasons recorded in ADR 0012 - Append dated graduation log entries to each owning ADR - Append amendments to ADRs 0003, 0004, 0008 and 0013 recording what later ADRs changed (census of 6 commands, 5 skills, 2 subagents; registry extensions; reverse-pass checks that had already landed) - Remove references to the deleted MCP server and pre-ADR 0011 script paths from the PR and bug templates, README, scripts README and CONTRIBUTING - Remove docs/skills/, eight specs for the superseded eight-skill design Co-Authored-By: Claude Opus 5.5 --- .github/ISSUE_TEMPLATE/bug_report.md | 15 +-- .github/pull_request_template.md | 22 +-- CHANGELOG.md | 4 + CONTRIBUTING.md | 8 +- README.md | 14 +- checks/README.md | 12 +- checks/enforcement.config.json | 24 ++-- docs/adrs/0001-prompt-frontmatter-schema.md | 10 ++ docs/adrs/0002-mcp-prompt-packaging.md | 10 ++ .../0003-context-registry-state-management.md | 30 +++++ .../adrs/0004-skill-subagent-decomposition.md | 28 ++++ docs/adrs/0005-prompt-enhancement-schema.md | 10 ++ ...rogressive-disclosure-tiered-engagement.md | 10 ++ docs/adrs/0007-json-index-deprecation.md | 10 ++ docs/adrs/0008-plugin-architecture.md | 21 +++ docs/adrs/0009-prompt-enhancement-pattern.md | 12 ++ .../0010-spec-package-compilation-target.md | 11 ++ .../adrs/0012-adr-enforcement-architecture.md | 40 ++++++ .../adrs/0013-ux-optimization-reverse-pass.md | 26 ++++ .../0014-live-site-audit-and-objective.md | 9 ++ docs/skills/evaluate.md | 47 ------- docs/skills/flow.md | 44 ------ docs/skills/hypothesis.md | 60 --------- docs/skills/idea.md | 125 ------------------ docs/skills/problem.md | 68 ---------- docs/skills/prototype.md | 47 ------- docs/skills/spec.md | 58 -------- docs/skills/status.md | 63 --------- scripts/README.md | 23 ++-- 29 files changed, 295 insertions(+), 566 deletions(-) delete mode 100644 docs/skills/evaluate.md delete mode 100644 docs/skills/flow.md delete mode 100644 docs/skills/hypothesis.md delete mode 100644 docs/skills/idea.md delete mode 100644 docs/skills/problem.md delete mode 100644 docs/skills/prototype.md delete mode 100644 docs/skills/spec.md delete mode 100644 docs/skills/status.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index f934d49..f9ee336 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -25,19 +25,18 @@ What you thought would happen. - Plugin version: - Claude Code surface: - Python version (if `/compile` related): -- Node version (if MCP server related): - OS: ## Component -- [ ] Plugin command (`/idea`, `/problem`, `/spec`, `/compile`, `/summary`) -- [ ] Skill (product-ideation, product-flow, tech-spec, status) -- [ ] Tech-spec subagent +- [ ] Plugin command (`/idea`, `/problem`, `/spec`, `/compile`, `/summary`, `/optimize`) +- [ ] Skill (product-ideation, product-flow, tech-spec, ux-optimization, status) +- [ ] Subagent (tech-spec-writer, ux-extractor) - [ ] Prompt content (specify file path) -- [ ] Compilation pipeline (`scripts/compile_spec.py`) -- [ ] Validation pipeline (`scripts/validate_spec.py`) -- [ ] Handoff generator (`scripts/generate_handoff.py`) -- [ ] MCP server (`mcp/prompt-server/`) +- [ ] Compilation pipeline (`plugin/scripts/compile_spec.py`) +- [ ] Validation pipeline (`plugin/scripts/validate_spec.py`) +- [ ] Handoff generator (`plugin/scripts/generate_handoff.py`) +- [ ] Enforcement checks or hooks (`checks/`) - [ ] Documentation (README, CLAUDE.md, ADRs, schema) ## Output / logs diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 5d0bc2d..77023f0 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -2,8 +2,8 @@ Thanks for contributing! A few things to check before you open this PR: - Conventional commit prefix on the title (feat:, fix:, docs:, refactor:, perf:, test:, chore:, style:) - If this changes a prompt, run scripts/test-chain.md against examples/tea-tracker in a fresh Claude Code session -- If this changes the schema, validation, or compiler, ensure scripts/validate_spec.py still passes against examples/tea-tracker/spec-package -- If this changes anything in mcp/prompt-server/, ensure npm run typecheck and npm run build pass +- If this changes the schema, validation, or compiler, ensure plugin/scripts/validate_spec.py still passes against examples/tea-tracker/spec-package +- If this changes a prompt, skill, command, agent, ADR, or check, run python checks/run_checks.py --ci (blockers fail CI) and python -m unittest discover -s checks/tests - If this introduces an architectural decision, add or update an ADR in docs/adrs/ --> @@ -23,12 +23,12 @@ Thanks for contributing! A few things to check before you open this PR: ## Affected components -- [ ] Plugin (`plugin/`) — commands, skills, subagent -- [ ] Prompts (`prompts/dev/`) -- [ ] Compilation pipeline (`scripts/compile_spec.py`) -- [ ] Validation pipeline (`scripts/validate_spec.py`) -- [ ] Handoff generator (`scripts/generate_handoff.py`) -- [ ] MCP server (`mcp/prompt-server/`) +- [ ] Plugin (`plugin/`) — commands, skills, subagents +- [ ] Prompts (`plugin/prompts/`) +- [ ] Compilation pipeline (`plugin/scripts/compile_spec.py`) +- [ ] Validation pipeline (`plugin/scripts/validate_spec.py`) +- [ ] Handoff generator (`plugin/scripts/generate_handoff.py`) +- [ ] Enforcement checks and hooks (`checks/`, `.claude/settings.json`) - [ ] Documentation (`docs/`, `README.md`, `CLAUDE.md`) - [ ] CI (`.github/workflows/`) @@ -36,8 +36,8 @@ Thanks for contributing! A few things to check before you open this PR: -- [ ] `python scripts/validate_spec.py examples/tea-tracker/spec-package` still passes -- [ ] `cd mcp/prompt-server && npm ci && npm run typecheck && npm run build` (if MCP changed) +- [ ] `python plugin/scripts/validate_spec.py examples/tea-tracker/spec-package` still passes +- [ ] `python checks/run_checks.py --ci` reports no blockers - [ ] Manual runbook walkthrough (if prompts or skills changed) - [ ] CI green on this PR @@ -45,7 +45,7 @@ Thanks for contributing! A few things to check before you open this PR: - [ ] No ADR needed - [ ] New ADR added: -- [ ] Existing ADR updated: +- [ ] Existing ADR amended by an appended, dated section: ## Notes for reviewers diff --git a/CHANGELOG.md b/CHANGELOG.md index 8fda87d..9a16cf7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,11 +15,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `skills-claude-ai/` — Claude.ai Agent Skill ports of product-ideation and product-flow (issue #12): bundled prompts with skill-relative paths, conversation-scoped artifact ledger with `product-dev-artifacts.md` export replacing the `.product-dev/` registry ### Changed +- Enforcement suite: first graduation (ADR 0012 amendment, 2026-10-12). Twelve checks moved warn → block after 7+ clean days: `frontmatter-v2`, `name-uniqueness`, `body-structure`, `placeholder-syntax`, `placeholder-resolvability`, `dependency-graph`, `component-census`, `no-legacy`, `spec-fixture`, `adr-status`, `filename-convention`, `objective-parity`. Findings from these now fail CI and bounce the Stop-gate. `manifest`, `word-limit`, and `self-containment` stay at warn, with reasons in the amendment +- ADRs 0003, 0004, 0008, 0013: appended amendments recording what later ADRs changed (the 6-command / 5-skill / 2-subagent census, registry extensions, the reverse-pass checks that had landed) +- PR and bug-report templates, README, `scripts/README.md`, CONTRIBUTING: removed references to the deleted MCP server and to script paths that moved into `plugin/scripts/`; corrected component counts - PreToolUse guard (ADR 0012 amendment, 2026-10-12): appending to the end of an existing ADR is now allowed, so amendments and graduation-log entries no longer need the kill-switch; the guard also covers MultiEdit and Bash writes; rejections name moves an agent can actually take. Tests in `checks/tests/`, run in CI - product-ideation: the escape hatch now respects the first explicit request to move on, recording the remaining unvalidated assumptions instead of requiring a second override - ADR 0002: Superseded — MCP server removed; plugin is the sole delivery mechanism ### Removed +- `docs/skills/` — eight skill specs for the pre-ADR 0004 eight-skill design, referenced by nothing - `mcp/prompt-server/` — MCP server (issue #13 closed as superseded; revisit triggers never fired, and ADR 0011 left it pointing at a prompt directory that no longer holds the framework library) ## [0.1.0] - 2026-04-06 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 55d2fdc..28e41c9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -157,9 +157,13 @@ claude --plugin-dir ./plugin When making architectural decisions: 1. Create `docs/adrs/NNNN-short-title.md` (next number = highest existing + 1; check `ls docs/adrs/`) -2. Use the existing format: Status, Context, Decision, Consequences +2. Use the existing format: Status, Context, Decision, Consequences, Enforcement (testable consequences, the checks that verify them, and what is not machine-checkable — ADR 0012) 3. Set status to "Proposed" -4. Update status to "Accepted" after review +4. The repo owner updates status to "Accepted" after review + +Existing ADRs are append-only. To change one, append a dated `## Amendment (YYYY-MM-DD)` section at the end of the file, or write a new ADR that supersedes it. When a new ADR amends an older one, append a note to the older one saying so. In Claude Code sessions a hook (`checks/hooks/pretooluse_guard.py`) blocks rewrites and allows appends. + +Run `python checks/run_checks.py --ci` before pushing. Checks at `block` fail CI; see `checks/README.md`. ## Code Style diff --git a/README.md b/README.md index 3c66de3..3297129 100644 --- a/README.md +++ b/README.md @@ -81,9 +81,9 @@ Default is **Tier 1** (quick exploration, ~60 min total). The framework escalate ``` ├── plugin/ # Claude Code plugin (self-contained, installable) │ ├── .claude-plugin/plugin.json # Plugin manifest -│ ├── commands/ # 5 commands (/idea, /problem, /spec, /compile, /summary) -│ ├── skills/ # 4 skills (3 workflows + status) -│ ├── agents/ # 1 subagent (tech-spec-writer) +│ ├── commands/ # 6 commands (/idea, /problem, /spec, /compile, /summary, /optimize) +│ ├── skills/ # 5 skills (4 workflows + status) +│ ├── agents/ # 2 subagents (tech-spec-writer, ux-extractor) │ ├── prompts/ # Bundled prompt library │ │ ├── 01_ux_research/ # Prompts: phases 00-06 │ │ ├── 02_tech_requirements/ # Tech spec prompts: 4 areas + consolidation @@ -116,7 +116,7 @@ Default is **Tier 1** (quick exploration, ~60 min total). The framework escalate │ └── docs/ ├── spec-package-schema.md # Spec package YAML schema (v1.0.0) - ├── adrs/ # 17 Architecture Decision Records + ├── adrs/ # Architecture Decision Records └── updates/ # PRD v3, refactor roadmap, enhancement guides ``` @@ -140,9 +140,9 @@ Key decisions are documented as ADRs in `docs/adrs/`: | ADR | Decision | |-----|----------| | [0001](docs/adrs/0001-prompt-frontmatter-schema.md) | YAML frontmatter as canonical prompt metadata | -| [0002](docs/adrs/0002-mcp-prompt-packaging.md) | MCP prompt packaging (deferred in favor of plugin) | +| [0002](docs/adrs/0002-mcp-prompt-packaging.md) | MCP prompt packaging (superseded by ADR 0008; server removed) | | [0003](docs/adrs/0003-context-registry-state-management.md) | File-based context registry at `.product-dev/` | -| [0004](docs/adrs/0004-skill-subagent-decomposition.md) | 3 skills + 1 subagent decomposition | +| [0004](docs/adrs/0004-skill-subagent-decomposition.md) | Skill / command / subagent decomposition (amended by ADR 0013) | | [0005](docs/adrs/0005-prompt-enhancement-schema.md) | Prompt enhancement schema | | [0006](docs/adrs/0006-progressive-disclosure-tiered-engagement.md) | Progressive disclosure and tiered engagement | | [0007](docs/adrs/0007-json-index-deprecation.md) | JSON index deprecation | @@ -160,7 +160,7 @@ Key decisions are documented as ADRs in `docs/adrs/`: ## ADR Enforcement Every ADR declares its testable consequences in an appended `## Enforcement` -section, verified by a warn-only check suite: +section, verified by a check suite: ```bash python checks/run_checks.py diff --git a/checks/README.md b/checks/README.md index 556d04d..21df406 100644 --- a/checks/README.md +++ b/checks/README.md @@ -1,7 +1,8 @@ # ADR Enforcement Checks -Warn-only check suite verifying the testable consequences declared in each -ADR's `## Enforcement` section. Architecture: [ADR 0012](../docs/adrs/0012-adr-enforcement-architecture.md). +Check suite verifying the testable consequences declared in each ADR's +`## Enforcement` section. Each check is `warn` (reported) or `block` (fails CI +and the Stop-gate); `python checks/run_checks.py --list` shows which. Architecture: [ADR 0012](../docs/adrs/0012-adr-enforcement-architecture.md). ## Run the checks @@ -43,11 +44,12 @@ Demotion (block → warn) is always allowed; log it the same three ways. ## Scope and exclusions -All 91 prompts are v2 — there is no legacy scoping (ADR 0012 §6). To exempt a +All prompts are v2 — there is no legacy scoping (ADR 0012 §6). To exempt a file from prompt-content checks, add its repo-relative path to the `exclude` array in `enforcement.config.json`. Word limits live in `word_limits.json`, -keyed by prompt `name`; prompts absent there are reported as uncovered, not -checked. +keyed by prompt `name`; a prompt absent there is reported as uncovered, not +checked. Raising a limit is a decision recorded in the owning ADR, not a +check tweak. ## Hooks (the only blocking layer) diff --git a/checks/enforcement.config.json b/checks/enforcement.config.json index 6624056..7f97d5e 100644 --- a/checks/enforcement.config.json +++ b/checks/enforcement.config.json @@ -2,20 +2,20 @@ "$schema": "enforcement-config-v1", "exclude": [], "checks": [ - { "id": "frontmatter-v2", "adr": "0001, 0003, 0006, 0009", "tc": "0001:TC-1; 0003:TC-1; 0006:TC-1,TC-2,TC-3; 0009:TC-1", "status": "warn", "added": "2026-07-12", "graduated": null }, - { "id": "name-uniqueness", "adr": "0009", "tc": "0009:TC-6", "status": "warn", "added": "2026-07-12", "graduated": null }, - { "id": "body-structure", "adr": "0009", "tc": "0009:TC-2,TC-3", "status": "warn", "added": "2026-07-12", "graduated": null }, - { "id": "placeholder-syntax", "adr": "0003, 0009", "tc": "0003:TC-2; 0009:TC-4", "status": "warn", "added": "2026-07-12", "graduated": null }, - { "id": "placeholder-resolvability", "adr": "0003", "tc": "0003:TC-3", "status": "warn", "added": "2026-07-12", "graduated": null }, - { "id": "dependency-graph", "adr": "0003", "tc": "0003:TC-4", "status": "warn", "added": "2026-07-12", "graduated": null }, + { "id": "frontmatter-v2", "adr": "0001, 0003, 0006, 0009", "tc": "0001:TC-1; 0003:TC-1; 0006:TC-1,TC-2,TC-3; 0009:TC-1", "status": "block", "added": "2026-07-12", "graduated": "2026-10-12" }, + { "id": "name-uniqueness", "adr": "0009", "tc": "0009:TC-6", "status": "block", "added": "2026-07-12", "graduated": "2026-10-12" }, + { "id": "body-structure", "adr": "0009", "tc": "0009:TC-2,TC-3", "status": "block", "added": "2026-07-12", "graduated": "2026-10-12" }, + { "id": "placeholder-syntax", "adr": "0003, 0009", "tc": "0003:TC-2; 0009:TC-4", "status": "block", "added": "2026-07-12", "graduated": "2026-10-12" }, + { "id": "placeholder-resolvability", "adr": "0003", "tc": "0003:TC-3", "status": "block", "added": "2026-07-12", "graduated": "2026-10-12" }, + { "id": "dependency-graph", "adr": "0003", "tc": "0003:TC-4", "status": "block", "added": "2026-07-12", "graduated": "2026-10-12" }, { "id": "word-limit", "adr": "0009", "tc": "0009:TC-5", "status": "warn", "added": "2026-07-12", "graduated": null }, { "id": "manifest", "adr": "0008", "tc": "0008:TC-1,TC-3", "status": "warn", "added": "2026-07-12", "graduated": null }, - { "id": "component-census", "adr": "0004, 0008", "tc": "0004:TC-1,TC-2,TC-3,TC-4; 0008:TC-2", "status": "warn", "added": "2026-07-12", "graduated": null }, - { "id": "no-legacy", "adr": "0001, 0002, 0005, 0007", "tc": "0001:TC-2; 0002:TC-1; 0005:TC-1; 0007:TC-1,TC-2", "status": "warn", "added": "2026-07-12", "graduated": null }, + { "id": "component-census", "adr": "0004, 0008", "tc": "0004:TC-1,TC-2,TC-3,TC-4; 0008:TC-2", "status": "block", "added": "2026-07-12", "graduated": "2026-10-12" }, + { "id": "no-legacy", "adr": "0001, 0002, 0005, 0007", "tc": "0001:TC-2; 0002:TC-1; 0005:TC-1; 0007:TC-1,TC-2", "status": "block", "added": "2026-07-12", "graduated": "2026-10-12" }, { "id": "self-containment", "adr": "0011", "tc": "0011:TC-1,TC-2", "status": "warn", "added": "2026-07-12", "graduated": null }, - { "id": "spec-fixture", "adr": "0010", "tc": "0010:TC-1,TC-2", "status": "warn", "added": "2026-07-12", "graduated": null }, - { "id": "adr-status", "adr": "0002, process", "tc": "0002:TC-2; process:adr-status", "status": "warn", "added": "2026-07-12", "graduated": null }, - { "id": "filename-convention", "adr": "CONTRIBUTING", "tc": "CONTRIBUTING:naming-convention", "status": "warn", "added": "2026-07-12", "graduated": null }, - { "id": "objective-parity", "adr": "0014", "tc": "0014:TC-parity", "status": "warn", "added": "2026-07-25", "graduated": null } + { "id": "spec-fixture", "adr": "0010", "tc": "0010:TC-1,TC-2", "status": "block", "added": "2026-07-12", "graduated": "2026-10-12" }, + { "id": "adr-status", "adr": "0002, process", "tc": "0002:TC-2; process:adr-status", "status": "block", "added": "2026-07-12", "graduated": "2026-10-12" }, + { "id": "filename-convention", "adr": "CONTRIBUTING", "tc": "CONTRIBUTING:naming-convention", "status": "block", "added": "2026-07-12", "graduated": "2026-10-12" }, + { "id": "objective-parity", "adr": "0014", "tc": "0014:TC-parity", "status": "block", "added": "2026-07-25", "graduated": "2026-10-12" } ] } diff --git a/docs/adrs/0001-prompt-frontmatter-schema.md b/docs/adrs/0001-prompt-frontmatter-schema.md index 324daa2..083ec04 100644 --- a/docs/adrs/0001-prompt-frontmatter-schema.md +++ b/docs/adrs/0001-prompt-frontmatter-schema.md @@ -124,3 +124,13 @@ every prompt in the library uses ADR 0009's minimal 7-field format enforced by the `frontmatter-v2` check. The still-operative core of this ADR is unchanged: frontmatter is the canonical prompt metadata and the JSON indices stay dead (ADR 0007). For the plugin runtime schema, ADR 0009 governs. + +--- + +## Graduation log entry (2026-10-12) + +`frontmatter-v2` (TC-1) and `no-legacy` (TC-2): **warn → block**. Basis +(ADR 0012 §5): 7+ consecutive clean days — zero findings from either check in +every CI run since 2026-07-27. `checks/enforcement.config.json` is +authoritative for current status; the "warn" labels in the Enforcement section +above record the status when it was written. diff --git a/docs/adrs/0002-mcp-prompt-packaging.md b/docs/adrs/0002-mcp-prompt-packaging.md index af6725d..df7a66c 100644 --- a/docs/adrs/0002-mcp-prompt-packaging.md +++ b/docs/adrs/0002-mcp-prompt-packaging.md @@ -80,3 +80,13 @@ Separate CLI tools (not MCP): - TC-2 → `checks/run_checks.py :: adr-status` (status: **warn**) - **Not machine-checkable:** The revisit trigger in the supersession note (editor-agnostic prompt access becoming a real need) is a judgment call, not a repo state. - **Graduation log:** _(empty)_ + +--- + +## Graduation log entry (2026-10-12) + +`no-legacy` (TC-1) and `adr-status` (TC-2): **warn → block**. Basis +(ADR 0012 §5): 7+ consecutive clean days — zero findings from either check in +every CI run since 2026-07-27. `checks/enforcement.config.json` is +authoritative for current status; the "warn" labels in the Enforcement section +above record the status when it was written. diff --git a/docs/adrs/0003-context-registry-state-management.md b/docs/adrs/0003-context-registry-state-management.md index 3831fb1..624b9e3 100644 --- a/docs/adrs/0003-context-registry-state-management.md +++ b/docs/adrs/0003-context-registry-state-management.md @@ -140,3 +140,33 @@ against the set of artifacts some prompt produces (typo guard) and rejects placeholders that are simultaneously optional and required. Canonical resolution rules: `plugin/docs/registry-operations.md` § Template Variable Resolution. (Owner-directed, part of the issue-backlog cleanup wave.) + +--- + +## Amendment (2026-10-12): Later ADRs that extended this registry + +Recorded here so the amended ADR points at its amenders (previously only the +amending ADRs said so): + +- **ADR 0013 §4** added the optional top-level `"mode"` field to + `context.json` (`"forward"` default | `"reverse"`) and four frontmatter + fields on extracted artifacts (`mode`, `provenance`, `confidence`, + `validation_status`). This re-introduces a `mode` field with a different + meaning from the one the 2026-04-04 amendment removed. +- **ADR 0016 §3** added the `inputs` map on artifact entries (each `requires` + artifact name → its `version` at generation time), which makes staleness a + registry computation. +- **ADR 0017 §4** added `.product-dev/learnings.jsonl` beside the registry. +- **ADR 0011 (amendment 2026-07-25)** moved the canonical operations reference + to `plugin/docs/registry-operations.md`. The schema and operations table in + the Decision above are the design at acceptance; that file is current. + +## Graduation log entry (2026-10-12) + +`frontmatter-v2` (TC-1), `placeholder-syntax` (TC-2), +`placeholder-resolvability` (TC-3), and `dependency-graph` (TC-4): +**warn → block**. Basis (ADR 0012 §5): 7+ consecutive clean days — zero +findings from any of the four in every CI run since 2026-07-27. +`checks/enforcement.config.json` is authoritative for current status; the +"warn" labels in the Enforcement section above record the status when it was +written. diff --git a/docs/adrs/0004-skill-subagent-decomposition.md b/docs/adrs/0004-skill-subagent-decomposition.md index 2971193..a862b7e 100644 --- a/docs/adrs/0004-skill-subagent-decomposition.md +++ b/docs/adrs/0004-skill-subagent-decomposition.md @@ -124,3 +124,31 @@ User invokes command (e.g., /idea) - TC-1, TC-2, TC-3, TC-4 → `checks/run_checks.py :: component-census` (status: **warn**) - **Not machine-checkable:** The planning-in-chat principle, and whether future features land in the correct mechanism (skill vs command vs subagent vs MCP tool), are design judgments. - **Graduation log:** _(empty)_ + +--- + +## Amendment (2026-10-12): Census as amended by ADR 0013 + +ADR 0013 (2026-07-18) added the reverse pass and amended this ADR's counts, +but this file was never updated to say so; the `component-census` check has +enforced the amended set since that day. The census of record is: + +- **6 commands**: `plugin/commands/{idea,problem,spec,compile,summary,optimize}.md` +- **5 skills** — 4 workflows plus status: + `plugin/skills/{product-ideation,product-flow,tech-spec,ux-optimization,status}/SKILL.md` +- **2 subagents**: `plugin/agents/{tech-spec-writer,ux-extractor}.md` + +This supersedes the counts in the Decision tables ("Skills (3 total)", +"Commands (5 total)", "Subagents (1 total)"), in Consequences, and in +Enforcement TC-1 through TC-3 above. Those counted workflow skills only and +predate `/optimize`. TC-4 (the status skill stays read-only) is unchanged. The +assignment principle and the planning-in-chat principle are unchanged, and +ADR 0013 §3 explains why the extractor subagent is consistent with them. + +## Graduation log entry (2026-10-12) + +`component-census` (TC-1 to TC-4): **warn → block**. Basis (ADR 0012 §5): 7+ +consecutive clean days — zero findings in every CI run since 2026-07-27. +`checks/enforcement.config.json` is authoritative for current status; the +"warn" label in the Enforcement section above records the status when it was +written. diff --git a/docs/adrs/0005-prompt-enhancement-schema.md b/docs/adrs/0005-prompt-enhancement-schema.md index d3717ee..64b0279 100644 --- a/docs/adrs/0005-prompt-enhancement-schema.md +++ b/docs/adrs/0005-prompt-enhancement-schema.md @@ -160,3 +160,13 @@ mcp: - TC-1 → `checks/run_checks.py :: no-legacy` (status: **warn**) - **Not machine-checkable:** The deferred design itself — nothing here is operative until an MCP server revives it under a status change. - **Graduation log:** _(empty)_ + +--- + +## Graduation log entry (2026-10-12) + +`no-legacy` (TC-1): **warn → block**. Basis (ADR 0012 §5): 7+ consecutive +clean days — zero findings in every CI run since 2026-07-27. +`checks/enforcement.config.json` is authoritative for current status; the +"warn" label in the Enforcement section above records the status when it was +written. diff --git a/docs/adrs/0006-progressive-disclosure-tiered-engagement.md b/docs/adrs/0006-progressive-disclosure-tiered-engagement.md index 7f15ed1..7ae4aa5 100644 --- a/docs/adrs/0006-progressive-disclosure-tiered-engagement.md +++ b/docs/adrs/0006-progressive-disclosure-tiered-engagement.md @@ -147,3 +147,13 @@ Corrections of record: - Tier 1 count at this writing: **27 prompts** — 13 forward-pass UX research, 5 tech requirements, 9 reverse-pass (ADR 0013). The "14" in the status note predates the tech-requirements tagging and the reverse pass. + +--- + +## Graduation log entry (2026-10-12) + +`frontmatter-v2` (TC-1 to TC-3): **warn → block**. Basis (ADR 0012 §5): 7+ +consecutive clean days — zero findings in every CI run since 2026-07-27. +`checks/enforcement.config.json` is authoritative for current status; the +"warn" label in the Enforcement section above records the status when it was +written. diff --git a/docs/adrs/0007-json-index-deprecation.md b/docs/adrs/0007-json-index-deprecation.md index 6cf8d1a..9963aa5 100644 --- a/docs/adrs/0007-json-index-deprecation.md +++ b/docs/adrs/0007-json-index-deprecation.md @@ -90,3 +90,13 @@ Before deleting any source file, verify: - TC-1, TC-2 → `checks/run_checks.py :: no-legacy` (status: **warn**) - **Not machine-checkable:** None — this decision is fully structural. - **Graduation log:** _(empty)_ + +--- + +## Graduation log entry (2026-10-12) + +`no-legacy` (TC-1, TC-2): **warn → block**. Basis (ADR 0012 §5): 7+ +consecutive clean days — zero findings in every CI run since 2026-07-27. +`checks/enforcement.config.json` is authoritative for current status; the +"warn" label in the Enforcement section above records the status when it was +written. diff --git a/docs/adrs/0008-plugin-architecture.md b/docs/adrs/0008-plugin-architecture.md index 42e4c65..925df87 100644 --- a/docs/adrs/0008-plugin-architecture.md +++ b/docs/adrs/0008-plugin-architecture.md @@ -116,3 +116,24 @@ The existing MCP server (`mcp/prompt-server/`) remains functional but is not req - TC-2 → `checks/run_checks.py :: component-census` (status: **warn**) - **Not machine-checkable:** Whether skills "own the conversational UX" well, and the plugin-over-MCP tradeoff rationale. - **Graduation log:** _(empty)_ + +--- + +## Amendment (2026-10-12): Structure as extended by ADR 0013 + +The Plugin Structure diagram and Component Mapping above show the plugin as of +2026-07-03. ADR 0013 added `commands/optimize.md`, +`skills/ux-optimization/SKILL.md`, and `agents/ux-extractor.md`; the +ADR 0011 amendment added `docs/` (the bundled registry-operations canon). The +current census is recorded in ADR 0004's 2026-10-12 amendment and enforced by +`component-census`. The MCP rows are historical: ADR 0002 is superseded and +`mcp/` no longer exists. + +## Graduation log entry (2026-10-12) + +`component-census` (TC-2): **warn → block**. Basis (ADR 0012 §5): 7+ +consecutive clean days — zero findings in every CI run since 2026-07-27. +`manifest` (TC-1, TC-3) stays at **warn**: it reports a finding whenever the +`claude` CLI is absent, so at block it would stop every local session on a +machine without the CLI. `checks/enforcement.config.json` is authoritative for +current status. diff --git a/docs/adrs/0009-prompt-enhancement-pattern.md b/docs/adrs/0009-prompt-enhancement-pattern.md index 8b0d531..f01c801 100644 --- a/docs/adrs/0009-prompt-enhancement-pattern.md +++ b/docs/adrs/0009-prompt-enhancement-pattern.md @@ -140,3 +140,15 @@ undershot real prompt needs rather than that 20 migrations overshot. The `body-structure` check bound is updated to match; the one 8-rule prompt (`02_identify_screens_states.md`) was consolidated to 6 by merging paired invariants. Counting rule unchanged: list items inside ``. + +--- + +## Graduation log entry (2026-10-12) + +`frontmatter-v2` (TC-1), `body-structure` (TC-2, TC-3), `placeholder-syntax` +(TC-4), and `name-uniqueness` (TC-6): **warn → block**. Basis (ADR 0012 §5): +7+ consecutive clean days — zero findings from any of the four in every CI run +since 2026-07-27. `word-limit` (TC-5) stays at **warn** for now: the limits +are a ratchet of current size plus 10%, so ordinary prompt edits are the most +likely thing to trip it, and a tripped block stops the session. +`checks/enforcement.config.json` is authoritative for current status. diff --git a/docs/adrs/0010-spec-package-compilation-target.md b/docs/adrs/0010-spec-package-compilation-target.md index e41edbb..e361e0f 100644 --- a/docs/adrs/0010-spec-package-compilation-target.md +++ b/docs/adrs/0010-spec-package-compilation-target.md @@ -92,3 +92,14 @@ The manifest declares defaults for decisions the builder didn't explicitly make: - TC-1, TC-2 → `checks/run_checks.py :: spec-fixture` (status: **warn**; adopts the existing CI job rather than duplicating it) - **Not machine-checkable:** Whether the three-layer package actually reduces implementation-agent hallucination — measurable only through use. - **Graduation log:** _(empty)_ + +--- + +## Graduation log entry (2026-10-12) + +`spec-fixture` (TC-1, TC-2): **warn → block**. Basis (ADR 0012 §5): 7+ +consecutive clean days — zero findings in every CI run since 2026-07-27. The +separate "Python pipeline" CI job already failed the build on an invalid +fixture; graduation makes the Stop-gate agree with it and makes the failure +message name this ADR. `checks/enforcement.config.json` is authoritative for +current status. diff --git a/docs/adrs/0012-adr-enforcement-architecture.md b/docs/adrs/0012-adr-enforcement-architecture.md index cd9a532..27f4bf6 100644 --- a/docs/adrs/0012-adr-enforcement-architecture.md +++ b/docs/adrs/0012-adr-enforcement-architecture.md @@ -215,3 +215,43 @@ change in a new ADR. Not tested by the experiment that prompted this: its harness ran with no hooks, so it says nothing about whether a hook-based guard holds. The change rests on the no-legal-move finding and on reading this guard's own code. + +--- + +## Amendment (2026-10-12): First graduation; the suite is no longer warn-only + +Decision §3 calls the suite warn-only and §5 says nothing was promoted at +launch. That held for three months although §5's rule had been met since late +July: 14 of the 15 checks reported zero findings in every CI run from +2026-07-27, and the fifteenth (`manifest`) only ever reported the CLI being +absent from CI, fixed on 2026-09-02. + +At warn, a finding reaches nobody who can act on it: CI stays green, and the +Stop-gate's passing output goes to the debug log, not to the agent. The +experiment behind this review (chrispezza/portfolio#106) found that an agent +with no governing documents still stopped when a check's message named the +decision — which here only happens at block. + +**Graduated to block (12):** `frontmatter-v2`, `name-uniqueness`, +`body-structure`, `placeholder-syntax`, `placeholder-resolvability`, +`dependency-graph`, `component-census`, `no-legacy`, `spec-fixture`, +`adr-status`, `filename-convention`, `objective-parity`. Each owning ADR +carries a dated graduation log entry. `filename-convention` is owned by +CONTRIBUTING, not an ADR, so its entry is this one. + +**Held at warn (3), with reasons:** + +- `manifest` — emits a finding when the `claude` CLI is unavailable. At block + that would stop every local session on a machine without the CLI. It can + graduate once "validator unavailable" is reported as a note, not a finding. +- `word-limit` — limits are current size plus 10%, so routine prompt edits are + what trips it. One more clean cycle with prompt edits in it first. +- `self-containment` — its path pattern can match prose that mentions a + `prompts/` or `scripts/` path without being a reference. + +**Corrections of record:** the suite has 15 checks (§3 says 14; +`objective-parity` was added 2026-07-27), and 101 prompts (§6 and §7 say 91; +all have declared word limits, so the "77 uncovered" in §7 is resolved). + +**Graduation log entry (2026-10-12):** `adr-status` (TC-1) and +`filename-convention`: warn → block, basis as above. diff --git a/docs/adrs/0013-ux-optimization-reverse-pass.md b/docs/adrs/0013-ux-optimization-reverse-pass.md index 0e1d6c1..a1f0d06 100644 --- a/docs/adrs/0013-ux-optimization-reverse-pass.md +++ b/docs/adrs/0013-ux-optimization-reverse-pass.md @@ -170,3 +170,29 @@ whether `02_evidence_mining` gains Tier 2 depth prompts. ADR 0004 (skill/subagent decomposition — amended §1, §3), ADR 0006 (tiers), ADR 0008 (plugin architecture), ADR 0010 (spec package — possible future amendment), ADR 0011 (self-containment), ADR 0012 (enforcement). + +--- + +## Amendment (2026-10-12): Enforcement landed; sequence extended + +The Enforcement section above says "Checks: none yet — deferred until +implementation lands". Implementation landed on 2026-07-18 and the checks +followed the same day; this note records what the section should now be read +as saying. + +- **TC-1** (skill, command, subagent, and prompt directory exist) → + `checks/run_checks.py :: component-census`, which carries the amended census + (ADR 0004 amendment, 2026-10-12). Status: **block** as of 2026-10-12. +- **TC-2** (reverse-pass prompts carry the standard frontmatter; shadowed + `produces` names match the forward pass exactly) → `frontmatter-v2`, and the + cross-mode rule in `name-uniqueness` that permits a reverse-pass prompt to + share a `produces` name with at most one forward-pass prompt. Status: + **block** as of 2026-10-12. +- **TC-3** (plugin-internal references use `${CLAUDE_PLUGIN_ROOT}`) → + `self-containment`. Status: **warn**. + +The prompt table in Decision §2 is the sequence at acceptance (8 prompts). +ADR 0014 added `07_objective_metrics` and `10_live_site_audit` and renumbered +gap analysis and the optimization spec to 08 and 09; ADR 0015 added +`11_runtime_audit`; ADR 0017 inserted the scope walk between steps 8 and 9. +The current sequence is the one in `plugin/skills/ux-optimization/SKILL.md`. diff --git a/docs/adrs/0014-live-site-audit-and-objective.md b/docs/adrs/0014-live-site-audit-and-objective.md index 663d451..bb38b08 100644 --- a/docs/adrs/0014-live-site-audit-and-objective.md +++ b/docs/adrs/0014-live-site-audit-and-objective.md @@ -98,3 +98,12 @@ owner-directed): didn't, so headless runs can't silently read as fully verified. Its word budget was raised 300 → 350 to hold the new element (decision recorded here per the word-limits policy). + +--- + +## Graduation log entry (2026-10-12) + +`objective-parity` (TC-parity): **warn → block**. Basis (ADR 0012 §5): 7+ +consecutive clean days — zero findings in every CI run since the check was +added on 2026-07-27. `checks/enforcement.config.json` is authoritative for +current status. diff --git a/docs/skills/evaluate.md b/docs/skills/evaluate.md deleted file mode 100644 index c2556be..0000000 --- a/docs/skills/evaluate.md +++ /dev/null @@ -1,47 +0,0 @@ -# Skill Spec: `/evaluate` - -## Purpose - -Post-test synthesis: analyze test observations, evaluate the hypothesis, and plan next iteration or pivot. This is where learning happens. - -## Trigger - -- `/evaluate` (expects user to provide test observations) - -## System Prompt - -``` -You are a UX research analyst helping synthesize prototype test results. -Your role is to identify patterns in observations, evaluate hypotheses -honestly (including when results are inconclusive), and recommend -evidence-based next steps. Resist confirmation bias -- if the data -doesn't support the hypothesis, say so clearly. -``` - -## Behavior - -### Flow - -1. **Check context**: Read `hypothesis_statement`, `test_questions`. If missing, work with what the user provides. -2. **Collect**: Ask the user to share their test observations (paste notes, describe what happened). -3. **Synthesize**: Run `synthesize_patterns`. Present organized patterns: recurring themes, friction points, successes, surprises. -4. **Evaluate**: Run `evaluate_hypothesis`. Present honest assessment: validated, invalidated, or inconclusive. Connect back to specific evidence. -5. **Decide**: Based on evaluation: - - **Validated** -> Run `plan_next_iteration`. Suggest what to keep and refine. - - **Inconclusive** -> Suggest what additional data is needed and how to get it. - - **Invalidated** -> Run `explore_pivot_options`. Present 2-3 alternative directions. -6. **Checkpoint**: "Based on what we learned, should we iterate on this direction, explore a pivot, or take this to technical specs?" - -### Progressive Disclosure - -| Tier | Prompts Run | Artifacts Produced | -|------|------------|-------------------| -| 1 | synthesize_patterns, evaluate_hypothesis | test_insights, hypothesis_evaluation | -| 2 | + plan_next_iteration OR explore_pivot_options | + iteration_plan OR pivot_options | -| 3 | All above + loop back to refine earlier artifacts | Updated problem_statement, hypothesis_statement | - -## Context Management - -- **Reads**: `hypothesis_statement`, `test_questions`, `success_metrics`, `problem_statement` -- **Writes**: `test_insights`, `hypothesis_evaluation`, `iteration_plan`, `pivot_options` -- **Loops to**: `/problem` (if pivot changes problem), `/hypothesis` (if iterating), `/spec` (if validated) diff --git a/docs/skills/flow.md b/docs/skills/flow.md deleted file mode 100644 index c238a2e..0000000 --- a/docs/skills/flow.md +++ /dev/null @@ -1,44 +0,0 @@ -# Skill Spec: `/flow` - -## Purpose - -Map the primary user flow, identify screens and states, define decision points, and plan error handling. Translates the solution concept into an interaction blueprint. - -## Trigger - -- `/flow` (continues from context) -- `/flow "onboarding to first tea logged"` (provides specific flow scope) - -## System Prompt - -``` -You are an interaction designer helping map user flows for a product -concept. Your role is to think from the user's perspective and mental -model -- not the technical architecture. Focus on what the user is trying -to accomplish at each step, not how the system implements it. -``` - -## Behavior - -### Flow - -1. **Check context**: Read `solution_concept` and `feature_list`. If missing, suggest `/hypothesis` first. -2. **Happy path**: Run `primary_user_flow`. Present numbered sequence from entry to goal completion. -3. **Validate**: Ask: "Does this match how you'd expect a user to move through this?" -4. **Screens**: Run `identify_screens`. Present screen inventory with purpose and connections. -5. **Checkpoint**: "We have the core flow and screens. Want to map decision points and error cases, or move to prototype planning?" -6. **Branch (Tier 2)**: Run `identify_decisions` and `error_handling`. - -### Progressive Disclosure - -| Tier | Prompts Run | Artifacts Produced | -|------|------------|-------------------| -| 1 | primary_user_flow, identify_screens | user_flow, screen_inventory | -| 2 | + identify_decisions, error_handling | + decision_points, error_handling_plan | -| 3 | + entry_exit_points, validate_flow, create_flow_diagram | + entry_exit_analysis, flow_validation, flow_diagram | - -## Context Management - -- **Reads**: `solution_concept`, `feature_list`, `hypothesis_statement` -- **Writes**: `user_flow`, `screen_inventory`, `decision_points`, `error_handling_plan` -- **Required by downstream**: `/prototype` needs `user_flow`, `/spec` needs `user_flow` + `screen_inventory` diff --git a/docs/skills/hypothesis.md b/docs/skills/hypothesis.md deleted file mode 100644 index 6025fb4..0000000 --- a/docs/skills/hypothesis.md +++ /dev/null @@ -1,60 +0,0 @@ -# Skill Spec: `/hypothesis` - -## Purpose - -Guide the user through defining objectives, success metrics, and forming a testable solution hypothesis. Bridges problem definition to solution design. - -## Trigger - -- `/hypothesis` (continues from context) -- `/hypothesis "tea inventory management for serious collectors"` (provides direction) - -## System Prompt - -``` -You are a product strategist helping a team move from a validated problem -to a testable solution hypothesis. Your role is to ensure objectives are -outcome-focused, metrics are measurable, and the hypothesis is structured -for clear validation or invalidation. Avoid solution bias -- the hypothesis -is an experiment, not a commitment. -``` - -## Behavior - -### Flow - -1. **Check context**: Read `problem_statement`. If missing, ask or suggest `/problem` first. -2. **Objective**: Run `identify_core_objective`. Present outcome-focused objective. Ask: "Does this capture what success looks like for the user?" -3. **Metrics**: Run `define_metrics`. Present 1-2 measurable metrics. Ask: "Can we actually measure these in a prototype test?" -4. **Constraints**: Run `set_constraints`. Present constraints. Ask: "Anything missing here?" -5. **Solution Concept**: Run `generate_solution_concept`. Present concept in 2-3 paragraphs focused on user experience. -6. **Hypothesis**: Run `format_hypothesis`. Present in "We believe [approach] will result in [outcome] for [user], measurable by [metrics]" format. -7. **Checkpoint**: "We have a testable hypothesis. Should we assess risks and alternatives, or move to mapping the user flow?" - -### Progressive Disclosure - -| Tier | Prompts Run | Artifacts Produced | -|------|------------|-------------------| -| 1 | identify_core_objective, generate_solution_concept, format_hypothesis | core_objective, solution_concept, hypothesis_statement | -| 2 | + define_metrics, set_constraints, risk_assessment, generate_features | + success_metrics, constraints, risk_assessment, feature_list | -| 3 | + anti_goals, solution_alternatives, iteration_strategy | + anti_goals, alternative_solutions, iteration_strategy | - -## Context Management - -- **Reads**: `problem_statement`, `proto_persona`, `problem_analysis` (optional) -- **Writes**: `core_objective`, `success_metrics`, `constraints`, `solution_concept`, `hypothesis_statement`, `feature_list`, `risk_assessment` -- **Required by downstream**: `/flow` needs `solution_concept`, `/prototype` needs `hypothesis_statement` - -## Subagent Escalation - -No dedicated subagent. This skill handles all tiers conversationally since the prompts build sequentially and benefit from the user staying in the conversation loop. - -## Output - -At completion: -- Core objective with success criteria -- (Tier 2+) Measurable metrics and constraints -- Solution concept describing the user experience -- Testable hypothesis statement -- (Tier 2+) Risk assessment and feature list -- (Tier 3) Alternative solutions evaluated, iteration roadmap diff --git a/docs/skills/idea.md b/docs/skills/idea.md deleted file mode 100644 index e8bd42f..0000000 --- a/docs/skills/idea.md +++ /dev/null @@ -1,125 +0,0 @@ -# Skill Spec: `/idea` - -## Purpose - -Conversational product ideation from a vague concept. This is the primary entry point for users who have an inspiration, problem space, or rough concept they want to explore. - -## Trigger - -User invokes `/idea` optionally followed by a concept description: -- `/idea` (starts with open prompt) -- `/idea tea tracking app` (starts with concept provided) - -## System Prompt - -``` -You are a product development coach helping someone explore an early-stage -product idea. Your role is to help them discover what's interesting about -their concept, identify potential users and problems worth solving, and -crystallize their thinking without prematurely narrowing options. - -Be curious and encouraging. Ask questions that help the user think more -clearly. Surface non-obvious angles. Avoid jumping to solutions. -``` - -## Behavior - -### Flow - -1. **Open**: If no concept provided, ask: "What's on your mind? Tell me about the idea, problem, or space you're interested in." -2. **Reflect**: Run `capture_idea` prompt internally. Reflect the concept back in 2-3 sentences. Highlight what's interesting. -3. **Clarify**: Ask 1-2 targeted questions based on the concept (who is this for? what triggers the need?). -4. **Explore**: Based on response, select the most relevant Phase 00 prompt: - - Mentions an industry -> `industry_analysis` - - Mentions trends or future -> `predict_trend_evolution` - - Mentions combining things -> `combine_ideas` - - Mentions user pain -> `explore_problem` - - Mentions competition -> `competitive_analysis` - - Mentions audience -> `explore_user_segments` -5. **Present**: Share findings conversationally (not as a dump). -6. **Checkpoint**: "A few directions are emerging here. [summarize 2-3]. Should we go deeper on any of these, or are you ready to define a problem statement?" -7. **Branch**: - - "Go deeper" -> run additional Phase 00 prompts or spawn Competitive Intelligence subagent - - "Define problem" -> transition to `/problem` behavior - - "Something else" -> follow the user's lead - -### Progressive Disclosure - -- **Default**: Tier 1 (capture_idea + one contextual prompt + checkpoint) -- **Escalate to Tier 2**: User provides detailed response or asks for depth -- **Escalate to Tier 3**: User explicitly requests comprehensive analysis, spawn Competitive Intelligence subagent - -### Checkpoints - -After every 2-3 agent turns: -- "Does this capture what you're thinking?" (validation) -- "Should we go deeper on [X] or move forward?" (navigation) -- "I see [N] threads here. Which feels most promising?" (prioritization) - -## Context Management - -- **Creates**: New project in context registry if none exists -- **Writes**: `initial_concept`, `industry_pain_points`, `problem_space_map`, `competitive_landscape`, `user_segment_analysis` (as explored) -- **Reads**: Nothing (entry point) - -## MCP Tools Used - -- `get_project_status` -- check for existing project -- `get_prompt_with_context` -- fetch Phase 00 prompts -- `suggest_next_prompt` -- determine available next steps - -## Subagent Escalation - -**Competitive Intelligence Analyst**: Spawned when user asks about market landscape, competition, or existing solutions. Returns consolidated competitive landscape document. - -## Output - -At completion of `/idea` session, user has: -- A captured concept with key angles explored -- 3-5 potential user pain points identified -- A preliminary direction for problem definition -- Context stored for seamless `/problem` handoff - -## Example Interaction - -``` -User: /idea tea tracking app - -Agent: A tea tracking app -- interesting! So you're thinking about a -dedicated tool for managing a personal tea collection: tracking what -you own, what you want to try, and notes on your tasting experiences. - -A few things jump out: tea is a domain with deep expertise variance -(casual drinkers vs. serious enthusiasts), a physical inventory -component (what's actually on your shelf), and a knowledge-building -aspect (learning about origins, brewing methods, flavor profiles). - -Who do you see using this? A serious tea collector, or someone just -getting into tea? - -User: More the serious collector. They have 30+ teas and can't -remember what they have. - -Agent: That's a clear pain point -- inventory blindness. When your -collection grows past what you can hold in memory, you start -rebuying teas you already have, forgetting to finish ones that are -aging, and losing track of what you've tried. - -Let me look at what's already out there in this space and where the -gaps might be. - -[runs competitive_analysis internally] - -I've looked at the tea tracking landscape. There are a few apps but -they're mostly review/rating platforms (like Steepster) rather than -personal inventory tools. The gap seems to be between "social tea -reviewing" and "personal tea management." - -Three directions are emerging: -1. **Inventory-first**: Focus on the physical collection -2. **Knowledge-first**: Focus on building tea expertise over time -3. **Community-first**: Focus on sharing discoveries with other collectors - -Should we go deeper on any of these, or are you ready to define a -problem statement for one of them? -``` diff --git a/docs/skills/problem.md b/docs/skills/problem.md deleted file mode 100644 index 7e4bf38..0000000 --- a/docs/skills/problem.md +++ /dev/null @@ -1,68 +0,0 @@ -# Skill Spec: `/problem` - -## Purpose - -Guide the user through defining and refining a problem statement. This is the foundational artifact that all subsequent work builds on. - -## Trigger - -- `/problem` (starts fresh or continues from `/idea` context) -- `/problem "tea collectors can't track their inventory"` (starts with rough statement) - -## System Prompt - -``` -You are a UX research advisor helping a product team define a precise, -validated problem statement. Your role is to ensure the problem is -user-centered, specific enough to guide design, and broad enough to -allow creative solutions. Push for clarity and evidence over assumptions. -``` - -## Behavior - -### Flow - -1. **Check context**: Read project context. If `initial_concept` exists from `/idea`, reference it. If not, ask what problem space the user is working in. -2. **Draft**: Run `create_problem_statement` prompt. Present the draft in "[User type] needs [need] because [insight]" format. -3. **Validate**: Ask: "Does this capture the core problem? What feels off or missing?" -4. **Persona**: Run `create_proto_persona`. Present lightweight persona. Ask if it matches their mental model of the target user. -5. **Checkpoint**: "We have a problem statement and a user persona. Should we go deeper with analysis, or move on to defining objectives?" -6. **Branch (Tier 2)**: - - "Go deeper" -> run `analyze_problem`, `scope_problem`, `qualify_problem` in sequence - - "Move on" -> suggest `/hypothesis` -7. **Branch (Tier 3)** -- if user wants comprehensive: - - Spawn Problem Analyst subagent - - Runs full sequence: problem analysis -> scope -> qualify -> validation questions -> priority -> ecosystem - - Returns consolidated problem definition document - -### Progressive Disclosure - -| Tier | Prompts Run | Artifacts Produced | -|------|------------|-------------------| -| 1 | create_problem_statement, create_proto_persona | problem_statement, proto_persona | -| 2 | + analyze_problem, scope_problem, qualify_problem | + problem_analysis, problem_scope, problem_qualification | -| 3 | + validation_questions, problem_priority, problem_ecosystem | + validation_questions, priority_assessment, ecosystem_map | - -## Context Management - -- **Reads**: `initial_concept`, `industry_pain_points`, `problem_space_map` (from `/idea` if available) -- **Writes**: `problem_statement`, `proto_persona`, `problem_analysis`, `problem_scope`, `problem_qualification`, `ecosystem_map` -- **Required by downstream**: `/hypothesis`, `/flow`, `/spec` all require `problem_statement` - -## Missing Context Handling - -If `initial_concept` doesn't exist: -> "I don't have context from an earlier exploration. That's fine -- tell me about the problem space you're working in, and we'll build the problem statement from here." - -## Subagent Escalation - -**Problem Analyst**: Spawned for Tier 3. Runs full Phase 01 sequence with a dedicated system prompt focused on UX research methodology and problem decomposition. Returns a consolidated problem definition document with all artifacts. - -## Output - -At completion, user has: -- A validated problem statement in standard format -- A proto-persona with relevant characteristics -- (Tier 2+) Problem analysis, scope boundaries, qualification score -- (Tier 3) Complete problem definition with ecosystem mapping -- Context stored for `/hypothesis` handoff diff --git a/docs/skills/prototype.md b/docs/skills/prototype.md deleted file mode 100644 index d2b8f91..0000000 --- a/docs/skills/prototype.md +++ /dev/null @@ -1,47 +0,0 @@ -# Skill Spec: `/prototype` - -## Purpose - -Plan prototype scope, fidelity, test questions, and test execution. Prepares everything needed to validate the hypothesis with real users. - -## Trigger - -- `/prototype` (continues from context) - -## System Prompt - -``` -You are a usability testing specialist helping plan a prototype test. -Your role is to ensure the prototype scope is focused on testing the -hypothesis (not building a complete product), the fidelity matches -the testing goals, and the test script captures actionable insights. -Challenge scope creep aggressively. -``` - -## Behavior - -### Flow - -1. **Check context**: Read `user_flow`, `hypothesis_statement`. If missing, suggest prerequisite skills. -2. **Scope**: Run `scope_prototype`. Present what to include/exclude. Ask: "Does this feel like the right boundary?" -3. **Test questions**: Run `test_questions`. Present 3-5 specific questions tied to hypothesis. Ask: "Are these the right things to test?" -4. **Checkpoint**: "We have scope and test questions. Want to plan fidelity, participants, and a full test script?" -5. **Branch (Tier 2)**: Run `fidelity_choice` and `identify_interactions`. -6. **Branch (Tier 3)**: Spawn Test Planning Coordinator subagent for comprehensive test planning. - -### Progressive Disclosure - -| Tier | Prompts Run | Artifacts Produced | -|------|------------|-------------------| -| 1 | scope_prototype, test_questions | prototype_scope, test_questions | -| 2 | + fidelity_choice, identify_interactions | + fidelity_decision, key_interactions | -| 3 | + participant_criteria, test_script (via subagent) | + participant_criteria, test_script | - -## Subagent Escalation - -**Test Planning Coordinator**: Spawned for Tier 3. Runs full prototype planning sequence with a usability testing methodology system prompt. Returns complete test plan document including scope, fidelity rationale, participant criteria, and test script. - -## Context Management - -- **Reads**: `user_flow`, `screen_inventory`, `hypothesis_statement`, `feature_list` -- **Writes**: `prototype_scope`, `fidelity_decision`, `test_questions`, `test_script`, `participant_criteria` diff --git a/docs/skills/spec.md b/docs/skills/spec.md deleted file mode 100644 index 02193cf..0000000 --- a/docs/skills/spec.md +++ /dev/null @@ -1,58 +0,0 @@ -# Skill Spec: `/spec` - -## Purpose - -Generate technical specifications: data models, API contracts, business logic rules, and non-functional requirements. Bridges design artifacts into implementation-ready documentation. - -## Trigger - -- `/spec` (continues from context) -- `/spec "data models"` (targets specific spec area) - -## System Prompt - -``` -You are a technical architect helping translate product requirements into -implementation-ready specifications. Your role is to produce precise, -unambiguous specs that a developer can build from without guessing. -Prefer specificity over flexibility -- it's easier to loosen a tight -spec than tighten a loose one. -``` - -## Behavior - -### Flow - -1. **Check context**: Read `solution_concept`, `user_flow`, `screen_inventory`, `feature_list`. These are the primary inputs for technical specification. -2. **Scope**: Ask which spec areas to cover, or auto-select based on what's missing: - - Data models - - API contracts and interfaces - - Business logic and rules - - Non-functional requirements (performance, security, accessibility) -3. **Generate**: For each selected area, spawn Tech Spec Writer subagent with relevant context. -4. **Review**: Present specs one area at a time. Ask: "Does this match your expectations? Anything to adjust?" -5. **Validate**: After all areas, run consistency check across specs (e.g., do API endpoints reference all data models?). - -### Progressive Disclosure - -| Tier | Scope | Artifacts Produced | -|------|-------|-------------------| -| 1 | data_models, api_endpoints | data_models, api_contracts | -| 2 | + business_rules, interface_boundaries | + business_rules, interface_spec | -| 3 | + performance_reqs, security_reqs, accessibility_reqs, api_standards, integration_reqs | Full technical spec document | - -## Subagent: Tech Spec Writer - -Always spawned (spec writing benefits from focused context). Runs the tech requirements prompt sequence: - -1. `define_data_model` -> `validate_data_model` -> `data_access_patterns` -> `data_volume_scaling` -2. `define_api_endpoints` -> `interface_boundaries` -> `api_standards` -> `integration_requirements` -3. `define_business_rules` -> `map_decision_logic` -> `spec_calculations` -> `authorization_rules` -4. `performance_requirements` -> `security_requirements` -> `accessibility_requirements` - -Returns consolidated technical specification document. - -## Context Management - -- **Reads**: `solution_concept`, `user_flow`, `screen_inventory`, `feature_list`, `hypothesis_statement`, `constraints` -- **Writes**: `data_models`, `api_contracts`, `business_rules`, `nfr_spec`, `technical_specification` (consolidated) diff --git a/docs/skills/status.md b/docs/skills/status.md deleted file mode 100644 index ac12d2b..0000000 --- a/docs/skills/status.md +++ /dev/null @@ -1,63 +0,0 @@ -# Skill Spec: `/status` - -## Purpose - -Display current project state, completed artifacts, progress through phases, and suggest next steps. Primarily deterministic -- no LLM generation needed for core display. - -## Trigger - -- `/status` - -## Behavior - -### Flow - -1. **Read context**: Call `get_project_status` MCP tool. -2. **Display project overview**: - ``` - Project: Tea Tracker - Mode: Simulation - Tier: 2 (Structured Discovery) - Started: 2025-01-15 - ``` -3. **Display phase progress**: - ``` - Phase 00: Fuzzy Front End [3/7 prompts] ██████░░░░ - Phase 01: Define Problem [2/9 prompts] ████░░░░░░ - Phase 02: Objectives [not started] - Phase 03: Solution Hypothesis [not started] - Phase 04: User Flow [not started] - Phase 05: Prototype [not started] - Phase 06: Post-Test [not started] - Tech Requirements [not started] - ``` -4. **Display artifacts**: - ``` - Artifacts: - initial_concept (from capture_idea, Jan 15) - problem_space_map (from explore_problem, Jan 15) - problem_statement (from create_problem_statement, Jan 15) - proto_persona (from create_proto_persona, Jan 15) - ``` -5. **Suggest next steps**: Call `suggest_next_prompt` MCP tool. - ``` - Suggested next steps: - /hypothesis - Define objectives and form a testable hypothesis - /problem - Go deeper: analyze, scope, or qualify the problem - ``` -6. **Validation gates**: If any phase is complete, show gate status. - -### No LLM Needed - -Core display is deterministic: read JSON context, format output. LLM is only used if the user asks follow-up questions about their project state. - -## Context Management - -- **Reads**: Full context registry -- **Writes**: Nothing - -## MCP Tools Used - -- `get_project_status` -- primary data source -- `suggest_next_prompt` -- next step recommendations -- `validate_gate` -- gate status for completed phases diff --git a/scripts/README.md b/scripts/README.md index 6f44bfc..aaad4d2 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -1,11 +1,16 @@ # Scripts -Build pipeline for compiling working artifacts into validated spec packages. +This folder holds dev and test material only (`archive/`, `test-chain.md`, +`test-registry.md`). The compile pipeline documented below moved into the +plugin bundle at `plugin/scripts/` (ADR 0011), so it ships with the plugin. +Inside a plugin session it is invoked as +`python "${CLAUDE_PLUGIN_ROOT}/scripts/compile_spec.py"`; from a checkout of +this repo, use the `plugin/scripts/` paths shown here. ## Prerequisites ```bash -pip install -r requirements.txt +pip install -r plugin/scripts/requirements.txt ``` Requires Python 3.9+. @@ -26,9 +31,9 @@ artifacts/ ──→ compile_spec.py ──→ spec-package/ Assembles working artifacts from a project directory into a structured spec package. ```bash -python scripts/compile_spec.py -python scripts/compile_spec.py examples/tea-tracker -python scripts/compile_spec.py .product-dev +python plugin/scripts/compile_spec.py +python plugin/scripts/compile_spec.py examples/tea-tracker +python plugin/scripts/compile_spec.py .product-dev ``` **Input:** A directory containing `context.json` (registry) and `artifacts/` (working outputs from prompt chain). @@ -53,8 +58,8 @@ Also generates `manifest.yaml`, runs validation, and produces `CLAUDE.md` handof Runs 20 cross-reference integrity checks across spec package YAML files. ```bash -python scripts/validate_spec.py -python scripts/validate_spec.py examples/tea-tracker/spec-package +python plugin/scripts/validate_spec.py +python plugin/scripts/validate_spec.py examples/tea-tracker/spec-package ``` **Checks:** Referential integrity (8), completeness (7), consistency (5). See `docs/spec-package-schema.md` for the full check list. @@ -73,8 +78,8 @@ python scripts/validate_spec.py examples/tea-tracker/spec-package Generates a `CLAUDE.md` implementation instruction from a compiled spec package. ```bash -python scripts/generate_handoff.py -python scripts/generate_handoff.py examples/tea-tracker/spec-package +python plugin/scripts/generate_handoff.py +python plugin/scripts/generate_handoff.py examples/tea-tracker/spec-package ``` **Flags:**