flowmade-one/architecture
3
0
Fork 0
Code Issues 15 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Add ARCHITECTURE.md documenting component architecture

Browse Source 
Explains how commands, skills, and agents work together as a
composable AI workflow system. Includes ASCII diagram, component
relationships, data flow examples, and guidance for adding new
components.

Closes #2

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Hugo Nijhuis
2025-12-28 23:28:42 +01:00
parent 324326adac
commit 801f044a54
1 changed files with 411 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

411
ARCHITECTURE.md Normal file
View File

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