Skip to content

AGENTS.md

Latest commit

 

History

History
52 lines (47 loc) · 12 KB

AGENTS.md

File metadata and controls

52 lines (47 loc) · 12 KB
Raw

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. Four skills: three run in sequence — scaffold (.agents/skills/scaffold/SKILL.md) writes the docs set including docs/development-roadmap.md; 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 fourth, test-and-verify (.agents/skills/test-and-verify/SKILL.md), is a service the others call rather than a stage: it runs the tests, 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 all four 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.
  • Three skills write to the docs set, and their fields are disjoint. scaffold owns the roadmap's format, 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. Never let one skill start writing another's field. S67 is the check.
  • 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/UI 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/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