From 801f044a54e5203c97da527729af1edd74830f9f Mon Sep 17 00:00:00 2001
From: Hugo Nijhuis <hugo@flowmade.one>
Date: Sun, 28 Dec 2025 23:28:42 +0100
Subject: [PATCH] Add ARCHITECTURE.md documenting component architecture
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 ARCHITECTURE.md | 411 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 411 insertions(+)
 create mode 100644 ARCHITECTURE.md

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