chore: move documentation files to old2 folder
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
426
old2/ARCHITECTURE.md
Normal file
426
old2/ARCHITECTURE.md
Normal file
@@ -0,0 +1,426 @@
|
||||
# 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: <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
|
||||
|
||||
```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
|
||||
Reference in New Issue
Block a user