diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..14afef8 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,411 @@ +# 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: +--- + +# Work on Issue #$1 + +1. **View the issue**: `fj issue view $1` +2. **Create a branch**: `git checkout -b issue-$1-` +... +``` + +#### 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 | + +--- + +### 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 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 + +```markdown +# Product Manager Agent + +Specialized agent for backlog management and roadmap planning. + +## Skills +- forgejo +- issue-writing +- backlog-grooming +- roadmap-planning + +## Capabilities +This agent can: +- Review and improve existing issues +- Create new well-structured issues +... +``` + +#### 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 | + +--- + +## 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 list their skills explicitly: + +```markdown +## 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 +├── agents/ # Specialized subagents +│ └── product-manager/ +│ └── 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. 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 + +--- + +## 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