architecture/old2/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    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

---
description: Work on a Gitea issue
argument-hint: <issue-number>
---

# Work on Issue #$1

1. **View the issue**: `tea issues $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	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

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

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

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

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

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: The philosophy and goals behind this project
• CLAUDE.md: Setup and configuration instructions
• README.md: Project overview and quick start