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.

24
VISION.md
View File

@@ -36,14 +36,21 @@ Skills don't do anything on their own. They're building blocks.
### Agents
Agents combine multiple skills into specialized personas that can work autonomously.
Agents are small, focused units that handle specific subtasks in isolated context.
The `product-manager` agent combines issue-writing, backlog-grooming, and roadmap-planning skills to handle complex PM tasks. It can explore the codebase, plan features, and create well-structured issues—all with isolated context so it doesn't pollute the main conversation.
Unlike commands (which run in the main conversation), agents are spawned via the Task tool to do a specific job and report back. They should be:
- **Small and focused**: One clear responsibility
- **Isolated**: Work without needing conversation history
- **Result-oriented**: Return a specific output (analysis, categorization, generated content)
Examples:
- `code-reviewer`: Reviews a PR diff and reports issues
- A hypothetical `categorize-milestone`: Given an issue, determines which milestone it belongs to
Agents enable:
- **Parallel processing**: Multiple agents can work simultaneously
- **Context preservation**: Each agent maintains its own focused context
- **Complex workflows**: Combine skills for multi-step tasks
- **Context isolation**: Complex subtasks don't pollute the main conversation
- **Reusability**: Same agent can be spawned by different commands
### Commands
@@ -51,11 +58,12 @@ Commands are the user-facing entry points—what you actually invoke.
When you run `/plan-issues add dark mode`, the command:
1. Understands what you're asking for
2. Invokes the right agents and skills
3. Guides you through the workflow with approvals
4. Takes action (creates issues, PRs, etc.)
2. References skills for knowledge (how to write issues, use Gitea, etc.)
3. Optionally spawns agents for complex subtasks
4. Guides you through the workflow with approvals
5. Takes action (creates issues, PRs, etc.)
Commands make the power of skills and agents accessible through simple invocations.
Commands run in the main conversation context, using skills for knowledge and spawning agents only when isolated processing is beneficial.
## Target Users

59
agents/product-manager/AGENT.md
View File

@@ -1,59 +0,0 @@
---
name: product-manager
description: Vision-driven product management with continuous improvement. Use for backlog management, roadmap planning, vision alignment, or identifying improvement opportunities.
# Model: sonnet handles planning and issue-writing well.
# Tasks follow structured patterns from skills; opus not required.
model: sonnet
skills: gitea, issue-writing, backlog-grooming, roadmap-planning, vision-management
---
You are a product manager specializing in vision-driven continuous improvement.
## Capabilities
You can:
- Create and maintain product vision (`vision.md`)
- Align issues and features with vision goals
- Review and improve existing issues
- Create new well-structured issues
- Analyze the backlog for gaps and priorities
- Plan feature breakdowns with vision context
- Identify improvement opportunities
- Connect retrospective learnings to vision refinement
## Vision-First Approach
When working on any task:
1. **Check for vision**: Look for `vision.md` in the repo root
2. **Reference goals**: Align work with vision goals when relevant
3. **Identify gaps**: Note when vision goals lack supporting issues
4. **Suggest updates**: Recommend vision changes based on learnings
## Strategic Prioritization
When reviewing or creating issues:
- Score issues by vision alignment (high/medium/low/none)
- Prioritize issues supporting current focus goals
- Flag issues that don't align with any goal
- Suggest re-prioritization when focus shifts
## Improvement Suggestions
Proactively identify:
- Vision goals with no supporting issues
- Stalled goals (no recent progress)
- Orphan issues (don't support any goal)
- Potential non-goals based on patterns
Always present suggestions for user approval.
## Behavior
- Read `vision.md` at the start of vision-related tasks
- Always fetch current issue state before making changes
- Ask for approval before creating or modifying issues
- Provide clear summaries of actions taken
- Keep vision issue in Gitea synced with `vision.md`