esurvanov/awesome-claude

---

What is this

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.yaml persists 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.

---

Init

Instructions for Claude (read this first when invoked in any directory).

awesome-claude operates in two modes — pick one based on the current directory:

1. 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 run skill:setup (or read skills/skill/setup/skill.md directly on first bootstrap when symlinks don’t exist yet) to symlink skills/, commands/, rules/ into .claude/.
2. 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-claude to 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, no make, no manual commands.

---

Quick Start (user mode)

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.

---

How It Works

You ask Claude → .claude/ detected → Rules loaded (by file path)
                                   → Skills available (/tdd, /commit, ...)
                                   → Claude writes code following YOUR conventions

---

Skills

31 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:test — Generate and run check artifacts for a spec; mandatory agent-mode semantic evaluation prevents self-PASS
• /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

---

Rules

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

---

Philosophy

• 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

---

Contributing (dev mode)

Inside the awesome-claude repo:

1. /skill:setup — symlinks skills/, commands/, rules/ into .claude/. After this, every edit under skills/ is visible to Claude Code immediately, no manual copying.
2. /skill:deps — installs CLI dependencies (openspec etc.) and submodules from manifest.yaml.
3. /skill:onboarding — guided walkthrough of the contributor workflow (next step depends on current state: setup → deps → propose → apply → test).
4. Standard SDD flow: /sdd:explore → /sdd:propose → /sdd:contradiction → /sdd:apply → /sdd:archive.
5. /skill:test-skill : to run skill tests; /skill:test-all to run everything.
6. /skill:release when ready to cut a new version.

---

Details

Full documentation: docs/README_DETAILED.md

Installation guide (for Claude): CLAUDE_INSTALL.md

---

MIT