https://github.com/fmachucas/agent-dev-studios
Spec-driven multi-agent framework for Claude Code — turns one AI session into a 38-agent engineering team. Idea → ship.
https://github.com/fmachucas/agent-dev-studios
agentic-ai ai-agents anthropic claude claude-code developer-tools llm multi-agent sdlc software-engineering spec-driven-development
Last synced: 11 days ago
JSON representation
Spec-driven multi-agent framework for Claude Code — turns one AI session into a 38-agent engineering team. Idea → ship.
- Host: GitHub
- URL: https://github.com/fmachucas/agent-dev-studios
- Owner: fmachucas
- License: mit
- Created: 2026-05-07T22:23:43.000Z (27 days ago)
- Default Branch: main
- Last Pushed: 2026-05-22T19:40:39.000Z (12 days ago)
- Last Synced: 2026-05-22T22:30:07.582Z (12 days ago)
- Topics: agentic-ai, ai-agents, anthropic, claude, claude-code, developer-tools, llm, multi-agent, sdlc, software-engineering, spec-driven-development
- Language: Shell
- Size: 951 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Roadmap: ROADMAP.md
Awesome Lists containing this project
README
# Agent Dev Studios
**Spec-driven, agent-orchestrated.** Turn a single AI coding session into a structured product engineering team.
**38 agents · 49 skills · 13 hooks · 13 rules · 23 templates**
[](LICENSE)
[](.claude/agents)
[](.claude/skills)
[](.claude/hooks)
[](.claude/rules)
[](https://docs.anthropic.com/en/docs/claude-code)
[](https://ko-fi.com/felipemachucasanjuan)
---
## Why This Exists
A single AI session has no structure. Nothing stops you from skipping design
docs, hardcoding config, shipping without tests, or making cross-cutting
changes without coordination. There's no architecture review, no security
pass, no one asking *"have you thought about how this fails?"*
**Agent Dev Studios** gives your AI session the structure of a real engineering
org. Directors guard the technical and product vision. Leads own their domains.
Specialists do the hands-on work. Each agent has defined responsibilities,
escalation paths, and quality gates — and you stay in control of every decision.
It also fixes the **memory problem**. AI context windows reset. Plans get
forgotten halfway through. With this framework, every spec, decision, and
piece of working state lives on disk in predictable files, so any new session
can pick up exactly where the last one left off.
The methodology is **spec-driven development** — vision, PRDs, design docs,
and ADRs are written, validated, and approved *before* code. The flow
(`/vision` → `/prd` → `/architect` → `/scaffold` → `/proceed`) enforces it,
and `/validate` blocks advancement when a spec is missing required sections.
Specs are the spine; agents are the muscles.
> **Who this is for:** developers and teams using Claude Code who want
> production discipline (specs, reviews, audits, persistent memory) instead
> of one-shot vibes. Stack-agnostic for discovery and spec work; defaults
> tuned for NestJS + Next.js + Postgres but every dial is swappable.
---
## See it in action
```text
> /start
Where are you?
1. No idea — just exploring
2. Vague concept — I know roughly what I want to build
3. Clear design — I know the shape, ready to scaffold
4. Existing repo — code exists, want the framework
> 2
Routing to /vision → /prd. Ready when you are.
> /prd "Add invoice creation flow"
Drafting PRD with product-manager. Asking 4 clarifying questions
before writing anything. Ready for your review when finished.
> /proceed
Phase 1 (load context) ✓
Phase 2 (research) ✓ — findings written to .studio/features/.../findings.md
Phase 3 (implementation plan, solution-architect, plan mode)
⏸ awaiting your sign-off before code starts
```
Every step has a named agent owner. Every artifact is reviewable before
the next phase starts. Nothing ships without your approval.
---
## Quick start (60 seconds)
In your project root:
```bash
git clone https://github.com/fmachucas/agent-dev-studios.git /tmp/ads
cp -r /tmp/ads/.claude . && cp /tmp/ads/CLAUDE.md /tmp/ads/ETHOS.md .
chmod +x .claude/hooks/*.sh && rm -rf /tmp/ads
```
Open Claude Code, type `/start`, and follow the prompts. For the full
walkthrough (gitignore patterns, profile selection, recovery), jump to
[Getting Started](#getting-started).
---
## What's Included
| Category | Count | Purpose |
| ---------- | ----- | ------- |
| Agents | 38 | Directors, leads, and specialists across all engineering domains (31 core + 7 stack-pack) |
| Skills | 49 | Slash commands organised by SDLC phase: discovery → release |
| Hooks | 13 | Automated validation on commits, pushes, sessions, and tool use |
| Rules | 13 | Path-scoped standards enforced when editing API, services, infra… |
| Templates | 23 | Document scaffolds for PRDs, ADRs, design docs, plans, etc. |
| References | 16 | Deep-dive material loaded by skills only when relevant |
---
## Studio Hierarchy
**31 generic agents + 7 stack-pack specialists across 3 tiers**:
- **Tier 1 — Directors** (3, Opus): `product-director`, `engineering-director`, `delivery-manager`
- **Tier 2 — Department leads** (8): `product-manager`, `tech-lead` (Opus), `backend-lead`, `frontend-lead`, `data-lead`, `design-lead`, `qa-lead`, `security-lead`
- **Tier 3 — Specialists** (20): split across product, engineering, design, QA, security, writing — `solution-architect` and `appsec-engineer` are Opus despite the tier (depth of judgment)
See [`.claude/docs/agent-roster.md`](.claude/docs/agent-roster.md) for each
agent's model, parent, and domain.
### Stack Specialists
The framework ships with one stack pre-configured. Use the agents that match,
or follow [CONTRIBUTING.md → How to add a stack pack](CONTRIBUTING.md#how-to-add-a-stack-pack) to add your own:
All stack-pack agents are tier `specialist`; both columns name specialists with different focus areas (architecture vs. day-to-day implementation).
| Stack | Architect / Operator | Developer |
| ----- | -------------------- | --------- |
| **NestJS** | `nestjs-architect` | `nestjs-developer` |
| **Next.js** | `nextjs-architect` | `nextjs-developer` |
| **PostgreSQL** | `postgres-dba` | `postgres-developer` |
---
## Slash Commands
Type `/` in your AI tool to access the 49 skills:
**Discovery & Spec**
- `/start` — entry point; routes by project stage (auto-invokes `/configure` on first run)
- `/brainstorm` — open exploration when you don't know what you're building yet
- `/vision` — draft or update `docs/vision.md`
- `/research` — sourced findings on a specific question
- `/team-discovery` — multi-agent kickoff for a new product or direction
- `/prd` — product requirements document
- `/breakdown` — PRD → epics → stories
- `/roadmap` — maintain `docs/roadmap.md`
**Setup & Configuration**
- `/configure` — reconfigure `.studio/config.json` (profile, stack, hooks, models)
- `/scaffold` — bootstrap an empty repo into the framework's project layout
- `/profile` — switch the active profile (`full` / `slim` / `express`)
**Design**
- `/architect` — system-level design for a feature or new system
- `/adr` — architecture decision record (hard-to-reverse choice)
- `/design-api` — API surface design
- `/design-db` — DB schema and migration plan
- `/design-ux` — user flows and interaction patterns
- `/design-doc` — feature design document
**Build**
- `/make-plan` — write the feature's `plan.md` (or sprint plan)
- `/proceed` — run a feature end-to-end through the standard pipeline
- `/sprint` — run multiple features in parallel with capped parallelism
- `/bugfix` — focused bug-fix flow (lighter than `/proceed`)
- `/tech-debt` — triage accumulated should-fix and audit-deferred items; scope a batch as a feature
- `/scope-check` — detect scope drift mid-feature; surface as Extend / Cut / Escalate
**Quality**
- `/reflect` — self-review pass before `/impl-review`
- `/impl-review` — multi-agent code review
- `/validate` — quality gate between phases (doc completeness, cross-links, scope drift)
**Reviews** (structured multi-agent gates with `APPROVE/CONCERNS/REJECT` verdicts; see [`.claude/docs/agent-gates.md`](.claude/docs/agent-gates.md))
- `/vision-review` — retroactive `PD-VISION` sign-off on a vision doc
- `/prd-review` — retroactive `PD-PRD` sign-off on a PRD
- `/story-review` — retroactive `PM-STORY-READY` sign-off on user stories
- `/product-review` — product-stage umbrella; cross-consistency between PRD and breakdown
- `/architecture-review` — system design review (`ED-ARCHITECTURE` + `TL-DESIGN-REVIEW` + conditional security gates)
- `/api-review` — API spec review (`BL-API-REVIEW` + `TL-API-DESIGN` + conditional appsec)
- `/db-review` — schema review (`DE-SCHEMA-REVIEW` + `TL-DB-DESIGN` + conditional data-sensitivity)
- `/ux-review` — UX flow review (`DL-UX-FLOW` + `AC-UX-REVIEW` + conditional research-coherence)
- `/design-review` — design-stage umbrella; cross-consistency across system / api / db / ux
**Release**
- `/release` — cut a release: version, tag, deploy (`ED-RELEASE-READINESS` + `QL-RELEASE-READINESS`)
- `/draft-release-notes` — user-facing release notes
- `/changelog` — maintain `CHANGELOG.md` from PR titles + commits
- `/wrapup` — finalize a feature, archive state, capture lessons
**Audits**
- `/audit-security` — security pass; OWASP walkthrough; logs to `docs/audits/security/`
- `/audit-perf` — performance audit; updates `docs/perf/budgets.md`
- `/audit-a11y` — accessibility audit against WCAG AA
- `/audit-seo` — SEO audit for public-facing routes (skip for internal-only projects)
**Project state**
- `/overview` — current state (active feature, phase, blockers, recent activity)
- `/catchup` — reload full context after a session reset
- `/map` — refresh `docs/INDEX.md` (map of all permanent specs)
- `/detect-stage` — analyze repo state (also runs as `/start` Phase 2)
- `/retro` — blameless retrospective on a sprint, feature, or incident
- `/template-drift` — detect drift between local templates and the framework
---
## The Flow
```
/start ──→ /configure (auto, first run) ──→ /detect-stage (auto, Phase 2)
↓
/vision → /validate → /prd → /validate
↓
/scaffold (if empty repo) ↓
↓
/architect → /design-api → /design-db → /design-ux
↓ ↓
/validate ← ← ← ← ← ← ← ← ← ← ←
↓
/proceed (single feature) /sprint (parallel features)
↓
/reflect → /impl-review → /audit-* → /wrapup
↓
/draft-release-notes → /release
```
`/validate` gates between phases. `/overview` and `/catchup` work at any point.
---
## Getting Started
The 10-minute guide to getting useful work done with Agent Dev Studios.
### Prerequisites
#### Required
**AI tooling**
- **Claude Code** (recommended) — runs the agents and hooks; or any tool with skills/agents support.
**Runtime**
- **Node.js 20+** — default-stack runtime and most tooling.
- **pnpm 9+** — workspace package manager.
- **Git 2.30+** — required by the framework's git hooks.
- **Bash 3.2+** — for hook scripts (macOS default works).
**For the default stack**
- **PostgreSQL 14+** — local for dev via Docker, Postgres.app, or brew.
#### Recommended
- **`jq`** — used by hooks to read `.studio/config.json`; falls back gracefully if missing.
- **Docker Desktop** — local Postgres, Testcontainers, ephemeral services.
- **`gh` (GitHub CLI)** — for some release-engineer flows.
- **`tmux`** or similar — multi-pane workflow with `/sprint`.
#### Operating systems
macOS 12+ and Linux (Ubuntu 22.04+, Debian 11+) are tested.
Windows works via WSL2; native Windows is unsupported (hooks are bash).
### 1. Drop the framework into your project
```bash
# In your project root
git clone https://github.com/fmachucas/agent-dev-studios.git /tmp/ads
cp -r /tmp/ads/.claude .
cp /tmp/ads/CLAUDE.md /tmp/ads/ETHOS.md .
chmod +x .claude/hooks/*.sh
# Merge the framework's gitignore patterns so per-user overrides and
# session-only state never land in your commits.
cat >> .gitignore <<'EOF'
# Agent Dev Studios — per-user overrides and session-only state
.claude/settings.local.json
.studio/state/log.jsonl
.studio/state/.lock
.studio/features/**/.lock
EOF
rm -rf /tmp/ads
```
That's it. Your project now has 38 agents, 49 skills, 13 hooks, 13 rules, and
23 templates available.
**Track `.claude/` and `.studio/` in git.** They're meant to be committed
to your project repo so the whole team shares the same agents, skills,
hooks, rules, and per-feature working state. The gitignore block above
excludes only what should stay local: per-user permission overrides
(`.claude/settings.local.json`), session-only state files
(`.studio/state/log.jsonl`, `.lock` files). Everything else is
shareable.
**To sync framework updates later**: re-run the install one-liner, run
`git diff` to see what changed, and commit the framework diff like any
other dependency upgrade.
Or just download the latest release zip and unzip the `.claude/` folder, plus
`CLAUDE.md` and `ETHOS.md`, into your project root. **After unzipping, run
`chmod +x .claude/hooks/*.sh`** — zip preservation of the executable bit is
unreliable across platforms — and append the gitignore patterns above.
### 2. Open Claude Code
```bash
cd /your/project
claude
```
The `SessionStart` hook will print a catchup summary. On a fresh project,
it prints a banner inviting you to run `/start` — that's expected.
### 3. First flow: `/start`
Type `/start` at the prompt. You'll be asked where you are:
```
Where are you?
1. No idea — just exploring
2. Vague concept — I know roughly what I want to build
3. Clear design — I know the shape, ready to scaffold
4. Existing repo — code already exists, want to add the framework
```
Pick the option that matches reality. The flow routes accordingly:
- **No idea** → `/brainstorm` → `/team-discovery`
- **Vague concept** → `/vision` → `/prd`
- **Clear design** → `/scaffold` then `/proceed`
- **Existing repo** → `/start` runs the `/detect-stage` checks for you, then routes to `/map` and `/catchup`
### 4. Pick a profile
Profiles are presets over a few orchestration dials. `/start` walks you
through the choice on first run via `/configure`; switch any time with
`/profile ` or by telling an agent.
| Profile | Use for | What changes |
| ------- | ------- | ------------ |
| `full` | Real product, customer-facing | Strict validation; multi-agent code review; audits when planned; reflection + attention hooks on |
| `slim` | Internal tools, MVPs | Lenient validation; single-agent code review; audits when planned; reflection + attention hooks on |
| `express` | Prototypes, hotfixes, `/bugfix` runs | Validation off; code review skipped; audits skipped; reflection + attention hooks off |
`full` is the default. Each dial is overrideable per-profile in
`.studio/config.json` if you want a non-standard combination —
see [`.claude/docs/templates/studio-config.example.json`](.claude/docs/templates/studio-config.example.json) for the schema.
### 5. Work a feature end-to-end
Say you're past `/start`. If you don't have a PRD yet, write one first:
```
> /prd "Add invoice creation flow"
```
Then build it:
```
> /proceed "Add invoice creation flow"
```
This runs the full pipeline for one feature:
```
spec → design → implement → reflect → impl-review → audits → wrapup
```
Validation gates between each phase. You approve at each gate.
For multiple features in parallel:
```
> /sprint
```
Pick which features to run in parallel. The framework caps parallelism (default 4)
and runs `/proceed` for each.
### 6. Recover from a context reset
```
> /catchup
```
Reads `.studio/state/current.md`, the active feature's `plan.md`, `findings.md`,
and `progress.md`, and gives you a catchup. You're back where you left off.
### 7. Check status anytime
```
> /overview
```
Shows: active feature, current phase, blockers, recent commits.
```
> /map
```
Shows: full project layout, all features (active + parked + complete), all
specs by area.
### Common scenarios
| Scenario | Use this |
| -------- | -------- |
| Existing repo, want the framework | `/start` (auto-runs `/detect-stage` Phase 2 → `/map` → `/catchup`) |
| **Add a new requirement to a working product** | `/prd "My feature"` → review + approve → `/proceed "My feature"`. That's it. `/proceed` picks up the PRD and runs the full pipeline: design → implement → review → ship. If the feature touches multiple surfaces, add `/architect` between prd and proceed. |
| **Validate a business idea, no code** | `/start` → "no idea / vague concept" → `/brainstorm` → `/team-discovery` → `/vision`. Stop there. The framework's discovery skills are stack-agnostic; you don't have to scaffold or build anything. Pick it back up months later. |
| Fix a bug fast | `/bugfix ""` in `express` profile (skips audits, no reflection) |
| Pre-release security pass | `/audit-security` (`security-lead` + `appsec-engineer` against the working branch) |
| Pre-release perf or A11y check | `/audit-perf` / `/audit-a11y` (logs to `docs/audits//.md`) |
| Start over | Delete `.claude/`, `CLAUDE.md`, `ETHOS.md`, `.studio/` — your code is untouched |
### What gets created on disk
After `/start` (which bootstraps `.studio/` via `/configure` on first run):
```
.studio/
config.json # Your overrides
state/
current.md # Where you are now
blockers.md # What's waiting on you
log.jsonl # Audit trail
features/
/
plan.md # Phases with checkboxes
findings.md # Research, decisions
progress.md # Session log, errors
knowledge/
assumptions/ # Cross-feature validated assumptions
lessons/ # Cross-feature lessons learned
agents/ # Per-agent persistent memory (owner agents only)
templates/ # Local copies (for /template-drift)
```
Commit the `.studio/` directory if you want collaborators to see history;
ignore `.studio/state/log.jsonl` (it's noisy).
### Troubleshooting
**Hooks aren't firing / "permission denied" on hook execution**
```bash
ls -la .claude/hooks/ # all .sh files should be executable
chmod +x .claude/hooks/*.sh
```
If `chmod` still doesn't help, your filesystem may not support the exec
bit (some Windows mounts). Run from WSL2 instead.
---
## Key Concepts
### Three-layer memory
| Layer | Where | Lifetime | Read by |
| ----- | ----- | -------- | ------- |
| **Specs & decisions** | `docs/` | Permanent | Humans + agents |
| **Working state** | `.studio/state/`, `.studio/features//` | Active features | Agents (auto-loaded) |
| **Cross-cutting knowledge** | `.studio/knowledge/{assumptions,lessons,agents}/` | Forever | Agents (referenced) |
Every agent reads relevant docs **before** proposing anything. Documentation
becomes runtime memory.
### The 3-file pattern (per active feature)
For each feature being worked on, three files live in `.studio/features//`:
- **`plan.md`** — Phases and checkpoints with checkboxes
- **`findings.md`** — Research and validated decisions
- **`progress.md`** — Session log, test results, errors
This is the [Manus pattern](https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus):
*Context window = RAM. Filesystem = disk. Anything important goes to disk.*
---
## Customization
Everything is configurable via `.studio/config.json`. Override any default:
```json
{
"profile": "full",
"stack": {
"backend": "nestjs",
"frontend": "nextjs",
"database": "postgres",
"package_manager": "pnpm"
},
"models": {
"tech-lead": "opus",
"code-reviewer": "sonnet"
},
"agents": {
"disabled": ["ai-engineer"]
},
"hooks": {
"validate-spec": true,
"post-tool-use": false
}
}
```
Defaults live in `.claude/settings.json`. Effective config = settings ⊕ overrides.
On first `/start`, the framework auto-invokes `/configure` to walk you through
the key choices and write the file. Run `/configure` directly later to
reconfigure.
---
## Scope
**What's in:** idea → release. Discovery, spec, design, build, audits, ship.
**What's out (for now):** the **operate** phase — runbooks, on-call, postmortems,
hotfixes, rollbacks, incident response. See [ROADMAP.md](ROADMAP.md).
**What's pinned (v1):** NestJS · Next.js · PostgreSQL · pnpm. The framework's
defaults match this stack today; that's a deliberate constraint to keep the
opinions sharp.
---
## Extensibility
The framework is a **template**, not a locked system. Three extension points:
1. **Stack packs** — add a stack under `.claude/agents/stacks//`
2. **Custom skills** — drop new skills into `.claude/skills//`
3. **Custom agents** — add specialists alongside the existing ones
See [CONTRIBUTING.md → How to add a stack pack](CONTRIBUTING.md#how-to-add-a-stack-pack) for the full guide.
---
## Foundations
Four ideas shape this framework. None are original — they come from teams
building with AI assistants who discovered patterns that work. The framework's
job is to make these ideas concrete and composable.
### 1. Specialized roles beat a generalist
A single AI session has no organizational structure. It can be asked to play
any role, but it has no consistent identity, no defined responsibilities, no
escalation path when work crosses a boundary it shouldn't. A real engineering
team has directors who own vision, leads who own domains, specialists who own
focused execution — and the friction between them is what catches mistakes.
This framework treats an AI session like an org chart. Each agent has a single
job, a parent it reports to, and named anti-patterns it watches for. When a
backend agent and a frontend agent disagree about an API contract, they
escalate to their tech lead. When the security lead and the product manager
conflict over scope, they go to a director. More friction. More thoughtfulness.
### 2. Phases need rituals
Software development has phases — discovery, design, build, audit, release —
and each phase produces a discrete output the next phase depends on. Skipping
or rushing a phase usually means re-doing it later under worse conditions.
Skills are named after the *actions* that mark these transitions: `/vision`,
`/architect`, `/impl-review`, `/release`. Verbs, not nouns. Each skill ends in a
validation step before the next phase can begin. The friction is intentional —
it forces "is this actually ready?" before moving on.
### 3. Filesystem is memory
AI context windows are volatile. They reset between sessions, get compacted
under pressure, get distracted by the most recent message. A filesystem doesn't.
Every spec, decision, finding, and progress note in this framework lives on
disk in predictable files. The 3-file pattern for active features (`plan.md`,
`findings.md`, `progress.md`) means any new session can read exactly where the
last one left off. Documentation isn't an afterthought of the work — it *is*
the work's persistent memory.
### 4. Concreteness beats principle
"Write good code" is true and useless. "Don't put business logic in
controllers" is specific and actionable. Every agent prompt includes a named
**Anti-patterns to avoid** section. Heavy topics — auth strategies, indexing,
REST vs GraphQL — get dedicated reference files that load only when relevant.
Behavior changes when prohibitions are named. Vague principles don't change
behavior; they just make people feel righteous about ignoring them.
---
## Project Structure
```
CLAUDE.md # Master config
ETHOS.md # Principles
ROADMAP.md # What's next
README.md # You are here
.claude/
settings.json # Hooks, permissions, defaults
agents/ # 31 generic + 7 stack-pack specialists
skills/ # 49 slash commands
hooks/ # 13 hook scripts + 1 helper in lib/
rules/ # 13 path-scoped standards
docs/
agent-roster.md # Per-agent tier / model / parent
agent-coordination-map.md # Delegation, escalation, worked patterns
agent-memory.md # Per-agent persistent-memory pattern
safety.md # Security policy (@-imported by CLAUDE.md)
templates/ # 23 templates (20 doc + 1 config + 2 editor)
.studio/ # Bootstrapped on first /start
config.json # Project overrides
state/ # Working memory
features/ # 3-file pattern per feature
knowledge/ # Validated assumptions, lessons, per-agent memory
templates/ # Local copies (for /template-drift)
# After /scaffold:
apps/api/ # NestJS — owns Prisma schema + migrations in v1
apps/web/ # Next.js
packages/ # Shared libs
infra/ # IaC
docs/ # Permanent specs
tests/ # Test suites
```
---
## Acknowledgments
Prior art that influenced specific mechanics:
- [Claude Code Game Studios](https://github.com/Donchitos/Claude-Code-Game-Studios) — the studio hierarchy and orchestration model
- [ADLC Toolkit](https://github.com/atelier-fashion/adlc-toolkit) — verb-named skills, validation gates, the `/proceed` and `/wrapup` pattern
- [Planning with Files](https://github.com/OthmanAdi/planning-with-files) — the 3-file Manus pattern for persistent memory
- [Impeccable](https://github.com/pbakaus/impeccable) — reference files inside skills, named anti-patterns
---
## Support
This is free, MIT-licensed, and built in spare time. If it's saved you hours
of arguing with an AI assistant, you can throw a coffee at it on Ko-fi.
[](https://ko-fi.com/felipemachucasanjuan)
---
## Community
- **Issues** — bug reports and feature requests on this repo
- **Discussions** — questions, ideas, showcasing what you've built
---
## License
MIT. See [LICENSE](LICENSE).