craftsman-suite
CLAUDE.md2 starsChanged 42 days agoMITView on GitHub
The repo (craftsman-suite, MIT, author Darren Yeh) is scaffolded as a single Claude Code plugin and marketplace. The scaffold is .claude-plugin/plugin.json, .claude-plugin/marketplace.json, README.md and LICENSE. All 10 skills/<name>/SKILL.md files are written. adversarial-review writes reports to .specs/reviews/, which behavior-tests, safe-refactor and dev-docs read. There is no build or test tooling; validate manifests with claude plugin validate .. The skills/*/SKILL.md files are the source of truth. Each skill that writes a .specs/ artifact inlines its template under an "Artifact Template" heading in…
- Reads credentials
In this repository10 other files it gives its agents.
- adversarial-reviewSkill
- arch-tradeoffsSkill
- behavior-testsSkill
- dev-docsSkill
- draft-scaffoldSkill
- env-foundrySkill
- problem-specSkill
- runtime-topologySkill
- safe-refactorSkill
- task-slicerSkill
The file
Files
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Current state
The repo (craftsman-suite, MIT, author Darren Yeh) is scaffolded as a single Claude Code plugin and marketplace. The scaffold is .claude-plugin/plugin.json, .claude-plugin/marketplace.json, README.md and LICENSE. All 10 skills/<name>/SKILL.md files are written. adversarial-review writes reports to .specs/reviews/, which behavior-tests, safe-refactor and dev-docs read. There is no build or test tooling; validate manifests with claude plugin validate ..
The skills/*/SKILL.md files are the source of truth. Each skill that writes a .specs/ artifact inlines its template under an "Artifact Template" heading in its SKILL.md (plugin files outside the project trigger permission prompts, so templates are not bundled as separate files). There is no root .specs/ folder in this repo and it is git-ignored: .specs/ belongs to the user's project, so the inline templates are the only copies. An original design blueprint may exist locally as an untracked plan.md; it is not part of the repo and may be out of date.
What is being built
A suite of 10 decoupled agent skills conforming to the open SKILL.md standard (agentskills.io). They target Claude Code, Cursor, Codex CLI, OpenCode, and Gemini CLI. Each skill is invoked on demand by slash command (e.g. /problem-spec). Every skill ends with a Transition Stop Gate: it halts and prompts the user instead of chaining into the next stage. Preserve this human-in-the-loop behavior in any new or edited skill.
Architecture
Pipeline (the order matters, and each stage reads the artifacts of earlier stages):
problem-spec→.specs/01-problem-spec.mdarch-tradeoffs→.specs/02-conceptual-architecture.md(always exactly three options, A/B/C)runtime-topology→.specs/03-runtime-topology.md(language-agnostic)env-foundry→.specs/04-environment-setup.md, plusdocker-compose.yml, version pin files,.env.exampletask-slicer→.specs/05-task-backlog.md(atomic tasks, at most 2 files and about 50 lines each, each with a verification command and a[TODO]/[IN_PROGRESS]/[DONE]status)- Implementation loop per task:
draft-scaffold→adversarial-review→safe-refactor→behavior-tests dev-docs(PR summary, ADR, or runbook)
Persistent context anchors: skills must recover state from the git-tracked .specs/ files, never from conversation memory. A skill's "Ingest Context" step names the exact .specs/ files it reads.
Stage-boundary guardrails (each skill enforces what it must NOT do):
- Stages 1–3 and
task-slicermust not emit application code. runtime-topologystays vendor/language-agnostic and rejects long-running work in synchronous handlers.draft-scaffoldtouches only the in-progress task's files and must prefix output with theDRAFT IMPLEMENTATIONbanner.safe-refactorhas hard invariants: no public API changes, no behavior changes, no new dependencies, and existing tests stay green without edits.adversarial-reviewclassifies findings as[CRITICAL BLOCKED],[WARNING/DEBT], or[NITPICK], with no praise.behavior-teststurns its breaking payloads into regression tests.
SKILL.md format: YAML frontmatter (name, description, license, compatibility, metadata.version, metadata.stage), then a persona, Operating Principles, Execution Steps, Hard Guardrails, and the Transition Stop Gate. New skills should follow the same structure.
Roadmap
The README lists the deferred skills (schema-evolution, telemetry-first, threat-model, ci-pipeline, release-runbook). Rollout gates: each design skill must halt cleanly, write its .specs/ file, and refuse to write application code; the implementation loop must run Draft → Critique → Refactor → Test with public APIs unchanged.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

