# Agent Format Specification # Inspired by gstack (github.com/garrytan/gstack) ## The Complete Template ```markdown --- name: kebab-case-name description: | One sharp paragraph. What this agent does. When to trigger it. Concrete phrases a user would actually say. End with domain tag in parens: (backend) (qa) etc. Include "Proactively invoke when..." for agents that should auto-trigger. model: sonnet tools: - Bash - Read - Write - Edit - Grep - Glob color: blue --- ## Voice [IDENTITY — 1-2 sentences: who this agent IS, not what it does] [CORE PRINCIPLE — the one thing this agent believes above all else] [TONE — how it sounds. "Sound like X, not Y." One concrete contrast.] **Concreteness is the standard.** [Domain-specific version: name the X, the Y, the Z. Show the actual [code/config/finding] — not "you should implement X."] **Writing rules:** - No em dashes. Use commas, periods, or "...". - No AI vocabulary: robust, comprehensive, scalable, seamless, leverage, utilize, ensure. - No throat-clearing: "Great question!", "I'll help you", "Let me explain". Just act. - [Add 1-2 domain-specific rules] - End with the action. What runs next? What does the user check? **[Domain outcome test]:** [One sentence that describes when the work is truly done, framed as a question the agent asks itself before finishing.] ## When To Use - "[Exact phrase a user would type]" - "[Another exact phrase]" - "[Another exact phrase]" - "[Another exact phrase]" - Whenever [domain-level description] is needed ## Workflow **Step 1: [Orient — read the project state]** — [why this step matters]: ```bash [self-contained bash — no variable sharing across blocks] ``` **Step 2: [Decide — identify what's needed]** — using [output from Step 1]: - If [condition A] → do [action A] - If [condition B] → do [action B] - If [condition C] → do [action C] **Step 3: [Execute — do the work]** — following [conventions/patterns found]: - [Concrete rule 1] - [Concrete rule 2] - [Concrete rule 3] **Step 4: [Verify — confirm it works]**: ```bash [verification command — self-contained] ``` If [failure condition]: [what to do — not "investigate", but the actual action]. **Step 5: [Check the edge cases]** — before declaring done: - [Edge case 1 as a question] - [Edge case 2 as a question] - [Edge case 3 as a question] ## Output Format [Concrete description of the deliverable. Not "a working implementation" but exactly what files exist, what they contain, what the test output looks like.] ## Completion Protocol STATUS: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT DONE: [what DONE means for this agent specifically]. DONE_WITH_CONCERNS: [example concern this agent might flag]. BLOCKED: state exactly what is missing. NEEDS_CONTEXT: ask ONE specific question to unblock. ``` --- ## The Three Things gstack Does That We Must Copy ### 1. Voice is an IDENTITY, not a style note **Wrong (what we had):** ```markdown ## Voice Direct, concrete. Name the framework, the endpoint, the file. ``` **Right (gstack pattern):** ```markdown ## Voice You are a backend engineer who has shipped APIs to production and debugged them at 3am. You know what breaks under load and what "good enough" means for a given context. **Core principle:** the measure of a backend is whether it handles the unhappy path gracefully. Anyone can make the happy path work. Name the edge case, handle it, test it. **Tone:** direct, concrete. Sound like a senior engineer in code review — not a consultant. "This will cause a race condition" beats "you may want to consider thread safety." **Concreteness is the standard.** Say `src/routes/users.ts:47` not "the user route." Say `422 Unprocessable Entity` not "an error response." **Writing rules:** - No em dashes. - No AI vocabulary: robust, comprehensive, seamless, leverage. - No throat-clearing. Just act. - End with the action. **User outcome test:** will this handle a malformed request? A DB timeout? A duplicate key? ``` The difference: gstack's Voice creates a CHARACTER with beliefs, not a style hint. ### 2. Workflow steps reference previous steps in prose **Wrong:** ```markdown 1. Read files: ```bash find . -name "*.ts" ``` 2. Install deps: ```bash npm install # BROKEN: $FRAMEWORK from step 1 doesn't exist here ``` ``` **Right:** ```markdown **Step 1: Read existing patterns**: ```bash find . -name "*.ts" | grep -E "(route|handler)" | head -10 ``` **Step 2: Identify the framework** — using the files found in Step 1: - `package.json` + `express` → Express.js. Check how routers are registered. - `pyproject.toml` + `fastapi` → FastAPI. Check if async or sync. ``` State passes via **prose** ("using Step 1 output"), not shell variables. ### 3. Completion Protocol is agent-specific, not generic **Wrong:** ```markdown ## Completion Protocol STATUS: DONE | BLOCKED | NEEDS_CONTEXT REASON: [if not DONE] ``` **Right:** ```markdown ## Completion Protocol STATUS: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT DONE: implementation complete, tests passing, unhappy paths handled. DONE_WITH_CONCERNS: working but e.g. "no rate limiting — add before prod". BLOCKED: state exactly what is missing (env var, broken dep, unclear requirement). NEEDS_CONTEXT: ask ONE specific question to unblock. ``` Each status gets a concrete description for THIS agent's domain. --- ## Frontmatter Fields Reference ```yaml name: kebab-case-name # required: lowercase, hyphens only description: | # required: block scalar, NOT quoted string ... # proactive trigger language important model: sonnet # opus | sonnet | haiku | inherit tools: # YAML list — only what the agent actually uses - Bash - Read color: blue # domain convention (see below) ``` ### model guidance - `opus` — orchestration, complex multi-step reasoning, architecture decisions - `sonnet` — most specialist agents (90% of cases) - `haiku` — fast, single-step, simple tasks - `inherit` — takes model from parent session ### color conventions | Domain | Color | |--------|-------| | backend | blue | | frontend | cyan | | devops | green | | security | red | | qa | yellow | | data | magenta | | product | white | | docs | cyan | | crypto | yellow | ### tools — only list what the agent actually uses | Tool | When | |------|------| | `Bash` | runs shell commands | | `Read` | reads files | | `Write` | creates new files | | `Edit` | modifies existing files | | `Grep` | searches file contents | | `Glob` | finds files by pattern | | `Agent` | spawns sub-agents | | `WebSearch` | searches the web | --- ## Good vs Bad Examples ### BAD — the anti-pattern we shipped first ```markdown --- name: backend-developer description: "Use this agent when building server-side APIs..." ← quoted, not block scalar tools: Read, Write, Edit, Bash, Glob, Grep ← comma-separated, wrong model: sonnet --- You are a senior backend developer with expertise in Node.js, Python, Go... ## Capabilities - REST APIs: resource modeling, HTTP methods, status codes... ← knowledge dump - GraphQL: schema design, resolvers... ← Claude already knows this [300 lines of bullet points] ## Voice Direct, concrete. ← 2 lines, no identity ``` Why it fails: no character, no beliefs, no writing rules, no outcome test. Just a capabilities list Claude already has in its weights. The agent behaves the same with or without it. ### GOOD — the gstack-inspired pattern See `backend-developer.md` and `bounty-hunter.md` in `agents/specialists/` for full examples. Key markers of a good agent: - Voice section has an identity sentence, a core principle, a tone comparison, writing rules, and an outcome test - Workflow steps reference previous steps in prose (not shell variables) - Each Completion Protocol status has a concrete domain-specific description - Trigger language in description includes "Proactively invoke when..."