# 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 gitea │ │ │ │ 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 Gitea issue argument-hint: --- # Work on Issue #$1 1. **View the issue**: `tea issues $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 | gitea | | `/dashboard` | View open issues and PRs | gitea | | `/review-pr` | Review and act on a PR | gitea | | `/create-issue` | Create single or batch issues | gitea, issue-writing | | `/groom` | Improve issue quality | backlog-grooming, issue-writing | | `/roadmap` | View issues organized by status | gitea, roadmap-planning | | `/plan-issues` | Break down features into issues | roadmap-planning, issue-writing, gitea | --- ### 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 | |-------|---------| | `gitea` | How to use the Gitea 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` | gitea, issue-writing, backlog-grooming, roadmap-planning | Batch issue operations, backlog reviews, feature planning | | `code-reviewer` | gitea, code-review | Automated PR review, quality checks | --- ## Data and Control Flow ### Invocation Flow ``` User invokes command │ ▼ ┌───────────────────┐ │ Command executes │ │ workflow steps │ └───────────────────┘ │ ├─── Direct action (git, tea 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 - `gitea`: 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: gitea, 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 + gitea 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 │ ├── gitea/ │ │ └── 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