{"id":49401418,"url":"https://github.com/erniker/understudy","last_synced_at":"2026-05-13T08:12:54.355Z","repository":{"id":353307827,"uuid":"1218151615","full_name":"erniker/understudy","owner":"erniker","description":"One AI, Every Role — A system that configures teams of specialized AI agents (Architect, Backend, Frontend, DevOps, Security, QA). Compatible with GitHub Copilot CLI, Claude Code, and Cursor.","archived":false,"fork":false,"pushed_at":"2026-05-06T10:01:06.000Z","size":1138,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-06T12:05:00.923Z","etag":null,"topics":["agentic-ai","ai","ai-agents","automation","claude","cursor","developer-tools","devops","github-copilot","llm","multi-agent","prompt-engineering","software-architecture"],"latest_commit_sha":null,"homepage":"","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/erniker.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"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-04-22T15:27:44.000Z","updated_at":"2026-05-06T10:01:08.000Z","dependencies_parsed_at":"2026-05-06T12:02:35.577Z","dependency_job_id":null,"html_url":"https://github.com/erniker/understudy","commit_stats":null,"previous_names":["erniker/understudy"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/erniker/understudy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erniker%2Funderstudy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erniker%2Funderstudy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erniker%2Funderstudy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erniker%2Funderstudy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/erniker","download_url":"https://codeload.github.com/erniker/understudy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erniker%2Funderstudy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32973490,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T06:31:55.726Z","status":"ssl_error","status_checked_at":"2026-05-13T06:31:51.336Z","response_time":115,"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","ai-agents","automation","claude","cursor","developer-tools","devops","github-copilot","llm","multi-agent","prompt-engineering","software-architecture"],"created_at":"2026-04-28T18:07:59.477Z","updated_at":"2026-05-13T08:12:54.348Z","avatar_url":"https://github.com/erniker.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎭 Understudy — One AI, Every Role\n\n\u003e A system that configures specialized AI agents in any project.\n\u003e One assistant, multiple roles: Architect, Backend, Frontend, DevOps, Security, QA.\n\u003e Compatible with **GitHub Copilot CLI**, **VS Code**, **Claude Code** and **Cursor**.\n\n## Installation\n\n### Linux / macOS / Windows Git Bash / WSL\n\n**One-liner:**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/erniker/understudy/main/install.sh | bash\n```\n\n**Specific version:**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/erniker/understudy/main/install.sh | bash -s -- --version v1.0.0\n```\n\n### Windows (PowerShell)\n\n**One-liner:**\n\n```powershell\nirm https://raw.githubusercontent.com/erniker/understudy/main/install.ps1 | iex\n```\n\n**Specific version:**\n\n```powershell\n.\\install.ps1 -Version v1.0.0\n```\n\n\u003e Requires **Git for Windows** (provides `bash.exe`). The installer detects it\n\u003e automatically and creates a PowerShell launcher that delegates to bash.\n\n### Manual (clone)\n\n```bash\ngit clone https://github.com/erniker/understudy.git\ncd understudy\nchmod +x wizard.sh\n```\n\n\u003e See [install options](#install-options) for `--dir`, `--no-path` and `--uninstall`.\n\n## Quick Start\n\n```bash\n# Deploy Understudy in any project\ncd /path/to/your/project\nunderstudy\n# → Choose platforms: Copilot, Claude Code, Cursor\n\n# Then open your AI tool\nclaude            # Claude Code\ncopilot           # GitHub Copilot CLI\ncursor .          # Cursor\n```\n\n### Zero-question deploy (`--here`)\n\nAlready inside an existing repo and don't want to answer the wizard's\nquestions? Use `--here` — Understudy infers project name, description,\nstack, repository URL and PM from the files in your working directory:\n\n```bash\ncd /path/to/your/project\nunderstudy --here          # shows inferred values, asks one confirmation\nunderstudy --here --yes    # fully unattended, no prompts\n```\n\nWhat gets inferred:\n\n- **Project name** — from the folder name or root `package.json`\n- **Description** — from `package.json` or the first paragraph of `README.md`\n- **Stack** — Node.js / React / Vue / Angular / .NET / Python / Terraform / Docker / Shell\n- **Repository URL** — from `git remote get-url origin`\n- **PM** — from `git config user.name`\n\nThe wizard prints a numbered summary of all 9 settings (the same questions\nthe interactive wizard asks) and offers three options at the confirmation\nprompt:\n\n- **`Y`** — deploy with the inferred settings (default).\n- **`n`** — cancel.\n- **`e`** — edit any field interactively. You enter the field number\n  (`1`-`9`), provide a new value, and repeat until satisfied. Then `d` to\n  deploy or `q` to quit.\n\nDefaults applied for non-inferable choices: `split` guardrails, all three\nplatforms enabled, files committed to the repo. Run without `--here` for\nthe full interactive wizard if you need to customize them.\n\n### Install options\n\n**Bash (`install.sh`):**\n\n| Flag | Description |\n|---|---|\n| `--version \u003ctag\u003e` | Install a specific version (e.g. `v1.2.0`) |\n| `--dir \u003cpath\u003e` | Custom install directory (default: `~/.understudy`) |\n| `--no-path` | Skip PATH setup |\n| `--uninstall` | Remove Understudy from the system |\n\n**PowerShell (`install.ps1`):**\n\n| Parameter | Description |\n|---|---|\n| `-Version \u003ctag\u003e` | Install a specific version (e.g. `v1.2.0`) |\n| `-InstallDir \u003cpath\u003e` | Custom install directory (default: `~/.understudy`) |\n| `-NoPath` | Skip PATH setup |\n| `-Uninstall` | Remove Understudy from the system |\n\n### Automatic update checks\n\nWhen you run `understudy`, it checks for a new release on GitHub.\nIf a newer version exists, it asks whether you want to update now.\n\nTo disable this check (for CI or offline environments):\n\n```bash\nexport UNDERSTUDY_SKIP_UPDATE_CHECK=1\n```\n\n## What is this?\n\nA system that automatically generates all the configuration needed for\n**GitHub Copilot CLI**, **VS Code**, **Claude Code** and **Cursor** to work as a complete development team:\n\n| Member | Role | Expertise |\n|---|---|---|\n| 🏛️ **Architect** | Solutions Architect | System design, APIs, databases, cloud |\n| ⚙️ **Backend** | Backend Developer | .NET, Node.js, C#, TypeScript, Python, Bash |\n| 🎨 **Frontend** | Frontend Developer | React, TypeScript, UX/UI, accessibility |\n| 🚀 **DevOps** | DevOps Engineer | Azure, AWS, Docker, K8s, Terraform, CI/CD |\n| 🔒 **Security** | Security Expert | OWASP, threat modeling, compliance, IAM |\n| 🧪 **QA** | QA Engineer | Testing .NET, Node.js, Python, E2E, contract testing |\n\n## Key Concepts\n\n### 1. AGENTS.md — \"Who is the team\"\nA file at the project root that defines agents selectable with `/agent` in Copilot CLI.\nEach agent has a name, role, expertise and behavioral rules.\n\n### 2. .github/copilot-instructions.md — \"Project rules\"\nGlobal instructions that Copilot loads **automatically** in every session.\nDefines project context, conventions and workflow.\n\n### 3. .github/instructions/*.instructions.md — \"How each member works\"\nModular instruction files per role. Activated with `/instructions`\nor loaded alongside the corresponding agent. They contain the detailed personality,\ncode standards and checklists for each member.\n\n### 4. Parallel sub-agents — \"Divide and conquer\"\nCopilot CLI can launch sub-agents (task tool) that work in parallel.\nIdeal for Backend and Frontend to implement simultaneously while\nDevOps prepares the infrastructure.\n\n### 5. Context files — \"Memory between sessions\"\nThe files `docs/session-log.md`, `docs/spec.md` and `docs/decisions.md`\nact as persistent memory. At the start of each session the agent reads them;\nat the end, it updates them. This saves tokens and avoids repeating information.\n\n### 6. 🛡️ Guardrails — \"What we NEVER do\"\nSecurity and behavioral limits that all agents respect.\nThey cover 8 categories: security, scope, process, destructive operations,\ndata/PII, quality, environments and documentation. They are **non-negotiable** and\ndeployed automatically with the wizard.\n\n### 7. 🔒 Local-only mode — \"Keep AI config out of git\"\nOptional. The wizard can append the generated AI config (`AGENTS.md`,\n`CLAUDE.md`, `.github/instructions/`, `.claude/`, `.cursor/`…) and/or the\nsession memory files (`docs/spec.md`, `docs/decisions.md`,\n`docs/session-log.md`) to the project's `.gitignore` so they stay local.\nUseful in corporate repos where AI tool config is private, or open source\nprojects where you don't want to expose your internal workflow. Toggle with\n`git.local_config` / `git.local_memory` in `understudy.yaml` — see\n[docs/09-configuration.md](docs/09-configuration.md#local-only-mode).\n\n## Guardrails\n\nGuardrails protect the team from:\n- Secrets or sensitive data leaks\n- Destructive operations without confirmation\n- Production changes without change control\n- Code without spec, without tests, or without review\n- Scope violations between agents\n\n### Deployment modes\n\n| Mode | Description |\n|---|---|\n| 🔀 **split** (recommended) | Critical guardrails always active in `copilot-instructions.md` + full details file in `guardrails.instructions.md` |\n| 📦 **embedded** | Only critical guardrails embedded in `copilot-instructions.md` (lighter, no separate file) |\n\n### Split vs Embedded: practical differences\n\n| Aspect | 🔀 split | 📦 embedded |\n|---|---|---|\n| **Enforcement level** | Critical guardrails are always active **and** full guardrails are available in a dedicated file | Only critical guardrails are always active |\n| **Visibility** | Higher: team can review complete guardrails in `guardrails.instructions.md` | Lower: only the reduced set is visible in global instructions |\n| **Maintenance** | Easier to evolve full guardrails without bloating global instructions | Simpler file structure, but less room for detailed policies |\n| **Best for** | Regulated teams, larger repos, multi-agent workflows, stricter governance | Small/fast projects, lightweight setups, teams that want minimal overhead |\n| **Trade-off** | More files and a bit more structure | Less explicit coverage of non-critical rules |\n\n**Rule of thumb:**\n- Choose **split** when you want stronger governance, better auditability and clearer team alignment.\n- Choose **embedded** when speed and simplicity matter more than policy depth.\n\nThe mode is selected during the wizard and can be changed by editing `understudy.yaml`:\n\n```yaml\nguardrails:\n  mode: \"split\"   # \"split\" or \"embedded\"\n```\n\n### Categories\n\n| # | Category | What it protects |\n|---|---|---|\n| 1 | 🛡️ Security | No secrets, no bypass, mandatory input validation |\n| 2 | 🎯 Scope | File ownership per agent, justification required to cross boundaries |\n| 3 | 📋 Process | Spec-first (with exceptions for bugfixes/emergencies), documented decisions |\n| 4 | 💥 Destructive | PM confirmation before deleting, purging or revoking |\n| 5 | 🔒 Data/PII | No real data, synthetic data in tests, GDPR |\n| 6 | 🏗️ Quality | Self-review, appropriate tests, naming, error handling |\n| 7 | ⚠️ Environments | Promotion order dev→prd, mandatory IaC, no manual changes |\n| 8 | 📝 Documentation | ADRs, session-log, updated spec |\n\n## System Structure\n\n```\nunderstudy/\n├── wizard.sh                    # 🧙 The wizard — deploys Understudy\n├── install.sh                   # 📦 One-liner curl installer\n├── run_tests.sh                 # 🧪 Local test runner\n├── understudy.yaml              # ⚙️ Global configuration\n├── templates/                   # 📋 Base templates\n│   ├── AGENTS.md                # Copilot: team definition\n│   ├── CLAUDE.md                # Claude: global instructions\n│   ├── .github/                 # Copilot / VS Code\n│   │   ├── copilot-instructions.md\n│   │   ├── instructions/\n│   │   │   ├── architect.instructions.md\n│   │   │   ├── backend.instructions.md\n│   │   │   ├── frontend.instructions.md\n│   │   │   ├── devops.instructions.md\n│   │   │   ├── security.instructions.md\n│   │   │   ├── qa-engineer.instructions.md\n│   │   │   └── guardrails.instructions.md\n│   │   └── prompts/\n│   │       ├── start-session.prompt.md\n│   │       ├── end-session.prompt.md\n│   │       ├── design-feature.prompt.md\n│   │       ├── security-review.prompt.md\n│   │       └── understudy.prompt.md\n│   ├── .claude/                 # Claude Code\n│   │   ├── agents/\n│   │   │   ├── architect.md, backend.md, frontend.md\n│   │   │   ├── devops.md, security.md, qa.md\n│   │   ├── commands/\n│   │   │   ├── start-session.md, end-session.md\n│   │   │   ├── design-feature.md, security-review.md\n│   │   │   ├── understudy.md\n│   │   ├── hooks/\n│   │   │   └── guardrails-check.sh\n│   │   └── settings.json\n│   ├── .cursor/                 # Cursor\n│   │   ├── agents/\n│   │   │   ├── architect.md, backend.md, frontend.md\n│   │   │   ├── devops.md, security.md, qa-engineer.md\n│   │   ├── commands/\n│   │   │   └── understudy.md\n│   │   └── rules/\n│   │       ├── understudy-global.mdc\n│   │       └── guardrails.mdc\n│   └── docs/\n│       ├── spec.md\n│       ├── decisions.md\n│       ├── session-log.md\n│       └── team-roster.md\n├── roles/                       # 🎭 Optional roles catalog\n│   ├── data-engineer.instructions.md\n│   ├── git-specialist.instructions.md\n│   ├── mobile-engineer.instructions.md\n│   ├── ml-engineer.instructions.md\n│   ├── repo-documenter.instructions.md\n│   ├── shell-scripting.instructions.md\n│   ├── tech-writer.instructions.md\n│   └── sre.instructions.md\n├── modules/                     # 🧩 Opt-in modules\n│   └── caveman/                 # Token-efficient communication\n│       ├── module.yaml          # Module manifest (auto-discovered)\n│       ├── role.instructions.md  # Caveman role definition\n│       ├── bin/                 # understudy-compress, install-hooks, etc.\n│       ├── commands/            # Slash command templates per platform\n│       ├── hooks/               # Reinforcement hook templates\n│       ├── statusline/          # Claude Code statusline script\n│       ├── evals/               # Token-reduction evaluation harness\n│       └── tests/               # Module-specific bats tests\n├── tests/                       # 🧪 bats test suite\n│   ├── unit/                    # config_read, detect, deploy_file, guardrails\n│   ├── hooks/                   # guardrails-check.sh tests\n│   ├── integration/             # end-to-end wizard deployment\n│   ├── fixtures/                # fake project structures\n│   └── lib/helpers.bash         # shared test helpers\n└── docs/                        # 📚 Documentation\n    ├── README.md                    # Index\n    ├── 01-introduction.md\n    ├── 02-quick-start.md\n    ├── 03-platform-comparison.md\n    ├── 04-guardrails.md\n    ├── 05-roles-and-workflow.md\n    ├── platforms/\n    │   ├── copilot-cli.md\n    │   ├── vscode-copilot.md\n    │   ├── claude-code.md\n    │   └── cursor.md\n    ├── 08-cross-platform-workflows.md\n    ├── 09-configuration.md\n    ├── 10-caveman-mode.md\n    └── 11-troubleshooting.md\n```\n\n## Documentation\n\nFull docs live under [`docs/`](docs/README.md) and are organized so they can be\npublished as a static site without restructuring.\n\n| Section | Contents |\n|---|---|\n| [Introduction and Core Concepts](docs/01-introduction.md) | Mental model, agents, spec-driven development, persistent memory, guardrails, roles catalog, generated files |\n| [Quick Start](docs/02-quick-start.md) | Install, first session, extending the team |\n| [Platform Capability Matrix](docs/03-platform-comparison.md) | What each tool supports out of the box |\n| [Guardrails](docs/04-guardrails.md) | 8 categories, deployment modes, enforcement per platform, customization |\n| [Roles \u0026 Spec-Driven Development](docs/05-roles-and-workflow.md) | Role system, `applyTo`, spec lifecycle, session protocol, ADRs, sub-agents |\n| [GitHub Copilot CLI](docs/platforms/copilot-cli.md) | Setup, commands, full feature flow, sub-agents, tips |\n| [VS Code Copilot](docs/platforms/vscode-copilot.md) | `applyTo` globs, prompt files, start → work → end flow |\n| [Claude Code](docs/platforms/claude-code.md) | Agents, slash commands, deny list, PreToolUse hook, adding commands |\n| [Cursor](docs/platforms/cursor.md) | Rules (MDC), agent panel, creating your own rules |\n| [Cross-Platform Workflows](docs/08-cross-platform-workflows.md) | Mixed setups and the shared session protocol |\n| [Configuration Reference](docs/09-configuration.md) | Full `understudy.yaml` reference |\n| [Caveman Mode](docs/10-caveman-mode.md) | Token-efficient role, compress script, hooks, statusline, evals |\n| [Troubleshooting and FAQ](docs/11-troubleshooting.md) | Common issues, model choice, reporting bugs |\n\n## Wizard Commands\n\n| Command | Description |\n|---|---|\n| `understudy` | Full interactive deployment |\n| `understudy --here` | Deploy in the current directory using values inferred from the repo (numbered summary, editable with `e`) |\n| `understudy --here --yes` | Same as `--here` but skip the confirmation prompt (fully unattended) |\n| `understudy --add-member` | Add a team member (data engineer, QA, etc.) |\n| `understudy --create-role` | Create a custom role from scratch |\n| `understudy --help` | Show help |\n\n\u003e If you installed manually via `git clone`, replace `understudy` with `./wizard.sh`.\n\n## Integration into Existing Projects and Monorepos\n\nThe wizard automatically detects existing projects and adapts:\n\n| Scenario | Behavior |\n|---|---|\n| 🆕 Folder doesn't exist | Creates new project with full structure |\n| 🔄 Existing project | Integrates Understudy without touching existing files |\n| ⚠️ Already has Understudy | Re-deploy: only adds missing files |\n\n### Automatic Stack Detection\n\nThe wizard scans up to 3 levels deep to detect technologies:\n\n| Technology | Marker | Example |\n|---|---|---|\n| .NET | `*.csproj`, `*.sln` | `.NET: services/api-customers (ApiCustomers)` |\n| Node.js | `package.json` (without React/Vue/Angular) | `Node.js: services/api-notifications` |\n| React | `package.json` with `\"react\"` | `React: frontend/web-app` |\n| Vue | `package.json` with `\"vue\"` | `Vue: frontend/admin` |\n| Angular | `package.json` with `\"@angular/core\"` | `Angular: frontend/portal` |\n| Python | `requirements.txt`, `pyproject.toml`, `setup.py`, `Pipfile` | `Python: services/ml-scoring` |\n| Terraform | `*.tf` | `Terraform: infra/terraform` |\n| Docker | `Dockerfile`, `docker-compose.yml` | `Docker: 4 Dockerfiles` |\n| Shell | `*.sh`, `*.bash`, `*.zsh` | `Shell` (auto-adds shell-scripting role) |\n\n### Monorepo Support\n\nWhen 2+ independent projects are detected, the stack is labeled as **Monorepo**:\n\n```\nMonorepo: .NET(2) + Node.js + React(2) + Python + Terraform + Docker\n\nComponents found:\n  • .NET: services/api-customers (ApiCustomers)\n  • .NET: services/api-policies (ApiPolicies)\n  • React: frontend/web-app\n  • Node.js: services/api-notifications\n  • Python: services/ml-scoring\n  • Terraform: infra/terraform\n  • Docker: 4 Dockerfiles\n  • Docker Compose: ./\n```\n\nThe detected stack is pre-filled as the default value, saving you time during setup.\n\n## Recommended Workflow\n\n```\nPM writes spec.md\n        │\n        ▼\n   /agent Architect ──── designs solution ──── docs/decisions.md\n        │\n        ▼\n   /agent Security ───── threat model\n        │\n        ├──────────────────────┐\n        ▼                      ▼\n   /agent Backend         /agent Frontend\n   (implements APIs)      (implements UI)\n        │                      │\n        └──────────┬───────────┘\n                   ▼\n             /agent QA\n        (test plan + tests)\n                   │\n                   ▼\n            /agent DevOps\n        (infra + CI/CD + deploy)\n                   │\n                   ▼\n            /agent Security\n          (final review)\n                   │\n                   ▼\n        session-log.md updated\n```\n\n## How to Add New Roles\n\nThe `roles/` folder is the **official optional roles catalog** for the system. The 6 core roles (Architect, Backend, Frontend, DevOps, Security, QA) are always deployed from `templates/`; roles in `roles/` are additional and you choose them.\n\n**Included optional roles:**\n\n| Role | When to use it |\n|---|---|\n| 🐉 **caveman** | Token-efficient prose. Drops fillers; keeps code/paths/URLs. Opt-in via `--caveman`. See [Caveman Mode](docs/10-caveman-mode.md). |\n| 📊 **data-engineer** | ETL/ELT pipelines, data warehouses, streaming, data governance |\n| 🌿 **git-specialist** | Git workflows, branch policies, PR hygiene, release discipline |\n| 📱 **mobile-engineer** | iOS/Android apps, React Native, Flutter |\n| 🤖 **ml-engineer** | ML models, MLOps, LLMs, RAG, responsible AI |\n| 📖 **repo-documenter** | Codebase understanding, architecture docs, onboarding guides |\n| 🐚 **shell-scripting** | Bash/sh automation, cross-platform scripting, ShellCheck best practices |\n| 📝 **tech-writer** | Technical documentation, API docs, tutorials, Diataxis |\n| 🧭 **sre** | SLOs, observability, incident response, chaos engineering |\n\n**Auto-deploy:** The wizard always includes `git-specialist` and\n`repo-documenter`. If shell scripts (`*.sh`, `*.bash`, `*.zsh`) are detected\nin your project, `shell-scripting` is added automatically. All are deployed to\nevery platform you selected (Copilot, Claude, Cursor).\n\n**How to add more:**\n\n1. **From the existing catalog**: `understudy --add-member` → choose from menu (works with Copilot, Claude and Cursor projects)\n2. **Create a new one**: `understudy --create-role` → saved in `roles/` for reuse\n3. **Manual**: create a file `name.instructions.md` in `roles/` following the existing format\n\n\u003e Roles you create with `--create-role` are stored in `roles/` and will be available for **all your future Understudy deployments**, not just the current project.\n\n## Tips for Project Managers\n\n- Use **Claude Opus** (`/model`) for the Architect — better reasoning for design\n- Use **Claude Sonnet** for Backend/Frontend — good speed/quality balance\n- Use **Claude Haiku** for quick DevOps tasks — economical and efficient\n- Always ask to update `session-log.md` at the end of each session\n- The spec is sacred: if scope changes, update the spec first\n\n\u003e These defaults are in `understudy.yaml`. Edit it in your project to customize.\n\n## Configuration and Override\n\nThe system uses an `understudy.yaml` configuration file with priority hierarchy:\n\n```\n1. Wizard defaults (built-in)                    ← lowest priority\n2. ~/.understudy/understudy.yaml (installed)     ← global defaults\n   OR understudy.yaml next to wizard.sh (cloned) ← if installed manually\n3. understudy.yaml in the project                ← per-project override (highest)\n```\n\nExample override: your project needs Opus for Security because it's fintech:\n```yaml\n# my-project/understudy.yaml\nmodels:\n  security: \"claude-opus-4.6\"   # override: more reasoning for fintech\nplatforms:\n  copilot: true\n  claude: true                  # or false if you only use one platform\n  cursor: true\nguardrails:\n  mode: \"embedded\"              # override: only critical guardrails for lighter project\n```\n\n## Compatibility: Copilot CLI + VS Code + Claude Code + Cursor\n\nUnderstudy works on **all four platforms** — choose one or all during deployment:\n\n| Feature | Copilot CLI | VS Code | Claude Code | Cursor |\n|---|---|---|---|---|\n| Global instructions | ✅ Auto-loaded | ✅ Auto-loaded | ✅ CLAUDE.md | ✅ `.cursor/rules/` |\n| Role instructions | ✅ `/instructions` | ✅ Auto-applies by `applyTo` | ✅ `.claude/agents/` | ✅ `.cursor/agents/` |\n| Guardrails | ✅ Auto + `/instructions` | ✅ Auto-applies (`**`) | ✅ CLAUDE.md + hooks | ✅ `guardrails.mdc` |\n| Agent selection | `/agent` | Chat with context | Invoke by name | Agent panel |\n| Reusable prompts | N/A | ✅ `.github/prompts/` | ✅ `/project:command` | N/A |\n| Team definition | ✅ AGENTS.md | ✅ AGENTS.md | ✅ `.claude/agents/` | ✅ `.cursor/agents/` |\n| File protection | N/A | N/A | ✅ `settings.json` deny | N/A |\n| Security hooks | N/A | N/A | ✅ `.claude/hooks/` | N/A |\n| Caveman role | ✅ opt-in | ✅ opt-in | ✅ opt-in | ✅ opt-in |\n| Caveman compress | ✅ repo-level | ✅ repo-level | ✅ repo-level | ✅ repo-level |\n| Caveman `/compress` `/restore` | N/A | ✅ `.github/prompts/` | ✅ `.claude/commands/` | ✅ `.cursor/commands/` |\n| Caveman hooks (reinforcement) | N/A | ⚠️ Marker block | ✅ Real hooks | ⚠️ Always-apply rule |\n| Caveman statusline | N/A | N/A | ✅ Claude only | N/A |\n\n### In VS Code\n- Instructions are applied **automatically** based on the file you're editing\n  (thanks to the `applyTo` frontmatter in each `.instructions.md`)\n- Prompts in `.github/prompts/` are available as reusable prompts\n- Use \"Start Session\" and \"End Session\" prompts for the context flow\n- **Caveman**: role via `.github/instructions/caveman.instructions.md`, slash commands\n  via `.github/prompts/compress.prompt.md` and `restore.prompt.md`, reinforcement\n  via marker block in `copilot-instructions.md`\n\n### In Claude Code\n- `CLAUDE.md` is loaded automatically when you open the project\n- Agents are in `.claude/agents/` — invoke them by name\n- Commands are in `.claude/commands/` — use them with `/project:name`\n- The guardrails hook blocks destructive operations automatically\n- `settings.json` protects sensitive files (.env, keys, secrets)\n- **Caveman**: role via `.claude/agents/caveman.md`, `/compress` and `/restore`\n  commands, real `SessionStart` / `UserPromptSubmit` hooks, statusline showing\n  cumulative compression savings\n\n### In Cursor\n- Global rules (`.cursor/rules/`) are applied **automatically** in every session\n- Agents are in `.cursor/agents/` — invoke them from the Agent panel\n- Guardrails are in `.cursor/rules/guardrails.mdc` — always active\n- Each agent has its model configured in the frontmatter (`auto`, `fast`, or a specific model)\n- **Caveman**: role via `.cursor/agents/caveman.md`, `/compress` and `/restore`\n  commands via `.cursor/commands/`, reinforcement via\n  `.cursor/rules/00-caveman-active.mdc` (alwaysApply)\n\n### Files by platform\n\n**Copilot / VS Code:**\n```\n.github/copilot-instructions.md        → Always active (includes critical guardrails)\n.github/instructions/*.instructions.md → By file type (applyTo)\n.github/instructions/guardrails.instructions.md → Always active (applyTo: \"**\")\n.github/prompts/*.prompt.md            → Invocable from Copilot Chat\nAGENTS.md                              → Read as context\n# Caveman (opt-in)\n.github/instructions/caveman.instructions.md → Role (applyTo: \"**\")\n.github/prompts/compress.prompt.md     → /compress slash command\n.github/prompts/restore.prompt.md      → /restore slash command\n```\n\n**Claude Code:**\n```\nCLAUDE.md                              → Always active (includes critical guardrails)\n.claude/agents/*.md                    → Agents by role (with frontmatter)\n.claude/commands/*.md                  → Commands (/project:name)\n.claude/settings.json                  → Permissions and hooks\n.claude/hooks/guardrails-check.sh      → Hook PreToolUse\n# Caveman (opt-in)\n.claude/agents/caveman.md              → Caveman role agent\n.claude/commands/compress.md           → /compress command\n.claude/commands/restore.md            → /restore command\nsettings.json → SessionStart + UserPromptSubmit hooks, statusLine\n```\n\n**Cursor:**\n```\n.cursor/agents/*.md                    → Agents by role (with frontmatter)\n.cursor/rules/understudy-global.mdc        → Global rules (always active)\n.cursor/rules/guardrails.mdc          → Guardrails (always active)\n# Caveman (opt-in)\n.cursor/agents/caveman.md             → Caveman role agent\n.cursor/commands/compress.md           → /compress command\n.cursor/commands/restore.md            → /restore command\n.cursor/rules/00-caveman-active.mdc    → Reinforcement (alwaysApply)\n```\n\n## Contributing\n\nContributions are welcome. Read the [contribution guide](CONTRIBUTING.md) before\nopening a PR — it includes commit conventions, versioning, CHANGELOG maintenance\nand the review process.\n\nTo report bugs or propose improvements use the [issue templates](https://github.com/erniker/understudy/issues/new/choose).\nTo report security vulnerabilities, see the [security policy](SECURITY.md).\n\nThis project follows the [Contributor Covenant](CODE_OF_CONDUCT.md) as its code of conduct.\n\n## Acknowledgments\n\n- **Caveman mode** (the `caveman` role and the `understudy-compress` script)\n  is inspired by [JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman) —\n  thanks to its author for the original idea of token-efficient AI prose and for\n  open-sourcing the prompt patterns that informed our port. See\n  [docs/10-caveman-mode.md](docs/10-caveman-mode.md) for what we adapted and\n  what we intentionally did not ship.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferniker%2Funderstudy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ferniker%2Funderstudy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferniker%2Funderstudy/lists"}