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. The only application code is examples/fixtures/pickup-queue/, a dependency-free Node project the skills are run against; everything else is markdown. Six skills: five run in sequence — scaffold (.agents/skills/scaffold/SKILL.md) writes the docs set including docs/development-roadmap.md; design-brand (.agents/skills/design-brand/SKILL.md), for products with a public face, imports or builds the brand into docs/brand/; design-ui (.agents/skills/design-ui/SKILL.md), for projects with a UI, settles the look in DESIGN.md, docs/design/screens.md, and static mockups before anything is planned; plan-module (.agents/skills/plan-module/SKILL.md) turns one module of that roadmap into docs/guides/feature_<module>_plan.md; and execute-plan (.agents/skills/execute-plan/SKILL.md) builds that plan file task by task. The sixth, test-and-verify (.agents/skills/test-and-verify/SKILL.md), is a service the others call rather than a stage: it runs the tests — and renders screens against their mockups — fixes what fails within a bounded loop, and returns a verdict. No skill name is reserved-but-unbuilt.

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 .agents/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.
• The frontmatter description must contain no < or >. Claude.ai and Claude Desktop reject an uploaded skill whose description holds anything tag-shaped — SKILL.md description cannot contain XML tags — because the description is injected into a system prompt where tags are structural. A placeholder written <module> is enough to trigger it. Claude Code, the skills CLI, and every other agent accept it happily, so the skill installs everywhere except the one surface that refuses it, and nothing in the repo says why. Write a placeholder as [module]. The release workflow's description checks are the guard.
• Never leave placeholder or TODO content in any SKILL.md or references/ — see CONTRIBUTING.md.
• .agents/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 skills live at .agents/skills/, and plugin.json's skills field is the only thing pointing Claude Code at them. Every agent but Claude Code reads .agents/skills/ natively; Claude Code reads it only because the manifest says to. Move or rename that directory without updating the manifest and Claude Code falls back to scanning ./skills/, finds nothing, and loads zero skills with no error anywhere — the same silent-non-registration failure as an over-length description. Change the two together. The release workflow's manifest step is the check.
• The frontmatter must be valid YAML under a strict parser, and use only the spec's six fields (name, description, license, compatibility, metadata, allowed-tools). Claude Code's parser is lenient enough to hide breakage that makes every other agent skip the skill entirely — a : inside an unquoted description did exactly that, undetected, for two skills. Use an em dash or a period instead. The release workflow parses every skill with PyYAML as the check.
• .claude-plugin/plugin.json is the single answer to "what version is this?", and two other places must agree with it. The git tag, and each skill's metadata.version — which exists because plugin.json does not travel with a skill copied into .agents/skills/, so a standalone install has no other way to know. Bump all of them together; CI blocks a tag whose plugin.json disagrees, and blocks a skill whose metadata.version disagrees. .claude-plugin/marketplace.json deliberately carries no version — 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 a future 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 .agents/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.
• Five skills write to the docs set, and their fields are disjoint. scaffold owns the context file (bar the ## Commands lines execute-plan fills in) and the roadmap's format, design-brand owns everything under docs/brand/, design-ui owns DESIGN.md and everything under docs/design/, plan-module owns each sub-module's **Tasks:** pointer, and execute-plan owns Status: write-back as phases close. Nothing else updates a roadmap status, so an execute-plan that skips it sends the next plan-module run at a module that is already built. The crossings are design-brand and design-ui each adding a single line to the context file's ## Related docs — which a scaffold re-run must keep, the same way it keeps a **Tasks:** pointer — pending-decision entries in the shape scaffold already writes, and design-brand's dated docs/decisions.md entries, accepted or pending, which are append-only and never edit a past one. Never let one skill start writing another's field. S67, S112, and S135 are the checks.
• The brand is design-brand's; its mapping onto the product is design-ui's. docs/brand/ is the brand's source of truth, and DESIGN.md is one mapping of it. design-ui never edits docs/brand/ — a brand-level problem found while mapping goes back as a question — and design-brand never writes a token, a mockup, or a convention. Precedence is a dated decision, then the source book, then the README's summary. S132 and S136 are the checks.
• design-brand never fakes an asset, and never repeats a claim it hasn't checked. A wordmark exploration is labelled one, and becomes a working mark with a pending decision, never a "logo pack". Photography, trademark clearance, legal wording, and market tests become briefs and pending decisions. A logo is used from its file, never retyped; a wrong pack file is corrected with a CORRECTIONS.md record or listed don't-use. A promise or proof line is checked against docs/product.md and docs/decisions.md, and a false one becomes a never-say rule. S127, S129, and S134 are the checks.
• Contrast is measured, never inherited. Every text pairing a brand allows is measured, and each failure becomes a rule saying what to do instead — a book that forbids one failing pairing has usually missed others. S126 is the check.
• A prototype's look and its stack are separate decisions. The stack a sandbox forced is re-recommended by scaffold; the look is often the best evidence of what the user wants, and design-ui imports it as the visual target. Each is confirmed on its own — never let one answer settle the other, and never drop the look just because the stack was suspect. That drop is why builds came out looking worse than the prototype. S107–S108 are the checks.
• The repo is the design's source of truth, never a preview. Mockups are files under docs/design/mockups/. A rendered artifact or a published page is how the user reviews one, never the only copy — no other agent can read it. Previewing is capability-shaped like the domain-skill hook: no SKILL.md names a host's artifact or browser tool. S110 is the check.
• A visual scenario is [x] only on a rendered comparison. test-and-verify renders the screen at the scenario's widths and compares it with the mockup; reading markup, or passing data tests, closes nothing. No browser means not checked, and execute-plan records [~]. S117–S118 are the checks.
• .agents/skills/design-ui/references/design-files.md is expected to age. It follows Google Labs' DESIGN.md format, which is alpha. Verify a section name or CLI command against the current spec before relying on it; a stale entry is a welcome PR.
• test-and-verify never writes a plan file. Not a glyph, not a count, not the Progress Log. It returns a verdict; execute-plan writes it down. Two writers on one file is how a plan stops being trustworthy, and it's the same disjoint-fields rule the roadmap follows. S89 is the check.
• The three-attempt circuit breaker is a ceiling, not a suggestion. execute-plan must not re-invoke test-and-verify to get past a failing verdict — that's the same attempt with the safety removed. A red verdict closes nothing and stops the loop. S90 is the check.
• .agents/skills/test-and-verify/references/test-commands.md is expected to age, like recommendation-heuristics.md. Runners and flags shift. A command read out of the project always beats one read out of that table — it's a fallback for when the project is silent, never an override.
• .agents/skills/execute-plan/references/progress-updates.md is subordinate to the two specs it applies. The checkbox vocabulary and counting rules live in plan-module's plan-template.md; the roadmap Status vocabulary lives in scaffold's templates.md. That file says only how to apply them during execution and must never become a third source of truth — if it disagrees with either, it is the bug. S66 is the check.
• [x] means verified, never merely written. execute-plan may not close an item on inspection, on intent, or on a passing type-check — a test covering that scenario has to have actually run and been read. Behavior that genuinely can't be checked in the environment is [~] with what would verify it, never [x] on faith. S68 is the check.
• A SKILL.md never names another skill outside this plugin. execute-plan Step 2 consults a domain skill when the environment offers one, but the hook is capability-shaped, not a list — naming impeccable or vercel:nextjs bakes a Claude-Code-plugin assumption into content that must also run on Codex, Cursor and the rest, and a renamed skill becomes a dead invocation with nothing erroring. The in-plugin test-and-verify delegation is the exception, and it survives because that skill has a contract — a verdict, and no plan-file writes. Anything consulted advises; the calling skill still decides, bounded by the task's Details and the project's conventions. It is its own step, ahead of implementation, and it has to produce something — a stated direction — so the consult is observable rather than assumed. examples/test-scenarios.md S102–S104 are the checks; S105–S106 cover the step's positioning and per-task cadence and are open, not passing — an A/B eval could not show the positioning changes behavior, so don't cite them as settled.
• 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 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

• See CONTRIBUTING.md's "Testing a change" section — run the skill against a sample plan before and after any SKILL.md edit, including at least one case where the new/changed rule should clearly fire and one where it clearly shouldn't.

Related docs

• README.md — human-facing overview, install/usage
• CONTRIBUTING.md — contribution guidelines and file-ownership map
• CHANGELOG.md — release history
• .agents/skills/scaffold/references/best-practices.md — the reasoning behind the skill's rules
• .agents/skills/scaffold/references/recommendation-heuristics.md — stack/database/naming defaults it proposes during its interview
• .agents/skills/scaffold/references/agent-profiles.md — per-agent container facts, with sources and dates; expected to age
• .agents/skills/design-brand/references/brand-strategy.md — positioning, promise, voice, distinctive assets, refresh versus rebrand
• .agents/skills/design-brand/references/brand-system.md — palette and contrast, type licences, the logo pack audit, imagery licences, what an agent can't make; partly expected to age
• .agents/skills/design-brand/references/brand-files.md — the docs/brand/ layout, README and CORRECTIONS.md formats
• .agents/skills/design-ui/references/visual-direction.md — escaping the generic default, visual theses, importing a prototype
• .agents/skills/design-ui/references/design-files.md — the DESIGN.md, screens.md, and mockup formats; expected to age
• .agents/skills/test-and-verify/references/visual-check.md — how a visual scenario is rendered and compared
• .agents/skills/plan-module/references/plan-template.md — the plan file's format, checkbox vocabulary, and counting rules
• .agents/skills/plan-module/references/scenario-writing.md — what makes a plain-English test scenario checkable
• .agents/skills/execute-plan/references/verification.md — finding or bootstrapping a test runner, and what counts as verified
• .agents/skills/execute-plan/references/progress-updates.md — the plan-file and roadmap writes execution makes
• .agents/skills/test-and-verify/references/test-commands.md — finding and scoping the test command; expected to age
• .agents/skills/test-and-verify/references/remediation.md — app-bug vs test-bug, the circuit breaker, and the report formats
• scripts/install.sh — installs the skills into any supported agent; its agent table carries sources and a verified-on date, and is expected to age
• examples/test-scenarios.md — the scenarios a change must be checked against
• examples/fixtures/pickup-queue/ — the runnable Fixture I, plus how to A/B one skill text against another; read its README before claiming a change altered behavior