Spec-driven development layer for Claude Code.
Built on top of OpenSpec. Agent reads state from files, finds contradictions in requirements autonomously, and never loses contract between sessions.
OpenSpec gives you the folder structure and CLI for spec-driven development. awesome-claude adds a layer on top:
- Autonomous contradiction detection — Claude finds conflicts in requirements, not just lints structure
- Agent-first state —
.sdd-state.yamlpersists change stage across sessions, nothing is lost between conversations - Higher-level requirements — describe intent, Claude decomposes and verifies
Specs are primarily written for the agent, not the human. By default this is chaos-driven development: you declare desired state, the agent reconciles. Contradiction detection is the stability layer.
Instructions for Claude (read this first when invoked in any directory).
awesome-claude operates in two modes — pick one based on the current directory:
- dev mode — directory contains
skills/,commands/,manifest.yaml(or.openspec.yaml): you are inside the awesome-claude repo itself. The contributor wants to edit skills/rules. Suggest dev mode and runskill:setup(or readskills/skill/setup/skill.mddirectly on first bootstrap when symlinks don't exist yet) to symlinkskills/,commands/,rules/into.claude/.- user mode — any other directory: the user wants to install awesome-claude into their project. Ask which namespaces to install (or all by default),
git clone https://github.com/Hedgehogues/awesome-claudeto a temp directory, copy selected namespaces into.claude/, remove the temp directory.Briefly describe both options to the user (1–2 sentences each), ask them to confirm, then perform setup directly — no
curl | bash, nomake, no manual commands.
Open Claude Code in your project directory and ask:
"Install awesome-claude from https://github.com/Hedgehogues/awesome-claude"
Claude clones the repo, copies the selected skills/rules into .claude/, and your project is ready.
You ask Claude → .claude/ detected → Rules loaded (by file path)
→ Skills available (/tdd, /commit, ...)
→ Claude writes code following YOUR conventions
30 slash commands. Core is spec-driven development.
Drive changes with specs:
/sdd:explore— Clarify the problem before proposing/sdd:propose— Requirements + design + tasks in one step/sdd:contradiction— Agent finds contradictions in requirements autonomously/sdd:apply— Implement against specs, verify on completion/sdd:archive— Merge specs into the registry, verify nothing was lost
SDD tracks state in .sdd-state.yaml per change — agent resumes from the last
known stage across sessions without losing contract.
Plus utilities for TDD, debugging, commits, reports, and TRIZ problem-solving.
Full list: docs/README_DETAILED.md
Automatically load based on file paths:
- Architecture: state ownership, visual cohesion, dependency direction
- Workflow: Git discipline, testing conventions, monorepo structure
- Interface: Claude Code only, MCP for external systems
- Quality: Security, unit tests, never silently fix broken tests
- Claude Code is the only interface — every operation goes through a skill, no direct shell calls
- Tests are specs — no red test, no requirement
- Stop on red — never silently fix broken tests
- Backend owns state — frontend is a stateless projection
- Dependencies flow inward — domain knows nothing about infrastructure, never the reverse
- MCP for external systems — scripts, services, CLI tools accessed through MCP, not raw Bash
- Commits tell a story — What / Why / Details
Inside the awesome-claude repo:
/skill:setup— symlinksskills/,commands/,rules/into.claude/. After this, every edit underskills/is visible to Claude Code immediately, no manual copying./skill:deps— installs CLI dependencies (openspecetc.) and submodules frommanifest.yaml./skill:onboarding— guided walkthrough of the contributor workflow (next step depends on current state: setup → deps → propose → apply → test).- Standard SDD flow:
/sdd:explore→/sdd:propose→/sdd:contradiction→/sdd:apply→/sdd:archive. /skill:test-skill <ns>:<skill>to run skill tests;/skill:test-allto run everything./skill:releasewhen ready to cut a new version.
Full documentation: docs/README_DETAILED.md
Installation guide (for Claude): CLAUDE_INSTALL.md