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

Clarify agent architecture: small focused subtasks, not broad personas

Browse Source 
- Remove product-manager agent (too broad, not being used)
- Update vision.md: agents are small, isolated, result-oriented
- Update CLAUDE.md: add Architecture section explaining skills/commands/agents

🤖 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
2026-01-01 22:49:42 +01:00
parent 28242d44cc
commit e1ed17e2bf
3 changed files with 61 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
CLAUDE.md
View File

@@ -16,8 +16,8 @@ make install
```
ai/
├── commands/ # Slash commands (/work-issue, /dashboard)
├── skills/ # Auto-triggered capabilities
├── agents/ # Subagents with isolated context
├── skills/ # Knowledge modules (auto-triggered)
├── agents/ # Focused subtask handlers (isolated context)
├── scripts/ # Hook scripts (pre-commit, token loading)
├── settings.json # Claude Code settings
└── Makefile # Install/uninstall symlinks
@@ -25,6 +25,42 @@ ai/
All files symlink to `~/.claude/` via `make install`.
## Architecture
### Skills
Knowledge modules that teach Claude how to do something. Referenced by commands via `@~/.claude/skills/xxx/SKILL.md`.
- **Purpose**: Encode best practices and tool knowledge
- **Location**: `skills/<name>/SKILL.md`
- **Usage**: Included in commands for context, auto-triggered by Claude Code
Example: `gitea` skill teaches tea CLI usage, `issue-writing` teaches how to structure issues.
### Commands
User-facing entry points invoked with `/command-name`. Run in main conversation context.
- **Purpose**: Orchestrate workflows with user interaction
- **Location**: `commands/<name>.md`
- **Usage**: User types `/dashboard`, `/work-issue 42`, etc.
Commands reference skills for knowledge and optionally spawn agents for subtasks.
### Agents
Small, focused units that handle specific subtasks in isolated context.
- **Purpose**: Complex subtasks that benefit from isolation
- **Location**: `agents/<name>/agent.md`
- **Usage**: Spawned via Task tool, return results to caller
Good agent candidates:
- Code review (analyze diff, report issues)
- Content generation (write issue body, PR description)
- Analysis tasks (categorize, prioritize, summarize)
**When to use agents vs direct execution:**
- Use agents when: task is self-contained, benefits from isolation, can run in parallel
- Use direct execution when: task needs conversation history, requires user interaction mid-task
## Gitea Integration
Uses `tea` CLI for issue/PR management:
@@ -37,7 +73,7 @@ tea logins add --name flowmade --url https://git.flowmade.one --token <your-toke
# Create token at: https://git.flowmade.one/user/settings/applications
```
### Available Commands
## Available Commands
| Command | Description |
|---------|-------------|
@@ -45,8 +81,11 @@ tea logins add --name flowmade --url https://git.flowmade.one --token <your-toke
| `/dashboard` | Show open issues and PRs |
| `/review-pr <n>` | Review PR with diff and comments |
| `/create-issue` | Create single or batch issues |
| `/retro` | Capture learnings from completed work, create improvement issues |
| `/retro` | Capture learnings, create improvement issues |
| `/vision` | View/manage product vision and milestones |
| `/plan-issues` | Break down features into issues |
| `/improve` | Identify gaps between vision and backlog |
## Usage
## Vision & Goals
This project is meant to be used alongside Claude Code to enhance productivity and maintain consistent workflows.
Product vision lives in `vision.md` (philosophy) and Gitea milestones (goals with progress tracking). See `/vision` command.