diff --git a/CLAUDE.md b/CLAUDE.md index df52a07..4840dae 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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//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/.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//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 ` | 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. diff --git a/VISION.md b/VISION.md index 0a71bf8..e578903 100644 --- a/VISION.md +++ b/VISION.md @@ -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 diff --git a/agents/product-manager/AGENT.md b/agents/product-manager/AGENT.md deleted file mode 100644 index da1c7c4..0000000 --- a/agents/product-manager/AGENT.md +++ /dev/null @@ -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`