{
  "markdown": "# Orchestra\n\n> Disciplined AI engineering toolkit. Many skills playing together. One conductor.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-Plugin-orange.svg)](https://docs.claude.com/en/docs/claude-code/plugins)\n\nBy [Hassan Mohiddin](https://github.com/hassan-mohiddin) — founder/CEO of SCALE.\n\n---\n\n## What is Orchestra\n\nOrchestra is a Claude Code plugin that ships a curated set of skills for **doc-driven, gate-enforced AI engineering**. Each skill encodes an industry-grade pattern; together they form a workflow that prevents the most common failure modes of agent-led code change (orphan fix-commits, design drift, doc rot, undisciplined multi-attempt bug fixes).\n\nThe metaphor: an orchestra has many instruments, but they all play to the same score. Each Orchestra skill plays its part in a unified discipline.\n\n## What ships in v1.0\n\n**🎼 design-docs** — typed documentation discipline (the first instrument)\n\nTriggers when a feature, bug, architectural decision, incident, runbook, or component architecture needs writing up before code is written.\n\n- **7 typed doc templates** — Feature LLD, Bug Report, ADR, Postmortem, Runbook, Design Doc (living), short-form ADR. Every template has industry-canonical sections.\n- **2 cross-tool AI standards** — `AGENTS.md` (Linux Foundation Agentic AI Foundation, 60k+ projects) at repo root, `llms.txt` (Jeremy Howard / Answer.AI) for external LLMs.\n- **4-gate spec review** — Completeness / Evidence / Clarity / Consistency. Failures named, not vague.\n- **Auto-numbering** — `next_doc_number.sh` returns `003`, `BUG-014`, `ADR-007`, `POSTMORTEM-2026-05-06`. Bash octal-safe.\n- **Mandatory mermaid diagrams** — sequence (LLD/Bug/Postmortem), activity (workflows), architecture (system), deployment (infra). 5 diagram-type guides + 28-error troubleshooting reference.\n- **Industry-aligned vocabulary** — ADR is RECORDED, not deliberated (Nygard 2011). Design Doc replaces deprecated HLD. RFC opt-in for team mode only.\n- **Bug iteration loop** — One BUG-NNN doc spans all fix attempts. `fix:` commit only after user confirms. No more orphan fix-commits.\n- **Doc gates** — Discovery / Design / Spec Review / Commit / Implementation Sync. Five named gates that block code from drifting from docs.\n- **Lint CLI** — `python -m cli.lint` validates `Refs:` line on `fix:` / `feat:` commits, doc metadata, status enums. Pre-commit + GitHub Action ready.\n- **Auto `DECISIONS.md` index** — `python -m cli.decisions_index` generates a searchable ADR index with relationship types (Supersedes / Superseded by / Related) + bidirectional consistency checking.\n\n## Roadmap — future instruments\n\nThe Orchestra umbrella will absorb additional skills over time. Planned:\n\n| Skill | Purpose | Status |\n|-------|---------|--------|\n| `orchestra:design-docs` | Typed docs + 4-gate review (this release) | ✅ v1.0 |\n| `orchestra:spec-review` | Multi-judge spec review (judge-1 default) — `/orchestra:spec-review <doc-path>` | ✅ v1.6 |\n| `orchestra:commit` | Commit-discipline (Refs: rules, canon-frozen tiered narrow-change, doc/code separation, supersession decision) — `/orchestra:commit` | ✅ v1.7 |\n| `orchestra:workflow` | Master workflow file with situation-language routing | 🟡 v2.0 |\n| `orchestra:skills-registry` | Situation → skill binding table + override rules | 🟡 v1.1 |\n| `orchestra:tasks` | Task-tracking discipline + cross-agent state | 🟡 v1.2 |\n| `orchestra:gates` | Pre-commit / CI gate enforcement (broader than docs) | 🟡 v1.2 |\n| `orchestra:plans` | Plan-as-source artifact with TDD vertical slicing | 🟡 v1.3 |\n\nSubscribe via repo watch for releases.\n\n---\n\n## Why another doc / orchestration plugin\n\n| Plugin | Doc types | Gates | Bug iteration | Mandatory mermaid | Multi-skill umbrella |\n|---|---|---|---|---|---|\n| **orchestra** (this) | **7** | **5 (Discovery / Design / Spec Review / Commit / Sync)** | ✅ One-doc-spans-attempts | ✅ Required for LLD/Bug/Postmortem | ✅ (v1.1+) |\n| Pimzino/claude-code-spec-workflow | 4 | 0 | ❌ | Optional | ❌ |\n| rvdbreemen/adr-kit | 1 (ADR) | 4 | n/a | ❌ | ❌ |\n| anthropics/skills doc-coauthoring | Generic | 0 | ❌ | ❌ | ❌ |\n| obra/superpowers | n/a (process skills) | n/a | n/a | n/a | ✅ |\n| mattpocock-skills | n/a (process skills) | n/a | n/a | n/a | ✅ |\n\nNo competitor combines typed doc taxonomy + 5 gates + bug iteration loop + mandatory mermaid + multi-skill orchestration umbrella. Orchestra does.\n\n---\n\n## Install\n\n### Via plugin marketplace (recommended once approved)\n\n```bash\n/plugin marketplace add hassan-mohiddin/orchestra\n/plugin install orchestra\n```\n\n### Direct git install\n\n```bash\n/plugin install hassan-mohiddin/orchestra\n```\n\n### Local development\n\n```bash\ngit clone https://github.com/hassan-mohiddin/orchestra.git\nclaude --plugin-dir ./orchestra\n```\n\n---\n\n## Usage — design-docs skill\n\nTrigger by describing your situation. Description matches naturally:\n\n| You say | Skill produces |\n|---|---|\n| \"I want to add transaction search\" | Feature LLD at `docs/features/NNN-name.md` |\n| \"Found a bug — auth tokens leak on refresh\" | Bug Report at `docs/bugs/BUG-NNN-name.md` |\n| \"We've decided to migrate to Postgres\" | ADR at `docs/adr/ADR-NNN-name.md` |\n| \"Auth had a 23-min outage this morning\" | Postmortem at `docs/postmortems/POSTMORTEM-YYYY-MM-DD-name.md` |\n| \"Need a runbook for queue backlogs\" | Runbook at `docs/runbooks/RUNBOOK-name.md` |\n| \"Update the api-design doc — v2 endpoint shipped\" | Updates `docs/design/api-design.md` + Changelog |\n| \"Set up AGENTS.md so Cursor + Codex see context\" | `AGENTS.md` + symlink instructions |\n\nFor every produced doc, the skill walks you through:\n\n1. **Get doc number** — `bash skills/design-docs/scripts/next_doc_number.sh <type>` returns the next ID\n2. **Load template** — only the template you need (progressive disclosure)\n3. **Fill all sections** — no `TBD`, no placeholders\n4. **Add mermaid diagram** — sequence/activity/architecture/deployment per type\n5. **Run 4-gate spec review** — Completeness / Evidence / Clarity / Consistency\n6. **Commit doc before code** — `Refs:` line links every `fix:`/`feat:` to its doc\n\n---\n\n## Viewing diagrams\n\nOrchestra docs include mermaid diagrams in markdown code fences. Render them with:\n\n| Tool | Setup | Use case |\n|---|---|---|\n| **GitHub** | None — native render in markdown preview, PRs, issues, README | Reading docs in PR review or browsing repo on github.com |\n| **VS Code** | Install [\"Markdown Preview Mermaid Support\"](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid) extension | Local editing + preview side-by-side |\n| **JetBrains IDEs** | Install [Mermaid plugin](https://plugins.jetbrains.com/plugin/20146-mermaid) | Same — preview pane in IntelliJ/PyCharm/etc. |\n| **mermaid.live** | None — paste markdown into [mermaid.live](https://mermaid.live) | Ad-hoc editing, sharing renderable links |\n| **CLI offline** | `npx -y @mermaid-js/mermaid-cli -i doc.md` (no install needed; fetches per-invocation) | Air-gapped environments, batch export to PNG/SVG |\n| **`cli.viewer` (v1.2)** | `python -m cli.viewer render docs/path.md` (or `render-all`) | Orchestra-managed export to `docs/.rendered/`. Auto-appends `docs/.rendered/` to `.gitignore` on first run. `--format png\\|svg`, `--output <dir>`. |\n| **MkDocs site (v1.3 — Tier 3)** | `python -m cli.viewer install-mkdocs` → `pip install -r requirements-docs.txt` → `mkdocs serve` | Full doc browser at `http://localhost:8000`. Mermaid renders natively, full-text search, type/status filters, GitHub Pages publish via `python -m cli.viewer publish-gh-pages`. |\n\nMermaid validation is built into `python -m cli.lint --doc` and `--pre-commit` modes (default-on; opt out via `--no-mermaid`). Lint catches syntax errors at commit time so broken diagrams never land in main.\n\n**Note for repos using pre-commit (`.pre-commit-config.yaml`):** the shipped `mkdocs.yml` contains a YAML python-tag (`!!python/name:mermaid2.fence_mermaid_custom`) required by mkdocs-mermaid2-plugin. Strict `check-yaml` hooks reject python-tags without the `--unsafe` flag. After running `cli.viewer install-mkdocs`, add `args: [--unsafe]` to your `check-yaml` hook entry. See `cli/templates/precommit-yaml-patch.txt` (orchestra plugin) for the exact snippet (BUG-007).\n\n## Configuration\n\nEdit your project's `.claude/settings.local.json` or `.claude/settings.json`:\n\n```json\n{\n  \"orchestra\": {\n    \"mode\": \"solo\",\n    \"doc_paths\": {\n      \"features\": \"docs/features\",\n      \"bugs\": \"docs/bugs\",\n      \"adr\": \"docs/adr\",\n      \"design\": \"docs/design\",\n      \"postmortems\": \"docs/postmortems\",\n      \"runbooks\": \"docs/runbooks\",\n      \"plans\": \"docs/plans\"\n    },\n    \"spec_review_skill\": \"superpowers:requesting-code-review\"\n  }\n}\n```\n\n### `mode` — solo or team\n\n- **solo** (default) — Single decision-maker. RFC vocabulary suppressed. ADRs record decisions you've made. No reviewer-assignment workflow.\n- **team** — 2+ senior engineers (industry threshold per Pragmatic Engineer). RFC vocabulary enabled (deliberation phase before ADR). Spec review can assign reviewers. ADR `OKR Alignment` field becomes mandatory.\n\n### `doc_paths` — repo layout overrides\n\nDefault paths match the canonical layout. Override any path to point at your existing structure.\n\n### `spec_review_skill` — Step 4.5 binding\n\nThe skill that handles Step 4.5 spec review. Default points at `superpowers:requesting-code-review`. Set to your own project's review skill, or `null` to skip review (not recommended).\n\n---\n\n## CLI tools\n\n### `orchestra lint`\n\n```bash\npython -m cli.lint --commit HEAD                       # Lint a commit\npython -m cli.lint --range main..HEAD                  # Lint a commit range\npython -m cli.lint --doc docs/bugs/BUG-014-leak.md     # Lint a single doc\npython -m cli.lint --pre-commit                        # Pre-commit hook mode (L1+L2-detect+L3+L4)\npython -m cli.lint --commit-msg-finalize <msg-file>    # v1.7+ L2-finalize tiered narrow-change\npython -m cli.lint --pre-stage-check <doc> --commit-msg-draft \"<msg>\"  # Author pre-stage check\n```\n\n### `orchestra install-hooks` (v1.7+ framework-aware)\n\n```bash\npython -m cli.install_hooks --all                      # Raw hook install (.git/hooks/*)\npython -m cli.install_hooks --apply                    # Pre-commit framework: auto-merge into .pre-commit-config.yaml + transactional rollback\npython -m cli.install_hooks --verify                   # Hybrid verify (substring fingerprint + entrypoint pattern)\npython -m cli.install_hooks --force-raw                # Bypass framework detection; install raw hooks\n```\n\nFor pre-commit.com framework users: `--apply` deep-merges the orchestra entry, runs `pre-commit install --hook-type pre-commit --hook-type commit-msg`, verifies, and rolls back on failure.\n\nGitHub Action template ships at `.github/workflows/lint.yml`.\n\n### `orchestra decisions-index`\n\nAuto-generates `docs/adr/DECISIONS.md` — a searchable ADR index with relationship types and bidirectional supersession consistency checking.\n\n```bash\npython -m cli.decisions_index --adr-dir docs/adr/ --output docs/adr/DECISIONS.md\n```\n\n---\n\n## Examples\n\nSee `examples/` for filled-in samples (all lint-green):\n\n- `examples/bugs/BUG-001-checkout-double-charge.md`\n- `examples/adr/ADR-001-postgres-to-timescale.md`\n- `examples/postmortems/POSTMORTEM-2026-04-22-auth-token-expiry-boundary.md`\n\nMore examples (Feature LLD, Runbook, Design Doc, AGENTS.md) ship in v1.1.\n\n---\n\n## Industry alignment\n\nPatterns adopted from public sources:\n\n- **ADR format** — Michael Nygard, *Documenting Architecture Decisions* (Cognitect 2011)\n- **Postmortem template** — Google SRE Book, *Postmortem Culture: Learning from Failure*\n- **AGENTS.md spec** — [agents.md](https://agents.md/) (Linux Foundation Agentic AI Foundation, Dec 2025)\n- **llms.txt spec** — [llmstxt.org](https://llmstxt.org/) (Jeremy Howard / Answer.AI, Sept 2024)\n- **4-gate review** — [`rvdbreemen/adr-kit`](https://github.com/rvdbreemen/adr-kit) (Apr 2026)\n- **Conventional Commits** — [conventionalcommits.org/v1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)\n- **Mermaid C4** — Simon Brown's C4 model adapted for inline markdown rendering\n- **RFC vs ADR taxonomy** — *RFCs and Design Docs* (Pragmatic Engineer)\n\nSurveyed 16 competing plugins to inform positioning. See `docs/competitor-analysis.md` (ships in v1.1).\n\n---\n\n## Skill structure\n\n```\norchestra/\n├── .claude-plugin/plugin.json         # Plugin metadata + config defaults\n├── skills/\n│   └── design-docs/                   # First skill (more coming)\n│       ├── SKILL.md                   # Skill instructions + decision tree\n│       ├── STANDARDS.md               # Canonical doc-section requirements\n│       ├── templates/                 # 8 templates (Feature LLD, Bug, ADR, etc.)\n│       ├── references/                # Spec review gates, mermaid guides, etc.\n│       └── scripts/                   # next_doc_number.sh + diagram tooling\n├── cli/\n│   ├── lint.py                        # Refs: gate + metadata + status validator\n│   └── decisions_index.py             # Auto DECISIONS.md generator\n├── examples/                          # Filled-in lint-green sample docs\n├── hooks/hooks.json                   # Hook stubs for project customization\n├── .github/workflows/lint.yml         # CI lint workflow template\n├── README.md                          # This file\n├── LICENSE                            # MIT\n├── CHANGELOG.md\n└── CONTRIBUTING.md\n```\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). PRs welcome — especially:\n\n- New doc-type templates with industry citations\n- Additional mermaid diagram types\n- Lint CLI improvements\n- Config conveniences for non-default repo layouts\n- Future Orchestra skills (workflow, registry, tasks, etc.)\n\n---\n\n## Acknowledgements\n\n- Patterns from Michael Nygard, Google SRE, Pragmatic Engineer's *RFCs and Design Docs*, Bruno Scheufler, Martin Fowler's *Architecture Decision Record* bliki\n- Plugin structure inspired by [`obra/superpowers`](https://github.com/obra/superpowers) and `mattpocock-skills`\n- 4-gate review naming adapted from [`rvdbreemen/adr-kit`](https://github.com/rvdbreemen/adr-kit)\n- Mermaid troubleshooting reference adapted from [`SpillwaveSolutions/design-doc-mermaid`](https://github.com/SpillwaveSolutions/design-doc-mermaid)\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE). Created and maintained by [Hassan Mohiddin](https://github.com/hassan-mohiddin).\n",
  "bytes": 14491,
  "sha": "ef418921c28e6012bbe4245a1bf545186c426bd4866fc55648a0b68a252a696f",
  "repo_slug": "hassan-mohiddin/orchestra",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_hassan_mohiddin_orchestra_orchestra_3ec5c4c5/readme"
}