From ca525da65eb5a92c325faa34be0bf7daa8466d11 Mon Sep 17 00:00:00 2001 From: Krishna Vyas Date: Fri, 21 Aug 2026 22:46:08 -0600 Subject: [PATCH 1/6] chore: drop ignores for tooling dirs that no longer exist --- .gitignore | 6 ------ 1 file changed, 6 deletions(-) diff --git a/.gitignore b/.gitignore index e7447c7..f7f98fb 100644 --- a/.gitignore +++ b/.gitignore @@ -7,9 +7,3 @@ Thumbs.db *.swp .vscode/ .idea/ - -# Superpower skill folders -docs/superpowers/ - -# SDD scratch workspace -.superpowers/ From 2168988911c3c80e56c7cfe429e50eb23424688a Mon Sep 17 00:00:00 2001 From: Krishna Vyas Date: Fri, 21 Aug 2026 22:46:15 -0600 Subject: [PATCH 2/6] refactor: move the skill into skills/scaffold for plugin layout --- SKILL.md => skills/scaffold/SKILL.md | 0 {references => skills/scaffold/references}/agent-profiles.md | 0 {references => skills/scaffold/references}/best-practices.md | 0 .../scaffold/references}/recommendation-heuristics.md | 0 {references => skills/scaffold/references}/templates.md | 0 5 files changed, 0 insertions(+), 0 deletions(-) rename SKILL.md => skills/scaffold/SKILL.md (100%) rename {references => skills/scaffold/references}/agent-profiles.md (100%) rename {references => skills/scaffold/references}/best-practices.md (100%) rename {references => skills/scaffold/references}/recommendation-heuristics.md (100%) rename {references => skills/scaffold/references}/templates.md (100%) diff --git a/SKILL.md b/skills/scaffold/SKILL.md similarity index 100% rename from SKILL.md rename to skills/scaffold/SKILL.md diff --git a/references/agent-profiles.md b/skills/scaffold/references/agent-profiles.md similarity index 100% rename from references/agent-profiles.md rename to skills/scaffold/references/agent-profiles.md diff --git a/references/best-practices.md b/skills/scaffold/references/best-practices.md similarity index 100% rename from references/best-practices.md rename to skills/scaffold/references/best-practices.md diff --git a/references/recommendation-heuristics.md b/skills/scaffold/references/recommendation-heuristics.md similarity index 100% rename from references/recommendation-heuristics.md rename to skills/scaffold/references/recommendation-heuristics.md diff --git a/references/templates.md b/skills/scaffold/references/templates.md similarity index 100% rename from references/templates.md rename to skills/scaffold/references/templates.md From 89f1dd92be632b6f296c3a985cfd2a5f320a0f47 Mon Sep 17 00:00:00 2001 From: Krishna Vyas Date: Fri, 21 Aug 2026 22:53:16 -0600 Subject: [PATCH 3/6] feat!: convert to a plugin, rename skill to scaffold, rework the roadmap Repo becomes a Claude Code plugin so it can host the planned plan-module and execute-plan skills alongside the existing one. The scaffolding skill is renamed code-idea -> scaffold, since skills namespace as : and code-idea:code-idea stutters. docs/roadmap.md becomes docs/development-roadmap.md: Module -> Sub-Module blocks with Status, Depends on, and scope boundaries, generated unconditionally because downstream module planning reads it as an input contract. It stops at sub-modules -- task tables are plan-module's output, and inventing them before any code exists would be guessing. Step 2 gains a decomposition question and a one-decision-at-a-time confirmation rule, paid for by merging two questions and dropping a duplicate example, so SKILL.md stays at 119 lines. The description gains sibling anti-triggers at 1006/1024 chars with every trigger phrase intact. CI now validates description length, frontmatter name, and manifest version on every tag -- S33 was a manual check guarding a failure that already shipped once. Co-Authored-By: Claude Opus 5 (1M context) --- .claude-plugin/marketplace.json | 11 +++ .claude-plugin/plugin.json | 10 ++ .github/workflows/release.yml | 96 +++++++++++++++---- AGENTS.md | 23 +++-- CHANGELOG.md | 76 +++++++++++++++ CONTRIBUTING.md | 25 +++-- README.md | 46 ++++++--- examples/sample-output/AGENTS.md | 2 +- .../sample-output/docs/development-roadmap.md | 54 +++++++++++ examples/sample-output/docs/roadmap.md | 16 ---- examples/test-scenarios.md | 22 ++++- skills/scaffold/SKILL.md | 24 ++--- skills/scaffold/references/best-practices.md | 11 +++ skills/scaffold/references/templates.md | 58 +++++++++-- 14 files changed, 385 insertions(+), 89 deletions(-) create mode 100644 .claude-plugin/marketplace.json create mode 100644 .claude-plugin/plugin.json create mode 100644 examples/sample-output/docs/development-roadmap.md delete mode 100644 examples/sample-output/docs/roadmap.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..688d35b --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,11 @@ +{ + "name": "code-idea", + "owner": { "name": "Melconcoast Inc", "url": "https://github.com/melconcoast" }, + "plugins": [ + { + "name": "code-idea", + "source": "./", + "description": "Turn a plan or idea into an AI-coding-agent-ready docs set, then plan and build the modules it defines." + } + ] +} diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..114b7f4 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,10 @@ +{ + "name": "code-idea", + "version": "3.0.0", + "description": "Turn a plan or idea into an AI-coding-agent-ready docs set, then plan and build the modules it defines.", + "author": { "name": "Melconcoast Inc" }, + "homepage": "https://github.com/melconcoast/code-idea#readme", + "repository": "https://github.com/melconcoast/code-idea", + "license": "MIT", + "keywords": ["claude-code", "skills", "agents-md", "claude-md", "scaffolding", "planning"] +} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 7db3973..39f027e 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,8 +1,14 @@ -name: Package and release skill +name: Package and release skills # Runs whenever a version tag (v1.0.0, v1.2.3, etc.) is pushed. -# Packages SKILL.md + references/ into a .skill file (a zip with the -# skill folder at its root) and attaches it to a GitHub Release. +# Validates the plugin manifest and every skill's frontmatter, then packages each +# skills// into .skill (a zip with the skill folder at its root) and +# attaches them to a GitHub Release. +# +# The plugin itself is NOT packaged as an archive. Claude Code installs plugins from +# a marketplace source pinned by git ref, so the tag is the plugin's distribution +# artifact. The .skill files exist for Claude.ai / Claude Desktop, which do take an +# uploaded skill folder. on: push: @@ -12,9 +18,6 @@ on: permissions: contents: write -env: - SKILL_NAME: code-idea - jobs: package: runs-on: ubuntu-latest @@ -22,23 +25,80 @@ jobs: - name: Checkout uses: actions/checkout@v6 - - name: Validate SKILL.md has required frontmatter + - name: Validate plugin manifest + run: | + jq -e . .claude-plugin/plugin.json > /dev/null \ + || (echo "::error::.claude-plugin/plugin.json is not valid JSON" && exit 1) + jq -e . .claude-plugin/marketplace.json > /dev/null \ + || (echo "::error::.claude-plugin/marketplace.json is not valid JSON" && exit 1) + + tag_version="${GITHUB_REF_NAME#v}" + manifest_version=$(jq -r '.version' .claude-plugin/plugin.json) + if [ "$manifest_version" != "$tag_version" ]; then + echo "::error::plugin.json version ($manifest_version) does not match tag ($tag_version)" + exit 1 + fi + echo "plugin.json version $manifest_version matches tag" + + - name: Validate every skill run: | - head -n 5 SKILL.md | grep -q '^name:' || (echo "SKILL.md is missing a 'name' field in its frontmatter" && exit 1) - head -n 5 SKILL.md | grep -q '^description:' || (echo "SKILL.md is missing a 'description' field in its frontmatter" && exit 1) + found=0 + for skill_md in skills/*/SKILL.md; do + [ -e "$skill_md" ] || continue + found=1 + name=$(basename "$(dirname "$skill_md")") + echo "Validating $name" + + grep -q '^name:' "$skill_md" \ + || (echo "::error file=$skill_md::missing 'name' in frontmatter" && exit 1) + grep -q '^description:' "$skill_md" \ + || (echo "::error file=$skill_md::missing 'description' in frontmatter" && exit 1) + + # The frontmatter name must match the directory, or the skill loads under + # a name nothing references. + fm_name=$(awk -F': *' '/^name:/{print $2; exit}' "$skill_md") + if [ "$fm_name" != "$name" ]; then + echo "::error file=$skill_md::frontmatter name '$fm_name' != directory '$name'" + exit 1 + fi + + # Reject a folded/multiline description rather than measuring a partial + # line and letting an over-length description through silently. + desc=$(awk -F'^description: ' '/^description: /{print $2; exit}' "$skill_md") + if [ -z "$desc" ]; then + echo "::error file=$skill_md::description must be a single-line 'description: ...' field" + exit 1 + fi + + # wc -m (characters), not wc -c (bytes) — em dashes are 3 bytes each and + # byte-counting would fail a description that is actually within the limit. + len=$(printf '%s' "$desc" | wc -m | tr -d ' ') + echo " description: $len chars" + if [ "$len" -gt 1024 ]; then + echo "::error file=$skill_md::description is $len chars, over the 1024 limit — the skill would silently fail to register" + exit 1 + fi + if [ "$len" -gt 970 ]; then + echo "::warning file=$skill_md::description is $len chars, within 55 of the 1024 limit" + fi + done + [ "$found" = "1" ] || (echo "::error::no skills/*/SKILL.md found" && exit 1) - - name: Package skill + - name: Package each skill run: | - mkdir -p "dist/${SKILL_NAME}" - cp SKILL.md "dist/${SKILL_NAME}/" - cp -r references "dist/${SKILL_NAME}/" - cd dist - zip -rq "../${SKILL_NAME}.skill" "${SKILL_NAME}" - cd .. - ls -la "${SKILL_NAME}.skill" + mkdir -p dist staging + for skill_md in skills/*/SKILL.md; do + [ -e "$skill_md" ] || continue + dir=$(dirname "$skill_md") + name=$(basename "$dir") + rm -rf "staging/$name" && mkdir -p "staging/$name" + cp -R "$dir"/. "staging/$name/" + (cd staging && zip -rq "../dist/${name}.skill" "$name") + done + ls -la dist/ - name: Create GitHub Release uses: softprops/action-gh-release@v3 with: - files: ${{ github.workspace }}/${{ env.SKILL_NAME }}.skill + files: ${{ github.workspace }}/dist/*.skill generate_release_notes: true diff --git a/AGENTS.md b/AGENTS.md index 275e9b0..84c89e7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,18 +1,21 @@ # code-idea -"Code this idea" — a Claude Skill (see `SKILL.md`) that turns a plan into an AI-coding-agent-ready docs set. This repo *is* the skill — there's no application code, only `SKILL.md` and `references/`. +"Code this idea" — a Claude Code plugin that turns a plan into an AI-coding-agent-ready docs set, then plans and builds the modules it defines. There's no application code, only markdown. One skill exists today: `scaffold` (see `skills/scaffold/SKILL.md`). Two more are planned and deliberately unbuilt — `plan-module` and `execute-plan` — and neither ships a directory until it is written. ## Critical rules (read first) -- **Confirmation must be explicit, never assumed from silence.** A fact that appears in a planning conversation because the assistant proposed it, or because it showed up in a prototype/demo (especially one shaped by the demo environment's own constraints), is NOT the same as something the user explicitly stated or confirmed. Step 2 of `SKILL.md` must apply the recommend-and-confirm pattern to both cases the same way — don't let "it's already in the conversation" substitute for a real confirmation. -- **`SKILL.md` stays lean.** Treat ~150 lines as a hard ceiling, ~30 as a starting point. If an edit grows it significantly, something else should shrink. +- **Confirmation must be explicit, never assumed from silence.** A fact that appears in a planning conversation because the assistant proposed it, or because it showed up in a prototype/demo (especially one shaped by the demo environment's own constraints), is NOT the same as something the user explicitly stated or confirmed. Step 2 of `skills/scaffold/SKILL.md` must apply the recommend-and-confirm pattern to both cases the same way — don't let "it's already in the conversation" substitute for a real confirmation. +- **Each `SKILL.md` stays lean.** Treat ~150 lines as a hard ceiling, ~30 as a starting point. If an edit grows it significantly, something else should shrink. - **The frontmatter `description` has a hard 1024-character limit.** Exceeding it is a load-time error — the skill silently fails to register, so nothing else in it can work. Measure after any edit to that field, and never trim a quoted trigger phrase to fit; cut descriptive text instead. `examples/test-scenarios.md` S33 is the check. -- **Never leave placeholder or TODO content** in `SKILL.md` or `references/` — see `CONTRIBUTING.md`. -- **`references/recommendation-heuristics.md` is expected to age.** Verify a specific tool/version recommendation against a current search before trusting it, and treat outdated entries there as a normal, welcome PR rather than a bug. -- **The container is per-agent; the content is not.** Which files the skill generates depends on the target agent (Claude Code reads `CLAUDE.md` and never `AGENTS.md`; Codex and Antigravity read `AGENTS.md` natively). What those files *say* is identical in every mode. When changing `SKILL.md`, check you haven't let a layout assumption leak into content guidance or vice versa — `examples/test-scenarios.md` S12 is the check for this. +- **Never leave placeholder or TODO content** in any `SKILL.md` or `references/` — see `CONTRIBUTING.md`. +- **`skills/scaffold/references/recommendation-heuristics.md` is expected to age.** Verify a specific tool/version recommendation against a current search before trusting it, and treat outdated entries there as a normal, welcome PR rather than a bug. +- **The container is per-agent; the content is not.** Which files the skill generates depends on the target agent (Claude Code reads `CLAUDE.md` and never `AGENTS.md`; Codex and Antigravity read `AGENTS.md` natively). What those files *say* is identical in every mode. When changing a `SKILL.md`, check you haven't let a layout assumption leak into content guidance or vice versa — `examples/test-scenarios.md` S12 is the check for this. +- **The plugin has three version sources — keep them equal.** The git tag, `.claude-plugin/plugin.json`, and `.claude-plugin/marketplace.json` all carry a version. CI blocks a tag whose `plugin.json` version doesn't match, but the marketplace entry is not machine-checked. Bump all three together. +- **A skill directory without a `SKILL.md` is not a placeholder for a future skill.** Git can't track an empty directory, and a `.gitkeep` stub registers a broken skill for every user. Reserve an unbuilt skill's name in `README.md` and `CHANGELOG.md`; create the directory when you write it. +- **`scaffold` stops at sub-modules.** `docs/development-roadmap.md` records modules and sub-modules only — never task tables. Task detail is `plan-module`'s output, and inventing it at scaffold time means guessing implementation detail nobody has decided. `examples/test-scenarios.md` S37 is the check. - **A deferred decision is not a placeholder.** "Undecided as of [date], do X meanwhile" is required output when the user defers; `[Project name]` and `TODO` are not. Don't let the no-placeholder rule suppress the pending-decision feature. ## Commands -- No build step — this is a pure markdown skill. +- No build step — this is a pure markdown plugin. - Package for release: `.github/workflows/release.yml` handles this automatically on a `v*.*.*` tag push. To test packaging locally, see the packaging step in that workflow file directly. ## Testing a change @@ -22,7 +25,7 @@ - `README.md` — human-facing overview, install/usage - `CONTRIBUTING.md` — contribution guidelines and file-ownership map - `CHANGELOG.md` — release history -- `references/best-practices.md` — the reasoning behind `SKILL.md`'s rules -- `references/recommendation-heuristics.md` — stack/database/UI defaults it proposes during its interview -- `references/agent-profiles.md` — per-agent container facts, with sources and dates; expected to age +- `skills/scaffold/references/best-practices.md` — the reasoning behind the skill's rules +- `skills/scaffold/references/recommendation-heuristics.md` — stack/database/UI defaults it proposes during its interview +- `skills/scaffold/references/agent-profiles.md` — per-agent container facts, with sources and dates; expected to age - `examples/test-scenarios.md` — the scenarios a change must be checked against diff --git a/CHANGELOG.md b/CHANGELOG.md index c8ad1e6..194997d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,81 @@ # Changelog +## [3.0.0] — 2026-08-21 + +Major release. `code-idea` is now a Claude Code **plugin** rather than a standalone skill repo, the +skill inside it is renamed `scaffold`, and `docs/roadmap.md` becomes `docs/development-roadmap.md` +with a module/sub-module structure and unconditional generation. Read **Breaking** before upgrading. + +### Breaking +- **The skill is renamed `code-idea` → `scaffold`.** It now lives at `skills/scaffold/` inside a + plugin named `code-idea`, so explicit invocation is `/code-idea:scaffold`. Natural-language + triggering is unchanged — every trigger phrase from 2.x still fires. +- **The repo is now a plugin.** `SKILL.md` and `references/` moved from the repo root to + `skills/scaffold/`, alongside a new `.claude-plugin/plugin.json` and `marketplace.json`. Any skills + directory pointed at this repo's root — a symlink into `~/.claude/skills/`, a vendored copy, a + submodule — no longer finds a skill and loads nothing, *silently*. See **Upgrading**. +- **`docs/roadmap.md` is renamed `docs/development-roadmap.md` and restructured.** The three flat + lists (`## MVP scope`, `## Deferred`, `## Open questions`) become `## Module ` blocks holding + `### Sub-Module .` blocks, each carrying `Status`, `Depends on`, `In scope`, `Out of scope`, + and `Tasks`, in dependency order. `## Deferred` and `## Open questions` survive unchanged. Anything + reading the old `## MVP scope` list will find nothing. A re-run detects a pre-3.0 `roadmap.md`, + proposes the rename and conversion, and waits for approval — like any other content migration. +- **The development roadmap is now always generated**, including for projects with no MVP-vs-later + split. It is the input contract for downstream module planning, so its absence removes that step's + input rather than degrading it. This is a deliberate, documented exception to "don't generate a + file nobody needs" — see `references/best-practices.md`, "Why the development roadmap is always + generated." A re-run against a project with no roadmap will add one. +- **`Status` is a closed vocabulary** — `planned`, `in progress`, `done`, `blocked`, `dropped` — at + both module and sub-module level. A dropped module keeps its block with `Status: dropped` rather + than moving into `## Deferred`, so `Depends on:` references to its id don't dangle. This replaces + the old "move items between sections rather than deleting them" directive for modules; it still + holds for `## Deferred` items themselves. + +### Added +- **A module/sub-module decomposition question in Step 2**, covering both the units of work and their + dependency order, delivered as a specific proposal to accept or reorder rather than an open + question. It fills the roadmap, and it is mandatory rather than conditional now that the roadmap + always ships. +- **A one-decision-at-a-time confirmation rule.** Recommendations are no longer bundled, and a single + "sounds good" against a bundle confirms none of them. +- **Anti-triggers in the frontmatter `description`.** "plan the next module", "build task 3", and + "execute the plan" no longer wake this skill into re-scaffolding a repo that already has docs. + Every existing trigger phrase is preserved verbatim; the room was paid for out of descriptive text. +- **CI validates every skill on a tag** — description length against the 1024-character limit, + frontmatter `name` matching its directory, and `plugin.json`'s version matching the tag. Scenario + S33 was a manual check guarding a failure that has already shipped once (see 2.0.1's Fixed + section); it now blocks the release. Length is measured in characters, not bytes — em dashes made + byte-counting reject valid descriptions. +- `examples/test-scenarios.md` — S35–S44, covering the roadmap format, unconditional generation, the + scaffold-stops-at-sub-modules boundary, the dropped-module rule, dependency integrity, pre-3.0 + migration, the decomposition question, the confirmation rule, and the sibling anti-triggers. +- `plan-module` and `execute-plan` are reserved skill names in this plugin. Neither is authored yet, + and neither ships a directory — git cannot track an empty one, and a stub `SKILL.md` would register + a broken skill for every user. + +### Changed +- `.github/workflows/release.yml` discovers and packages every `skills/*/SKILL.md` instead of a + hardcoded root `SKILL.md`, so a new skill needs no workflow change. Each still ships as its own + `.skill` asset — the plugin itself is distributed by git ref, not as an archive, because Claude + Code installs plugins from a marketplace source and has no install path for a zipped plugin. +- `README.md`, `AGENTS.md`, and `CONTRIBUTING.md` rewritten for a multi-skill repo. + `CONTRIBUTING.md`'s "Where things live" is no longer written in the singular. +- Step 2 trimmed to pay for the additions: the single-app and per-subsystem questions merged into + one, and the palette Bad/Good example pair dropped — the database pair already carries the pattern, + and the prototype-theme pair still covers the UI case. `SKILL.md` is unchanged in length at 119 lines. +- `examples/sample-output/` regenerated in the new format, now demonstrating a `blocked` sub-module + whose blocker is the pending decision already recorded in `decisions.md`. + +### Upgrading from 2.x +1. Remove the old install. If you symlinked or copied this repo into a skills directory, delete it — + it points at a location that no longer holds a skill. +2. Install the plugin: `/plugin marketplace add melconcoast/code-idea` then + `/plugin install code-idea@code-idea`. For Claude.ai or Claude Desktop, download the + `scaffold.skill` asset from the release instead; that path is unchanged apart from the filename. +3. Re-run the skill against existing projects. It detects the scaffold, proposes the roadmap rename + and migration to the module format, and adds a roadmap to any project that doesn't have one. + Nothing is written without approval. + ## [2.0.1] — 2026-08-12 Major release. The skill's central rule is reversed: content no longer always lives in `AGENTS.md`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 88a2e91..56d2621 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,14 +1,21 @@ # Contributing -Thanks for considering a contribution. This skill is small on purpose — most useful contributions will be sharpening what's already here, not adding new files. +Thanks for considering a contribution. This plugin is small on purpose — most useful contributions will be sharpening what's already here, not adding new files. ## Where things live -- **`SKILL.md`** — the workflow itself: when the skill triggers, how the interview works, how structure is decided, how content gets drafted and written. Changes here affect behavior directly, so keep edits scoped and explain the reasoning in the PR description. -- **`references/best-practices.md`** — the research and reasoning behind the size limits, ordering rules, and doc-vs-skill split. If you're proposing a change to `SKILL.md`'s rules, the backing reasoning (or a correction to outdated reasoning) belongs here. -- **`references/recommendation-heuristics.md`** — stack/database/caching/UI defaults the skill proposes during its interview. **This file is expected to age** — tooling and best practices shift. If something here is outdated, that's a welcome PR, not a bug report. -- **`references/agent-profiles.md`** — what each coding agent reads and how it loads it. **This file is expected to age**, like the heuristics file, and every claim carries a source URL and verified-on date. A stale entry is a welcome PR. Never add a row you can't cite from that agent's own docs. -- **`references/templates.md`** — the skeleton structure for each generated doc type. +The repo is a Claude Code plugin. Each skill owns a directory under `skills/`, holding its own +`SKILL.md` and its own `references/`. One skill exists today — `scaffold`. Two are planned and +deliberately unbuilt, `plan-module` and `execute-plan`; neither gets a directory until it is written, +because git can't track an empty directory and a stub `SKILL.md` registers a broken skill for everyone. + +- **`.claude-plugin/plugin.json`** and **`marketplace.json`** — the plugin manifest, and the entry that makes this repo its own marketplace. Both carry a version that must match the release tag; CI enforces the first. +- **`skills/scaffold/SKILL.md`** — the workflow itself: when the skill triggers, how the interview works, how structure is decided, how content gets drafted and written. Changes here affect behavior directly, so keep edits scoped and explain the reasoning in the PR description. +- **`skills/scaffold/references/best-practices.md`** — the research and reasoning behind the size limits, ordering rules, and doc-vs-skill split. If you're proposing a change to the skill's rules, the backing reasoning (or a correction to outdated reasoning) belongs here. +- **`skills/scaffold/references/recommendation-heuristics.md`** — stack/database/caching/UI defaults the skill proposes during its interview. **This file is expected to age** — tooling and best practices shift. If something here is outdated, that's a welcome PR, not a bug report. +- **`skills/scaffold/references/agent-profiles.md`** — what each coding agent reads and how it loads it. **This file is expected to age**, like the heuristics file, and every claim carries a source URL and verified-on date. A stale entry is a welcome PR. Never add a row you can't cite from that agent's own docs. +- **`skills/scaffold/references/templates.md`** — the skeleton structure for each generated doc type. +- **`examples/`** — shared across every skill in the plugin, which is why it stays at the repo root rather than moving under `skills/scaffold/`. ## Reporting an outdated recommendation @@ -20,17 +27,17 @@ Ground it, don't just assert it. "Recommend X because it's popular" is weaker th ## Testing a change -There's no automated test suite — this is a markdown-based skill, not code. To validate a change: +There's no automated test suite — this is a markdown-based plugin, not code. CI checks frontmatter and description length on a tag, but behavior is validated by hand. To validate a change: 1. Run the skill against a small sample plan (a paragraph describing a hypothetical project is enough) and check that the interview questions and generated structure make sense. 2. Try at least one case where your change should clearly kick in, and one where it clearly shouldn't, to make sure the trigger condition is specific enough. -3. If you're changing `SKILL.md` itself, re-read it end to end afterward — it's meant to stay short, so a change that grows it significantly should come with something else trimmed. +3. If you're changing a `SKILL.md` itself, re-read it end to end afterward — it's meant to stay short, so a change that grows it significantly should come with something else trimmed. 4. Run the relevant scenarios from `examples/test-scenarios.md`, including at least one "must NOT produce" case — a rule that fires when it shouldn't is as broken as one that never fires. ## Style - Bullet-point imperatives over prose paragraphs, consistent with how the skill asks generated instruction files (`AGENTS.md`, `CLAUDE.md`) to be written. - No placeholder or TODO content in what ships — if something's unfinished, leave it out rather than stubbing it in. One carve-out: a dated pending-decision entry (`undecided as of YYYY-MM-DD`, plus what to do meanwhile) asserts a real current fact and is required output when a user defers a choice — that's not a placeholder. -- Keep `SKILL.md` itself lean; anything that needs more than a few lines of explanation probably belongs in `references/` instead, linked from the relevant step. +- Keep each `SKILL.md` lean; anything that needs more than a few lines of explanation probably belongs in that skill's `references/` instead, linked from the relevant step. ## Code of conduct diff --git a/README.md b/README.md index b201105..bcefb9e 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ *"Code this idea"* — take a plan or idea from conversation to a state a coding agent can actually build from correctly. -A Claude Skill that turns a project plan, idea, or planning conversation into a complete, AI-coding-agent-ready documentation set — a lean root context file in whichever format your target agent reads natively (`CLAUDE.md` for Claude Code, `AGENTS.md` for Codex or Antigravity, or both for mixed/generic targets), plus linked docs (architecture, decisions, conventions, roadmap, product, design-system), and, for monorepos, nested per-subsystem context files. +A Claude Code **plugin**. Its `scaffold` skill turns a project plan, idea, or planning conversation into a complete, AI-coding-agent-ready documentation set — a lean root context file in whichever format your target agent reads natively (`CLAUDE.md` for Claude Code, `AGENTS.md` for Codex or Antigravity, or both for mixed/generic targets), plus linked docs (architecture, decisions, conventions, development roadmap, product, design-system), and, for monorepos, nested per-subsystem context files. It doesn't apply one fixed template. It interviews you (or reads the plan straight out of your conversation) to figure out what your specific project actually needs, proposes grounded recommendations for anything you don't have a strong opinion on — tech stack, database/caching choice, UI theme and typography — and lets you confirm or override each one. @@ -12,7 +12,7 @@ Most "let's add a CLAUDE.md" moments end one of two ways: a single giant file wi ## What it generates -The **container** — which root file(s) exist and how they load — depends on which agent(s) you target; see [`references/agent-profiles.md`](references/agent-profiles.md) for the sourced facts behind each row: +The **container** — which root file(s) exist and how they load — depends on which agent(s) you target; see [`references/agent-profiles.md`](skills/scaffold/references/agent-profiles.md) for the sourced facts behind each row: | Target agent(s) | Root file(s) | |---|---| @@ -28,7 +28,7 @@ The **content** is identical regardless of layout — only what a given project | `docs/architecture.md` | Real architectural complexity worth recording | | `docs/decisions.md` | Non-obvious decisions have been made (append-only, dated, rationale-first) | | `docs/conventions.md` | Naming/structural rules beyond what a linter enforces | -| `docs/roadmap.md` | There's a real MVP-vs-later split worth protecting | +| `docs/development-roadmap.md` | **Always** — modules and sub-modules, in dependency order, with scope boundaries | | `docs/product.md` | Business/feature rules an agent needs to implement correctly | | `docs/design-system.md` | There's a UI subsystem with real design conventions | | Nested `/AGENTS.md` or `/CLAUDE.md` | Genuine monorepo, subsystems with materially different conventions — matches the root layout | @@ -53,13 +53,22 @@ The **content** is identical regardless of layout — only what a given project - **Stale docs are worse than no docs** — architecture docs must be updated alongside real changes, or removed. - **Recurring procedures become Skills**, not static docs. -See [`references/best-practices.md`](references/best-practices.md) for the full reasoning, [`references/recommendation-heuristics.md`](references/recommendation-heuristics.md) for the stack/database/UI defaults it draws on, and [`references/agent-profiles.md`](references/agent-profiles.md) for the sourced per-agent facts behind the container table above. +See [`references/best-practices.md`](skills/scaffold/references/best-practices.md) for the full reasoning, [`references/recommendation-heuristics.md`](skills/scaffold/references/recommendation-heuristics.md) for the stack/database/UI defaults it draws on, and [`references/agent-profiles.md`](skills/scaffold/references/agent-profiles.md) for the sourced per-agent facts behind the container table above. ## Installation -**Claude.ai / Claude Desktop / Claude Code:** clone this repo (or download a packaged `.skill` release) and add it as a skill — see [Anthropic's skills documentation](https://docs.claude.com) for the current install path, since this changes over time. +**Claude Code** — install as a plugin: -**From source:** the skill is just `SKILL.md` plus `references/` — no build step. Point your tool's skill directory at this repo, or copy the two into an existing skills folder. +``` +/plugin marketplace add melconcoast/code-idea +/plugin install code-idea@code-idea +``` + +Skills are then invoked as `/code-idea:scaffold`, or triggered naturally by what you ask for. + +**Claude.ai / Claude Desktop** — download the `scaffold.skill` asset from a [release](https://github.com/melconcoast/code-idea/releases) and add it as a skill. + +**From source** — no build step. Point a local marketplace at your clone: `/plugin marketplace add /path/to/code-idea`. ## Usage @@ -69,22 +78,31 @@ Once installed, just ask naturally — "let's get this ready for Claude Code," " ``` . -├── SKILL.md # the skill itself -├── AGENTS.md # this repo's own content file -├── CLAUDE.md # @AGENTS.md import, so Claude Code loads it too -├── references/ -│ ├── best-practices.md # research/reasoning behind the rules -│ ├── recommendation-heuristics.md # stack/DB/UI defaults, with sources -│ ├── agent-profiles.md # what each target agent reads and how, with sources -│ └── templates.md # skeleton for each doc type +├── .claude-plugin/ +│ ├── plugin.json # plugin manifest +│ └── marketplace.json # so the repo is its own marketplace +├── skills/ +│ └── scaffold/ +│ ├── SKILL.md # the skill itself +│ └── references/ +│ ├── best-practices.md # research/reasoning behind the rules +│ ├── recommendation-heuristics.md # stack/DB/UI defaults, with sources +│ ├── agent-profiles.md # what each target agent reads and how, with sources +│ └── templates.md # skeleton for each doc type ├── examples/ │ ├── sample-output/ # example generated file tree │ └── test-scenarios.md # scenarios a change must be checked against +├── AGENTS.md # this repo's own content file +├── CLAUDE.md # @AGENTS.md import, so Claude Code loads it too ├── CONTRIBUTING.md ├── CHANGELOG.md └── LICENSE ``` +Two further skills are planned for this plugin and are **not built yet**: `plan-module`, which turns +one sub-module of the development roadmap into a task breakdown, and `execute-plan`, which builds it. +Neither ships a directory until it is written. + ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) — the reference docs are explicitly expected to age (tooling and best practices shift), so keeping them current is one of the most useful contributions. diff --git a/examples/sample-output/AGENTS.md b/examples/sample-output/AGENTS.md index 5c9dc72..2780dff 100644 --- a/examples/sample-output/AGENTS.md +++ b/examples/sample-output/AGENTS.md @@ -33,7 +33,7 @@ Express API talks to Postgres directly via a query layer in `/server/db`. React ## Related docs - `docs/decisions.md` — why non-obvious choices were made -- `docs/roadmap.md` — what's in scope now vs. deferred +- `docs/development-roadmap.md` — the module/sub-module breakdown, dependency order, and what's deliberately deferred - `docs/product.md` — current business/feature rules ## Maintaining these docs diff --git a/examples/sample-output/docs/development-roadmap.md b/examples/sample-output/docs/development-roadmap.md new file mode 100644 index 0000000..ce233cd --- /dev/null +++ b/examples/sample-output/docs/development-roadmap.md @@ -0,0 +1,54 @@ +# Development Roadmap + +*One block per module, sub-modules nested under it, in dependency order. A module or sub-module that's dropped keeps its block and becomes `Status: dropped` with a one-line reason — never deleted and never demoted into Deferred, or every `Depends on:` pointing at it dangles.* + +## Module 1 — Task core +**Status:** done +**Depends on:** none + +### Sub-Module 1.1 — Task CRUD +**Status:** done +**In scope:** create, edit, and delete tasks; title, description, and due date +**Out of scope:** recurring tasks — see Deferred +**Tasks:** not yet planned + +### Sub-Module 1.2 — Status machine +**Status:** done +**In scope:** the `todo -> in_progress -> done` transition rules, enforced server-side +**Out of scope:** custom per-workspace status names +**Tasks:** not yet planned + +## Module 2 — Workspace and membership +**Status:** done +**Depends on:** Module 1 + +### Sub-Module 2.1 — Single-team workspace +**Status:** done +**In scope:** one workspace, its member list, and the admin role that can override task status +**Out of scope:** multi-workspace support and tenant isolation — see Deferred +**Tasks:** not yet planned + +## Module 3 — Assignment +**Status:** in progress +**Depends on:** Module 2 + +### Sub-Module 3.1 — Assign a task +**Status:** in progress +**In scope:** exactly one assignee per task; only the assignee or a workspace admin may change status +**Out of scope:** multi-assignee tasks; reassignment history +**Tasks:** not yet planned + +### Sub-Module 3.2 — Assignment notifications +**Status:** blocked +**Depends on:** 3.1, plus the pending email-provider decision in `docs/decisions.md` +**In scope:** notify the new assignee by email when a task is assigned to them +**Out of scope:** digests, in-app notifications, per-user notification preferences +**Tasks:** not yet planned + +## Deferred (explicitly out of scope for now) +- Multi-workspace/team support — the data model isn't designed for tenant isolation yet, don't build features assuming it +- Recurring tasks — no demand from the pilot team yet +- Mobile app — web-only for now + +## Open questions +- Whether task comments are needed for v1 or can wait diff --git a/examples/sample-output/docs/roadmap.md b/examples/sample-output/docs/roadmap.md deleted file mode 100644 index f00deab..0000000 --- a/examples/sample-output/docs/roadmap.md +++ /dev/null @@ -1,16 +0,0 @@ -# Roadmap - -*Move items between sections rather than deleting them — a deleted "deferred" item loses the record that it was deliberately not built.* - -## MVP scope -- Create, assign, and update status of tasks -- Single-team workspace (no multi-tenancy yet) -- Email notification on assignment - -## Deferred (explicitly out of scope for now) -- Multi-workspace/team support — the data model isn't designed for tenant isolation yet, don't build features assuming it -- Recurring tasks -- Mobile app — web-only for now - -## Open questions -- Whether task comments are needed for v1 or can wait diff --git a/examples/test-scenarios.md b/examples/test-scenarios.md index 1419058..b26d102 100644 --- a/examples/test-scenarios.md +++ b/examples/test-scenarios.md @@ -47,7 +47,7 @@ Fixture A, with this appended. The values are fake, but the skill must treat the | S9 | Fixture A, target = Codex alone | Content in `AGENTS.md`, root file well under the 32 KiB cap | Any `CLAUDE.md` | | S10 | Fixture A, target = generic | `AGENTS.md` + `CLAUDE.md` containing `@AGENTS.md` | Native-mode layout | | S11 | Fixture A, target = Claude Code + Codex | Portable core; size reported against each agent's own limit, in its own unit (lines, then bytes) | Native mode for either; collapsing the two into a single "stricter" number | -| S12 | Fixture A run twice, Claude-native then Codex-native | `docs/*.md` byte-identical across both runs | Layer 2 content varying by target | +| S12 | Fixture A run twice, Claude-native then Codex-native | `docs/*.md` byte-identical across both runs, **`development-roadmap.md` included — same module and sub-module ids, same order, same `Status` values** | Layer 2 content varying by target | | S13 | Fixture B, Claude-native | Nested `CLAUDE.md` per subsystem; critical rules still in root | Critical rules pushed into `.claude/rules/` | | S16 | Fixture A, target = Antigravity alone | Content in `AGENTS.md` | A `GEMINI.md`, or any `CLAUDE.md` | | S17 | Fixture A, target = Antigravity, repo already has `GEMINI.md` | Content written into the existing `GEMINI.md` | A second root rules file alongside it | @@ -69,6 +69,24 @@ Fixture A, with this appended. The values are fake, but the skill must treat the | S23 | S22's output | The rule is a single italic line | A `## Maintaining` section inside a `docs/*.md` file | | S24 | Fixture A, user defers the theme | `decisions.md` extension rule present even though the only entry is `Status: Pending` | A pending-only decisions log with no append-only rule | +## Development-roadmap scenarios + +| ID | Setup | Must produce | Must NOT produce | +|---|---|---|---| +| S35 | Fixture A, trivial scope, user articulates no MVP-vs-later split | `docs/development-roadmap.md` generated anyway, with real module/sub-module blocks reflecting a decomposition confirmed in Step 2 | Skipping the file because "there's no real split"; a single `Module 1 — build the app` block that just restates the project title | +| S36 | Any run generating `docs/development-roadmap.md` | `## Module ` blocks holding `### Sub-Module .` blocks, each carrying `Status`, `In scope`, `Out of scope`, `Tasks`, in dependency order | A `## MVP scope` flat list; a sub-module missing any field | +| S37 | Fixture B, a rich planning conversation with plenty of implementation detail available | Sub-modules stop at scope boundaries, every one reading `**Tasks:** not yet planned` | Any task table, task rows, or invented implementation detail at scaffold time | +| S38 | Fixture A, user drops a sub-module mid-interview | That block stays in place with `Status: dropped` and a one-line reason | The block deleted; the sub-module demoted into `## Deferred` as a bullet | +| S39 | Fixture B | Every `Depends on:` names `none`, an id with a block in the same file, or an explicitly named external blocker | A `Depends on:` pointing at a module or sub-module id that has no block | +| S40 | Fixture C, an existing pre-3.0 `docs/roadmap.md` in the old three-list format | The rename to `docs/development-roadmap.md` and the conversion proposed, with what-maps-where shown, before anything is written | A silent rewrite; both files left side by side | + +## Interview scenarios + +| ID | Setup | Must produce | Must NOT produce | +|---|---|---|---| +| S41 | Fixture B (three subsystems, different owners) | A specific module/sub-module decomposition proposed *with* its dependency order — "Module 1 ingest API, then Module 2 device agent, since the agent needs somewhere to report to. Take it, or reorder?" | An open-ended "how would you like to break this into modules?"; a decomposition with no ordering | +| S42 | Fixture A, one assistant message bundling a stack recommendation, a module decomposition, and the target-agent question; user replies "sounds good" | Each of the three re-confirmed individually before any is written as settled | Any of the three written as settled on the strength of the single blanket reply | + ## Convention scenarios | ID | Setup | Must produce | Must NOT produce | @@ -93,6 +111,8 @@ scenario depends on. |---|---|---|---| | S28 | "get this ready for Claude Code" / "scaffold the project docs" / "turn this plan into context files" / "hand this off to a coding agent" | The skill fires on each | Silence on any of them | | S29 | "how does AGENTS.md work?" — abstract question, no project in play | An explanation | A scaffold, or an interview | +| S43 | "plan the next module" / "build task 3" / "execute the plan", against a repo that already has a scaffold | Silence, or an explicit hand-off | `scaffold` firing and re-scaffolding a repo that already has docs | +| S44 | S28's four trigger phrases, re-run after any anti-trigger edit | All four still fire | A positive trigger lost as collateral damage from an anti-trigger | ## Output-integrity scenarios diff --git a/skills/scaffold/SKILL.md b/skills/scaffold/SKILL.md index 9e04bc5..4e60cc2 100644 --- a/skills/scaffold/SKILL.md +++ b/skills/scaffold/SKILL.md @@ -1,6 +1,6 @@ --- -name: code-idea -description: Transforms a project plan, idea, or planning conversation into an AI-coding-agent-ready docs set — a lean root context file in whichever format the target agent reads natively (CLAUDE.md, AGENTS.md, or both), plus linked docs and nested per-subsystem files for monorepos. Interviews the user to pick the right structure, not one fixed template, re-confirms anything not explicitly decided, and supports deferring a choice as a tracked pending decision. Use this skill whenever the user wants to turn a plan/idea into files for Claude Code or another coding agent, says things like "set up AGENTS.md/CLAUDE.md for this", "get this ready for Claude Code", "scaffold the project docs", "turn this plan into context files", "hand this off to a coding agent", or has just finished a substantial planning/design discussion and is about to start building. Also trigger when the user asks how to structure AGENTS.md/CLAUDE.md and wants it actually applied to their project, not just explained in the abstract. +name: scaffold +description: Transforms a project plan, idea, or planning conversation into an AI-coding-agent-ready docs set — a lean root context file for the target agent (CLAUDE.md, AGENTS.md, or both), plus linked docs and nested per-subsystem files for monorepos. Interviews to pick the right structure, re-confirms undecided facts, and tracks deferred choices as pending decisions. Use this skill whenever the user wants to turn a plan/idea into files for Claude Code or another coding agent, says things like "set up AGENTS.md/CLAUDE.md for this", "get this ready for Claude Code", "scaffold the project docs", "turn this plan into context files", "hand this off to a coding agent", or has just finished a substantial planning/design discussion and is about to start building. Also trigger when the user asks how to structure AGENTS.md/CLAUDE.md and wants it actually applied to their project, not just explained in the abstract. Not for planning or building a module from an existing roadmap — use plan-module or execute-plan. --- # code-idea @@ -27,7 +27,7 @@ Turns a plan into the actual files a coding agent needs to work correctly — no ## Workflow ### Step 0 — Check for an existing scaffold -- Look for a root `AGENTS.md`, `CLAUDE.md`, or `GEMINI.md`, or a `docs/` file matching one of this skill's own generated names (`decisions.md`, `product.md`, `roadmap.md`, `architecture.md`, `conventions.md`, `design-system.md`) at the target path. If any exist, this is a **re-run**, not a fresh scaffold — say so, name what you found, and state that its contents will be re-confirmed rather than assumed. +- Look for a root `AGENTS.md`, `CLAUDE.md`, or `GEMINI.md`, or a `docs/` file matching one of this skill's own generated names (`decisions.md`, `product.md`, `development-roadmap.md`, `roadmap.md` from before 3.0, `architecture.md`, `conventions.md`, `design-system.md`) at the target path. If any exist, this is a **re-run**, not a fresh scaffold — say so, name what you found, and state that its contents will be re-confirmed rather than assumed. - If a previous run left pending decisions, surface those first: "last time you parked [X] — decide now, or keep it parked?" - Never infer the target agent from which files exist. The layout is a product of a previous answer; treating it as evidence makes that answer self-confirming forever. @@ -41,24 +41,24 @@ Turns a plan into the actual files a coding agent needs to work correctly — no ### Step 2 — Interview (this is what makes it dynamic, not templated) Ask only what isn't already known from the plan or conversation. Typical questions — adapt freely, don't ask ones you already have answers to: -- Single app, or multiple subsystems / a monorepo? (This alone determines whether nested per-subsystem files are needed at all — most small projects don't need them.) -- What does each subsystem do, and what stack does it use? +- Single app, or multiple subsystems / a monorepo — and if multiple, what does each do and what stack does it use? (This alone determines whether nested per-subsystem files are needed — most small projects don't need them.) - Which coding agent(s)? Claude Code, Codex, Antigravity, or generic/unsure. This decides the file layout only, never the content — see Step 3. Always ask; never infer it from which files already exist. - Is there a frontend/UI subsystem with its own design conventions worth a dedicated design-system doc? - Any naming or structural conventions beyond what a linter enforces — table/column naming, API route shapes, module boundaries? (These become `docs/conventions.md`; skip the file when the answer is "just the tooling defaults.") - Any business rules, pricing logic, or security/compliance constraints an agent must never quietly change? (These become the highest-priority root-file rules AND get a decisions.md entry.) - Writing into an existing repo, or drafting for one that doesn't exist yet? - Any procedures likely to recur (testing steps, deployment, local setup) that should become a Skill instead of a doc? +- How does this break into modules and sub-modules, and in what order? Propose a specific decomposition with its dependency chain ("Module 1 Infrastructure — 1.1 auth, 1.2 audit logging — then Module 2 Orders, since orders needs a user"), not an open-ended ask. This becomes `docs/development-roadmap.md`. **Don't leave these as open questions the user has to answer from scratch.** For anything with a genuine best-practice default — tech stack, database/caching choice, monorepo vs. single-repo, UI theme/typography/design pattern — propose a specific, context-grounded recommendation *as part of the question*, and let the user accept it or override it. This matters most for a user without strong opinions on the topic; don't make them invent an answer to a question they came here to avoid having to research themselves. - Bad: "What database do you want to use?" - Good: "For [the order/credit/job data described], I'd recommend Postgres (relational, transactional, handles the credits ledger cleanly) with Redis for the live print-queue/session state. Go with that, or do you have something else in mind?" -- Bad: "What's your color palette and typography?" -- Good: "Based on [the domain], I'd suggest [a specific grounded direction, not a generic default] for the palette and pairing. Want me to run with that, or do you already have brand colors/fonts in mind?" **Silence is not confirmation.** Anything tagged (b) in Step 1 — an assistant proposal, or a choice baked into a prototype/demo — goes through the same recommend-and-confirm pattern before it's written into any doc as settled, even if the user never objected to it at the time. Be explicit about where it came from, especially when the choice was forced by the demo environment rather than chosen on the merits. +**One decision at a time.** Never bundle several recommendations into one message and read a single "sounds good" as confirming all of them — a blanket yes against a bundle confirms nothing. Ask, confirm, then move to the next. + - Bad: silently carrying the prototype's UI stack and theme into `design-system.md` because it's "already decided." - Good: "The working prototype used [library + theme], but that was partly forced by what the chat artifact sandbox allows — it wasn't a production call. For the real build I'd recommend [grounded recommendation]. Keep the prototype's choice, go with this, or something else?" @@ -71,7 +71,7 @@ Ground every recommendation in the actual project context (data shape, expected Prefer short, specific questions. Use an elicitation/multiple-choice tool where the surface supports it and the question fits that shape (a recommendation plus 2–3 alternatives works well there); don't force an open-ended essay prompt when a recommend-and-confirm question would do. ### Step 3 — Decide the structure (per-project, not fixed) -Based on the interview, choose which files are actually warranted. Don't generate a file nobody needs — a trivial single-file project needs one root file and maybe nothing else. +Based on the interview, choose which files are actually warranted. Don't generate a file nobody needs — a trivial single-file project needs one root file, `docs/development-roadmap.md`, and often nothing else. First pick the **layout** from the target agent(s) — this decides which files exist, never what they say: @@ -84,14 +84,14 @@ First pick the **layout** from the target agent(s) — this decides which files One named agent gets its native layout; plural or generic gets the portable one. Size limits aren't comparable across agents (lines vs. bytes vs. characters) — report each in its own unit; the skill's own ~150-line root-file ceiling still applies to the root file independently of any agent's cap. Keep critical rules in the root file even in Claude-native mode — nested files and path-scoped rules don't survive `/compact`. See `references/agent-profiles.md`. -Then pick the **linked docs**, which are identical in every layout. Don't generate a file nobody needs: +Then pick the **linked docs**, which are identical in every layout. Don't generate a file nobody needs — with one deliberate exception, `development-roadmap.md`, which is always generated because downstream module planning reads it as its input contract (see `references/best-practices.md`): | File | Generate when | |---|---| | `docs/architecture.md` | There's real architectural complexity worth recording — skip for trivial projects | | `docs/decisions.md` | Any non-obvious decision has been made or deferred | | `docs/conventions.md` | There are naming/structure rules beyond what a linter enforces — otherwise keep a thin `## Code style` section in the content file | -| `docs/roadmap.md` | There's a real MVP-vs-later split to protect against scope creep | +| `docs/development-roadmap.md` | **Always** — record the Step 2 module/sub-module decomposition and its dependency order, even on a trivial project. Modules and sub-modules only; task-level detail is not invented here | | `docs/product.md` | There are business/feature rules an agent must implement correctly | | `docs/design-system.md` | There's a UI subsystem with real design conventions — **not** when the design decision was deferred | @@ -105,7 +105,7 @@ Then pick the **linked docs**, which are identical in every layout. Don't genera ### Step 5 — Write and confirm - If there's filesystem access to the actual project (e.g. running inside Claude Code with a real repo), write the files directly into the correct paths. - If running in a chat-only surface without a project filesystem, produce the files as downloadable/presentable content and tell the user exactly which path each one belongs at once they're in their project. -- If Step 0 found an existing scaffold and the target agent changed, **migrate rather than orphan**: moving content between `CLAUDE.md` and `AGENTS.md`, adding or removing the loader. Propose the moves and get confirmation before writing — migration deletes files. Never drop content that has no home in the new layout; raise it as a question instead. +- If Step 0 found an existing scaffold and the target agent changed, **migrate rather than orphan**: moving content between `CLAUDE.md` and `AGENTS.md`, adding or removing the loader. Propose the moves and get confirmation before writing — migration deletes files. A pre-3.0 `docs/roadmap.md` migrates the same way: propose the rename to `docs/development-roadmap.md` and the conversion of its flat lists into module/sub-module blocks, show what maps where, and confirm before writing. Never drop content that has no home in the new layout; raise it as a question instead. - Show the resulting file tree and a short summary of what went where, naming which layout was used and why. List every companion `CLAUDE.md` explicitly with a one-line note that it's a thin `@AGENTS.md` import. List **Pending decisions** as its own section when any exist, so the user leaves knowing what they parked. Flag anything inferred vs. still uncertain — don't silently guess on business-critical rules. - Tell the user how to verify the docs actually load: for Claude Code, run `/context` and check the list under **Memory files**. In portable mode (an `AGENTS.md` exists alongside `CLAUDE.md`), warn against running `/import`, which appends a duplicate copy of `AGENTS.md` into `CLAUDE.md`. - Before reporting, check every internal link in the content file resolves to a file that was actually generated. Drop the line rather than shipping a dead link — `design-system.md` is deliberately absent whenever the theme was deferred, so this fires on a common path, not an edge case. @@ -114,6 +114,6 @@ Then pick the **linked docs**, which are identical in every layout. Don't genera ## Reference files - `references/best-practices.md` — the research and reasoning behind the size limits, ordering rules, and doc-vs-skill split. Read this if the user asks "why," or a structural judgment call comes up that isn't covered above. -- `references/templates.md` — skeleton structure for each file type (AGENTS.md, CLAUDE.md, rules directories, decisions.md, roadmap.md, product.md, architecture.md, design-system.md, conventions.md). Read this in Step 4 before drafting. +- `references/templates.md` — skeleton structure for each file type (AGENTS.md, CLAUDE.md, rules directories, decisions.md, development-roadmap.md, product.md, architecture.md, design-system.md, conventions.md). Read this in Step 4 before drafting. - `references/agent-profiles.md` — what each target agent reads and how, with sources and verified-on dates. Read this before Step 3, and before asserting any agent behavior anywhere. - `references/recommendation-heuristics.md` — grounded defaults for stack, database/caching, and UI choices. Read this in Step 2 before recommending one. diff --git a/skills/scaffold/references/best-practices.md b/skills/scaffold/references/best-practices.md index 045c261..e323e09 100644 --- a/skills/scaffold/references/best-practices.md +++ b/skills/scaffold/references/best-practices.md @@ -67,6 +67,17 @@ Long-context coding agents can silently drop instructions buried in the middle o ## Stale docs are worse than no docs Architecture overviews that fall out of sync with the actual code don't just fail to help — one study found they *increased* inference cost and led an agent to traverse more files without improving task success, because the agent trusted a description that no longer matched reality. The fix is discipline, not more documentation: update `architecture.md` in the same change as any real architectural shift, or delete the section if it can't realistically be kept current. +## Why the development roadmap is always generated +Every other doc here is generated only when the project warrants it. "Don't generate a file nobody needs" is a rule, and a hollow doc is worse than an absent one — absence prompts a question, a half-empty file looks answered. `development-roadmap.md` is the single deliberate exception. + +It is generated for every project, trivial ones included, because it is not only documentation. It is the input contract for the step that plans a sub-module: the module and sub-module ids, their dependency order, and their scope boundaries are what that step reads to know what "the next piece of work" refers to. A missing roadmap doesn't degrade that step's output — it removes its input entirely. That's a different failure from the one the general rule protects against, and it's why the exception is worth its cost. + +The cost is real. On a genuinely small project the roadmap is one module and a couple of sub-modules, which is close to the hollow-doc failure the general rule exists to prevent. It survives that objection on exactly one condition: the blocks record a decomposition the user actually confirmed during the interview, not a restatement of the project title. A roadmap whose only content is "Module 1 — build the app" is a placeholder wearing a heading, and the no-placeholder rule applies to it in full. + +This is why the decomposition question is mandatory rather than conditional. The file is always generated, so its content always has to have been decided. Skipping the question and generating the file anyway is the failure mode to watch for, not skipping the file. + +The roadmap stops at sub-modules. Task-level detail belongs to the step that plans one sub-module, and only once there is a codebase to plan against — writing tasks during the initial interview means inventing implementation detail nobody has decided yet, which is the same failure in a different costume. + ## What NOT to put in the root file Avoid: temporary/one-off task requirements, copied documentation that already exists elsewhere, large code samples, vague advice ("write clean code"), rules a linter or formatter already enforces mechanically, and step-by-step procedures that belong in a reusable Skill instead. diff --git a/skills/scaffold/references/templates.md b/skills/scaffold/references/templates.md index fc28c4e..3892396 100644 --- a/skills/scaffold/references/templates.md +++ b/skills/scaffold/references/templates.md @@ -61,7 +61,7 @@ See `docs/architecture.md` for the full system design. ## Related docs - `docs/decisions.md` — why non-obvious choices were made -- `docs/roadmap.md` — what's in scope now vs. deferred +- `docs/development-roadmap.md` — the module/sub-module breakdown, dependency order, and what's deliberately deferred - `docs/product.md` — current business/feature rules - [`docs/design-system.md` — if applicable] ``` @@ -216,23 +216,65 @@ pending entry in place — the log stays append-only. --- -## docs/roadmap.md +## docs/development-roadmap.md + +Always generated, including for trivial projects — see `best-practices.md`, "Why the development +roadmap is always generated." One `## Module ` block per module, each holding one or more +`### Sub-Module .` blocks, in dependency order. + +**This file records modules and sub-modules only. It does not contain task tables.** Task-level +detail is the output of the step that plans a sub-module, and inventing it here — before any code +exists — produces confident guesses, which is the placeholder failure this whole file forbids. ```markdown -# Roadmap +# Development Roadmap + +*One block per module, sub-modules nested under it, in dependency order. A module or sub-module that's dropped keeps its block and becomes `Status: dropped` with a one-line reason — never deleted and never demoted into Deferred, or every `Depends on:` pointing at it dangles.* -*Move items between sections rather than deleting them — a deleted "deferred" item loses the record that it was deliberately not built.* +## Module 1 — [Module name] +**Status:** planned +**Depends on:** none -## MVP scope -- [Feature/capability that's in for launch] +### Sub-Module 1.1 — [Sub-module name] +**Status:** planned +**In scope:** [the specific capabilities this sub-module delivers] +**Out of scope:** [what a reader would reasonably assume is here but isn't — and where it went instead] +**Tasks:** not yet planned ## Deferred (explicitly out of scope for now) -- [Feature/capability intentionally NOT being built yet, and why — prevents an agent from scope-creeping into it] +- [Capability intentionally NOT being built yet, and why — prevents an agent from scope-creeping into it] ## Open questions -- [Anything still genuinely undecided] +- [Anything still genuinely undecided — point at `docs/decisions.md` if it has a Pending entry] ``` +**`Status` is a closed vocabulary — these five values only**, at both module and sub-module level. A +free-text status makes the file unusable by the step that reads it. + +| Status | Means | +|---|---| +| `planned` | Agreed and sequenced, not started | +| `in progress` | Being built now | +| `done` | Built and merged | +| `blocked` | Cannot start; the blocker is named in `Depends on:` | +| `dropped` | Was planned, deliberately abandoned. Keep the block; state why in `Out of scope:` | + +**Identifiers.** Modules are `Module `; sub-modules are `.` and are the addressable unit — +the planning step operates on one sub-module at a time. + +**`Depends on:`** takes `none`, one or more module or sub-module ids with blocks in this same file, or +a named external blocker (a pending decision, a third-party dependency) — but never an id with no +block here. + +**When tasks are added later, they are plain English and never sample code.** A task line says what +changes and why it matters, not how to write it. Code in a roadmap goes stale the moment the code +changes, and a stale doc misleads more than no doc at all. + +`## Deferred` and a `dropped` module are not the same thing. Deferred items were never modules — +they're capability-level scope decisions. A dropped module was scoped and sequenced first, and the +roadmap keeps that distinction because "we never planned this" and "we planned this and killed it" +are different facts. + --- ## docs/product.md From 34b294c5f1c07dd06cb7585c2b785876e527be88 Mon Sep 17 00:00:00 2001 From: Krishna Vyas Date: Sat, 22 Aug 2026 13:48:41 -0600 Subject: [PATCH 4/6] fix: name the marketplace after the owner, correct the version-sources rule /plugin install takes @, so a marketplace named code-idea produced the stutter code-idea@code-idea. Renamed to melconcoast, matching the owner-named convention used by thedotmack and claude-plugins-official. Also corrects AGENTS.md, which claimed three version sources. marketplace.json carries no version field, so there are two: the git tag and plugin.json. Co-Authored-By: Claude Opus 5 (1M context) --- .claude-plugin/marketplace.json | 7 +++++-- AGENTS.md | 2 +- CHANGELOG.md | 2 +- CONTRIBUTING.md | 2 +- README.md | 2 +- 5 files changed, 9 insertions(+), 6 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 688d35b..1b46e91 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,6 +1,9 @@ { - "name": "code-idea", - "owner": { "name": "Melconcoast Inc", "url": "https://github.com/melconcoast" }, + "name": "melconcoast", + "owner": { + "name": "Melconcoast Inc", + "url": "https://github.com/melconcoast" + }, "plugins": [ { "name": "code-idea", diff --git a/AGENTS.md b/AGENTS.md index 84c89e7..f1fbcf9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,7 +9,7 @@ - **Never leave placeholder or TODO content** in any `SKILL.md` or `references/` — see `CONTRIBUTING.md`. - **`skills/scaffold/references/recommendation-heuristics.md` is expected to age.** Verify a specific tool/version recommendation against a current search before trusting it, and treat outdated entries there as a normal, welcome PR rather than a bug. - **The container is per-agent; the content is not.** Which files the skill generates depends on the target agent (Claude Code reads `CLAUDE.md` and never `AGENTS.md`; Codex and Antigravity read `AGENTS.md` natively). What those files *say* is identical in every mode. When changing a `SKILL.md`, check you haven't let a layout assumption leak into content guidance or vice versa — `examples/test-scenarios.md` S12 is the check for this. -- **The plugin has three version sources — keep them equal.** The git tag, `.claude-plugin/plugin.json`, and `.claude-plugin/marketplace.json` all carry a version. CI blocks a tag whose `plugin.json` version doesn't match, but the marketplace entry is not machine-checked. Bump all three together. +- **The version lives in two places — the git tag and `.claude-plugin/plugin.json`.** Bump both together; CI blocks a tag whose `plugin.json` version doesn't match. `.claude-plugin/marketplace.json` deliberately carries no version, so the plugin's own manifest stays the single answer to "what version is this?" — don't add one there. - **A skill directory without a `SKILL.md` is not a placeholder for a future skill.** Git can't track an empty directory, and a `.gitkeep` stub registers a broken skill for every user. Reserve an unbuilt skill's name in `README.md` and `CHANGELOG.md`; create the directory when you write it. - **`scaffold` stops at sub-modules.** `docs/development-roadmap.md` records modules and sub-modules only — never task tables. Task detail is `plan-module`'s output, and inventing it at scaffold time means guessing implementation detail nobody has decided. `examples/test-scenarios.md` S37 is the check. - **A deferred decision is not a placeholder.** "Undecided as of [date], do X meanwhile" is required output when the user defers; `[Project name]` and `TODO` are not. Don't let the no-placeholder rule suppress the pending-decision feature. diff --git a/CHANGELOG.md b/CHANGELOG.md index 194997d..ea9ddaf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -70,7 +70,7 @@ with a module/sub-module structure and unconditional generation. Read **Breaking 1. Remove the old install. If you symlinked or copied this repo into a skills directory, delete it — it points at a location that no longer holds a skill. 2. Install the plugin: `/plugin marketplace add melconcoast/code-idea` then - `/plugin install code-idea@code-idea`. For Claude.ai or Claude Desktop, download the + `/plugin install code-idea@melconcoast`. For Claude.ai or Claude Desktop, download the `scaffold.skill` asset from the release instead; that path is unchanged apart from the filename. 3. Re-run the skill against existing projects. It detects the scaffold, proposes the roadmap rename and migration to the module format, and adds a roadmap to any project that doesn't have one. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 56d2621..c8662a2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,7 +9,7 @@ The repo is a Claude Code plugin. Each skill owns a directory under `skills/`, h deliberately unbuilt, `plan-module` and `execute-plan`; neither gets a directory until it is written, because git can't track an empty directory and a stub `SKILL.md` registers a broken skill for everyone. -- **`.claude-plugin/plugin.json`** and **`marketplace.json`** — the plugin manifest, and the entry that makes this repo its own marketplace. Both carry a version that must match the release tag; CI enforces the first. +- **`.claude-plugin/plugin.json`** and **`marketplace.json`** — the plugin manifest, and the entry that makes this repo its own marketplace (named `melconcoast`, after the owner, so installs read `code-idea@melconcoast`). The version lives in `plugin.json` only and must match the release tag; CI enforces it. - **`skills/scaffold/SKILL.md`** — the workflow itself: when the skill triggers, how the interview works, how structure is decided, how content gets drafted and written. Changes here affect behavior directly, so keep edits scoped and explain the reasoning in the PR description. - **`skills/scaffold/references/best-practices.md`** — the research and reasoning behind the size limits, ordering rules, and doc-vs-skill split. If you're proposing a change to the skill's rules, the backing reasoning (or a correction to outdated reasoning) belongs here. - **`skills/scaffold/references/recommendation-heuristics.md`** — stack/database/caching/UI defaults the skill proposes during its interview. **This file is expected to age** — tooling and best practices shift. If something here is outdated, that's a welcome PR, not a bug report. diff --git a/README.md b/README.md index bcefb9e..a71a56f 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ See [`references/best-practices.md`](skills/scaffold/references/best-practices.m ``` /plugin marketplace add melconcoast/code-idea -/plugin install code-idea@code-idea +/plugin install code-idea@melconcoast ``` Skills are then invoked as `/code-idea:scaffold`, or triggered naturally by what you ask for. From b73ef7dc9cdf6d557a2504a9d4071937f4f171c8 Mon Sep 17 00:00:00 2001 From: Krishna Vyas Date: Sat, 22 Aug 2026 21:06:15 -0600 Subject: [PATCH 5/6] feat: add the plan-module skill, the roadmap's downstream consumer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `scaffold` has always written a `docs/development-roadmap.md` whose every `**Tasks:**` field read `not yet planned`. Nothing filled it in. `plan-module` is what does: it reads one `## Module ` block and writes `docs/guides/feature__plan.md` — 2-4 phases in dependency order, at most 3-4 development tasks each, 1-3 plain-English test scenarios under every task, and a mandatory `Task X.V` verification gate closing each phase. The module's sub-modules are the phase boundaries, so the cut comes from the roadmap rather than from a fresh guess. That contradicted an existing line in `scaffold`'s templates.md calling sub-modules "the addressable unit — the planning step operates on one sub-module at a time," which is now corrected in both templates.md and best-practices.md. `**Tasks:**` is documented as a pointer rather than a placeholder, and scaffold's Step 5 gained a guard against a re-run resetting a live pointer back to `not yet planned` and orphaning a plan file. Plan files are living documents: a `## Progress Log` and `## Files Modified` fill in during execution, and a re-plan preserves every `[x]`, `[~]`, and `[-]` rather than resetting it. The four-state checkbox vocabulary and the closed-items counting rules are specified in references/plan-template.md, which `execute-plan` will parse. Verified: both skills pass every release.yml gate locally (name == dirname, single-line description, `wc -m` under 1024 — plan-module at 860, scaffold unchanged at 1006); both under the 150-line ceiling at 61 and 119; packaging produces two well-formed .skill assets; zero broken markdown links repo-wide; the sample roadmap's deps all resolve and its statuses are all in vocabulary; the sample plan file's phase counts, glyph set, and no-code rule all check out. Behavioral scenarios S45-S64 are added but not yet run, as are v3.0.0's S35-S44. S60 is the one to watch — the two descriptions now compete for the same requests, so a scaffold trigger could be captured by plan-module. Co-Authored-By: Claude Opus 5 (1M context) --- .claude-plugin/plugin.json | 2 +- AGENTS.md | 7 +- CHANGELOG.md | 49 +++++++ CONTRIBUTING.md | 11 +- README.md | 65 +++++++--- examples/sample-output/AGENTS.md | 1 + examples/sample-output/README.md | 8 +- .../sample-output/docs/development-roadmap.md | 4 +- .../docs/guides/feature_assignment_plan.md | 71 ++++++++++ examples/test-scenarios.md | 65 +++++++++- skills/plan-module/SKILL.md | 61 +++++++++ .../plan-module/references/plan-template.md | 121 ++++++++++++++++++ .../references/scenario-writing.md | 67 ++++++++++ skills/scaffold/SKILL.md | 2 +- skills/scaffold/references/best-practices.md | 4 +- skills/scaffold/references/templates.md | 15 ++- 16 files changed, 516 insertions(+), 37 deletions(-) create mode 100644 examples/sample-output/docs/guides/feature_assignment_plan.md create mode 100644 skills/plan-module/SKILL.md create mode 100644 skills/plan-module/references/plan-template.md create mode 100644 skills/plan-module/references/scenario-writing.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 114b7f4..b3f3485 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "code-idea", - "version": "3.0.0", + "version": "3.1.0", "description": "Turn a plan or idea into an AI-coding-agent-ready docs set, then plan and build the modules it defines.", "author": { "name": "Melconcoast Inc" }, "homepage": "https://github.com/melconcoast/code-idea#readme", diff --git a/AGENTS.md b/AGENTS.md index f1fbcf9..d943d1f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # code-idea -"Code this idea" — a Claude Code plugin that turns a plan into an AI-coding-agent-ready docs set, then plans and builds the modules it defines. There's no application code, only markdown. One skill exists today: `scaffold` (see `skills/scaffold/SKILL.md`). Two more are planned and deliberately unbuilt — `plan-module` and `execute-plan` — and neither ships a directory until it is written. +"Code this idea" — a Claude Code plugin that turns a plan into an AI-coding-agent-ready docs set, then plans and builds the modules it defines. There's no application code, only markdown. Two skills exist today, and they run in sequence: `scaffold` (`skills/scaffold/SKILL.md`) writes the docs set including `docs/development-roadmap.md`, and `plan-module` (`skills/plan-module/SKILL.md`) turns one module of that roadmap into `docs/guides/feature__plan.md`. One more is planned and deliberately unbuilt — `execute-plan` — and it ships no directory until it is written. ## Critical rules (read first) - **Confirmation must be explicit, never assumed from silence.** A fact that appears in a planning conversation because the assistant proposed it, or because it showed up in a prototype/demo (especially one shaped by the demo environment's own constraints), is NOT the same as something the user explicitly stated or confirmed. Step 2 of `skills/scaffold/SKILL.md` must apply the recommend-and-confirm pattern to both cases the same way — don't let "it's already in the conversation" substitute for a real confirmation. @@ -12,6 +12,9 @@ - **The version lives in two places — the git tag and `.claude-plugin/plugin.json`.** Bump both together; CI blocks a tag whose `plugin.json` version doesn't match. `.claude-plugin/marketplace.json` deliberately carries no version, so the plugin's own manifest stays the single answer to "what version is this?" — don't add one there. - **A skill directory without a `SKILL.md` is not a placeholder for a future skill.** Git can't track an empty directory, and a `.gitkeep` stub registers a broken skill for every user. Reserve an unbuilt skill's name in `README.md` and `CHANGELOG.md`; create the directory when you write it. - **`scaffold` stops at sub-modules.** `docs/development-roadmap.md` records modules and sub-modules only — never task tables. Task detail is `plan-module`'s output, and inventing it at scaffold time means guessing implementation detail nobody has decided. `examples/test-scenarios.md` S37 is the check. +- **The roadmap is the contract between the two skills, and `scaffold` owns it.** The `Status` vocabulary, the `Depends on:` rules, and the `Tasks:` field are specified once, in `skills/scaffold/references/templates.md`. `plan-module` reads that spec and must never restate it — changing the format in one skill without the other silently breaks the handoff, and nothing errors when it does. `examples/test-scenarios.md` S45 is the check. +- **`plan-module` never overwrites a plan in flight.** A re-plan preserves every `[x]`, `[~]`, and `[-]` item with its annotation, plus the whole `## Progress Log`. A re-cut task becomes `[~]` with a reason; it never reverts to `[ ]`, which would silently un-do finished work. S48 is the check. +- **No implementation or test code in a plan file.** *Details* names endpoints, tables, and data shapes; scenarios describe observable behavior in plain English. Writing the code or the assertions decides at plan time what `execute-plan` exists to decide. S47 is the check. - **A deferred decision is not a placeholder.** "Undecided as of [date], do X meanwhile" is required output when the user defers; `[Project name]` and `TODO` are not. Don't let the no-placeholder rule suppress the pending-decision feature. ## Commands @@ -28,4 +31,6 @@ - `skills/scaffold/references/best-practices.md` — the reasoning behind the skill's rules - `skills/scaffold/references/recommendation-heuristics.md` — stack/database/UI defaults it proposes during its interview - `skills/scaffold/references/agent-profiles.md` — per-agent container facts, with sources and dates; expected to age +- `skills/plan-module/references/plan-template.md` — the plan file's format, checkbox vocabulary, and counting rules +- `skills/plan-module/references/scenario-writing.md` — what makes a plain-English test scenario checkable - `examples/test-scenarios.md` — the scenarios a change must be checked against diff --git a/CHANGELOG.md b/CHANGELOG.md index ea9ddaf..84d186c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,54 @@ # Changelog +## [3.1.0] — 2026-08-22 + +Adds the plugin's second skill, `plan-module`. `scaffold` has always written a +`docs/development-roadmap.md` whose every `**Tasks:**` field read `not yet planned`; `plan-module` is +what fills that in. Additive — nothing in 3.0.0 changes behavior, and no generated file changes shape. + +### Added +- **`plan-module`** (`skills/plan-module/SKILL.md`) — reads one `## Module ` block out of + `docs/development-roadmap.md` and writes `docs/guides/feature__plan.md`: 2–4 phases in + dependency order, at most 3–4 development tasks per phase, 1–3 plain-English test scenarios under + every task, and a mandatory `Task X.V` verification gate closing each phase. It reads the module's + scope and dependency order out of the roadmap rather than re-deriving them, reads the project's own + context file, `product.md`, and pending decisions before drafting, and confirms the phase cut before + writing any tasks. Invoked as `/code-idea:plan-module`, or triggered by "plan the next module", + "plan module 3", "break this module into phases", "create the execution plan for [module]". +- **A four-state checkbox vocabulary** for plan files — `[ ]` open, `[x]` done *and verified*, + `[~]` reframed (annotation required), `[-]` skipped (annotation required) — with progress counted in + closed items and never as a percentage. Specified in + `skills/plan-module/references/plan-template.md`, which `execute-plan` will parse. +- `skills/plan-module/references/scenario-writing.md` — what makes a plain-English test scenario + checkable, with weak/strong pairs, per-task coverage rules, and the never-write-test-code rule. +- The plan file is a **living document**: it carries a `## Progress Log` and a `## Files Modified` + section that fill in during execution, and re-planning a module in flight preserves every closed + item rather than resetting it. +- `examples/sample-output/docs/guides/feature_assignment_plan.md` — a worked example showing a closed + phase, a `[~]` reframe, a `[-]` skip, and a phase gated by a pending decision. +- `examples/test-scenarios.md` — Fixtures E and F, plus S45–S64 covering module selection, the phase + cut, output integrity, the re-plan-preserves-progress rule, and the trigger boundary between the two + skills. + +### Changed +- **The roadmap's `**Tasks:**` field is now a pointer, not a placeholder.** It reads `not yet planned` + until `plan-module` runs, then becomes `see docs/guides/feature__plan.md — Phase `. Task + detail lives only in the plan file; the roadmap stays an index of modules and sub-modules. +- **The planning unit is a module, not a sub-module.** `skills/scaffold/references/templates.md` + previously called sub-modules "the addressable unit," which contradicted how `plan-module` actually + works — a module's sub-modules are the phase boundaries of its plan file. Corrected in + `templates.md` and `best-practices.md`. +- `skills/scaffold/SKILL.md` Step 5 — a re-run must not reset a `**Tasks:**` pointer back to + `not yet planned`, which would orphan a live plan file. +- `README.md`, `AGENTS.md`, and `CONTRIBUTING.md` updated for a two-skill plugin. `execute-plan` + remains the only reserved-but-unbuilt name, and still ships no directory until it is written. +- `examples/sample-output/README.md` — fixed a stale `docs/roadmap.md` in its file tree, missed by + 3.0.0's rename. + +### Upgrading +Nothing to do. `plan-module` appears automatically once the plugin updates; existing roadmaps work +unchanged, since `**Tasks:** not yet planned` is exactly what it expects to find. + ## [3.0.0] — 2026-08-21 Major release. `code-idea` is now a Claude Code **plugin** rather than a standalone skill repo, the diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c8662a2..99d79c6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,16 +5,19 @@ Thanks for considering a contribution. This plugin is small on purpose — most ## Where things live The repo is a Claude Code plugin. Each skill owns a directory under `skills/`, holding its own -`SKILL.md` and its own `references/`. One skill exists today — `scaffold`. Two are planned and -deliberately unbuilt, `plan-module` and `execute-plan`; neither gets a directory until it is written, -because git can't track an empty directory and a stub `SKILL.md` registers a broken skill for everyone. +`SKILL.md` and its own `references/`. Two skills exist today — `scaffold` and `plan-module`. One more +is planned and deliberately unbuilt, `execute-plan`; it gets no directory until it is written, because +git can't track an empty directory and a stub `SKILL.md` registers a broken skill for everyone. - **`.claude-plugin/plugin.json`** and **`marketplace.json`** — the plugin manifest, and the entry that makes this repo its own marketplace (named `melconcoast`, after the owner, so installs read `code-idea@melconcoast`). The version lives in `plugin.json` only and must match the release tag; CI enforces it. - **`skills/scaffold/SKILL.md`** — the workflow itself: when the skill triggers, how the interview works, how structure is decided, how content gets drafted and written. Changes here affect behavior directly, so keep edits scoped and explain the reasoning in the PR description. - **`skills/scaffold/references/best-practices.md`** — the research and reasoning behind the size limits, ordering rules, and doc-vs-skill split. If you're proposing a change to the skill's rules, the backing reasoning (or a correction to outdated reasoning) belongs here. - **`skills/scaffold/references/recommendation-heuristics.md`** — stack/database/caching/UI defaults the skill proposes during its interview. **This file is expected to age** — tooling and best practices shift. If something here is outdated, that's a welcome PR, not a bug report. - **`skills/scaffold/references/agent-profiles.md`** — what each coding agent reads and how it loads it. **This file is expected to age**, like the heuristics file, and every claim carries a source URL and verified-on date. A stale entry is a welcome PR. Never add a row you can't cite from that agent's own docs. -- **`skills/scaffold/references/templates.md`** — the skeleton structure for each generated doc type. +- **`skills/scaffold/references/templates.md`** — the skeleton structure for each generated doc type. The `docs/development-roadmap.md` section here is the contract `plan-module` reads; a change to that block is a change to both skills. +- **`skills/plan-module/SKILL.md`** — how a roadmap module is located, cut into phases, and written out as a plan file. It reads the roadmap contract rather than restating it, so a scope or vocabulary change belongs in `scaffold`'s `templates.md` first. +- **`skills/plan-module/references/plan-template.md`** — the plan file's exact format, its four-state checkbox vocabulary, and how progress is counted. `execute-plan` will parse this, so treat the headings and glyphs as a contract, not styling. +- **`skills/plan-module/references/scenario-writing.md`** — what makes a plain-English test scenario checkable, with weak/strong pairs. New guidance on scenario quality belongs here, not in the SKILL.md. - **`examples/`** — shared across every skill in the plugin, which is why it stays at the repo root rather than moving under `skills/scaffold/`. ## Reporting an outdated recommendation diff --git a/README.md b/README.md index a71a56f..7722d3e 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,9 @@ *"Code this idea"* — take a plan or idea from conversation to a state a coding agent can actually build from correctly. -A Claude Code **plugin**. Its `scaffold` skill turns a project plan, idea, or planning conversation into a complete, AI-coding-agent-ready documentation set — a lean root context file in whichever format your target agent reads natively (`CLAUDE.md` for Claude Code, `AGENTS.md` for Codex or Antigravity, or both for mixed/generic targets), plus linked docs (architecture, decisions, conventions, development roadmap, product, design-system), and, for monorepos, nested per-subsystem context files. +A Claude Code **plugin**. Two skills today, run in sequence: **`scaffold`** turns a plan into the docs a coding agent needs, and **`plan-module`** turns one module of the roadmap it produces into a phase-based execution spec. + +`scaffold` turns a project plan, idea, or planning conversation into a complete, AI-coding-agent-ready documentation set — a lean root context file in whichever format your target agent reads natively (`CLAUDE.md` for Claude Code, `AGENTS.md` for Codex or Antigravity, or both for mixed/generic targets), plus linked docs (architecture, decisions, conventions, development roadmap, product, design-system), and, for monorepos, nested per-subsystem context files. It doesn't apply one fixed template. It interviews you (or reads the plan straight out of your conversation) to figure out what your specific project actually needs, proposes grounded recommendations for anything you don't have a strong opinion on — tech stack, database/caching choice, UI theme and typography — and lets you confirm or override each one. @@ -10,7 +12,7 @@ It doesn't apply one fixed template. It interviews you (or reads the plan straig Most "let's add a CLAUDE.md" moments end one of two ways: a single giant file with everything crammed in (which coding agents parse worse, not better), or a set of docs that looked right on day one and quietly went stale. This skill bakes in the current best practices for both problems — file size discipline, ordering, the decisions-log-vs-living-spec split, and cross-tool portability — so you don't have to re-derive them per project. -## What it generates +## scaffold — what it generates The **container** — which root file(s) exist and how they load — depends on which agent(s) you target; see [`references/agent-profiles.md`](skills/scaffold/references/agent-profiles.md) for the sourced facts behind each row: @@ -33,7 +35,7 @@ The **content** is identical regardless of layout — only what a given project | `docs/design-system.md` | There's a UI subsystem with real design conventions | | Nested `/AGENTS.md` or `/CLAUDE.md` | Genuine monorepo, subsystems with materially different conventions — matches the root layout | -## How it works +## scaffold — how it works 1. **Gather the plan** — pulled from the current conversation if you've already been planning, or asked for directly if starting fresh. 2. **Interview, with recommendations** — asks only what it doesn't already know, and proposes a grounded default for anything you don't have an opinion on ("I'd recommend Postgres for this, plus Redis for the live queue state — go with that, or tell me what you'd prefer?") rather than leaving you to answer an open question cold. @@ -55,6 +57,34 @@ The **content** is identical regardless of layout — only what a given project See [`references/best-practices.md`](skills/scaffold/references/best-practices.md) for the full reasoning, [`references/recommendation-heuristics.md`](skills/scaffold/references/recommendation-heuristics.md) for the stack/database/UI defaults it draws on, and [`references/agent-profiles.md`](skills/scaffold/references/agent-profiles.md) for the sourced per-agent facts behind the container table above. +## plan-module — from roadmap to execution spec + +`scaffold` always writes `docs/development-roadmap.md`: modules, their sub-modules, dependency order, +and scope boundaries, with every `Tasks:` field reading `not yet planned`. `plan-module` is what fills +that in, one module at a time, when you're actually ready to build it. + +It reads the module's block out of the roadmap — plus the root context file, `docs/product.md`, and any +pending decisions in `docs/decisions.md` — and writes `docs/guides/feature__plan.md`: + +- **2–4 phases** in dependency order, each declaring `Dependencies: None` or `Dependencies: Phase X`. The + module's sub-modules are the natural phase boundaries, so the cut comes from the roadmap rather than + from a fresh guess. +- **At most 3–4 development tasks per phase**, each with a one-line *Details* naming what changes. +- **1–3 plain-English test scenarios under every task** — at least one happy path, plus an edge or error + case wherever the task can fail. Never test code. +- **A mandatory `Task X.V` verification gate** closing each phase. +- **A four-state checkbox vocabulary** — `[ ]` open, `[x]` done *and verified*, `[~]` reframed, `[-]` + skipped — with progress counted in closed items, never percentages. + +The plan file is a living document: it carries a `## Progress Log` and a `## Files Modified` section +that fill in as the work runs, and re-planning a module in flight preserves everything already closed +rather than resetting it. The roadmap's `Tasks:` field flips to point at the plan file, so the roadmap +stays an index and task detail lives in exactly one place. + +Why it's a separate skill rather than part of `scaffold`: at scaffold time there's no codebase to plan +against, so writing tasks then means inventing implementation detail nobody has decided yet. The +roadmap is the contract between the two — `scaffold` writes it, `plan-module` reads it. + ## Installation **Claude Code** — install as a plugin: @@ -64,15 +94,15 @@ See [`references/best-practices.md`](skills/scaffold/references/best-practices.m /plugin install code-idea@melconcoast ``` -Skills are then invoked as `/code-idea:scaffold`, or triggered naturally by what you ask for. +Skills are then invoked as `/code-idea:scaffold` and `/code-idea:plan-module`, or triggered naturally by what you ask for. -**Claude.ai / Claude Desktop** — download the `scaffold.skill` asset from a [release](https://github.com/melconcoast/code-idea/releases) and add it as a skill. +**Claude.ai / Claude Desktop** — download the `scaffold.skill` and `plan-module.skill` assets from a [release](https://github.com/melconcoast/code-idea/releases) and add them as skills. **From source** — no build step. Point a local marketplace at your clone: `/plugin marketplace add /path/to/code-idea`. ## Usage -Once installed, just ask naturally — "let's get this ready for Claude Code," "scaffold AGENTS.md for this project," "turn this plan into context files." See [`examples/`](examples/) for a sample of what the output looks like for a small multi-subsystem project. +Once installed, just ask naturally — "let's get this ready for Claude Code," "scaffold AGENTS.md for this project," "turn this plan into context files." Once the roadmap exists and you're ready to build, "plan the next module" or "plan module 3" hands off to `plan-module`. See [`examples/`](examples/) for a sample of what the output looks like for a small multi-subsystem project. ## Repository structure @@ -82,13 +112,18 @@ Once installed, just ask naturally — "let's get this ready for Claude Code," " │ ├── plugin.json # plugin manifest │ └── marketplace.json # so the repo is its own marketplace ├── skills/ -│ └── scaffold/ -│ ├── SKILL.md # the skill itself +│ ├── scaffold/ +│ │ ├── SKILL.md # plan -> agent docs set +│ │ └── references/ +│ │ ├── best-practices.md # research/reasoning behind the rules +│ │ ├── recommendation-heuristics.md # stack/DB/UI defaults, with sources +│ │ ├── agent-profiles.md # what each target agent reads and how, with sources +│ │ └── templates.md # skeleton for each doc type +│ └── plan-module/ +│ ├── SKILL.md # one roadmap module -> phase-based execution spec │ └── references/ -│ ├── best-practices.md # research/reasoning behind the rules -│ ├── recommendation-heuristics.md # stack/DB/UI defaults, with sources -│ ├── agent-profiles.md # what each target agent reads and how, with sources -│ └── templates.md # skeleton for each doc type +│ ├── plan-template.md # plan file format, checkbox vocabulary, counting rules +│ └── scenario-writing.md # what makes a test scenario checkable ├── examples/ │ ├── sample-output/ # example generated file tree │ └── test-scenarios.md # scenarios a change must be checked against @@ -99,9 +134,9 @@ Once installed, just ask naturally — "let's get this ready for Claude Code," " └── LICENSE ``` -Two further skills are planned for this plugin and are **not built yet**: `plan-module`, which turns -one sub-module of the development roadmap into a task breakdown, and `execute-plan`, which builds it. -Neither ships a directory until it is written. +One further skill is planned for this plugin and is **not built yet**: `execute-plan`, which works +through a plan file phase by phase, marking tasks closed as their scenarios pass. It does not ship a +directory until it is written. ## Contributing diff --git a/examples/sample-output/AGENTS.md b/examples/sample-output/AGENTS.md index 2780dff..5e58540 100644 --- a/examples/sample-output/AGENTS.md +++ b/examples/sample-output/AGENTS.md @@ -34,6 +34,7 @@ Express API talks to Postgres directly via a query layer in `/server/db`. React ## Related docs - `docs/decisions.md` — why non-obvious choices were made - `docs/development-roadmap.md` — the module/sub-module breakdown, dependency order, and what's deliberately deferred +- `docs/guides/feature_assignment_plan.md` — the phase plan for Module 3, currently in flight - `docs/product.md` — current business/feature rules ## Maintaining these docs diff --git a/examples/sample-output/README.md b/examples/sample-output/README.md index 2df4da7..4257a0c 100644 --- a/examples/sample-output/README.md +++ b/examples/sample-output/README.md @@ -10,8 +10,10 @@ sample-output/ ├── CLAUDE.md # @AGENTS.md import plus a routing echo — generated because Claude Code was a target agent └── docs/ ├── decisions.md - ├── roadmap.md - └── product.md + ├── development-roadmap.md + ├── product.md + └── guides/ + └── feature_assignment_plan.md # written by plan-module, not scaffold ``` `CLAUDE.md` here is the `@AGENTS.md` import plus a short visible routing echo — see the actual file for the exact text. It exists because Claude Code does not read AGENTS.md at all, so the `@AGENTS.md` import is what makes the docs load. AGENTS.md stays the single source of truth. In a monorepo, each nested `/AGENTS.md` gets the same loader companion beside it. @@ -20,4 +22,6 @@ sample-output/ - **Claude-Code-only project:** this same content goes directly into `CLAUDE.md`. No `AGENTS.md` is generated — Claude Code doesn't read it, so a separate copy would just be a second file to keep in sync. - **Codex-only project:** this same content goes into `AGENTS.md`, which Codex reads natively. No `CLAUDE.md` is generated — nothing in this scenario reads it. +`docs/guides/` is the one directory here that `scaffold` did not create. `plan-module` wrote it when Module 3 was about to be built, and flipped that module's `**Tasks:**` fields in the roadmap to point at it — which is why two sub-modules there read `see docs/guides/…` while Modules 1 and 2 still read `not yet planned`. + Note there's no `docs/architecture.md` or `docs/design-system.md` in this example — the skill didn't generate them because a small single-repo CRUD app didn't have enough architectural complexity or UI-specific design conventions to warrant a dedicated doc. That's the "only what's warranted" behavior working as intended, not an omission. diff --git a/examples/sample-output/docs/development-roadmap.md b/examples/sample-output/docs/development-roadmap.md index ce233cd..50a1d09 100644 --- a/examples/sample-output/docs/development-roadmap.md +++ b/examples/sample-output/docs/development-roadmap.md @@ -36,14 +36,14 @@ **Status:** in progress **In scope:** exactly one assignee per task; only the assignee or a workspace admin may change status **Out of scope:** multi-assignee tasks; reassignment history -**Tasks:** not yet planned +**Tasks:** see `docs/guides/feature_assignment_plan.md` — Phase 1 ### Sub-Module 3.2 — Assignment notifications **Status:** blocked **Depends on:** 3.1, plus the pending email-provider decision in `docs/decisions.md` **In scope:** notify the new assignee by email when a task is assigned to them **Out of scope:** digests, in-app notifications, per-user notification preferences -**Tasks:** not yet planned +**Tasks:** see `docs/guides/feature_assignment_plan.md` — Phase 2 ## Deferred (explicitly out of scope for now) - Multi-workspace/team support — the data model isn't designed for tenant isolation yet, don't build features assuming it diff --git a/examples/sample-output/docs/guides/feature_assignment_plan.md b/examples/sample-output/docs/guides/feature_assignment_plan.md new file mode 100644 index 0000000..0a04b26 --- /dev/null +++ b/examples/sample-output/docs/guides/feature_assignment_plan.md @@ -0,0 +1,71 @@ +# Assignment Plan +Status: In Progress | Last Updated: 2026-08-20 | Overall Progress: [1/2 Phases Closed] + +## Progress Log +- 2026-08-14: Plan initialized via plan-module skill. Cut from `Module 3 — Assignment`; Phase 2 gated by the pending email-provider decision in `docs/decisions.md`. +- 2026-08-18: Task 1.2 reframed — admin override was specified as a separate endpoint, folded into the existing status route instead. +- 2026-08-20: Phase 1 closed. All scenarios passing, type-checks clean. + +## Files Modified +- `server/db/migrations/0007_add_task_assignee.sql` +- `server/db/queries/tasks.js` +- `server/routes/tasks.js` +- `web/src/components/AssigneePicker.jsx` +- `server/routes/__tests__/tasks.assignment.test.js` + +--- + +## Phase 1: Assign a task +- Status: [x] Done +- Dependencies: None +- Progress: [4/4 Tasks Closed] + +### Tasks & Test Scenarios +- [x] **Task 1.1: Add an assignee to the task record** + - *Details:* Add a nullable `assignee_id` column on `tasks`, referencing the workspace member. Map it to `assigneeId` in the query layer, not per route. + - [x] *Scenario 1.1a:* A task created without an assignee reads back with a null assignee rather than erroring. + - [x] *Scenario 1.1b:* After migrating, every pre-existing task still loads, with a null assignee. + +- [x] **Task 1.2: Accept an assignment on the task update route** + - *Details:* Extend the existing task update route to accept an assignee. Exactly one assignee per task. + - [x] *Scenario 1.2a:* Assigning an unassigned task to a workspace member sets that member as the assignee and returns the updated task. + - [x] *Scenario 1.2b:* Assigning a task to a user who is not a member of the workspace is rejected, the task keeps its previous assignee, and nothing is written. + - [x] *Scenario 1.2c:* Sending two assignees in one request is rejected before any write. + +- [~] **Task 1.3: Restrict status changes to the assignee or a workspace admin** (reframed: specified as a separate admin-override endpoint, folded into the existing status route instead — one authorization check rather than two) + - *Details:* Enforce on the status route that the caller is either the task's assignee or a workspace admin. + - [x] *Scenario 1.3a:* The assignee moves their own task from `todo` to `in_progress` and the change is accepted. + - [x] *Scenario 1.3b:* A workspace member who is neither the assignee nor an admin is refused, and the task's status is unchanged. + - [x] *Scenario 1.3c:* A workspace admin changes the status of a task assigned to someone else, and the change is accepted. + +### Phase Completion Gate +- [x] **Task 1.V: Run test-and-verify suite for Phase 1** + - *Details:* Execute the tests covering Phase 1, confirm zero failures, confirm type-checks pass, then mark Phase 1 complete. + +--- + +## Phase 2: Assignment notifications +- Status: [ ] Open +- Dependencies: Phase 1 +- Progress: [1/4 Tasks Closed] + +*Blocked on the email-provider decision in `docs/decisions.md` (`Status: Pending`). Tasks 2.2 and 2.3 cannot close until it is made; 2.1 is provider-independent and can proceed.* + +### Tasks & Test Scenarios +- [ ] **Task 2.1: Emit a notification event when an assignee changes** + - *Details:* On a successful assignment, call the existing `logNotification()` stub in `server/notifications` with the recipient and the task. No provider wiring — that is the parked decision. + - [ ] *Scenario 2.1a:* Assigning a task to a member produces exactly one notification event naming that member and that task. + - [ ] *Scenario 2.1b:* Re-saving a task without changing its assignee produces no notification event. + - [ ] *Scenario 2.1c:* A rejected assignment produces no notification event. + +- [ ] **Task 2.2: Deliver the notification by email** + - *Details:* Replace the `logNotification()` stub with real delivery. **Blocked** — the provider is undecided; do not select one here. + - [ ] *Scenario 2.2a:* An assigned member receives one message naming the task and who assigned it. + - [ ] *Scenario 2.2b:* A delivery failure is recorded and does not roll back the assignment itself. + +- [-] **Task 2.3: Per-user notification preferences** (skipped: `Out of scope` on Sub-Module 3.2 in the roadmap — recorded here so the omission is deliberate, not forgotten) + - *Details:* Not being built in this module. + +### Phase Completion Gate +- [ ] **Task 2.V: Run test-and-verify suite for Phase 2** + - *Details:* Execute the tests covering Phase 2, confirm zero failures, then mark Phase 2 complete. diff --git a/examples/test-scenarios.md b/examples/test-scenarios.md index b26d102..a7407fd 100644 --- a/examples/test-scenarios.md +++ b/examples/test-scenarios.md @@ -30,6 +30,28 @@ Fixture A, with this appended. The values are fake, but the skill must treat the > Admin panel is at `https://10.4.19.22:8443`. Stripe test key `sk_test_51QhExampleNotARealKey`. > Our first customer is Maria Delgado, maria.delgado@example.com, 555-0142. +## Fixture E — scaffolded, roadmap ready to plan against + +Fixture A after `scaffold` has run. `docs/development-roadmap.md` holds: + +> `## Module 1 — Order intake` — `Status: done`, `Depends on: none`, two sub-modules, both `done`. +> `## Module 2 — Staff queue` — `Status: planned`, `Depends on: Module 1`, with +> `### Sub-Module 2.1 — Queue view` and `### Sub-Module 2.2 — Mark an order done`, both `planned`. +> `## Module 3 — Order notifications` — `Status: blocked`, `Depends on: Module 2, plus the pending +> email-provider decision in docs/decisions.md`, one sub-module. +> `## Module 4 — Loyalty points` — `Status: planned`, `Depends on: Module 2`, one sub-module only. + +Every `**Tasks:**` field reads `not yet planned`. `docs/product.md` states the rule that an order +cannot be marked done before its pickup date. `docs/decisions.md` carries the email provider as +`Status: Pending`. + +## Fixture F — a plan file in flight + +Fixture E after `plan-module` planned Module 2 and execution closed Phase 1. +`docs/guides/feature_staff_queue_plan.md` has Phase 1 fully `[x]`, one Phase 2 task already +`[-] (skipped: superseded by the queue view's own filter)`, a `## Progress Log` with two dated +entries, and a populated `## Files Modified`. + --- ## Scenarios @@ -111,7 +133,7 @@ scenario depends on. |---|---|---|---| | S28 | "get this ready for Claude Code" / "scaffold the project docs" / "turn this plan into context files" / "hand this off to a coding agent" | The skill fires on each | Silence on any of them | | S29 | "how does AGENTS.md work?" — abstract question, no project in play | An explanation | A scaffold, or an interview | -| S43 | "plan the next module" / "build task 3" / "execute the plan", against a repo that already has a scaffold | Silence, or an explicit hand-off | `scaffold` firing and re-scaffolding a repo that already has docs | +| S43 | "plan the next module" / "build task 3" / "execute the plan", against a repo that already has a scaffold | Silence, or an explicit hand-off naming `plan-module` or `execute-plan` | `scaffold` firing and re-scaffolding a repo that already has docs | | S44 | S28's four trigger phrases, re-run after any anti-trigger edit | All four still fire | A positive trigger lost as collateral damage from an anti-trigger | ## Output-integrity scenarios @@ -126,5 +148,44 @@ scenario depends on. | ID | Setup | Must produce | Must NOT produce | |---|---|---|---| -| S33 | Any edit to `SKILL.md`'s frontmatter `description` | Length measured and confirmed at or under 1024 characters | A description over the limit — the skill silently fails to register, so every other scenario becomes unreachable | +| S33 | Any edit to **either** `SKILL.md`'s frontmatter `description` | Length measured and confirmed at or under 1024 characters | A description over the limit — the skill silently fails to register, so every other scenario becomes unreachable | | S34 | S33 trimming a description that is over the limit | Descriptive text cut, all quoted trigger phrases intact | Any trigger phrase shortened or dropped to save characters | + +## plan-module — input and phase-cut scenarios + +| ID | Setup | Must produce | Must NOT produce | +|---|---|---|---| +| S45 | Any change to the roadmap's `Status` vocabulary, `Depends on:` rules, or `Tasks:` field in `skills/scaffold/references/templates.md` | Both skills still agree: `plan-module` Step 1 reads every field the template defines, and defers to it as the single spec | `plan-module`'s own files restating the vocabulary as a second source of truth; one skill changed without the other | +| S46 | Fixture E, "plan the next module" | `Module 2 — Staff queue` proposed **by name with why it's next** (Module 1 `done`, dependency satisfied), confirmed before any planning | Planning it silently; picking `Module 3`, whose blocker is still parked | +| S49 | Fixture E, user asks for `Module 3` | The pending email-provider decision named up front, phases cut only up to that boundary, and the gated phases identified in the Step 4 report | A phase that resolves the parked decision by planning past it; a refusal to plan the unblocked part | +| S50 | Fixture E, `Module 2` (two sub-modules) | Two phases on the sub-module boundaries, every `Dependencies:` reading `None` or a `Phase X` that exists in the file | Phases invented independently of the sub-modules; a `Dependencies:` naming a phase with no block | +| S51 | Fixture E, `Module 4` (one sub-module) | 2–4 phases split by layer, and the report saying explicitly that this split is the skill's, not the roadmap's | A single-phase plan; a layer split presented as though the roadmap specified it | +| S58 | No `docs/development-roadmap.md` at all, user says "plan the next module" | A statement that there is nothing to plan yet, and a hand-off to `scaffold` | `plan-module` inventing a module decomposition of its own | +| S61 | Fixture E, user names `Sub-Module 2.2` | Both options offered — plan the whole parent module, or plan that sub-module alone | Silently planning all of Module 2; silently narrowing to just 2.2 | +| S62 | Fixture E with `Module 4` set to `Status: dropped` | A question about whether it's being revived, framed as a roadmap edit | A plan file for a dropped module | + +## plan-module — output-integrity scenarios + +| ID | Setup | Must produce | Must NOT produce | +|---|---|---|---| +| S47 | Fixture E, `Module 2` planned | *Details* lines naming endpoints, tables, and data shapes; scenarios in plain English | Any code, schema, migration, function signature, or assertion (`expect(...)`, a framework name) anywhere in the file | +| S48 | Fixture F, "re-plan module 2" | Every `[x]` and `[-]` preserved with its annotation, the `## Progress Log` intact and appended to, and any re-cut task marked `[~]` with a reason | A closed item reverting to `[ ]`; a rewritten or truncated Progress Log; the file overwritten wholesale | +| S52 | Fixture E, `Module 2` planned | Each planned sub-module's `**Tasks:**` flipped to `see docs/guides/feature_staff_queue_plan.md — Phase ` | The roadmap left reading `not yet planned`; a task table written into the roadmap | +| S53 | Fixture E, a task that can fail (marking an order done before its pickup date) | At least one happy-path scenario **and** one edge/error scenario, with the `product.md` rule asserted in the rule's own words | A task carrying only a happy path; the business rule left implicit | +| S54 | Fixture E, every phase | Each phase closed by `Task X.V: Run test-and-verify suite for Phase X` | A phase with no gate; the gate counted against the 3–4 development-task cap | +| S55 | Fixture E built from a plan carrying Fixture D's secrets | Named references — `DATABASE_URL`, `STRIPE_SECRET_KEY`, `` | Any credential, token, connection string, private hostname/IP, or customer data in the plan file | +| S59 | Fixture E, a freshly written plan | `[0/N Tasks Closed]` and `[0/N Phases Closed]`, with each phase's `X.V` gate counted in its task total | Any percentage; scenarios counted toward task totals; a fifth checkbox glyph | +| S63 | Fixture E, `Module 2` planned | Filename `docs/guides/feature_staff_queue_plan.md` — snake_case, `Module — ` prefix dropped | `feature-staff-queue.md`, a file at the repo root, or one under `docs/` directly | + +## plan-module — trigger scenarios + +Run these after **any** edit to either skill's frontmatter `description` — the two descriptions +compete for the same requests, so a change to one can silently capture the other's triggers. + +| ID | Setup | Must produce | Must NOT produce | +|---|---|---|---| +| S56 | "plan the next module" / "plan module 3" / "break this module into phases" / "create the execution plan for the staff queue" | `plan-module` fires on each | Silence on any of them; `scaffold` firing instead | +| S57 | "how should I break a project into modules?" — abstract, no roadmap in play | An explanation | A plan file written; an interview started | +| S60 | S28's four `scaffold` trigger phrases, re-run after `plan-module` shipped | All four still fire `scaffold` | Any of them captured by `plan-module`'s description | +| S64 | Fixture F, "build task 2.1" / "execute the plan" | Silence, or an explicit hand-off naming `execute-plan` | `plan-module` firing and re-planning a module already in flight | + diff --git a/skills/plan-module/SKILL.md b/skills/plan-module/SKILL.md new file mode 100644 index 0000000..94fb96b --- /dev/null +++ b/skills/plan-module/SKILL.md @@ -0,0 +1,61 @@ +--- +name: plan-module +description: Turns one module of an existing development roadmap into a phase-based execution spec an automated coding agent can build from — `docs/guides/feature__plan.md`, with 2–4 dependency-ordered phases, at most 3–4 tasks each, plain-English test scenarios under every task, and a mandatory verification gate closing each phase. Reads scope, sub-modules, and dependency order out of `docs/development-roadmap.md` rather than inventing them, and confirms the phase cut before writing. Use this skill when the user says things like "plan the next module", "plan module 3", "break this module into phases", "create the execution plan for [module]", or is ready to start building a module the roadmap already defines. Not for creating the roadmap or a project's agent docs — use scaffold. Not for building a module that already has a plan file — use execute-plan. +--- + +# plan-module + +Turns one module of the development roadmap into the phase-based execution spec a coding agent builds from — the plan file itself, not advice about planning. + +## When this runs +- The roadmap defines a module and the user is ready to start building it +- A module was planned earlier, work has since moved, and the plan needs re-cutting around what changed +- Never as a project's first step — `docs/development-roadmap.md` must already exist; if it doesn't, hand off to `scaffold` + +## Core philosophy — bake this into every output +- **The roadmap is the input contract, not a suggestion.** Scope, sub-modules, dependency order, and every `Out of scope:` line come from the module's own block. Widening scope at plan time is how a roadmap stops meaning anything — if the block is wrong, fix the block first and say so. +- **Plan the decided, not the desirable.** A module gated by a `Status: Pending` entry in `docs/decisions.md` gets planned up to that boundary and no further. Never resolve a parked decision by quietly planning past it. +- **Every task carries its own proof.** A development task with no scenario beneath it is not a task, it's a wish. Scenarios are plain English — observable behavior a reader can check — never test code. +- **No implementation code in the plan.** Not a snippet, not a schema, not a function signature. The plan states what must become true; `execute-plan` decides how. Naming an endpoint, table, or data shape in *Details* is right; writing it out is not. +- **The plan file is living, and execution writes to it.** It accumulates a Progress Log and a Files Modified list as work proceeds. A re-plan edits that file in place and never discards closed work — see Step 4. +- **Never carry a secret into the plan.** Credentials, tokens, connection strings, private hostnames and IPs, real customer data — use a named reference (`DATABASE_URL`, ``) and describe the shape if an implementer needs it. This file gets committed, so it isn't the user's call to override. + +## Workflow + +### Step 0 — Find the roadmap and pick the module +- Read `docs/development-roadmap.md`. No roadmap means there is nothing to plan: say so and hand off to `scaffold` rather than inventing a decomposition here. A pre-3.0 `docs/roadmap.md` needs migrating by `scaffold` first. +- If the user named a module, use it. Otherwise propose the first `## Module ` that is not `done` or `dropped` and whose `Depends on:` modules are all `done` — name it, say why it's next, and confirm before planning. +- If the user named a **sub-module**, say plans are cut per module and offer both: plan the whole parent module, or plan that sub-module alone as its own file. Never silently widen or narrow the ask. +- A `Status: dropped` block is not plannable. Ask whether it's being revived — that's a roadmap edit, not a planning decision. + +### Step 1 — Read the block, then read around it +- Extract from the module's block: every `### Sub-Module`, its `Status`, `In scope`, `Out of scope`, and every `Depends on:`. +- Read the root context file (`CLAUDE.md` / `AGENTS.md`) and whichever of `docs/product.md`, `docs/conventions.md`, `docs/architecture.md` it links. Business rules and conventions constrain the tasks; a plan that ignores them tells the coding agent to violate the project's own docs. +- Check `docs/decisions.md` for `Status: Pending` entries this module touches, and name each one before planning. A task depending on a parked decision is a phase boundary, not a task. +- If a `Depends on:` module is not `done`, say so and ask whether to plan this one anyway or plan the dependency first. Don't assume either. + +### Step 2 — Cut the phases, then confirm the cut +- Propose 2–4 phases in dependency order, each carrying `Dependencies: None` or `Dependencies: Phase X`. +- **Sub-modules are the natural phase boundaries** — one per phase, unless two are genuinely inseparable. When a module has a single sub-module, split by layer instead (data → behavior → surface) and say explicitly that you did, since that split is yours and not the roadmap's. +- Cap each phase at 3–4 development tasks. A phase needing more is two phases. The verification gate doesn't count toward the cap. +- Show the phase titles, their order, and their dependencies, and get confirmation before writing any tasks. A wrong cut wastes the entire plan and costs one question to catch. +- Anything the roadmap marks `Out of scope:` stays out. If the user wants it in, the roadmap block changes first. + +### Step 3 — Write tasks and scenarios +- Read `references/plan-template.md` for the exact output shape, the four-state checkbox vocabulary, and the counting rules before drafting. Read `references/scenario-writing.md` before writing the scenarios. +- Give each development task a one-line *Details* naming what gets created or changed — endpoints, tables, data shapes, by name — and 1–3 scenarios beneath it. +- Write at least one happy-path scenario, plus at least one edge or error scenario wherever the task can fail. A task carrying only a happy path is under-specified. +- Scenarios state observable behavior: given what, what happens, with what result. No test code, no assertions, no framework names. +- Close every phase with its gate task, `Task X.V: Run test-and-verify suite for Phase X`. It is mandatory and it is not a development task. +- Use the project's own domain vocabulary, pulled from its docs, rather than generic placeholders. + +### Step 4 — Write the file and link it back +- Write `docs/guides/feature__plan.md`, snake_case, derived from the module title (`Module 3 — Assignment` → `docs/guides/feature_assignment_plan.md`). Create `docs/guides/` if it doesn't exist. +- **If that file already exists, this is a re-plan, not a fresh write.** Preserve every `[x]`, `[~]`, and `[-]` item with its annotation, and preserve the Progress Log and Files Modified list whole. Show the user the diff before writing. A task being re-cut becomes `[~]` with its reason — it never reverts to `[ ]`, because that would silently un-do finished work. +- Update the roadmap in the same pass: each planned sub-module's `**Tasks:** not yet planned` becomes `**Tasks:** see docs/guides/feature__plan.md — Phase `. The roadmap stays an index of modules and sub-modules; task detail lives only in the plan file. +- Append a dated Progress Log line saying the plan was initialized or re-cut, and what changed. +- Report the phase count, the total task count, any decisions still parked and which phases they gate, and the exact path written. Then offer to hand off to `execute-plan`. + +## Reference files +- `references/plan-template.md` — the exact output format, the four-state checkbox vocabulary, and how progress is counted. Read this in Step 3 before drafting. +- `references/scenario-writing.md` — what makes a scenario checkable, with weak/strong pairs. Read this in Step 3, and again if a scenario comes out vague or starts drifting toward test code. diff --git a/skills/plan-module/references/plan-template.md b/skills/plan-module/references/plan-template.md new file mode 100644 index 0000000..26b6c74 --- /dev/null +++ b/skills/plan-module/references/plan-template.md @@ -0,0 +1,121 @@ +# Plan file template + +The exact shape of `docs/guides/feature__plan.md`. Read this before drafting in Step 3. +`execute-plan` parses this file, so the structure is a contract — the headings, the checkbox glyphs, +and the counting format are fixed. Prose inside a *Details* line or a scenario is free. + +## Filename + +`docs/guides/feature__plan.md`, snake_case, derived from the roadmap module title with +the `Module — ` prefix dropped. + +| Roadmap module | Plan file | +|---|---| +| `## Module 1 — Task core` | `docs/guides/feature_task_core_plan.md` | +| `## Module 3 — Assignment` | `docs/guides/feature_assignment_plan.md` | +| `## Module 4 — Billing & invoicing` | `docs/guides/feature_billing_invoicing_plan.md` | + +Drop punctuation, lowercase everything, join words with underscores. One file per module. + +## Checkbox vocabulary — exactly four states + +| Glyph | State | Meaning | Required annotation | +|---|---|---|---| +| `[ ]` | Open | Pending, not started | none | +| `[x]` | Done | Completed **and verified** — test output, build log, or smoke test | none | +| `[~]` | Reframed | Changed mid-flight | `(reframed: )` | +| `[-]` | Skipped | Deliberately omitted | `(skipped: )` | + +No fifth state, and no free-text substitutes. `[x]` means verified, not "written" — a task whose code +exists but whose scenarios never ran is still `[ ]`. `execute-plan` relies on that distinction to +know what it still owes. + +## Counting rules — closed items, never percentages + +- An item is **Closed** when it is `[x]`, `[~]`, or `[-]`. Only `[ ]` is open. +- Write counts as `[/ Tasks Closed]` and `[/ Phases Closed]`. +- Never write a percentage. `3/7` survives a task being added mid-flight; `43%` silently becomes a lie. +- A phase's task total **includes** its `X.V` gate task. The 3–4 task cap in Step 2 is on development + tasks only, so a full phase counts 4 or 5. +- Scenarios carry their own checkboxes and are **not** counted in the task totals. They are evidence + that a task is done, not units of progress on their own. + +## Template + +```markdown +# Plan +Status: In Progress | Last Updated: | Overall Progress: [0/ Phases Closed] + +## Progress Log +- : Plan initialized via plan-module skill. + +## Files Modified +*(Accumulated during execution)* + +--- + +## Phase 1: +- Status: [ ] Open +- Dependencies: None +- Progress: [0/ Tasks Closed] + +### Tasks & Test Scenarios +- [ ] **Task 1.1: ** + - *Details:* + - [ ] *Scenario 1.1a:* + - [ ] *Scenario 1.1b:* + +- [ ] **Task 1.2: ** + - *Details:* + - [ ] *Scenario 1.2a:* + +### Phase Completion Gate +- [ ] **Task 1.V: Run test-and-verify suite for Phase 1** + - *Details:* Execute the tests covering Phase 1, confirm zero failures, confirm type-checks pass, then mark Phase 1 complete. + +--- + +## Phase 2: +- Status: [ ] Open +- Dependencies: Phase 1 +- Progress: [0/ Tasks Closed] + +### Tasks & Test Scenarios +- [ ] **Task 2.1: ** + - *Details:* + - [ ] *Scenario 2.1a:* + +### Phase Completion Gate +- [ ] **Task 2.V: Run test-and-verify suite for Phase 2** + - *Details:* Execute the tests covering Phase 2, confirm zero failures, then mark Phase 2 complete. +``` + +Phases repeat this shape. Separate every phase with a `---` rule. + +## The living sections + +**`## Progress Log`** starts with one dated initialization line and is append-only during execution. +A re-plan appends a line naming what was re-cut; it never rewrites earlier lines. This is the same +append-only discipline `docs/decisions.md` uses, and for the same reason — the log is the record of +what happened, not a summary of the current state. + +**`## Files Modified`** starts as the literal italic line `*(Accumulated during execution)*` and is +filled in by `execute-plan` as it touches files. `plan-module` never populates it — at plan time +nothing has been modified, and guessing which files a task will touch is exactly the invented +implementation detail this file forbids. + +## Header fields + +- **Status** — `In Progress` from the moment the plan is written, since planning a module is the + start of working on it. It becomes `Done` when every phase is closed. +- **Last Updated** — today's date, rewritten on every edit including each execution pass. +- **Overall Progress** — phases closed over total phases, by the counting rules above. + +## What never appears in this file + +- Implementation code, test code, schemas, migrations, or function signatures. Naming an endpoint or + a table in *Details* is right; writing it out is not. +- Credentials, tokens, connection strings, private hostnames or IPs, or real customer data. Use a + named reference (`DATABASE_URL`, ``). +- Percentages, free-text statuses, or a fifth checkbox glyph. +- Any scope the roadmap block marks `Out of scope:`. diff --git a/skills/plan-module/references/scenario-writing.md b/skills/plan-module/references/scenario-writing.md new file mode 100644 index 0000000..f141cc1 --- /dev/null +++ b/skills/plan-module/references/scenario-writing.md @@ -0,0 +1,67 @@ +# Writing test scenarios + +Every development task in a plan file carries 1–3 scenarios. They exist so `execute-plan` can tell +whether a task is actually done, and so a human reviewing the plan can spot a missing requirement +before any code is written. Read this in Step 3, and again whenever a scenario comes out vague. + +## The bar + +A scenario is checkable when someone who has never seen the code can read it, exercise the system, +and say yes or no without asking a follow-up question. If confirming it requires opening the +implementation to find out what "correct" means, the scenario is not finished. + +State three things: the starting condition, the action, and the observable result. The phrasing +doesn't have to be Given/When/Then, but all three parts have to be recoverable from the sentence. + +## Weak and strong pairs + +| Weak | Strong | +|---|---| +| Test that assignment works | Assigning an unassigned task to a workspace member sets that member as the assignee and returns the updated task | +| Handles errors properly | Assigning a task to a user who is not a member of the workspace is rejected, the task keeps its previous assignee, and nothing is written | +| Validates input | A status transition request with a status outside `todo`/`in_progress`/`done` is rejected before any write, and the response names the offending value | +| Should be fast | A workspace with 500 tasks returns its task list in one request, without the caller paginating manually | +| Verify the migration ran | After migrating, every existing task has a non-null `status`, and tasks that had no status before read `todo` | + +The weak column fails the bar for the same reason each time: "works", "properly", "validates", "fast" +are judgments the reader has to supply themselves. + +## Coverage per task + +- **At least one happy path.** The task's reason for existing, exercised once, end to end. +- **At least one edge or error case wherever the task can fail** — rejected input, a missing record, + an unauthorized caller, a boundary value, a concurrent write. Most tasks can fail. A task with only + a happy path is under-specified, and should be challenged rather than shipped. +- **Stop at three.** More than three scenarios on one task is a signal the task is doing too much; + split the task instead of stacking scenarios onto it. + +## Business rules get their own scenario + +If the project's root context file or `docs/product.md` states a rule the module touches — a +forbidden state transition, an authorization boundary, a pricing rule, a retention limit — write a +scenario asserting it directly, in the rule's own words. These are the requirements a coding agent +is most likely to satisfy approximately, and approximately is wrong. + +Where a rule is stated as a prohibition, the scenario is the prohibition: + +> *Scenario 2.1b:* A request moving a task directly from `todo` to `done` is rejected and the task +> stays `todo`. + +## Never write test code + +Scenarios are plain English. No assertions, no framework names, no fixture setup, no `expect(...)`, +no describe blocks, no HTTP snippets. `execute-plan` chooses the framework and writes the tests; a +scenario that names one has made that decision early and probably wrongly. + +- Wrong: `expect(res.status).toBe(403)` for a non-member +- Right: A non-member's assignment request is refused as unauthorized + +Naming a status code, an endpoint path, or a field in prose is fine — that's the behavior. Writing +the call that checks it is not. + +## Scenarios are not the same as the gate + +Per-task scenarios describe behavior. The phase's `Task X.V` gate is the instruction to actually run +the suite covering them and confirm zero failures. Don't collapse the two: a phase with scenarios but +no gate never gets verified as a whole, and a gate with no scenarios beneath its tasks has nothing +specific to verify. diff --git a/skills/scaffold/SKILL.md b/skills/scaffold/SKILL.md index 4e60cc2..1937f35 100644 --- a/skills/scaffold/SKILL.md +++ b/skills/scaffold/SKILL.md @@ -105,7 +105,7 @@ Then pick the **linked docs**, which are identical in every layout. Don't genera ### Step 5 — Write and confirm - If there's filesystem access to the actual project (e.g. running inside Claude Code with a real repo), write the files directly into the correct paths. - If running in a chat-only surface without a project filesystem, produce the files as downloadable/presentable content and tell the user exactly which path each one belongs at once they're in their project. -- If Step 0 found an existing scaffold and the target agent changed, **migrate rather than orphan**: moving content between `CLAUDE.md` and `AGENTS.md`, adding or removing the loader. Propose the moves and get confirmation before writing — migration deletes files. A pre-3.0 `docs/roadmap.md` migrates the same way: propose the rename to `docs/development-roadmap.md` and the conversion of its flat lists into module/sub-module blocks, show what maps where, and confirm before writing. Never drop content that has no home in the new layout; raise it as a question instead. +- If Step 0 found an existing scaffold and the target agent changed, **migrate rather than orphan**: moving content between `CLAUDE.md` and `AGENTS.md`, adding or removing the loader. Propose the moves and get confirmation before writing — migration deletes files. A pre-3.0 `docs/roadmap.md` migrates the same way: propose the rename to `docs/development-roadmap.md` and the conversion of its flat lists into module/sub-module blocks, show what maps where, and confirm before writing. Never drop content that has no home in the new layout; raise it as a question instead. On any re-run, a sub-module whose `**Tasks:**` already points at a `docs/guides/feature_*_plan.md` file keeps that pointer — `plan-module` wrote it, and resetting it to `not yet planned` orphans a live plan. - Show the resulting file tree and a short summary of what went where, naming which layout was used and why. List every companion `CLAUDE.md` explicitly with a one-line note that it's a thin `@AGENTS.md` import. List **Pending decisions** as its own section when any exist, so the user leaves knowing what they parked. Flag anything inferred vs. still uncertain — don't silently guess on business-critical rules. - Tell the user how to verify the docs actually load: for Claude Code, run `/context` and check the list under **Memory files**. In portable mode (an `AGENTS.md` exists alongside `CLAUDE.md`), warn against running `/import`, which appends a duplicate copy of `AGENTS.md` into `CLAUDE.md`. - Before reporting, check every internal link in the content file resolves to a file that was actually generated. Drop the line rather than shipping a dead link — `design-system.md` is deliberately absent whenever the theme was deferred, so this fires on a common path, not an edge case. diff --git a/skills/scaffold/references/best-practices.md b/skills/scaffold/references/best-practices.md index e323e09..a030efc 100644 --- a/skills/scaffold/references/best-practices.md +++ b/skills/scaffold/references/best-practices.md @@ -70,13 +70,13 @@ Architecture overviews that fall out of sync with the actual code don't just fai ## Why the development roadmap is always generated Every other doc here is generated only when the project warrants it. "Don't generate a file nobody needs" is a rule, and a hollow doc is worse than an absent one — absence prompts a question, a half-empty file looks answered. `development-roadmap.md` is the single deliberate exception. -It is generated for every project, trivial ones included, because it is not only documentation. It is the input contract for the step that plans a sub-module: the module and sub-module ids, their dependency order, and their scope boundaries are what that step reads to know what "the next piece of work" refers to. A missing roadmap doesn't degrade that step's output — it removes its input entirely. That's a different failure from the one the general rule protects against, and it's why the exception is worth its cost. +It is generated for every project, trivial ones included, because it is not only documentation. It is the input contract for `plan-module`: the module and sub-module ids, their dependency order, and their scope boundaries are what that skill reads to know what "the next piece of work" refers to, and the sub-modules become the phase boundaries of the plan file it writes. A missing roadmap doesn't degrade `plan-module`'s output — it removes its input entirely. That's a different failure from the one the general rule protects against, and it's why the exception is worth its cost. The cost is real. On a genuinely small project the roadmap is one module and a couple of sub-modules, which is close to the hollow-doc failure the general rule exists to prevent. It survives that objection on exactly one condition: the blocks record a decomposition the user actually confirmed during the interview, not a restatement of the project title. A roadmap whose only content is "Module 1 — build the app" is a placeholder wearing a heading, and the no-placeholder rule applies to it in full. This is why the decomposition question is mandatory rather than conditional. The file is always generated, so its content always has to have been decided. Skipping the question and generating the file anyway is the failure mode to watch for, not skipping the file. -The roadmap stops at sub-modules. Task-level detail belongs to the step that plans one sub-module, and only once there is a codebase to plan against — writing tasks during the initial interview means inventing implementation detail nobody has decided yet, which is the same failure in a different costume. +The roadmap stops at sub-modules. Task-level detail belongs to `plan-module`, which writes it into `docs/guides/feature__plan.md` and leaves the roadmap's `Tasks:` field as a pointer to it — and it runs when a module is about to be built, not during the initial interview, where writing tasks means inventing implementation detail nobody has decided yet. That's the same failure in a different costume. ## What NOT to put in the root file Avoid: temporary/one-off task requirements, copied documentation that already exists elsewhere, large code samples, vague advice ("write clean code"), rules a linter or formatter already enforces mechanically, and step-by-step procedures that belong in a reusable Skill instead. diff --git a/skills/scaffold/references/templates.md b/skills/scaffold/references/templates.md index 3892396..59c02f4 100644 --- a/skills/scaffold/references/templates.md +++ b/skills/scaffold/references/templates.md @@ -223,8 +223,8 @@ roadmap is always generated." One `## Module ` block per module, each holding `### Sub-Module .` blocks, in dependency order. **This file records modules and sub-modules only. It does not contain task tables.** Task-level -detail is the output of the step that plans a sub-module, and inventing it here — before any code -exists — produces confident guesses, which is the placeholder failure this whole file forbids. +detail is `plan-module`'s output, written to its own plan file, and inventing it here — before any +code exists — produces confident guesses, which is the placeholder failure this whole file forbids. ```markdown # Development Roadmap @@ -259,16 +259,17 @@ free-text status makes the file unusable by the step that reads it. | `blocked` | Cannot start; the blocker is named in `Depends on:` | | `dropped` | Was planned, deliberately abandoned. Keep the block; state why in `Out of scope:` | -**Identifiers.** Modules are `Module `; sub-modules are `.` and are the addressable unit — -the planning step operates on one sub-module at a time. +**Identifiers.** Modules are `Module `; sub-modules are `.`. `plan-module` operates on one +**module** at a time and its sub-modules become the phase boundaries of that module's plan file. **`Depends on:`** takes `none`, one or more module or sub-module ids with blocks in this same file, or a named external blocker (a pending decision, a third-party dependency) — but never an id with no block here. -**When tasks are added later, they are plain English and never sample code.** A task line says what -changes and why it matters, not how to write it. Code in a roadmap goes stale the moment the code -changes, and a stale doc misleads more than no doc at all. +**`Tasks:` is a pointer, never a task list.** It reads `not yet planned` until `plan-module` runs, +and then becomes `see docs/guides/feature__plan.md — Phase `. Task detail lives in the +plan file only. Code in a roadmap goes stale the moment the code changes, and a stale doc misleads +more than no doc at all. `## Deferred` and a `dropped` module are not the same thing. Deferred items were never modules — they're capability-level scope decisions. A dropped module was scoped and sequenced first, and the From 0187013510d6e50002a0147530e4a8bc5c0c8475 Mon Sep 17 00:00:00 2001 From: Krishna Vyas Date: Sat, 22 Aug 2026 23:11:45 -0600 Subject: [PATCH 6/6] docs: note that 3.0.0 ships inside the 3.1.0 tag MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 3.0.0 was prepared but never tagged; both branches release together as v3.1.0. Keep its entry — that's where the breaking changes and the 2.x upgrade steps are written — but say plainly it was never released on its own, and point 2.x upgraders at it from the 3.1.0 intro. Co-Authored-By: Claude Opus 5 (1M context) --- CHANGELOG.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 84d186c..bf1038b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,12 @@ Adds the plugin's second skill, `plan-module`. `scaffold` has always written a `docs/development-roadmap.md` whose every `**Tasks:**` field read `not yet planned`; `plan-module` is -what fills that in. Additive — nothing in 3.0.0 changes behavior, and no generated file changes shape. +what fills that in. `plan-module` itself is purely additive — it changes nothing 3.0.0 established, and +no generated file changes shape. + +**This release also carries everything listed under 3.0.0 below**, which was prepared but never tagged. +If you are upgrading from 2.x, read 3.0.0's **Breaking** and **Upgrading from 2.x** sections — they +apply to this release. ### Added - **`plan-module`** (`skills/plan-module/SKILL.md`) — reads one `## Module ` block out of @@ -51,6 +56,9 @@ unchanged, since `**Tasks:** not yet planned` is exactly what it expects to find ## [3.0.0] — 2026-08-21 +*Never tagged on its own — these changes ship as part of 3.1.0. Kept as a separate entry because it is +where the breaking changes are described.* + Major release. `code-idea` is now a Claude Code **plugin** rather than a standalone skill repo, the skill inside it is renamed `scaffold`, and `docs/roadmap.md` becomes `docs/development-roadmap.md` with a module/sub-module structure and unconditional generation. Read **Breaking** before upgrading.