hongdosan-spec-driven-orchestra

🎼 Spec-Driven Orchestra

An experimental package that makes the SDD framework the conductor of 4 skills it can call, in one Claude Code workflow. All 5 instruments come from open-source projects (across 4 repositories).

For new, early-stage, or refactoring projects. Claude Code interviews your project, then integrates the methodologies semi-autonomously.

🌐 Language: English | 한국어

Quick Start • The Symphony • How It Works • FAQ • Contribute

🌟 What Is This?

One framework — SDD — with skills it commands. This is not five equal tools; it’s a conductor (SDD) that calls skills when the work needs them, backed by enforcement gates that make the process non-optional.

🎼 The framework (conductor):

The skills SDD calls:

The Idea: Drop the package into your project. SDD assesses your context, runs its flow, and calls skills as needed — while enforcement gates block anything that skips a step. It applies universally (new, legacy, or production); context only changes how strict the gates are. How much it helps still depends on your project — see Honest Limitations.

🪜 Tiered Adoption

Do not adopt everything at once. SDD always runs, but layering on all the skills plus a 7-step flow is a lot of overhead, and piling it on a small project contradicts the very “Simplicity First” principle this package promotes. Start at the lowest tier that fits, and climb only when you feel the need.

The AI interview recommends a tier based on context. You can always override it. SDD is the framework, so it is in every tier; Karpathy + grill-me (the lightest skills) sit in Tier 1 alongside it — you get most of the value early.

⚡ Quick Start

Steps to Symphony

0️⃣ Prerequisite: install spec-kit (needed by BOTH paths below)

# spec-kit provides the SDD core via the `specify` CLI + /speckit.* commands.
# This installs the `specify` CLI on your PATH (a global tool, not per-project) — it
# creates no project files. The per-project step (`specify init`, which creates
# `.specify/` in your project root) runs later in Step 3, driven by Claude Code.
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

Don’t have uv? See spec-kit’s README for install instructions.

1️⃣ Get the package — pick ONE

Option A — fastest (install.sh does the file placement)

# run inside your project (default target = current dir). Be in a git repo first so the
# pre-commit hook installs; otherwise the script prints how to add it and skips.
curl -sL https://raw.githubusercontent.com/hongdosan/hongdosan-spec-driven-orchestra/main/install.sh | bash -s -- --lang en
# Korean docs: --lang ko    |    other target: append a path

Beyond the 4 methodology docs (one language), this also places the local hooks and CI gate (R1/R2/R3; the package-internal R7 doc-sync is omitted as it is not portable). It does not install spec-kit or run specify init (see Step 0 and Step 3).

Option B — manual (clone & copy)

# Clone this repo somewhere OUTSIDE your project (you don't clone it into your project).
git clone https://github.com/hongdosan/hongdosan-spec-driven-orchestra.git

# Copy the 4 methodology docs into your project.
SRC=hongdosan-spec-driven-orchestra/symphony
cp "$SRC"/AI-INTERVIEW.md        /path/to/your/project/
cp "$SRC"/AI-EXECUTION.md        /path/to/your/project/
cp "$SRC"/ORCHESTRA-GUIDE.md     /path/to/your/project/
cp "$SRC"/INTEGRATION-CHECKLIST.md /path/to/your/project/
cd /path/to/your/project/

Option B copies docs only. The gates (hooks + CI) are installed by Claude Code in Step 3 from this repo’s enforcement/ — so keep the clone around.

2️⃣ Git Safety Net (Recommended)

git checkout -b feat/spec-driven-orchestra
git add *.md
git commit -m "docs: add Spec-Driven Orchestra package"

3️⃣ Launch Claude Code

claude

Then tell it:

Read AI-INTERVIEW.md and start the integration process.
Assess the context, run `specify init`, install the enforcement gates, then proceed with SDD.

That’s it. Claude Code assesses your project, runs specify init (spec-kit) and installs the gates, then drives the /speckit.* flow.

