architecture/ARCHITECTURE.md

# Architecture

This document explains how the three component types—Commands, Skills, and Agents—work together to create a composable AI workflow system.

## Overview

The architecture follows a layered composition model where each component type serves a distinct purpose:

```
┌─────────────────────────────────────────────────────────────────┐
│                         USER                                    │
│                           │                                     │
│                           ▼                                     │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                      COMMANDS                            │   │
│  │           User-facing entry points                       │   │
│  │   /work-issue  /dashboard  /plan-issues  /groom         │   │
│  └─────────────────────────────────────────────────────────┘   │
│                           │                                     │
│              ┌────────────┼────────────┐                       │
│              ▼            ▼            ▼                       │
│  ┌─────────────────┐ ┌─────────────────────────────────────┐   │
│  │     AGENTS      │ │              SKILLS                  │   │
│  │  Specialized    │ │         Knowledge modules            │   │
│  │   subagents     │ │                                      │   │
│  │                 │ │  issue-writing    forgejo            │   │
│  │ product-manager │ │  backlog-grooming roadmap-planning   │   │
│  └─────────────────┘ └─────────────────────────────────────┘   │
│              │                    ▲                            │
│              └────────────────────┘                            │
│                   Agents use skills                            │
└─────────────────────────────────────────────────────────────────┘
```

## Components

### Commands

**Location:** `commands/*.md`

Commands are user-facing entry points that trigger workflows. They define *what* to do, not *how* to do it.

#### Structure

Each command file contains:
- **Frontmatter**: Metadata including description and argument hints
- **Instructions**: Step-by-step workflow for Claude to follow
- **Tool references**: Which CLI tools or skills to invoke

```yaml
---
description: Work on a Forgejo issue
argument-hint: <issue-number>
---

# Work on Issue #$1

1. **View the issue**: `fj issue view $1`
2. **Create a branch**: `git checkout -b issue-$1-<title>`
...
```

#### Characteristics

- **Invoked explicitly** by users via `/command-name`
- **Self-contained workflows** with clear start and end
- **May use skills** for domain knowledge
- **May spawn agents** for complex subtasks
- **Request approval** before significant actions

#### When to Create a Command

Create a command when you have:
- A repeatable workflow with clear steps
- User-initiated action (not automatic)
- Need for consistent behavior across sessions

#### Current Commands

| Command | Purpose | Skills Used |
|---------|---------|-------------|
| `/work-issue` | Implement an issue end-to-end | forgejo |
| `/dashboard` | View open issues and PRs | forgejo |
| `/review-pr` | Review and act on a PR | forgejo |
| `/create-issue` | Create single or batch issues | forgejo, issue-writing |
| `/groom` | Improve issue quality | backlog-grooming, issue-writing |
| `/roadmap` | View issues organized by status | forgejo, roadmap-planning |
| `/plan-issues` | Break down features into issues | roadmap-planning, issue-writing, forgejo |

---

### Skills

**Location:** `skills/<skill-name>/SKILL.md`

Skills are knowledge modules—focused documents that teach Claude how to do something well. They encode domain expertise and best practices.

#### Structure

Each skill file contains:
- **Conceptual knowledge**: What Claude needs to understand
- **Patterns and templates**: Reusable structures
- **Guidelines and checklists**: Quality standards
- **Examples**: Concrete illustrations

```markdown
# Issue Writing

How to write clear, actionable issues.

## Issue Structure
### Title
- Start with action verb: "Add", "Fix", "Update"
- Be specific: "Add user authentication" not "Auth stuff"
...
```

#### Characteristics

- **Passive knowledge** that doesn't act on its own
- **Focused scope**: one domain, one concern
- **Composable**: multiple skills can be combined
- **Referenced** by commands and agents
- **No side effects**: information only

#### When to Create a Skill

Create a skill when you find yourself:
- Explaining the same concepts repeatedly
- Wanting consistent quality in a specific area
- Building up domain expertise that should persist

#### Current Skills

| Skill | Purpose |
|-------|---------|
| `forgejo` | How to use the Forgejo CLI for issues and PRs |
| `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 |

---

### Agents

**Location:** `agents/<agent-name>/AGENT.md`

Agents are specialized subagents that combine multiple skills into focused personas. They can work autonomously on complex tasks with isolated context.

#### Structure

Each agent file uses YAML frontmatter followed by a system prompt:

```markdown
---
name: agent-name
description: When this agent should be invoked (used for automatic delegation)
model: inherit
skills: skill1, skill2, skill3
---

You are a [role] specializing in [domain].

## Capabilities

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
- **Skill composition**: Combines multiple skills for complex tasks
- **Autonomous operation**: Can work with minimal intervention
- **Spawned by commands**: Commands decide when to use agents
- **Returns results**: Reports back to the main conversation

#### When to Create an Agent

