v3.1.0 — convert to a plugin and add the plan-module skill

.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "melconcoast",
+  "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."
+    }
+  ]
+}

.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "code-idea",
+  "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",
+  "repository": "https://github.com/melconcoast/code-idea",
+  "license": "MIT",
+  "keywords": ["claude-code", "skills", "agents-md", "claude-md", "scaffolding", "planning"]
+}

.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/<name>/ into <name>.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,33 +18,87 @@ on:
 permissions:
   contents: write
 
-env:
-  SKILL_NAME: code-idea
-
 jobs:
   package:
     runs-on: ubuntu-latest
     steps:
       - 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

.gitignore

@@ -7,9 +7,3 @@ Thumbs.db
 *.swp
 .vscode/
 .idea/
-
-# Superpower skill folders
-docs/superpowers/
-
-# SDD scratch workspace
-.superpowers/

AGENTS.md

@@ -1,18 +1,24 @@
 # 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. 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_<module>_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 `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 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
-- 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 +28,9 @@
 - `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
+- `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