Update agents to use YAML frontmatter format

- Update product-manager agent to use official Claude Code format
- Update ARCHITECTURE.md to document frontmatter fields
- Add code-reviewer agent and code-review skill to docs
- Update README.md project structure

This aligns our agent documentation with the official Claude Code
agent format which uses YAML frontmatter for name, description,
model, skills, and tools.

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

ARCHITECTURE.md

@@ -138,6 +138,7 @@ Create a skill when you find yourself:
 | `issue-writing` | How to structure clear, actionable issues |
 | `backlog-grooming` | How to review and improve existing issues |
 | `roadmap-planning` | How to plan features and create issue breakdowns |
+| `code-review` | How to review code for quality, bugs, security, and style |
 
 ---
 
@@ -149,30 +150,40 @@ Agents are specialized subagents that combine multiple skills into focused perso
 
 #### Structure
 
-Each agent file contains:
+Each agent file uses YAML frontmatter followed by a system prompt:
-- **Skills list**: Which skills the agent has access to
-- **Capabilities**: What the agent can do
-- **When to use**: Guidance on spawning the agent
-- **Behavior**: How the agent should operate
 
 ```markdown
-# Product Manager Agent
+---
+name: agent-name
+description: When this agent should be invoked (used for automatic delegation)
+model: inherit
+skills: skill1, skill2, skill3
+---
 
-Specialized agent for backlog management and roadmap planning.
+You are a [role] specializing in [domain].
-
-## Skills
-- forgejo
-- issue-writing
-- backlog-grooming
-- roadmap-planning
 
 ## Capabilities
-This agent can:
+
-- Review and improve existing issues
+You can:
-- Create new well-structured issues
+- Do thing one
-...
+- Do thing two
+
+## Behavior
+
+- Guideline one
+- Guideline two
 ```
 
+#### Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Unique identifier (lowercase, hyphens) |
+| `description` | Yes | When to use this agent (enables auto-delegation) |
+| `model` | No | `sonnet`, `opus`, `haiku`, or `inherit` |
+| `skills` | No | Comma-separated skill names to auto-load |
+| `tools` | No | Limit available tools (inherits all if omitted) |
+
 #### Characteristics
 
 - **Isolated context**: Each agent maintains separate conversation state
@@ -194,6 +205,7 @@ Create an agent when you need:
 | Agent | Skills | Use Case |
 |-------|--------|----------|
 | `product-manager` | forgejo, issue-writing, backlog-grooming, roadmap-planning | Batch issue operations, backlog reviews, feature planning |
+| `code-reviewer` | forgejo, code-review | Automated PR review, quality checks |
 
 ---
 
@@ -287,13 +299,13 @@ Claude reads the referenced skill files to gain the necessary knowledge before e
 
 ### How Agents Use Skills
 
-Agents list their skills explicitly:
+Agents declare their skills in the YAML frontmatter:
 
-```markdown
+```yaml
-## Skills
+---
-- forgejo
+name: product-manager
-- issue-writing
+skills: forgejo, issue-writing, backlog-grooming
-- backlog-grooming
+---
 ```
 
 When spawned, the agent has access to all listed skills as part of its context.
@@ -362,10 +374,14 @@ ai/
 │   │   └── SKILL.md
 │   ├── backlog-grooming/
 │   │   └── SKILL.md
-│   └── roadmap-planning/
+│   ├── roadmap-planning/
+│   │   └── SKILL.md
+│   └── code-review/
 │       └── SKILL.md
 ├── agents/                      # Specialized subagents
-│   └── product-manager/
+│   ├── product-manager/
+│   │   └── AGENT.md
+│   └── code-reviewer/
 │       └── AGENT.md
 ├── scripts/                     # Hook scripts
 │   └── pre-commit-checks.sh
@@ -397,10 +413,9 @@ ai/
 ### Adding an Agent
 
 1. Create `agents/<name>/AGENT.md`
-2. List the skills the agent needs
+2. Add YAML frontmatter with `name`, `description`, and `skills`
-3. Define capabilities and behavior
+3. Write system prompt defining capabilities and behavior
-4. Document when to spawn the agent
+4. Update commands to use the agent where appropriate
-5. Update commands to use the agent where appropriate
 
 ---
 

README.md

@@ -100,9 +100,11 @@ ai/
 │   ├── forgejo/        # Forgejo CLI integration
 │   ├── issue-writing/  # Issue structure best practices
 │   ├── backlog-grooming/  # Backlog maintenance
-│   └── roadmap-planning/  # Feature breakdown
+│   ├── roadmap-planning/  # Feature breakdown
+│   └── code-review/    # Code review best practices
 ├── agents/             # Specialized subagents
-│   └── product-manager/  # Combines skills for PM tasks
+│   ├── product-manager/  # Combines skills for PM tasks
+│   └── code-reviewer/  # Automated PR code review
 ├── scripts/            # Git hooks and utilities
 │   └── pre-commit-checks.sh
 ├── settings.json       # Claude Code configuration

agents/product-manager/AGENT.md

@@ -1,34 +1,24 @@
-# Product Manager Agent
+---
+name: product-manager
+description: Backlog management and roadmap planning specialist. Use for batch issue operations, comprehensive backlog reviews, or feature planning that requires codebase exploration.
+model: inherit
+skills: forgejo, issue-writing, backlog-grooming, roadmap-planning
+---
 
-Specialized agent for backlog management and roadmap planning.
+You are a product manager specializing in backlog management and roadmap planning.
-
-## Skills
-
-- forgejo
-- issue-writing
-- backlog-grooming
-- roadmap-planning
 
 ## Capabilities
 
-This agent can:
+You can:
 - Review and improve existing issues
 - Create new well-structured issues
 - Analyze the backlog for gaps and priorities
 - Plan feature breakdowns
 - Maintain roadmap clarity
 
-## 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
-
 ## Behavior
 
-- Always fetches current issue state before making changes
+- Always fetch current issue state before making changes
-- Asks for approval before creating or modifying issues
+- Ask for approval before creating or modifying issues
-- Provides clear summaries of actions taken
+- Provide clear summaries of actions taken
-- Uses the fj CLI for all Forgejo operations
+- Use the `fj` CLI for all Forgejo operations