{"id":50097894,"url":"https://github.com/fmachucas/agent-dev-studios","last_synced_at":"2026-05-23T05:13:41.799Z","repository":{"id":356702558,"uuid":"1232396348","full_name":"fmachucas/agent-dev-studios","owner":"fmachucas","description":"Spec-driven multi-agent framework for Claude Code — turns one AI session into a 38-agent engineering team. Idea → ship.","archived":false,"fork":false,"pushed_at":"2026-05-22T19:40:39.000Z","size":974,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T22:30:07.582Z","etag":null,"topics":["agentic-ai","ai-agents","anthropic","claude","claude-code","developer-tools","llm","multi-agent","sdlc","software-engineering","spec-driven-development"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fmachucas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-07T22:23:43.000Z","updated_at":"2026-05-22T19:40:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fmachucas/agent-dev-studios","commit_stats":null,"previous_names":["fmachucas/agent-dev-studios"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/fmachucas/agent-dev-studios","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmachucas%2Fagent-dev-studios","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmachucas%2Fagent-dev-studios/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmachucas%2Fagent-dev-studios/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmachucas%2Fagent-dev-studios/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fmachucas","download_url":"https://codeload.github.com/fmachucas/agent-dev-studios/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmachucas%2Fagent-dev-studios/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33383641,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T04:15:53.637Z","status":"ssl_error","status_checked_at":"2026-05-23T04:15:53.242Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","ai-agents","anthropic","claude","claude-code","developer-tools","llm","multi-agent","sdlc","software-engineering","spec-driven-development"],"created_at":"2026-05-23T05:13:40.980Z","updated_at":"2026-05-23T05:13:41.790Z","avatar_url":"https://github.com/fmachucas.png","language":"Shell","funding_links":["https://ko-fi.com/felipemachucasanjuan"],"categories":[],"sub_categories":[],"readme":"# Agent Dev Studios\n\n**Spec-driven, agent-orchestrated.** Turn a single AI coding session into a structured product engineering team.\n\n**38 agents · 49 skills · 13 hooks · 13 rules · 23 templates**\n\n[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![38 Agents](https://img.shields.io/badge/agents-38-blueviolet)](.claude/agents)\n[![49 Skills](https://img.shields.io/badge/skills-49-green)](.claude/skills)\n[![13 Hooks](https://img.shields.io/badge/hooks-13-orange)](.claude/hooks)\n[![13 Rules](https://img.shields.io/badge/rules-13-red)](.claude/rules)\n[![Built for Claude Code](https://img.shields.io/badge/built%20for-Claude%20Code-f5f5f5?logo=anthropic)](https://docs.anthropic.com/en/docs/claude-code)\n[![Ko-fi](https://img.shields.io/badge/Ko--fi-Support%20this%20project-FF5E5B?logo=kofi\u0026logoColor=white)](https://ko-fi.com/felipemachucasanjuan)\n\n---\n\n## Why This Exists\n\nA single AI session has no structure. Nothing stops you from skipping design\ndocs, hardcoding config, shipping without tests, or making cross-cutting\nchanges without coordination. There's no architecture review, no security\npass, no one asking *\"have you thought about how this fails?\"*\n\n**Agent Dev Studios** gives your AI session the structure of a real engineering\norg. Directors guard the technical and product vision. Leads own their domains.\nSpecialists do the hands-on work. Each agent has defined responsibilities,\nescalation paths, and quality gates — and you stay in control of every decision.\n\nIt also fixes the **memory problem**. AI context windows reset. Plans get\nforgotten halfway through. With this framework, every spec, decision, and\npiece of working state lives on disk in predictable files, so any new session\ncan pick up exactly where the last one left off.\n\nThe methodology is **spec-driven development** — vision, PRDs, design docs,\nand ADRs are written, validated, and approved *before* code. The flow\n(`/vision` → `/prd` → `/architect` → `/scaffold` → `/proceed`) enforces it,\nand `/validate` blocks advancement when a spec is missing required sections.\nSpecs are the spine; agents are the muscles.\n\n\u003e **Who this is for:** developers and teams using Claude Code who want\n\u003e production discipline (specs, reviews, audits, persistent memory) instead\n\u003e of one-shot vibes. Stack-agnostic for discovery and spec work; defaults\n\u003e tuned for NestJS + Next.js + Postgres but every dial is swappable.\n\n---\n\n## See it in action\n\n```text\n\u003e /start\nWhere are you?\n  1. No idea — just exploring\n  2. Vague concept — I know roughly what I want to build\n  3. Clear design — I know the shape, ready to scaffold\n  4. Existing repo — code exists, want the framework\n\n\u003e 2\nRouting to /vision → /prd. Ready when you are.\n\n\u003e /prd \"Add invoice creation flow\"\nDrafting PRD with product-manager. Asking 4 clarifying questions\nbefore writing anything. Ready for your review when finished.\n\n\u003e /proceed\nPhase 1 (load context) ✓\nPhase 2 (research)     ✓ — findings written to .studio/features/.../findings.md\nPhase 3 (implementation plan, solution-architect, plan mode)\n                       ⏸  awaiting your sign-off before code starts\n```\n\nEvery step has a named agent owner. Every artifact is reviewable before\nthe next phase starts. Nothing ships without your approval.\n\n---\n\n## Quick start (60 seconds)\n\nIn your project root:\n\n```bash\ngit clone https://github.com/fmachucas/agent-dev-studios.git /tmp/ads\ncp -r /tmp/ads/.claude . \u0026\u0026 cp /tmp/ads/CLAUDE.md /tmp/ads/ETHOS.md .\nchmod +x .claude/hooks/*.sh \u0026\u0026 rm -rf /tmp/ads\n```\n\nOpen Claude Code, type `/start`, and follow the prompts. For the full\nwalkthrough (gitignore patterns, profile selection, recovery), jump to\n[Getting Started](#getting-started).\n\n---\n\n## What's Included\n\n| Category   | Count | Purpose |\n| ---------- | ----- | ------- |\n| Agents     | 38    | Directors, leads, and specialists across all engineering domains (31 core + 7 stack-pack) |\n| Skills     | 49    | Slash commands organised by SDLC phase: discovery → release |\n| Hooks      | 13    | Automated validation on commits, pushes, sessions, and tool use |\n| Rules      | 13    | Path-scoped standards enforced when editing API, services, infra… |\n| Templates  | 23    | Document scaffolds for PRDs, ADRs, design docs, plans, etc. |\n| References | 16    | Deep-dive material loaded by skills only when relevant |\n\n---\n\n## Studio Hierarchy\n\n**31 generic agents + 7 stack-pack specialists across 3 tiers**:\n\n- **Tier 1 — Directors** (3, Opus): `product-director`, `engineering-director`, `delivery-manager`\n- **Tier 2 — Department leads** (8): `product-manager`, `tech-lead` (Opus), `backend-lead`, `frontend-lead`, `data-lead`, `design-lead`, `qa-lead`, `security-lead`\n- **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)\n\nSee [`.claude/docs/agent-roster.md`](.claude/docs/agent-roster.md) for each\nagent's model, parent, and domain.\n\n### Stack Specialists\n\nThe framework ships with one stack pre-configured. Use the agents that match,\nor follow [CONTRIBUTING.md → How to add a stack pack](CONTRIBUTING.md#how-to-add-a-stack-pack) to add your own:\n\nAll stack-pack agents are tier `specialist`; both columns name specialists with different focus areas (architecture vs. day-to-day implementation).\n\n| Stack | Architect / Operator | Developer |\n| ----- | -------------------- | --------- |\n| **NestJS**      | `nestjs-architect`     | `nestjs-developer` |\n| **Next.js**     | `nextjs-architect`     | `nextjs-developer` |\n| **PostgreSQL**  | `postgres-dba`         | `postgres-developer` |\n\n---\n\n## Slash Commands\n\nType `/` in your AI tool to access the 49 skills:\n\n**Discovery \u0026 Spec**\n\n- `/start` — entry point; routes by project stage (auto-invokes `/configure` on first run)\n- `/brainstorm` — open exploration when you don't know what you're building yet\n- `/vision` — draft or update `docs/vision.md`\n- `/research` — sourced findings on a specific question\n- `/team-discovery` — multi-agent kickoff for a new product or direction\n- `/prd` — product requirements document\n- `/breakdown` — PRD → epics → stories\n- `/roadmap` — maintain `docs/roadmap.md`\n\n**Setup \u0026 Configuration**\n\n- `/configure` — reconfigure `.studio/config.json` (profile, stack, hooks, models)\n- `/scaffold` — bootstrap an empty repo into the framework's project layout\n- `/profile` — switch the active profile (`full` / `slim` / `express`)\n\n**Design**\n\n- `/architect` — system-level design for a feature or new system\n- `/adr` — architecture decision record (hard-to-reverse choice)\n- `/design-api` — API surface design\n- `/design-db` — DB schema and migration plan\n- `/design-ux` — user flows and interaction patterns\n- `/design-doc` — feature design document\n\n**Build**\n\n- `/make-plan` — write the feature's `plan.md` (or sprint plan)\n- `/proceed` — run a feature end-to-end through the standard pipeline\n- `/sprint` — run multiple features in parallel with capped parallelism\n- `/bugfix` — focused bug-fix flow (lighter than `/proceed`)\n- `/tech-debt` — triage accumulated should-fix and audit-deferred items; scope a batch as a feature\n- `/scope-check` — detect scope drift mid-feature; surface as Extend / Cut / Escalate\n\n**Quality**\n\n- `/reflect` — self-review pass before `/impl-review`\n- `/impl-review` — multi-agent code review\n- `/validate` — quality gate between phases (doc completeness, cross-links, scope drift)\n\n**Reviews** (structured multi-agent gates with `APPROVE/CONCERNS/REJECT` verdicts; see [`.claude/docs/agent-gates.md`](.claude/docs/agent-gates.md))\n\n- `/vision-review` — retroactive `PD-VISION` sign-off on a vision doc\n- `/prd-review` — retroactive `PD-PRD` sign-off on a PRD\n- `/story-review` — retroactive `PM-STORY-READY` sign-off on user stories\n- `/product-review` — product-stage umbrella; cross-consistency between PRD and breakdown\n- `/architecture-review` — system design review (`ED-ARCHITECTURE` + `TL-DESIGN-REVIEW` + conditional security gates)\n- `/api-review` — API spec review (`BL-API-REVIEW` + `TL-API-DESIGN` + conditional appsec)\n- `/db-review` — schema review (`DE-SCHEMA-REVIEW` + `TL-DB-DESIGN` + conditional data-sensitivity)\n- `/ux-review` — UX flow review (`DL-UX-FLOW` + `AC-UX-REVIEW` + conditional research-coherence)\n- `/design-review` — design-stage umbrella; cross-consistency across system / api / db / ux\n\n**Release**\n\n- `/release` — cut a release: version, tag, deploy (`ED-RELEASE-READINESS` + `QL-RELEASE-READINESS`)\n- `/draft-release-notes` — user-facing release notes\n- `/changelog` — maintain `CHANGELOG.md` from PR titles + commits\n- `/wrapup` — finalize a feature, archive state, capture lessons\n\n**Audits**\n\n- `/audit-security` — security pass; OWASP walkthrough; logs to `docs/audits/security/`\n- `/audit-perf` — performance audit; updates `docs/perf/budgets.md`\n- `/audit-a11y` — accessibility audit against WCAG AA\n- `/audit-seo` — SEO audit for public-facing routes (skip for internal-only projects)\n\n**Project state**\n\n- `/overview` — current state (active feature, phase, blockers, recent activity)\n- `/catchup` — reload full context after a session reset\n- `/map` — refresh `docs/INDEX.md` (map of all permanent specs)\n- `/detect-stage` — analyze repo state (also runs as `/start` Phase 2)\n- `/retro` — blameless retrospective on a sprint, feature, or incident\n- `/template-drift` — detect drift between local templates and the framework\n\n---\n\n## The Flow\n\n```\n   /start  ──→  /configure (auto, first run)  ──→  /detect-stage (auto, Phase 2)\n      ↓\n   /vision  →  /validate  →  /prd  →  /validate\n                                        ↓\n   /scaffold (if empty repo)            ↓\n                                        ↓\n   /architect  →  /design-api  →  /design-db  →  /design-ux\n      ↓                                        ↓\n   /validate  ←  ←  ←  ←  ←  ←  ←  ←  ←  ←  ←\n                                        ↓\n   /proceed (single feature)  /sprint (parallel features)\n      ↓\n   /reflect  →  /impl-review  →  /audit-*  →  /wrapup\n      ↓\n   /draft-release-notes  →  /release\n```\n\n`/validate` gates between phases. `/overview` and `/catchup` work at any point.\n\n---\n\n## Getting Started\n\nThe 10-minute guide to getting useful work done with Agent Dev Studios.\n\n### Prerequisites\n\n#### Required\n\n**AI tooling**\n\n- **Claude Code** (recommended) — runs the agents and hooks; or any tool with skills/agents support.\n\n**Runtime**\n\n- **Node.js 20+** — default-stack runtime and most tooling.\n- **pnpm 9+** — workspace package manager.\n- **Git 2.30+** — required by the framework's git hooks.\n- **Bash 3.2+** — for hook scripts (macOS default works).\n\n**For the default stack**\n\n- **PostgreSQL 14+** — local for dev via Docker, Postgres.app, or brew.\n\n#### Recommended\n\n- **`jq`** — used by hooks to read `.studio/config.json`; falls back gracefully if missing.\n- **Docker Desktop** — local Postgres, Testcontainers, ephemeral services.\n- **`gh` (GitHub CLI)** — for some release-engineer flows.\n- **`tmux`** or similar — multi-pane workflow with `/sprint`.\n\n#### Operating systems\n\nmacOS 12+ and Linux (Ubuntu 22.04+, Debian 11+) are tested.\nWindows works via WSL2; native Windows is unsupported (hooks are bash).\n\n### 1. Drop the framework into your project\n\n```bash\n# In your project root\ngit clone https://github.com/fmachucas/agent-dev-studios.git /tmp/ads\ncp -r /tmp/ads/.claude .\ncp /tmp/ads/CLAUDE.md /tmp/ads/ETHOS.md .\nchmod +x .claude/hooks/*.sh\n\n# Merge the framework's gitignore patterns so per-user overrides and\n# session-only state never land in your commits.\ncat \u003e\u003e .gitignore \u003c\u003c'EOF'\n\n# Agent Dev Studios — per-user overrides and session-only state\n.claude/settings.local.json\n.studio/state/log.jsonl\n.studio/state/.lock\n.studio/features/**/.lock\nEOF\n\nrm -rf /tmp/ads\n```\n\nThat's it. Your project now has 38 agents, 49 skills, 13 hooks, 13 rules, and\n23 templates available.\n\n**Track `.claude/` and `.studio/` in git.** They're meant to be committed\nto your project repo so the whole team shares the same agents, skills,\nhooks, rules, and per-feature working state. The gitignore block above\nexcludes only what should stay local: per-user permission overrides\n(`.claude/settings.local.json`), session-only state files\n(`.studio/state/log.jsonl`, `.lock` files). Everything else is\nshareable.\n\n**To sync framework updates later**: re-run the install one-liner, run\n`git diff` to see what changed, and commit the framework diff like any\nother dependency upgrade.\n\nOr just download the latest release zip and unzip the `.claude/` folder, plus\n`CLAUDE.md` and `ETHOS.md`, into your project root. **After unzipping, run\n`chmod +x .claude/hooks/*.sh`** — zip preservation of the executable bit is\nunreliable across platforms — and append the gitignore patterns above.\n\n### 2. Open Claude Code\n\n```bash\ncd /your/project\nclaude\n```\n\nThe `SessionStart` hook will print a catchup summary. On a fresh project,\nit prints a banner inviting you to run `/start` — that's expected.\n\n### 3. First flow: `/start`\n\nType `/start` at the prompt. You'll be asked where you are:\n\n```\nWhere are you?\n  1. No idea — just exploring\n  2. Vague concept — I know roughly what I want to build\n  3. Clear design — I know the shape, ready to scaffold\n  4. Existing repo — code already exists, want to add the framework\n```\n\nPick the option that matches reality. The flow routes accordingly:\n\n- **No idea** → `/brainstorm` → `/team-discovery`\n- **Vague concept** → `/vision` → `/prd`\n- **Clear design** → `/scaffold` then `/proceed`\n- **Existing repo** → `/start` runs the `/detect-stage` checks for you, then routes to `/map` and `/catchup`\n\n### 4. Pick a profile\n\nProfiles are presets over a few orchestration dials. `/start` walks you\nthrough the choice on first run via `/configure`; switch any time with\n`/profile \u003cname\u003e` or by telling an agent.\n\n| Profile | Use for | What changes |\n| ------- | ------- | ------------ |\n| `full` | Real product, customer-facing | Strict validation; multi-agent code review; audits when planned; reflection + attention hooks on |\n| `slim` | Internal tools, MVPs | Lenient validation; single-agent code review; audits when planned; reflection + attention hooks on |\n| `express` | Prototypes, hotfixes, `/bugfix` runs | Validation off; code review skipped; audits skipped; reflection + attention hooks off |\n\n`full` is the default. Each dial is overrideable per-profile in\n`.studio/config.json` if you want a non-standard combination —\nsee [`.claude/docs/templates/studio-config.example.json`](.claude/docs/templates/studio-config.example.json) for the schema.\n\n### 5. Work a feature end-to-end\n\nSay you're past `/start`. If you don't have a PRD yet, write one first:\n\n```\n\u003e /prd \"Add invoice creation flow\"\n```\n\nThen build it:\n\n```\n\u003e /proceed \"Add invoice creation flow\"\n```\n\nThis runs the full pipeline for one feature:\n\n```\nspec → design → implement → reflect → impl-review → audits → wrapup\n```\n\nValidation gates between each phase. You approve at each gate.\n\nFor multiple features in parallel:\n\n```\n\u003e /sprint\n```\n\nPick which features to run in parallel. The framework caps parallelism (default 4)\nand runs `/proceed` for each.\n\n### 6. Recover from a context reset\n\n```\n\u003e /catchup\n```\n\nReads `.studio/state/current.md`, the active feature's `plan.md`, `findings.md`,\nand `progress.md`, and gives you a catchup. You're back where you left off.\n\n### 7. Check status anytime\n\n```\n\u003e /overview\n```\n\nShows: active feature, current phase, blockers, recent commits.\n\n```\n\u003e /map\n```\n\nShows: full project layout, all features (active + parked + complete), all\nspecs by area.\n\n### Common scenarios\n\n| Scenario | Use this |\n| -------- | -------- |\n| Existing repo, want the framework | `/start` (auto-runs `/detect-stage` Phase 2 → `/map` → `/catchup`) |\n| **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. |\n| **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. |\n| Fix a bug fast | `/bugfix \"\u003cdesc\u003e\"` in `express` profile (skips audits, no reflection) |\n| Pre-release security pass | `/audit-security` (`security-lead` + `appsec-engineer` against the working branch) |\n| Pre-release perf or A11y check | `/audit-perf` / `/audit-a11y` (logs to `docs/audits/\u003ctype\u003e/\u003cdate\u003e.md`) |\n| Start over | Delete `.claude/`, `CLAUDE.md`, `ETHOS.md`, `.studio/` — your code is untouched |\n\n### What gets created on disk\n\nAfter `/start` (which bootstraps `.studio/` via `/configure` on first run):\n\n```\n.studio/\n  config.json              # Your overrides\n  state/\n    current.md             # Where you are now\n    blockers.md            # What's waiting on you\n    log.jsonl              # Audit trail\n  features/\n    \u003cfeature-id\u003e/\n      plan.md              # Phases with checkboxes\n      findings.md          # Research, decisions\n      progress.md          # Session log, errors\n  knowledge/\n    assumptions/           # Cross-feature validated assumptions\n    lessons/               # Cross-feature lessons learned\n    agents/                # Per-agent persistent memory (owner agents only)\n  templates/               # Local copies (for /template-drift)\n```\n\nCommit the `.studio/` directory if you want collaborators to see history;\nignore `.studio/state/log.jsonl` (it's noisy).\n\n### Troubleshooting\n\n**Hooks aren't firing / \"permission denied\" on hook execution**\n\n```bash\nls -la .claude/hooks/   # all .sh files should be executable\nchmod +x .claude/hooks/*.sh\n```\n\nIf `chmod` still doesn't help, your filesystem may not support the exec\nbit (some Windows mounts). Run from WSL2 instead.\n\n---\n\n## Key Concepts\n\n### Three-layer memory\n\n| Layer | Where | Lifetime | Read by |\n| ----- | ----- | -------- | ------- |\n| **Specs \u0026 decisions** | `docs/` | Permanent | Humans + agents |\n| **Working state** | `.studio/state/`, `.studio/features/\u003cid\u003e/` | Active features | Agents (auto-loaded) |\n| **Cross-cutting knowledge** | `.studio/knowledge/{assumptions,lessons,agents}/` | Forever | Agents (referenced) |\n\nEvery agent reads relevant docs **before** proposing anything. Documentation\nbecomes runtime memory.\n\n### The 3-file pattern (per active feature)\n\nFor each feature being worked on, three files live in `.studio/features/\u003cid\u003e/`:\n\n- **`plan.md`** — Phases and checkpoints with checkboxes\n- **`findings.md`** — Research and validated decisions\n- **`progress.md`** — Session log, test results, errors\n\nThis is the [Manus pattern](https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus):\n*Context window = RAM. Filesystem = disk. Anything important goes to disk.*\n\n---\n\n## Customization\n\nEverything is configurable via `.studio/config.json`. Override any default:\n\n```json\n{\n  \"profile\": \"full\",\n  \"stack\": {\n    \"backend\": \"nestjs\",\n    \"frontend\": \"nextjs\",\n    \"database\": \"postgres\",\n    \"package_manager\": \"pnpm\"\n  },\n  \"models\": {\n    \"tech-lead\": \"opus\",\n    \"code-reviewer\": \"sonnet\"\n  },\n  \"agents\": {\n    \"disabled\": [\"ai-engineer\"]\n  },\n  \"hooks\": {\n    \"validate-spec\": true,\n    \"post-tool-use\": false\n  }\n}\n```\n\nDefaults live in `.claude/settings.json`. Effective config = settings ⊕ overrides.\nOn first `/start`, the framework auto-invokes `/configure` to walk you through\nthe key choices and write the file. Run `/configure` directly later to\nreconfigure.\n\n---\n\n## Scope\n\n**What's in:** idea → release. Discovery, spec, design, build, audits, ship.\n\n**What's out (for now):** the **operate** phase — runbooks, on-call, postmortems,\nhotfixes, rollbacks, incident response. See [ROADMAP.md](ROADMAP.md).\n\n**What's pinned (v1):** NestJS · Next.js · PostgreSQL · pnpm. The framework's\ndefaults match this stack today; that's a deliberate constraint to keep the\nopinions sharp.\n\n---\n\n## Extensibility\n\nThe framework is a **template**, not a locked system. Three extension points:\n\n1. **Stack packs** — add a stack under `.claude/agents/stacks/\u003cname\u003e/`\n2. **Custom skills** — drop new skills into `.claude/skills/\u003cname\u003e/`\n3. **Custom agents** — add specialists alongside the existing ones\n\nSee [CONTRIBUTING.md → How to add a stack pack](CONTRIBUTING.md#how-to-add-a-stack-pack) for the full guide.\n\n---\n\n## Foundations\n\nFour ideas shape this framework. None are original — they come from teams\nbuilding with AI assistants who discovered patterns that work. The framework's\njob is to make these ideas concrete and composable.\n\n### 1. Specialized roles beat a generalist\n\nA single AI session has no organizational structure. It can be asked to play\nany role, but it has no consistent identity, no defined responsibilities, no\nescalation path when work crosses a boundary it shouldn't. A real engineering\nteam has directors who own vision, leads who own domains, specialists who own\nfocused execution — and the friction between them is what catches mistakes.\n\nThis framework treats an AI session like an org chart. Each agent has a single\njob, a parent it reports to, and named anti-patterns it watches for. When a\nbackend agent and a frontend agent disagree about an API contract, they\nescalate to their tech lead. When the security lead and the product manager\nconflict over scope, they go to a director. More friction. More thoughtfulness.\n\n### 2. Phases need rituals\n\nSoftware development has phases — discovery, design, build, audit, release —\nand each phase produces a discrete output the next phase depends on. Skipping\nor rushing a phase usually means re-doing it later under worse conditions.\n\nSkills are named after the *actions* that mark these transitions: `/vision`,\n`/architect`, `/impl-review`, `/release`. Verbs, not nouns. Each skill ends in a\nvalidation step before the next phase can begin. The friction is intentional —\nit forces \"is this actually ready?\" before moving on.\n\n### 3. Filesystem is memory\n\nAI context windows are volatile. They reset between sessions, get compacted\nunder pressure, get distracted by the most recent message. A filesystem doesn't.\n\nEvery spec, decision, finding, and progress note in this framework lives on\ndisk in predictable files. The 3-file pattern for active features (`plan.md`,\n`findings.md`, `progress.md`) means any new session can read exactly where the\nlast one left off. Documentation isn't an afterthought of the work — it *is*\nthe work's persistent memory.\n\n### 4. Concreteness beats principle\n\n\"Write good code\" is true and useless. \"Don't put business logic in\ncontrollers\" is specific and actionable. Every agent prompt includes a named\n**Anti-patterns to avoid** section. Heavy topics — auth strategies, indexing,\nREST vs GraphQL — get dedicated reference files that load only when relevant.\n\nBehavior changes when prohibitions are named. Vague principles don't change\nbehavior; they just make people feel righteous about ignoring them.\n\n---\n\n## Project Structure\n\n```\nCLAUDE.md                              # Master config\nETHOS.md                               # Principles\nROADMAP.md                             # What's next\nREADME.md                              # You are here\n\n.claude/\n  settings.json                        # Hooks, permissions, defaults\n  agents/                              # 31 generic + 7 stack-pack specialists\n  skills/                              # 49 slash commands\n  hooks/                               # 13 hook scripts + 1 helper in lib/\n  rules/                               # 13 path-scoped standards\n  docs/\n    agent-roster.md                    # Per-agent tier / model / parent\n    agent-coordination-map.md          # Delegation, escalation, worked patterns\n    agent-memory.md                    # Per-agent persistent-memory pattern\n    safety.md                          # Security policy (@-imported by CLAUDE.md)\n    templates/                         # 23 templates (20 doc + 1 config + 2 editor)\n\n.studio/                               # Bootstrapped on first /start\n  config.json                          # Project overrides\n  state/                               # Working memory\n  features/                            # 3-file pattern per feature\n  knowledge/                           # Validated assumptions, lessons, per-agent memory\n  templates/                           # Local copies (for /template-drift)\n\n# After /scaffold:\napps/api/                              # NestJS — owns Prisma schema + migrations in v1\napps/web/                              # Next.js\npackages/                              # Shared libs\ninfra/                                 # IaC\ndocs/                                  # Permanent specs\ntests/                                 # Test suites\n```\n\n---\n\n## Acknowledgments\n\nPrior art that influenced specific mechanics:\n\n- [Claude Code Game Studios](https://github.com/Donchitos/Claude-Code-Game-Studios) — the studio hierarchy and orchestration model\n- [ADLC Toolkit](https://github.com/atelier-fashion/adlc-toolkit) — verb-named skills, validation gates, the `/proceed` and `/wrapup` pattern\n- [Planning with Files](https://github.com/OthmanAdi/planning-with-files) — the 3-file Manus pattern for persistent memory\n- [Impeccable](https://github.com/pbakaus/impeccable) — reference files inside skills, named anti-patterns\n\n---\n\n## Support\n\nThis is free, MIT-licensed, and built in spare time. If it's saved you hours\nof arguing with an AI assistant, you can throw a coffee at it on Ko-fi.\n\n[![Support on Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/felipemachucasanjuan)\n\n---\n\n## Community\n\n- **Issues** — bug reports and feature requests on this repo\n- **Discussions** — questions, ideas, showcasing what you've built\n\n---\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffmachucas%2Fagent-dev-studios","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffmachucas%2Fagent-dev-studios","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffmachucas%2Fagent-dev-studios/lists"}