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:
-- **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
+Each agent file uses YAML frontmatter followed by a system prompt:
 
 ```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.
-
-## Skills
-- forgejo
-- issue-writing
-- backlog-grooming
-- roadmap-planning
+You are a [role] specializing in [domain].
 
 ## Capabilities
-This agent can:
-- Review and improve existing issues
-- Create new well-structured issues
-...
+
+You can:
+- 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
-## Skills
-- forgejo
-- issue-writing
-- backlog-grooming
+```yaml
+---
+name: product-manager
+skills: forgejo, issue-writing, 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
-3. Define capabilities and behavior
-4. Document when to spawn the agent
-5. Update commands to use the agent where appropriate
+2. Add YAML frontmatter with `name`, `description`, and `skills`
+3. Write system prompt defining capabilities and behavior
+4. Update commands to use the agent where appropriate
 
 ---