🎯 Who Is This For?

Any project, at any stage. SDD assesses context and adapts: the same flow applies whether you’re starting fresh or fixing a deployed service; only the strictness of the enforcement gates changes.

💡 Production is not blocked. Detecting production signals raises the enforcement level so the existing gates become non-bypassable. Universal application, with safety scaled to risk. Legacy is supported but not prioritized over other contexts.

🎼 The Symphony

The 7-Step SDD Flow (Standard)

1. Specify    🎼  What & Why
   ↓
2. Clarify    🎹  Remove ambiguity (grill-me)
   ↓
3. Plan       🎼  How (tech selection)
   ↓
4. Tasks      🎼  Break down (30min-2h units)
   ↓
5. Verify     🎼  Design verification (SDD-owned)
   ↓
6. Implement  🎻  Karpathy's 4 Principles
   ↓
7. Handoff    🎺  Context preservation

When Existing Code Is Present (added steps)

0. Survey      🎼  Analyze existing code      ← only if existing code
1-5. [Standard]
5b. Regression 🎼  Preserve existing behavior ← only if existing code
6. Implement   🎻  Karpathy (+ migration if replacing behavior)
7. Handoff

Work Classification

🎭 How It Works

┌────────────────────────────────────────────────────┐
│                                                    │
│  You: "Read AI-INTERVIEW.md and start"             │
│                                                    │
│           ↓                                        │
│                                                    │
│  AI: Auto-scan (10-30 sec)                         │
│      Directory, code, Git, production signals      │
│                                                    │
│           ↓                                        │
│                                                    │
│  AI: Interview (5-10 min)                          │
│      5-7 questions with AI-recommended answers     │
│                                                    │
│           ↓                                        │
│                                                    │
│  AI: Assessment + Single Approval                  │
│      enforcement level (standard/strict) + survey  │
│                                                    │
│           ↓                                        │
│                                                    │
│  AI: Autonomous Execution (10-30 min)              │
│      one SDD flow, gates installed, fully automatic│
│                                                    │
│           ↓                                        │
│                                                    │
│  You: Verification (Day 0/7/30 checklists)         │
│                                                    │
└────────────────────────────────────────────────────┘

📦 Package Contents

hongdosan-spec-driven-orchestra/
├── README.md                    # This file (English)
├── README.ko.md                 # Korean version
├── LICENSE                      # MIT
│
└── symphony/                    # The methodology package (English default + Korean .ko.md)
    ├── README.md                # Package overview
    ├── AI-INTERVIEW.md          # 🎤 Interview entry point
    ├── AI-EXECUTION.md          # 🛠️ Single SDD execution flow
    ├── ORCHESTRA-GUIDE.md       # 🎼 5-instrument guide
    ├── INTEGRATION-CHECKLIST.md # ✅ Verification checklists
    └── *.ko.md                  # Korean counterpart of each file above

File Purposes