Create an agent when you need:
- To combine multiple skills for a role
- Parallel processing of independent tasks
- Isolated context to prevent pollution
- Autonomous handling of complex workflows

#### Current Agents

| 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 |

---

## Data and Control Flow

### Invocation Flow

```
User invokes command
        │
        ▼
┌───────────────────┐
│ Command executes  │
│ workflow steps    │
└───────────────────┘
        │
        ├─── Direct action (git, fj CLI)
        │
        ├─── Reference skill for knowledge
        │           │
        │           ▼
        │    ┌─────────────────┐
        │    │ Skill provides  │
        │    │ patterns and    │
        │    │ guidelines      │
        │    └─────────────────┘
        │
        └─── Spawn agent for complex subtask
                    │
                    ▼
             ┌─────────────────┐
             │ Agent works     │
             │ autonomously    │
             │ with its skills │
             └─────────────────┘
                    │
                    ▼
             Results return to command
```

### Example: `/plan-issues add dark mode`

1. **Command invoked**: User runs `/plan-issues add dark mode`

2. **Skills consulted**:
   - `roadmap-planning`: How to break down features
   - `issue-writing`: How to structure each issue
   - `forgejo`: How to create issues via CLI

3. **Workflow executed**:
   - Analyze what "dark mode" involves
   - Break down into discrete issues
   - Present plan for approval
   - Create issues in dependency order

4. **Output**: Issues created with proper structure and references

### Example: `/groom` (batch mode)

1. **Command invoked**: User runs `/groom` with no argument

2. **Skills consulted**:
   - `backlog-grooming`: Checklist and evaluation criteria
   - `issue-writing`: Standards for improvements

3. **Potential agent spawn**: For many issues, could spawn `product-manager` agent

4. **Agent workflow**:
   - Fetches all open issues
   - Evaluates each against grooming checklist
   - Categorizes as ready/needs-work/stale
   - Proposes improvements

5. **Output**: Summary table with suggestions, optional issue updates

---

## Component Relationships

### How Commands Use Skills

Commands reference skills by name in their instructions:

```markdown
# Groom Issues

Use the backlog-grooming and issue-writing skills.
```

Claude reads the referenced skill files to gain the necessary knowledge before executing the command workflow.

### How Agents Use Skills

Agents declare their skills in the YAML frontmatter:

```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.

### How Commands Spawn Agents

Commands can delegate to agents for complex subtasks:

```markdown
For comprehensive backlog review, spawn the product-manager agent.
```

The agent works autonomously and returns results to the command.

---

## Design Principles

### Separation of Concerns

- **Commands**: Define workflows (what to do)
- **Skills**: Encode knowledge (how to do it well)
- **Agents**: Execute complex tasks (who does it)

### Composability

Small, focused components combine to handle complex scenarios:

```
/plan-issues = roadmap-planning + issue-writing + forgejo
product-manager = all four skills combined
```

### Single Responsibility

Each component has one clear purpose:
- One command = one workflow
- One skill = one domain
- One agent = one role

### Progressive Enhancement

Start simple, add complexity as needed:
1. Use skills directly for simple tasks
2. Create commands for repeatable workflows
3. Add agents for complex parallel work

---

## File Structure

```
ai/
├── commands/                    # User-invoked workflows
│   ├── work-issue.md
│   ├── dashboard.md
│   ├── review-pr.md
│   ├── create-issue.md
│   ├── groom.md
│   ├── roadmap.md
│   └── plan-issues.md
├── skills/                      # Knowledge modules
│   ├── forgejo/
│   │   └── SKILL.md
│   ├── issue-writing/
│   │   └── SKILL.md
│   ├── backlog-grooming/
│   │   └── SKILL.md
│   ├── roadmap-planning/
│   │   └── SKILL.md
│   └── code-review/
│       └── SKILL.md
├── agents/                      # Specialized subagents
│   ├── product-manager/
│   │   └── AGENT.md
│   └── code-reviewer/
│       └── AGENT.md
├── scripts/                     # Hook scripts
│   └── pre-commit-checks.sh
├── settings.json                # Claude Code configuration
├── CLAUDE.md                    # Project instructions
├── VISION.md                    # Why this project exists
└── ARCHITECTURE.md              # This document
```

---

## Adding New Components

### Adding a Command

1. Create `commands/<name>.md`
2. Add frontmatter with description and argument hints
3. Define the workflow steps
4. Reference any needed skills
5. Test the workflow

### Adding a Skill

1. Create `skills/<name>/SKILL.md`
2. Document the domain knowledge
3. Include patterns, templates, and examples
4. Reference from commands or agents as needed

### Adding an Agent

1. Create `agents/<name>/AGENT.md`
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

---

## See Also

- [VISION.md](VISION.md): The philosophy and goals behind this project
- [CLAUDE.md](CLAUDE.md): Setup and configuration instructions
- [README.md](README.md): Project overview and quick start