From 4045c73507a3504b446a1ec7a72f1c676bfeb52c Mon Sep 17 00:00:00 2001
From: Hugo Nijhuis <hugo@flowmade.one>
Date: Sun, 28 Dec 2025 23:44:11 +0100
Subject: [PATCH] Add agent authoring guide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Create docs/writing-agents.md with comprehensive documentation for
writing new agents:
- File structure and naming conventions (agents/<name>/AGENT.md)
- How agents combine multiple skills into focused personas
- Use cases: parallel processing, context isolation, complex workflows,
  autonomous exploration
- When to use agents vs direct skill invocation with decision matrix
- Annotated walkthrough of product-manager agent
- Best practices for skill selection, boundaries, and guardrails

Closes #4

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 docs/writing-agents.md | 512 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 512 insertions(+)
 create mode 100644 docs/writing-agents.md

diff --git a/docs/writing-agents.md b/docs/writing-agents.md
new file mode 100644
index 0000000..c62c47b
--- /dev/null
+++ b/docs/writing-agents.md
@@ -0,0 +1,512 @@
+# Writing Agents
+
+A guide to creating specialized subagents that combine multiple skills for complex, context-isolated tasks.
+
+## What is an Agent?
+
+Agents are **specialized subprocesses** that combine multiple skills into focused personas. Unlike commands (which define workflows) or skills (which encode knowledge), agents are autonomous workers that can handle complex tasks independently.
+
+Think of agents as specialists you can delegate work to. They have their own context, their own expertise (via skills), and they report back when finished.
+
+## File Structure
+
+Agents live in the `agents/` directory, each in its own folder:
+
+```
+agents/
+└── product-manager/
+    └── AGENT.md
+```
+
+### Why AGENT.md?
+
+The uppercase `AGENT.md` filename:
+- Makes the agent file immediately visible in directory listings
+- Follows a consistent convention across all agents
+- Clearly identifies the primary file in an agent folder
+
+### Supporting Files (Optional)
+
+An agent folder can contain additional files if needed:
+
+```
+agents/
+└── code-reviewer/
+    ├── AGENT.md           # Main agent document (required)
+    └── checklists/        # Supporting materials
+        └── security.md
+```
+
+However, prefer keeping everything in `AGENT.md` when possible—agent definitions should be concise.
+
+## Agent Document Structure
+
+A well-structured `AGENT.md` follows this pattern:
+
+```markdown
+# Agent Name
+
+Brief description of what this agent does.
+
+## Skills
+List of skills this agent has access to.
+
+## Capabilities
+What the agent can do—its areas of competence.
+
+## When to Use
+Guidance on when to spawn this agent.
+
+## Behavior
+How the agent should operate—rules and constraints.
+```
+
+All sections are important:
+- **Skills**: Defines what knowledge the agent has
+- **Capabilities**: Tells spawners what to expect
+- **When to Use**: Prevents misuse and guides selection
+- **Behavior**: Sets expectations for operation
+
+## How Agents Combine Skills
+
+Agents gain their expertise by combining multiple skills. Each skill contributes domain knowledge to the agent's overall capability.
+
+### Skill Composition
+
+```
+┌────────────────────────────────────────────────┐
+│           Product Manager Agent                │
+│                                                │
+│  ┌──────────┐  ┌──────────────┐                │
+│  │ forgejo  │  │issue-writing │                │
+│  │          │  │              │                │
+│  │ CLI      │  │ Structure    │                │
+│  │ commands │  │ patterns     │                │
+│  └──────────┘  └──────────────┘                │
+│                                                │
+│  ┌──────────────────┐  ┌─────────────────┐     │
+│  │backlog-grooming  │  │roadmap-planning │     │
+│  │                  │  │                 │     │
+│  │ Review           │  │ Feature         │     │
+│  │ checklists       │  │ breakdown       │     │
+│  └──────────────────┘  └─────────────────┘     │
+│                                                │
+└────────────────────────────────────────────────┘
+```
+
+The agent can:
+- Use **forgejo** to interact with issues and PRs
+- Apply **issue-writing** patterns when creating content
+- Follow **backlog-grooming** checklists when reviewing
+- Use **roadmap-planning** strategies when breaking down features
+
+### Emergent Capabilities
+
+When skills combine, new capabilities emerge:
+
+| Skills Combined | Emergent Capability |
+|-----------------|---------------------|
+| forgejo + issue-writing | Create well-structured issues programmatically |
+| backlog-grooming + issue-writing | Improve existing issues systematically |
+| roadmap-planning + forgejo | Plan and create linked issue hierarchies |
+| All four skills | Full backlog management lifecycle |
+
+## Use Cases for Agents
+
+### 1. Parallel Processing
+
+Agents work independently with their own context. Spawn multiple agents to work on separate tasks simultaneously.
+
+```
+Command: /groom (batch mode)
+         │
+         ├─── Spawn Agent: Review issues #1-5
+         │
+         ├─── Spawn Agent: Review issues #6-10
+         │
+         └─── Spawn Agent: Review issues #11-15
+
+         ↓ (agents work in parallel)
+
+Results aggregated by command
+```
+
+**Use when:**
+- Tasks are independent and don't need to share state
+- Workload can be divided into discrete chunks
+- Speed matters more than sequential consistency
+
+### 2. Context Isolation
+
+Each agent maintains separate conversation state. This prevents context pollution when handling complex, unrelated subtasks.
+
+```
+Main Context                    Agent Context
+┌─────────────────┐            ┌─────────────────┐
+│ User working on │            │ Isolated work   │
+│ feature X       │   spawn    │ on backlog      │
+│                 │ ─────────► │ review          │
+│ (preserves      │            │                 │
+│  feature X      │   return   │ (doesn't know   │
+│  context)       │ ◄───────── │  about X)       │
+└─────────────────┘            └─────────────────┘
+```
+
+**Use when:**
+- Subtask requires deep exploration that would pollute main context
+- Work involves many files or concepts unrelated to main task
+- You want clean separation between different concerns
+
+### 3. Complex Workflows
+
+Some workflows are better handled by a specialized agent than by inline execution. Agents can make decisions, iterate, and adapt.
+
+```
+Command: /plan-issues "add user authentication"
+         │
+         └─── Spawn product-manager agent
+                   │
+                   ├── Explore codebase to understand structure
+                   ├── Research authentication patterns
+                   ├── Design issue breakdown
+                   ├── Create issues in dependency order
+                   └── Return summary to command
+```
+
+**Use when:**
+- Task requires iterative decision-making
+- Workflow has many steps that depend on intermediate results
+- Specialist expertise (via combined skills) adds value
+
+### 4. Autonomous Exploration
+
+Agents can explore codebases independently, building understanding without polluting the main conversation.
+
+**Use when:**
+- You need to understand a new part of the codebase
+- Exploration might involve many file reads and searches
+- Results should be summarized, not shown in full
+
+## When to Use an Agent vs Direct Skill Invocation
+
+### Use Direct Skill Invocation When:
+
+- **Simple, single-skill task**: Writing one issue doesn't need an agent
+- **Main context is relevant**: The current conversation context helps
+- **Quick reference needed**: Just need to check a pattern or command
+- **Sequential workflow**: Command can orchestrate step-by-step
+
+Example: Creating a single issue with `/create-issue`
+```
+Command reads issue-writing skill directly
+         │
+         └── Creates one issue following patterns
+```
+
+### Use an Agent When:
+
+- **Multiple skills needed together**: Complex tasks benefit from composition
+- **Context isolation required**: Don't want to pollute main conversation
+- **Parallel execution possible**: Can divide and conquer
+- **Autonomous exploration needed**: Agent can figure things out independently
+- **Specialist persona helps**: "Product manager" framing improves outputs
+
+Example: Grooming entire backlog with `/groom`
+```
+Command spawns product-manager agent
+         │
+         └── Agent iterates through all issues
+             using multiple skills
+```
+
+### Decision Matrix
+
+| Scenario | Agent? | Reason |
+|----------|--------|--------|
+| Create one issue | No | Single skill, simple task |
+| Review 20 issues | Yes | Batch processing, isolation |
+| Quick CLI lookup | No | Just need forgejo reference |
+| Plan new feature | Yes | Multiple skills, exploration |
+| Fix issue title | No | Trivial edit |
+| Reorganize backlog | Yes | Complex, multi-skill workflow |
+
+## Annotated Example: Product Manager Agent
+
+Let's examine the `product-manager` agent in detail:
+
+```markdown
+# Product Manager Agent
+
+Specialized agent for backlog management and roadmap planning.
+```
+
+**The opening** identifies the agent's role clearly. "Product Manager" is a recognizable persona that sets expectations.
+
+```markdown
+## Skills
+
+- forgejo
+- issue-writing
+- backlog-grooming
+- roadmap-planning
+```
+
+**Skills section** lists all knowledge the agent has access to. These skills are loaded into the agent's context when spawned. The combination enables:
+- Reading/writing issues (forgejo)
+- Creating quality content (issue-writing)
+- Evaluating existing issues (backlog-grooming)
+- Planning work strategically (roadmap-planning)
+
+```markdown
+## Capabilities
+
+This agent can:
+- Review and improve existing issues
+- Create new well-structured issues
+- Analyze the backlog for gaps and priorities
+- Plan feature breakdowns
+- Maintain roadmap clarity
+```
+
+**Capabilities section** tells spawners what to expect. Each capability maps to skill combinations:
+- "Review and improve" = backlog-grooming + issue-writing
+- "Create new issues" = forgejo + issue-writing
+- "Analyze backlog" = backlog-grooming + roadmap-planning
+- "Plan breakdowns" = roadmap-planning + issue-writing
+
+```markdown
+## When to Use
+
+Spawn this agent for:
+- Batch operations on multiple issues
+- Comprehensive backlog reviews
+- Feature planning that requires codebase exploration
+- Complex issue creation with dependencies
+```
+
+**When to Use section** guides appropriate usage. Note the criteria:
+- "Batch operations" → Parallel/isolation benefit
+- "Comprehensive reviews" → Complex workflow benefit
+- "Requires exploration" → Context isolation benefit
+- "Complex with dependencies" → Multi-skill benefit
+
+```markdown
+## Behavior
+
+- Always fetches current issue state before making changes
+- Asks for approval before creating or modifying issues
+- Provides clear summaries of actions taken
+- Uses the fj CLI for all Forgejo operations
+```
+
+**Behavior section** sets operational rules. These ensure:
+- Accuracy: Fetches current state, doesn't assume
+- Safety: Asks before acting
+- Transparency: Summarizes what happened
+- Consistency: Uses standard tooling
+
+## Naming Conventions
+
+### Agent Folder Names
+
+- Use **kebab-case**: `product-manager`, `code-reviewer`
+- Name by **role or persona**: what the agent "is"
+- Keep **recognizable**: familiar roles are easier to understand
+
+Good names:
+- `product-manager` - Recognizable role
+- `code-reviewer` - Clear function
+- `security-auditor` - Specific expertise
+- `documentation-writer` - Focused purpose
+
+Avoid:
+- `helper` - Too vague
+- `do-stuff` - Not a role
+- `issue-thing` - Not recognizable
+
+### Agent Titles
+
+The H1 title in `AGENT.md` should be the role name in Title Case:
+
+| Folder | Title |
+|--------|-------|
+| `product-manager` | Product Manager Agent |
+| `code-reviewer` | Code Reviewer Agent |
+| `security-auditor` | Security Auditor Agent |
+
+## Best Practices
+
+### 1. Choose Skills Deliberately
+
+Include only skills the agent needs. More skills = more context = potential confusion.
+
+**Too many skills:**
+```markdown
+## Skills
+- forgejo
+- issue-writing
+- backlog-grooming
+- roadmap-planning
+- code-review
+- testing
+- documentation
+- deployment
+```
+
+**Right-sized:**
+```markdown
+## Skills
+- forgejo
+- issue-writing
+- backlog-grooming
+- roadmap-planning
+```
+
+### 2. Define Clear Boundaries
+
+Agents should know what they can and cannot do.
+
+**Vague:**
+```markdown
+## Capabilities
+This agent can help with project management.
+```
+
+**Clear:**
+```markdown
+## Capabilities
+This agent can:
+- Review and improve existing issues
+- Create new well-structured issues
+- Analyze the backlog for gaps
+
+This agent cannot:
+- Merge pull requests
+- Deploy code
+- Make architectural decisions
+```
+
+### 3. Set Behavioral Guardrails
+
+Prevent agents from causing problems by setting explicit rules.
+
+**Important behaviors to specify:**
+- When to ask for approval
+- What to do before making changes
+- How to report results
+- Error handling expectations
+
+### 4. Match Persona to Purpose
+
+The agent's name and description should align with its skills and capabilities.
+
+**Mismatched:**
+```markdown
+# Security Agent
+
+## Skills
+- issue-writing
+- documentation
+```
+
+**Aligned:**
+```markdown
+# Security Auditor Agent
+
+## Skills
+- security-scanning
+- vulnerability-assessment
+- code-review
+```
+
+### 5. Keep Agents Focused
+
+One agent = one role. If an agent does too many unrelated things, split it.
+
+**Too broad:**
+```markdown
+# Everything Agent
+Handles issues, code review, deployment, and customer support.
+```
+
+**Focused:**
+```markdown
+# Product Manager Agent
+Specialized for backlog management and roadmap planning.
+```
+
+## When to Create a New Agent
+
+Create an agent when you need:
+
+1. **Role-based expertise**: A recognizable persona improves outputs
+2. **Skill composition**: Multiple skills work better together
+3. **Context isolation**: Work shouldn't pollute main conversation
+4. **Parallel capability**: Tasks can run independently
+5. **Autonomous operation**: Agent should figure things out on its own
+
+### Signs You Need a New Agent
+
+- Commands repeatedly spawn similar skill combinations
+- Tasks require deep exploration that pollutes context
+- Work benefits from a specialist "persona"
+- Batch processing would help
+
+### Signs You Don't Need a New Agent
+
+- Single skill is sufficient
+- Task is simple and sequential
+- Main context is helpful, not harmful
+- No clear persona or role emerges
+
+## Agent Lifecycle
+
+### 1. Design
+
+Define the agent's role:
+- What persona makes sense?
+- Which skills does it need?
+- What can it do (and not do)?
+- When should it be spawned?
+
+### 2. Implement
+
+Create the agent file:
+- Clear name and description
+- Appropriate skill list
+- Specific capabilities
+- Usage guidance
+- Behavioral rules
+
+### 3. Integrate
+
+Connect the agent to workflows:
+- Update commands that should spawn it
+- Document in ARCHITECTURE.md
+- Test with real tasks
+
+### 4. Refine
+
+Improve based on usage:
+- Add/remove skills as needed
+- Clarify capabilities
+- Strengthen behavioral rules
+- Update documentation
+
+## Checklist: Before Submitting a New Agent
+
+- [ ] File is at `agents/<name>/AGENT.md`
+- [ ] Name follows kebab-case convention
+- [ ] Agent has a clear, recognizable role
+- [ ] Skills list is deliberate (not too many, not too few)
+- [ ] Capabilities are specific and achievable
+- [ ] "When to Use" guidance is clear
+- [ ] Behavioral rules prevent problems
+- [ ] Agent is referenced by at least one command
+- [ ] ARCHITECTURE.md is updated
+
+## See Also
+
+- [ARCHITECTURE.md](../ARCHITECTURE.md): How agents fit into the overall system
+- [writing-skills.md](writing-skills.md): Creating the skills that agents use
+- [VISION.md](../VISION.md): The philosophy behind composable components