Bilingual: every symphony/*.md is English by default and has a Korean counterpart *.ko.md. To work in Korean, copy the .ko.md files renaming them to .md (so Claude Code recognizes the entry filename). Korean users can also start from README.ko.md.

🎵 What Gets Generated

Common Assets

your-project/
├── CLAUDE.md                    # AI entry point (auto-loaded)
├── DECISION-LOG.md              # All decisions tracked
├── INTEGRATION-REPORT.md        # Integration result
├── INTERVIEW-RESULT.md          # Interview record
│
├── .claude/skills/              # 3 skills generated by this package
│   ├── grill-me/                # 🎹 Clarification
│   ├── sdd-conductor/           # 🎼 Conductor
│   └── handoff/          # 🎺 Handoff writer
│                                # External plugins (/plugin): 🎻 karpathy-guidelines, 🎸 Harness
│
├── .specify/                    # 🎼 spec-kit (created by `specify init`)
│   ├── memory/constitution.md   # R1–R7 rules (gates read this) + project principles
│   └── templates/               # spec-kit's spec/plan/tasks/checklist templates
│
└── specs/<NNN-slug>/            # feature work, per git branch (via /speckit.*)
    ├── spec.md  plan.md  tasks.md          # spec-kit outputs
    └── survey.md  regression.md            # this package's additions
        handoff.md  implementation-notes.md

.claude/hooks/                   # ⛔ Enforcement (installed from enforcement/)
├── pre-implement.sh             # blocks code without spec+plan (R1,R2)
└── post-task.sh                 # warns on missing handoff (R5)
.git/hooks/pre-commit            # blocks commit without passing tests (R3,R4,R6)
.github/workflows/sdd-gate.yml   # non-bypassable merge gate (R1,R3,R6,R7)

Context Additions

The same flow adapts to what it finds — no MODE_* branching:

• Existing code present → a survey.md precedes Specify; regression.md is required before commit (R4).
• Production signals detected → ENFORCEMENT_LEVEL=strict; tests & regression become non-bypassable (R6).
• Greenfield → same flow and gates, but nothing to preserve, so they pass easily.

SDD reads the context and adjusts strictness automatically.

🌟 Key Features

⛔ Enforced, Not Advised

• Spec/plan missing → implement blocked (R1, R2)
• Tests not passing → commit blocked (R3)
• Existing behavior at risk → regression required (R4)
• Production context → gates non-bypassable (R6)
• Docs out of sync → merge blocked (R7)

Precondition for “non-bypassable”. Local hooks can be skipped (git commit --no-verify). The CI gate is the real backstop — but only if you enable required-PR branch protection on your default branch. Without that, enforcement is best-effort (local hooks + honesty), not guaranteed.

🔍 Interview-Based Adaptation

• 5-7 questions for context understanding
• Auto-scan assists AI’s recommendation
• Enforcement level set automatically

🛡️ Safety First

• Production → strict gates, not blocked (non-bypassable tests)
• Existing assets backed up to archive/
• Global settings (~/.claude/) untouched
• Easy Git rollback

📝 Traceability

• Auto-generated DECISION-LOG.md
• Decision Log section in every document
• Interview results preserved

🎼 Harmonious Integration

• SDD as conductor
• Clear role for each instrument
• Tool conflicts prevented

📚 Built On

This package integrates 5 instruments — all repo-backed open-source pieces (across 4 repositories). Their maturity varies — shown qualitatively below so you can judge each for yourself (check the live star counts on each repo, as they change over time):

🎸 Why a 5th Instrument?

Four of the instruments help a single agent work better (spec & verify, clarify, quality, handoff). Harness is different in kind: it helps split one big task across a team of agents. That difference is exactly why it is the optional 5th, gated behind Tier 3 and a single condition:

Bring in Harness only when a task is genuinely too large for one agent — e.g. work that splits into clear specialties (frontend / backend / QA), or a large research-and-build effort.

Honesty about it: Harness is not generated by this package (it’s an external plugin, revfactory/harness), it is the newest of the six and relies on an experimental Claude Code feature (AGENT_TEAMS=1). For most projects you will never need it, and the orchestra works fine as a “quintet + optional guest”. It’s included because agent-team design is a real, actively-adopted approach that maps cleanly onto SDD’s task-breakdown step — but it earns its place only when the work demands it.

⚖️ Honest Limitations

A fair README states where it might not help:

• Unproven in combination. Each tool is individually credible, but the claim that combining all 5 produces compounding benefit is a hypothesis, not a measured result. No usage data is published yet.
• Two skill installs are path-pinned to main. grill-me and handoff are fetched via curl from a fixed path on mattpocock/skills’ main branch (that repo documents no plugin). If the upstream renames or moves the file, the install breaks until the path is updated. (spec-kit uses its own CLI; karpathy-guidelines and harness install via /plugin — none of these are affected.) Hardening the two curl installs — pin to a commit SHA — is deferred for now; treat a failed skill install as “upstream path changed.”
• Overhead is real. The full flow can slow down small or trivial work. This is why Tiered Adoption exists — using everything everywhere would violate the Karpathy “Simplicity First” principle the package itself preaches.
• Agent compliance isn’t guaranteed. Claude Code may skip steps, fill templates without substance, or drift from CONSTITUTION.md over long sessions. The skills nudge it, but an LLM’s probabilistic nature means 100% adherence is impossible.
• Tool frictions exist. The pieces can pull against each other — e.g. grill-me’s relentless questioning vs a “move fast” priority. When they conflict, prefer the lower tier and the user’s explicit intent.
• spec-kit’s behavior is assumed, not tested here. This package invokes specify init and /speckit.* and relies on them producing spec.md/plan.md/tasks.md; it ships no test that the upstream flow actually works, and pins skill installs to upstream main (see the deferred fragility note). Track upstream versions yourself.
• Production raises overhead, not a free pass. Production projects are not blocked, but the gates become strict (non-bypassable tests + regression), which adds friction. The package reduces process risk; it cannot reduce the inherent risk of changing a live service.

If any of these outweigh the benefit for you, use only Tier 1, or skip the package entirely. That’s a valid outcome.

❓ FAQ

# Git rollback
git reset --hard HEAD~1

# Or restore from archive (if applicable)
cp -r archive/legacy/* ./
rm -rf .claude/skills/

🛣️ Roadmap

Recently Shipped (v2)

• ✅ Context-based dynamic assessment
• ✅ Enforcement gates (R1–R7)
• ✅ Universal application (new/legacy/production)
• ✅ 4 skills under SDD
• ✅ Archive backup strategy
• ✅ Bilingual documentation (English + Korean)

In Progress

• 🚧 Case study collection
• 🚧 Cursor adaptation guide
• 🚧 Cline adaptation guide

Planned

• 📋 Additional language docs (Chinese, Japanese)
• 📋 Video tutorial
• 📋 More enforcement gate templates (per-language test runners)
• 📋 Quantitative effectiveness metrics
• 📋 Team adoption playbook

Future

• 🌟 Web-based interview tool
• 🌟 Methodology benchmark dashboard
• 🌟 Community case studies

🤝 Contribute

Contributions of all kinds are welcome!

High-Impact Contributions

1. Case studies — Apply Spec-Driven Orchestra to your project and share results
2. Curated resources — Submit PR with related tools/methods
3. Adaptations — Cursor/Cline/Aider guides
4. Translations — Help non-English speakers
5. Tutorials — Help newcomers

How to Contribute

1. Open an Issue to discuss
2. Fork this repository
3. Create a feature branch (git checkout -b feat/your-feature)
4. Commit your changes
5. Push to your branch
6. Open a Pull Request

Guidelines

• Be kind and constructive
• Test before submitting
• Document your changes
• Follow existing style

📜 License

MIT License - see LICENSE file.

TL;DR: Use it freely. Modify it. Share it. Just keep the copyright notice.

🙏 Acknowledgments

This project stands on the shoulders of giants:

• Andrej Karpathy (@karpathy) for the observations on LLM coding pitfalls that inspired the principles
• multica-ai (@jiayuan_jy) for the 4-principle formulation derived from those observations
• GitHub Spec Kit team
• Matt Pocock (@mpocock1) for grill-me
• Anthropic (@AnthropicAI) for Claude Code
• The entire AI coding community

Special thanks to early adopters who provide feedback.

🌟 Star History

📬 Connect

• 💬 Discussions — Q&A, ideas
• 🐛 Issues — Bugs, requests
• 👤 Creator: @hongdosan

🎯 If This Helps You

⭐ Star this repo if it helped you in any way! 🍴 Fork it to customize for your team 📢 Share it with fellow developers 💡 Contribute to make it better

Together, we’re orchestrating the future of AI-powered coding.

Created with 🎼 by @hongdosan

_{If you find this useful, please ⭐ star it!}