refactor: migrate commands to user-invocable skills
Claude Code has unified commands into skills with the user-invocable frontmatter field. This migration: - Converts 20 commands to skills with user-invocable: true - Consolidates docs into single writing-capabilities.md - Rewrites capability-writing skill for unified model - Updates CLAUDE.md, Makefile, and other references - Removes commands/ directory Skills now have two types: - user-invocable: true - workflows users trigger with /name - user-invocable: false - background knowledge auto-loaded Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
170
skills/arch-refine-issue/SKILL.md
Normal file
170
skills/arch-refine-issue/SKILL.md
Normal file
@@ -0,0 +1,170 @@
|
||||
---
|
||||
name: arch-refine-issue
|
||||
description: >
|
||||
Refine an issue with architectural perspective. Analyzes existing codebase patterns
|
||||
and provides implementation guidance. Use when refining issues, adding architectural
|
||||
context, or when user says /arch-refine-issue.
|
||||
model: opus
|
||||
argument-hint: <issue-number>
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Architecturally Refine Issue #$1
|
||||
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
@~/.claude/skills/issue-writing/SKILL.md
|
||||
|
||||
## Overview
|
||||
|
||||
Refine an issue in the context of the project's architecture. This command:
|
||||
1. Fetches the issue details
|
||||
2. Spawns the software-architect agent to analyze the codebase
|
||||
3. Identifies how the issue fits existing patterns
|
||||
4. Proposes refined description and acceptance criteria
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Fetch Issue Details
|
||||
|
||||
```bash
|
||||
tea issues $1 --comments
|
||||
```
|
||||
|
||||
Capture:
|
||||
- Title
|
||||
- Description
|
||||
- Acceptance criteria
|
||||
- Any existing discussion
|
||||
|
||||
### Step 2: Spawn Software-Architect Agent
|
||||
|
||||
Use the Task tool to spawn the software-architect agent for issue refinement analysis:
|
||||
|
||||
```
|
||||
Task tool with:
|
||||
- subagent_type: "software-architect"
|
||||
- prompt: See prompt below
|
||||
```
|
||||
|
||||
**Agent Prompt:**
|
||||
```
|
||||
Analyze the architecture for issue refinement.
|
||||
|
||||
ANALYSIS_TYPE: issue-refine
|
||||
TARGET: $1
|
||||
CONTEXT:
|
||||
<issue title and description from step 1>
|
||||
|
||||
Repository path: <current working directory>
|
||||
|
||||
Focus on:
|
||||
1. Understanding existing project structure and patterns
|
||||
2. Identifying packages/modules that will be affected
|
||||
3. Analyzing existing conventions and code style
|
||||
4. Detecting potential architectural concerns
|
||||
5. Suggesting implementation approach that fits existing patterns
|
||||
```
|
||||
|
||||
### Step 3: Parse Agent Analysis
|
||||
|
||||
The software-architect agent returns structured output with:
|
||||
- Summary of architectural findings
|
||||
- Affected packages/modules
|
||||
- Pattern recommendations
|
||||
- Potential concerns (breaking changes, tech debt, pattern violations)
|
||||
- Implementation suggestions
|
||||
|
||||
### Step 4: Present Refinement Proposal
|
||||
|
||||
Present the refined issue to the user with:
|
||||
|
||||
**1. Architectural Context**
|
||||
- Affected packages/modules
|
||||
- Existing patterns that apply
|
||||
- Dependency implications
|
||||
|
||||
**2. Concerns and Risks**
|
||||
- Breaking changes
|
||||
- Tech debt considerations
|
||||
- Pattern violations to avoid
|
||||
|
||||
**3. Proposed Refinement**
|
||||
- Refined description with architectural context
|
||||
- Updated acceptance criteria (if needed)
|
||||
- Technical notes section
|
||||
|
||||
**4. Implementation Guidance**
|
||||
- Suggested approach
|
||||
- Files likely to be modified
|
||||
- Recommended order of changes
|
||||
|
||||
### Step 5: User Decision
|
||||
|
||||
Ask the user what action to take:
|
||||
|
||||
- **Apply**: Update the issue with refined description and technical notes
|
||||
- **Edit**: Let user modify the proposal before applying
|
||||
- **Skip**: Keep the original issue unchanged
|
||||
|
||||
### Step 6: Update Issue (if approved)
|
||||
|
||||
If user approves, update the issue using tea CLI:
|
||||
|
||||
```bash
|
||||
tea issues edit $1 --description "<refined description>"
|
||||
```
|
||||
|
||||
Add a comment with the architectural analysis:
|
||||
|
||||
```bash
|
||||
tea comment $1 "## Architectural Analysis
|
||||
|
||||
<findings from software-architect agent>
|
||||
|
||||
---
|
||||
Generated by /arch-refine-issue"
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
Present findings in a clear, actionable format:
|
||||
|
||||
```markdown
|
||||
## Architectural Analysis for Issue #$1
|
||||
|
||||
### Affected Components
|
||||
- `package/name` - Description of impact
|
||||
- `another/package` - Description of impact
|
||||
|
||||
### Existing Patterns
|
||||
- Pattern 1: How it applies
|
||||
- Pattern 2: How it applies
|
||||
|
||||
### Concerns
|
||||
- [ ] Breaking change: description (if applicable)
|
||||
- [ ] Tech debt: description (if applicable)
|
||||
- [ ] Pattern violation risk: description (if applicable)
|
||||
|
||||
### Proposed Refinement
|
||||
|
||||
**Updated Description:**
|
||||
<refined description>
|
||||
|
||||
**Updated Acceptance Criteria:**
|
||||
- [ ] Original criteria (unchanged)
|
||||
- [ ] New criteria based on analysis
|
||||
|
||||
**Technical Notes:**
|
||||
<implementation guidance based on architecture>
|
||||
|
||||
### Recommended Approach
|
||||
1. Step 1
|
||||
2. Step 2
|
||||
3. Step 3
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
- If issue does not exist, inform user
|
||||
- If software-architect agent fails, report partial analysis
|
||||
- If tea CLI fails, show manual instructions
|
||||
79
skills/arch-review-repo/SKILL.md
Normal file
79
skills/arch-review-repo/SKILL.md
Normal file
@@ -0,0 +1,79 @@
|
||||
---
|
||||
name: arch-review-repo
|
||||
description: >
|
||||
Perform a full architecture review of the current repository. Analyzes structure,
|
||||
patterns, dependencies, and generates prioritized recommendations. Use when reviewing
|
||||
architecture, auditing codebase, or when user says /arch-review-repo.
|
||||
model: opus
|
||||
argument-hint:
|
||||
context: fork
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
@~/.claude/skills/software-architecture/SKILL.md
|
||||
|
||||
## Process
|
||||
|
||||
1. **Identify the repository**: Use the current working directory as the repository path.
|
||||
|
||||
2. **Spawn the software-architect agent** for deep analysis:
|
||||
|
||||
```
|
||||
ANALYSIS_TYPE: repo-audit
|
||||
TARGET: <repository-path>
|
||||
CONTEXT: Full repository architecture review
|
||||
```
|
||||
|
||||
The agent will:
|
||||
- Analyze directory structure and package organization
|
||||
- Identify patterns and anti-patterns in the codebase
|
||||
- Assess dependency graph and module boundaries
|
||||
- Review test coverage approach
|
||||
- Generate structured findings with prioritized recommendations
|
||||
|
||||
3. **Present the results** to the user in this format:
|
||||
|
||||
```markdown
|
||||
## Repository Architecture Review: <repo-name>
|
||||
|
||||
### Structure: <Good|Needs Work>
|
||||
- [Key observations about package organization]
|
||||
- [Directory structure assessment]
|
||||
- [Naming conventions evaluation]
|
||||
|
||||
### Patterns Identified
|
||||
- [Positive patterns found in the codebase]
|
||||
- [Architectural styles detected (layered, hexagonal, etc.)]
|
||||
|
||||
### Anti-Patterns Detected
|
||||
- [Anti-pattern name]: [Location and description]
|
||||
- [Anti-pattern name]: [Location and description]
|
||||
|
||||
### Concerns
|
||||
- [Specific issues that need attention]
|
||||
- [Technical debt areas]
|
||||
|
||||
### Recommendations (prioritized)
|
||||
1. **P0 - Critical**: [Most urgent recommendation]
|
||||
2. **P1 - High**: [Important improvement]
|
||||
3. **P2 - Medium**: [Nice-to-have improvement]
|
||||
4. **P3 - Low**: [Minor optimization]
|
||||
|
||||
### Health Score: <A|B|C|D|F>
|
||||
[Brief justification for the grade]
|
||||
```
|
||||
|
||||
4. **Offer follow-up actions**:
|
||||
- Create issues for critical findings
|
||||
- Generate a detailed report
|
||||
- Review specific components in more depth
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Be specific: Reference exact files, packages, and locations
|
||||
- Be actionable: Every finding should have a clear path to resolution
|
||||
- Be balanced: Acknowledge what the codebase does well
|
||||
- Be proportionate: Focus on high-impact issues first
|
||||
- Stay objective: Focus on patterns and principles, not style preferences
|
||||
@@ -2,23 +2,23 @@
|
||||
name: capability-writing
|
||||
description: >
|
||||
Guide for designing and creating capabilities for the architecture repository.
|
||||
A capability is a cohesive set of components (skill + command + agent).
|
||||
Use when creating new skills, commands, or agents, or when extending the
|
||||
A capability is a cohesive set of components (skill + agent).
|
||||
Use when creating new skills, agents, or extending the
|
||||
AI workflow system. Includes templates, design guidance, and conventions.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Capability Writing
|
||||
|
||||
How to design and create capabilities for the architecture repository. A capability is often a cohesive set of components (skill + command + agent) that work together.
|
||||
How to design and create capabilities for the architecture repository. A capability may be a single component or a cohesive set (skill + agent).
|
||||
|
||||
## Component Overview
|
||||
|
||||
| Component | Location | Purpose | Example |
|
||||
|-----------|----------|---------|---------|
|
||||
| **Skill** | `skills/name/SKILL.md` | Knowledge Claude applies automatically | software-architecture |
|
||||
| **Command** | `commands/name.md` | User-invoked workflow entry point | /work-issue |
|
||||
| **Agent** | `agents/name/AGENT.md` | Isolated subtask handler with focused context | code-reviewer |
|
||||
| **User-invocable Skill** | `skills/name/SKILL.md` | Workflow users trigger with `/name` | /work-issue, /dashboard |
|
||||
| **Background Skill** | `skills/name/SKILL.md` | Knowledge auto-loaded when needed | gitea, issue-writing |
|
||||
| **Agent** | `agents/name/AGENT.md` | Isolated subtask handler | code-reviewer |
|
||||
|
||||
## When to Use Each Component
|
||||
|
||||
@@ -28,36 +28,36 @@ How to design and create capabilities for the architecture repository. A capabil
|
||||
Start here: What do you need?
|
||||
|
|
||||
+--> Just knowledge to apply automatically?
|
||||
| --> Skill only
|
||||
| --> Background skill (user-invocable: false)
|
||||
|
|
||||
+--> User-initiated workflow using existing knowledge?
|
||||
| --> Command (reference skills via @)
|
||||
+--> User-initiated workflow?
|
||||
| --> User-invocable skill (user-invocable: true)
|
||||
|
|
||||
+--> Complex isolated work needing focused context?
|
||||
| --> Command + Agent (agent uses skills)
|
||||
| --> User-invocable skill + Agent
|
||||
|
|
||||
+--> New domain expertise + workflow + isolated work?
|
||||
--> Full capability (all three)
|
||||
--> Full capability (background skill + user-invocable skill + agent)
|
||||
```
|
||||
|
||||
### Decision Matrix
|
||||
|
||||
| Need | Component | Example |
|
||||
|------|-----------|---------|
|
||||
| Knowledge Claude should apply automatically | Skill | software-architecture, issue-writing |
|
||||
| User-invoked workflow | Command | /work-issue, /dashboard |
|
||||
| Knowledge Claude applies automatically | Background skill | gitea, issue-writing |
|
||||
| User-invoked workflow | User-invocable skill | /work-issue, /dashboard |
|
||||
| Isolated subtask with focused context | Agent | code-reviewer, issue-worker |
|
||||
| All three working together | Full capability | arch-review (skill + command + agent) |
|
||||
| All three working together | Full capability | architecture review |
|
||||
|
||||
### Signs You Need Each Component
|
||||
|
||||
**Create a Skill when:**
|
||||
**Create a Background Skill when:**
|
||||
- You explain the same concepts repeatedly
|
||||
- Quality is inconsistent without explicit guidance
|
||||
- Multiple commands need the same knowledge
|
||||
- There is a clear domain that does not fit existing skills
|
||||
- Multiple user-invocable skills need the same knowledge
|
||||
- There is a clear domain that doesn't fit existing skills
|
||||
|
||||
**Create a Command when:**
|
||||
**Create a User-Invocable Skill when:**
|
||||
- Same workflow is used multiple times
|
||||
- User explicitly triggers the action
|
||||
- Approval checkpoints are needed
|
||||
@@ -71,7 +71,47 @@ Start here: What do you need?
|
||||
|
||||
## Component Templates
|
||||
|
||||
### Skill Template
|
||||
### User-Invocable Skill Template
|
||||
|
||||
Location: `skills/<name>/SKILL.md`
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: skill-name
|
||||
description: >
|
||||
What this skill does and when to use it.
|
||||
Use when [trigger conditions] or when user says /skill-name.
|
||||
model: haiku
|
||||
argument-hint: <required> [optional]
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Skill Title
|
||||
|
||||
@~/.claude/skills/relevant-skill/SKILL.md
|
||||
|
||||
Brief intro if needed.
|
||||
|
||||
1. **First step**: What to do
|
||||
2. **Second step**: What to do next
|
||||
3. **Ask for approval** before significant actions
|
||||
4. **Execute** the approved actions
|
||||
5. **Present results** with links and summary
|
||||
```
|
||||
|
||||
**Frontmatter fields:**
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `name` | Yes | Lowercase, hyphens, matches directory name |
|
||||
| `description` | Yes | What it does + when to use (max 1024 chars) |
|
||||
| `user-invocable` | Yes | Set `true` for user-triggered workflows |
|
||||
| `argument-hint` | No | Shows expected args: `<required>`, `[optional]` |
|
||||
| `model` | No | `haiku`, `sonnet`, `opus` |
|
||||
| `context` | No | Use `fork` for isolated context |
|
||||
| `allowed-tools` | No | Restrict available tools |
|
||||
|
||||
### Background Skill Template
|
||||
|
||||
Location: `skills/<name>/SKILL.md`
|
||||
|
||||
@@ -80,8 +120,7 @@ Location: `skills/<name>/SKILL.md`
|
||||
name: skill-name
|
||||
description: >
|
||||
What this skill teaches and when to use it.
|
||||
Include trigger conditions in description (not body).
|
||||
List specific capabilities users would mention.
|
||||
Include trigger conditions in description.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
@@ -114,49 +153,6 @@ Document pitfalls to avoid.
|
||||
Quick-reference tables, checklists, or commands.
|
||||
```
|
||||
|
||||
**Frontmatter fields:**
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `name` | Yes | Lowercase, hyphens, matches directory name |
|
||||
| `description` | Yes | What it does + when to use (max 1024 chars) |
|
||||
| `user-invocable` | No | Set `false` for reference-only skills |
|
||||
| `model` | No | Specific model: `haiku`, `sonnet`, `opus` |
|
||||
| `context` | No | Use `fork` for isolated context |
|
||||
| `allowed-tools` | No | Restrict available tools |
|
||||
|
||||
### Command Template
|
||||
|
||||
Location: `commands/<name>.md`
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: What this command does (one-line summary)
|
||||
argument-hint: <required> [optional]
|
||||
model: haiku
|
||||
---
|
||||
|
||||
# Command Title
|
||||
|
||||
@~/.claude/skills/relevant-skill/SKILL.md
|
||||
|
||||
1. **First step**: What to do
|
||||
2. **Second step**: What to do next
|
||||
3. **Ask for approval** before significant actions
|
||||
4. **Execute** the approved actions
|
||||
5. **Present results** with links and summary
|
||||
```
|
||||
|
||||
**Frontmatter fields:**
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `description` | Yes | One-line summary for help/listings |
|
||||
| `argument-hint` | No | Shows expected args: `<required>`, `[optional]` |
|
||||
| `model` | No | Override model: `haiku`, `sonnet`, `opus` |
|
||||
| `context` | No | Use `fork` for isolated context |
|
||||
| `allowed-tools` | No | Restrict available tools |
|
||||
|
||||
### Agent Template
|
||||
|
||||
Location: `agents/<name>/AGENT.md`
|
||||
@@ -165,7 +161,7 @@ Location: `agents/<name>/AGENT.md`
|
||||
---
|
||||
name: agent-name
|
||||
description: What this agent does and when to spawn it
|
||||
model: haiku
|
||||
model: sonnet
|
||||
skills: skill1, skill2
|
||||
disallowedTools:
|
||||
- Edit
|
||||
@@ -210,13 +206,13 @@ Describe expected output structure.
|
||||
| Model | Use When | Examples |
|
||||
|-------|----------|----------|
|
||||
| `haiku` | Simple fetch/display, formatting, mechanical tasks | /dashboard, /roadmap |
|
||||
| `sonnet` | Most commands and agents, balanced performance | /work-issue, issue-worker, code-reviewer |
|
||||
| `opus` | Deep reasoning, architectural analysis, complex judgment | software-architect, security auditor |
|
||||
| `sonnet` | Most skills and agents, balanced performance | /work-issue, code-reviewer |
|
||||
| `opus` | Deep reasoning, architectural analysis, complex judgment | /arch-review-repo |
|
||||
|
||||
### Decision Criteria
|
||||
|
||||
- **Start with `sonnet`** - handles most tasks well
|
||||
- **Use `haiku` for volume** - speed and cost matter at scale
|
||||
- **Start with `haiku`** for simple display/fetch workflows
|
||||
- **Use `sonnet`** for most skills and agents (default choice)
|
||||
- **Reserve `opus` for judgment** - when errors are costly or reasoning is complex
|
||||
- **Consider the stakes** - higher consequence tasks warrant more capable models
|
||||
|
||||
@@ -226,31 +222,26 @@ Describe expected output structure.
|
||||
|
||||
| Component | Convention | Examples |
|
||||
|-----------|------------|----------|
|
||||
| Skill folder | kebab-case | `software-architecture`, `issue-writing` |
|
||||
| Skill folder | kebab-case | `software-architecture`, `work-issue` |
|
||||
| Skill file | UPPERCASE | `SKILL.md` |
|
||||
| Command file | kebab-case | `work-issue.md`, `review-pr.md` |
|
||||
| Agent folder | kebab-case | `code-reviewer`, `issue-worker` |
|
||||
| Agent file | UPPERCASE | `AGENT.md` |
|
||||
|
||||
### Naming Patterns
|
||||
|
||||
**Skills:** Name after the domain or knowledge area
|
||||
- Good: `gitea`, `issue-writing`, `software-architecture`
|
||||
**Skills:** Name after the domain, knowledge area, or action
|
||||
- Good: `gitea`, `issue-writing`, `work-issue`, `dashboard`
|
||||
- Bad: `utils`, `helpers`, `misc`
|
||||
|
||||
**Commands:** Use verb or verb-phrase (actions)
|
||||
- Good: `work-issue`, `review-pr`, `create-issue`
|
||||
- Bad: `issue-work`, `pr-review`, `issue`
|
||||
|
||||
**Agents:** Name by role or persona (recognizable specialist)
|
||||
- Good: `code-reviewer`, `issue-worker`, `software-architect`
|
||||
- Bad: `helper`, `do-stuff`, `agent1`
|
||||
|
||||
## Referencing Skills
|
||||
|
||||
### In Commands
|
||||
### In User-Invocable Skills
|
||||
|
||||
Use the `@` file reference syntax to guarantee skill content is loaded:
|
||||
Use the `@` file reference syntax to guarantee background skill content is loaded:
|
||||
|
||||
```markdown
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
@@ -274,7 +265,7 @@ The agent runtime loads these skills automatically.
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Approval Workflow (Commands)
|
||||
### Approval Workflow (User-Invocable Skills)
|
||||
|
||||
Always ask before significant actions:
|
||||
|
||||
@@ -284,7 +275,7 @@ Always ask before significant actions:
|
||||
6. **Present summary** with links
|
||||
```
|
||||
|
||||
### Conditional Behavior (Commands)
|
||||
### Conditional Behavior (User-Invocable Skills)
|
||||
|
||||
Handle optional arguments with mode switching:
|
||||
|
||||
@@ -298,7 +289,7 @@ Handle optional arguments with mode switching:
|
||||
2. Process each
|
||||
```
|
||||
|
||||
### Spawning Agents from Commands
|
||||
### Spawning Agents from Skills
|
||||
|
||||
Delegate complex subtasks:
|
||||
|
||||
@@ -323,7 +314,7 @@ disallowedTools:
|
||||
|
||||
### Overly Broad Components
|
||||
|
||||
**Bad:** One skill/command/agent that does everything
|
||||
**Bad:** One skill/agent that does everything
|
||||
```markdown
|
||||
# Project Management
|
||||
Handles issues, PRs, releases, documentation, deployment...
|
||||
@@ -383,37 +374,32 @@ Use `tea issues create --title "..." --description "..."`
|
||||
|
||||
## Detailed Documentation
|
||||
|
||||
For comprehensive guides, see the `docs/` directory:
|
||||
For comprehensive guides, see:
|
||||
|
||||
- `docs/writing-skills.md` - Complete skill writing guide
|
||||
- `docs/writing-commands.md` - Complete command writing guide
|
||||
- `docs/writing-agents.md` - Complete agent writing guide
|
||||
|
||||
These documents include:
|
||||
- Full frontmatter reference
|
||||
- Annotated examples from the codebase
|
||||
- Lifecycle management
|
||||
- Integration checklists
|
||||
- `docs/writing-capabilities.md` - Complete guide covering skills and agents
|
||||
|
||||
## Checklists
|
||||
|
||||
### Before Creating a Skill
|
||||
### Before Creating a User-Invocable Skill
|
||||
|
||||
- [ ] Workflow is used multiple times
|
||||
- [ ] User explicitly triggers it (not automatic)
|
||||
- [ ] Clear start and end points
|
||||
- [ ] Frontmatter has `user-invocable: true`
|
||||
- [ ] Description includes "Use when... or when user says /skill-name"
|
||||
- [ ] Background skills referenced via `@~/.claude/skills/<name>/SKILL.md`
|
||||
- [ ] Approval checkpoints before significant actions
|
||||
- [ ] File at `skills/<name>/SKILL.md`
|
||||
|
||||
### Before Creating a Background Skill
|
||||
|
||||
- [ ] Knowledge is used in multiple places (not just once)
|
||||
- [ ] Existing skills do not already cover this domain
|
||||
- [ ] Content is specific and actionable (not generic)
|
||||
- [ ] Frontmatter has descriptive `description` with trigger terms
|
||||
- [ ] Frontmatter has `user-invocable: false`
|
||||
- [ ] Description includes trigger terms
|
||||
- [ ] File at `skills/<name>/SKILL.md`
|
||||
|
||||
### Before Creating a Command
|
||||
|
||||
- [ ] Workflow is repeatable (used multiple times)
|
||||
- [ ] User explicitly triggers it (not automatic)
|
||||
- [ ] Clear start and end points
|
||||
- [ ] Skills referenced via `@~/.claude/skills/<name>/SKILL.md`
|
||||
- [ ] Approval checkpoints before significant actions
|
||||
- [ ] File at `commands/<name>.md`
|
||||
|
||||
### Before Creating an Agent
|
||||
|
||||
- [ ] Built-in agents (Explore, Plan) are not sufficient
|
||||
|
||||
92
skills/commit/SKILL.md
Normal file
92
skills/commit/SKILL.md
Normal file
@@ -0,0 +1,92 @@
|
||||
---
|
||||
name: commit
|
||||
description: >
|
||||
Create a commit with an auto-generated conventional commit message. Analyzes staged
|
||||
changes and proposes a message for approval. Use when committing changes, creating
|
||||
commits, or when user says /commit.
|
||||
model: haiku
|
||||
argument-hint:
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Commit Changes
|
||||
|
||||
## Process
|
||||
|
||||
1. **Check for staged changes**:
|
||||
```bash
|
||||
git diff --staged --stat
|
||||
```
|
||||
|
||||
If no staged changes, inform the user and suggest staging files first:
|
||||
- Show unstaged changes with `git status`
|
||||
- Ask if they want to stage all changes (`git add -A`) or specific files
|
||||
|
||||
2. **Analyze staged changes**:
|
||||
```bash
|
||||
git diff --staged
|
||||
```
|
||||
|
||||
Examine the diff to understand:
|
||||
- What files were changed, added, or deleted
|
||||
- The nature of the changes (new feature, bug fix, refactor, docs, etc.)
|
||||
- Key details worth mentioning
|
||||
|
||||
3. **Generate commit message**:
|
||||
|
||||
Create a conventional commit message following this format:
|
||||
```
|
||||
<type>(<scope>): <description>
|
||||
|
||||
[optional body with more details]
|
||||
|
||||
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
|
||||
```
|
||||
|
||||
**Types:**
|
||||
- `feat`: New feature or capability
|
||||
- `fix`: Bug fix
|
||||
- `refactor`: Code restructuring without behavior change
|
||||
- `docs`: Documentation changes
|
||||
- `style`: Formatting, whitespace (no code change)
|
||||
- `test`: Adding or updating tests
|
||||
- `chore`: Maintenance tasks, dependencies, config
|
||||
|
||||
**Scope:** The component or area affected (optional, use when helpful)
|
||||
|
||||
**Description:**
|
||||
- Imperative mood ("add" not "added")
|
||||
- Lowercase first letter
|
||||
- No period at the end
|
||||
- Focus on the "why" when the "what" is obvious
|
||||
|
||||
4. **Present message for approval**:
|
||||
|
||||
Show the proposed message and ask the user to:
|
||||
- **Approve**: Use the message as-is
|
||||
- **Edit**: Let them modify the message
|
||||
- **Regenerate**: Create a new message with different focus
|
||||
|
||||
5. **Create the commit**:
|
||||
|
||||
Once approved, execute:
|
||||
```bash
|
||||
git commit -m "$(cat <<'EOF'
|
||||
<approved message>
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
6. **Confirm success**:
|
||||
|
||||
Show the commit result and suggest next steps:
|
||||
- Push to remote: `git push`
|
||||
- Continue working and commit more changes
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Only commits what's staged (respects partial staging)
|
||||
- Never auto-commits without user approval
|
||||
- Keep descriptions concise (50 chars or less for first line)
|
||||
- Include body for non-obvious changes
|
||||
- Always include Co-Authored-By attribution
|
||||
117
skills/create-capability/SKILL.md
Normal file
117
skills/create-capability/SKILL.md
Normal file
@@ -0,0 +1,117 @@
|
||||
---
|
||||
name: create-capability
|
||||
description: >
|
||||
Create a new capability (skill, agent, or a cohesive set) for the architecture
|
||||
repository. Use when creating new skills, agents, extending AI workflows, or when
|
||||
user says /create-capability.
|
||||
model: haiku
|
||||
argument-hint: <description>
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Create Capability
|
||||
|
||||
@~/.claude/skills/capability-writing/SKILL.md
|
||||
|
||||
Create new capabilities following established patterns. A capability may be a single component or a cohesive set (skill + agent).
|
||||
|
||||
## Process
|
||||
|
||||
1. **Understand the capability**: Analyze "$1" to understand what the user wants to build
|
||||
- What domain or workflow does this cover?
|
||||
- What user need does it address?
|
||||
- What existing capabilities might overlap?
|
||||
|
||||
2. **Determine components needed**: Based on the description, recommend which components:
|
||||
|
||||
| Pattern | When to Use |
|
||||
|---------|-------------|
|
||||
| Skill only (background) | Knowledge to apply automatically (reused across other skills) |
|
||||
| Skill only (user-invocable) | User-invoked workflow |
|
||||
| Skill + Agent | Workflow with isolated worker for complex subtasks |
|
||||
| Full set | New domain expertise + workflow + isolated work |
|
||||
|
||||
Present recommendation with reasoning:
|
||||
```
|
||||
## Recommended Components for: $1
|
||||
|
||||
Based on your description, I recommend:
|
||||
- **Skill**: `name` - [why this knowledge is needed]
|
||||
- **Agent**: `name` - [why isolation/specialization is needed] (optional)
|
||||
|
||||
Reasoning: [explain why this combination fits the need]
|
||||
```
|
||||
|
||||
3. **Gather information**: For each recommended component, ask:
|
||||
|
||||
**For all components:**
|
||||
- Name (kebab-case, descriptive)
|
||||
- Description (one-line summary)
|
||||
|
||||
**For Skills:**
|
||||
- What domain/knowledge does this cover?
|
||||
- What are the key concepts to teach?
|
||||
- What patterns or templates should it include?
|
||||
- Is it user-invocable (workflow) or background (reference)?
|
||||
|
||||
**For Agents:**
|
||||
- What specialized role does this fill?
|
||||
- What skills does it need?
|
||||
- Should it be read-only (no Edit/Write)?
|
||||
|
||||
4. **Select appropriate models**:
|
||||
|
||||
| Model | Use For |
|
||||
|-------|---------|
|
||||
| `haiku` | Simple fetch/display skills, formatting tasks |
|
||||
| `sonnet` | Most skills and agents (default) |
|
||||
| `opus` | Deep reasoning, architectural analysis, complex judgment |
|
||||
|
||||
For each component, recommend a model with reasoning.
|
||||
|
||||
5. **Generate files**: Create content using templates from capability-writing skill
|
||||
|
||||
Ensure proper inter-references:
|
||||
- User-invocable skill references background skills via `@~/.claude/skills/name/SKILL.md`
|
||||
- Agent lists skills in `skills:` frontmatter (names only, not paths)
|
||||
- User-invocable skill spawns agent via Task tool if agent is part of the set
|
||||
|
||||
6. **Present for approval**: Show all generated files with their full content:
|
||||
```
|
||||
## Generated Files
|
||||
|
||||
### skills/name/SKILL.md
|
||||
[full content]
|
||||
|
||||
### agents/name/AGENT.md (if applicable)
|
||||
[full content]
|
||||
|
||||
Ready to create these files?
|
||||
```
|
||||
|
||||
7. **Create files** in correct locations after approval:
|
||||
- `skills/<name>/SKILL.md`
|
||||
- `agents/<name>/AGENT.md`
|
||||
|
||||
8. **Report success**:
|
||||
```
|
||||
## Capability Created: name
|
||||
|
||||
Files created:
|
||||
- skills/name/SKILL.md
|
||||
- agents/name/AGENT.md (if applicable)
|
||||
|
||||
Next steps:
|
||||
1. Run `make install` to symlink to ~/.claude/
|
||||
2. Test with: /name (for user-invocable skills)
|
||||
3. Background skills will auto-activate based on context
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Follow all conventions from capability-writing skill
|
||||
- Reference existing skills rather than duplicating knowledge
|
||||
- Keep components focused - split if scope is too broad
|
||||
- User-invocable skills should have approval checkpoints before significant actions
|
||||
- Default to `sonnet` model unless there's a clear reason for haiku/opus
|
||||
- Skills should have descriptive `description` fields for auto-activation
|
||||
48
skills/create-issue/SKILL.md
Normal file
48
skills/create-issue/SKILL.md
Normal file
@@ -0,0 +1,48 @@
|
||||
---
|
||||
name: create-issue
|
||||
description: >
|
||||
Create a new Gitea issue. Can create single issues or batch create from a plan.
|
||||
Use when creating issues, adding tickets, or when user says /create-issue.
|
||||
model: haiku
|
||||
argument-hint: [title] or "batch"
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Create Issue(s)
|
||||
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
|
||||
## Milestone Assignment
|
||||
|
||||
Before creating issues, fetch available milestones:
|
||||
|
||||
```bash
|
||||
tea milestones -f title,description
|
||||
```
|
||||
|
||||
For each issue, automatically assign to the most relevant milestone by matching:
|
||||
- Issue content/problem area → Milestone title and description
|
||||
- If no clear match, ask the user which milestone (goal) the issue supports
|
||||
- If no milestones exist, skip milestone assignment
|
||||
|
||||
Include `--milestone "<milestone>"` in the create command when a milestone is assigned.
|
||||
|
||||
## Single Issue (default)
|
||||
|
||||
If title provided:
|
||||
1. Create an issue with that title
|
||||
2. Ask for description
|
||||
3. Assign to appropriate milestone (see above)
|
||||
4. Ask if this issue depends on any existing issues
|
||||
5. If dependencies exist, link them: `tea issues deps add <new-issue> <blocker>`
|
||||
|
||||
## Batch Mode
|
||||
|
||||
If $1 is "batch":
|
||||
1. Ask user for the plan/direction
|
||||
2. Fetch available milestones
|
||||
3. Generate list of issues with titles, descriptions, milestone assignments, and dependencies
|
||||
4. Show for approval
|
||||
5. Create each issue with milestone (in dependency order)
|
||||
6. Link dependencies between created issues: `tea issues deps add <issue> <blocker>`
|
||||
7. Display all created issue numbers with dependency graph
|
||||
214
skills/create-repo/SKILL.md
Normal file
214
skills/create-repo/SKILL.md
Normal file
@@ -0,0 +1,214 @@
|
||||
---
|
||||
name: create-repo
|
||||
description: >
|
||||
Create a new repository with standard structure. Scaffolds vision.md, CLAUDE.md,
|
||||
and CI configuration. Use when creating repos, initializing projects, or when user
|
||||
says /create-repo.
|
||||
model: haiku
|
||||
argument-hint: <repo-name>
|
||||
context: fork
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Create Repository
|
||||
|
||||
@~/.claude/skills/repo-conventions/SKILL.md
|
||||
@~/.claude/skills/vision-management/SKILL.md
|
||||
@~/.claude/skills/claude-md-writing/SKILL.md
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
|
||||
Create a new repository with Flowmade's standard structure.
|
||||
|
||||
## Process
|
||||
|
||||
1. **Get repository name**: Use `$1` or ask the user
|
||||
- Validate: lowercase, hyphens only, no `flowmade-` prefix
|
||||
- Check it doesn't already exist: `tea repos flowmade-one/<name>`
|
||||
|
||||
2. **Determine visibility**:
|
||||
- Ask: "Should this repo be public (open source) or private (proprietary)?"
|
||||
- Refer to repo-conventions skill for guidance on open vs proprietary
|
||||
|
||||
3. **Gather vision context**:
|
||||
- Read the organization manifesto: `../architecture/manifesto.md`
|
||||
- Ask: "What does this product do? (one sentence)"
|
||||
- Ask: "Which manifesto personas does it serve?"
|
||||
- Ask: "What problem does it solve?"
|
||||
|
||||
4. **Create the repository on Gitea**:
|
||||
```bash
|
||||
tea repos create --name <repo-name> --private/--public --description "<description>"
|
||||
```
|
||||
|
||||
5. **Clone and set up structure**:
|
||||
```bash
|
||||
# Clone the new repo
|
||||
git clone ssh://git@git.flowmade.one/flowmade-one/<repo-name>.git
|
||||
cd <repo-name>
|
||||
```
|
||||
|
||||
6. **Create vision.md**:
|
||||
- Use the vision structure template from vision-management skill
|
||||
- Link to `../architecture/manifesto.md`
|
||||
- Fill in based on user's answers
|
||||
|
||||
7. **Create CLAUDE.md** (following claude-md-writing skill):
|
||||
```markdown
|
||||
# <Repo Name>
|
||||
|
||||
<One-line description from step 3>
|
||||
|
||||
## Organization Context
|
||||
|
||||
This repo is part of Flowmade. See:
|
||||
- [Organization manifesto](../architecture/manifesto.md) - who we are, what we believe
|
||||
- [Repository map](../architecture/repos.md) - how this fits in the bigger picture
|
||||
- [Vision](./vision.md) - what this specific product does
|
||||
|
||||
## Setup
|
||||
|
||||
```bash
|
||||
# TODO: Add setup instructions
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
TODO: Document key directories once code exists.
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
make build # Build the project
|
||||
make test # Run tests
|
||||
make lint # Run linters
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
TODO: Document key patterns and conventions once established.
|
||||
```
|
||||
|
||||
8. **Create Makefile** (basic template):
|
||||
```makefile
|
||||
.PHONY: build test lint
|
||||
|
||||
build:
|
||||
@echo "TODO: Add build command"
|
||||
|
||||
test:
|
||||
@echo "TODO: Add test command"
|
||||
|
||||
lint:
|
||||
@echo "TODO: Add lint command"
|
||||
```
|
||||
|
||||
9. **Create CI workflow**:
|
||||
```bash
|
||||
mkdir -p .gitea/workflows
|
||||
```
|
||||
|
||||
Create `.gitea/workflows/ci.yaml`:
|
||||
```yaml
|
||||
name: CI
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
branches: [main]
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Build
|
||||
run: make build
|
||||
- name: Test
|
||||
run: make test
|
||||
- name: Lint
|
||||
run: make lint
|
||||
```
|
||||
|
||||
10. **Create .gitignore** (basic, expand based on language):
|
||||
```
|
||||
# IDE
|
||||
.idea/
|
||||
.vscode/
|
||||
*.swp
|
||||
|
||||
# OS
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
|
||||
# Build artifacts
|
||||
/dist/
|
||||
/build/
|
||||
/bin/
|
||||
|
||||
# Dependencies (language-specific, add as needed)
|
||||
/node_modules/
|
||||
/vendor/
|
||||
```
|
||||
|
||||
11. **Initial commit and push**:
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Initial repository structure
|
||||
|
||||
- vision.md linking to organization manifesto
|
||||
- CLAUDE.md with project instructions
|
||||
- CI workflow template
|
||||
- Basic Makefile
|
||||
|
||||
Generated with [Claude Code](https://claude.com/claude-code)
|
||||
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||||
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
12. **Report success**:
|
||||
```
|
||||
Repository created: https://git.flowmade.one/flowmade-one/<repo-name>
|
||||
|
||||
Next steps:
|
||||
1. cd ../<repo-name>
|
||||
2. Update CLAUDE.md with actual setup instructions
|
||||
3. Update Makefile with real build commands
|
||||
4. Start building!
|
||||
```
|
||||
|
||||
## Output Example
|
||||
|
||||
```
|
||||
## Creating Repository: my-service
|
||||
|
||||
Visibility: Private (proprietary)
|
||||
Description: Internal service for processing events
|
||||
|
||||
### Files Created
|
||||
|
||||
- vision.md (linked to manifesto)
|
||||
- CLAUDE.md (project instructions)
|
||||
- Makefile (build template)
|
||||
- .gitea/workflows/ci.yaml (CI pipeline)
|
||||
- .gitignore (standard ignores)
|
||||
|
||||
### Repository URL
|
||||
|
||||
https://git.flowmade.one/flowmade-one/my-service
|
||||
|
||||
### Next Steps
|
||||
|
||||
1. cd ../my-service
|
||||
2. Update CLAUDE.md with setup instructions
|
||||
3. Update Makefile with build commands
|
||||
4. Start coding!
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Always link vision.md to the sibling architecture repo
|
||||
- Keep initial structure minimal - add complexity as needed
|
||||
- CI should pass on empty repo (use placeholder commands)
|
||||
- Default to private unless explicitly open-sourcing
|
||||
90
skills/dashboard/SKILL.md
Normal file
90
skills/dashboard/SKILL.md
Normal file
@@ -0,0 +1,90 @@
|
||||
---
|
||||
name: dashboard
|
||||
description: >
|
||||
Show dashboard of open issues, PRs awaiting review, and CI status. Use when
|
||||
checking project status, viewing issues/PRs, or when user says /dashboard.
|
||||
model: haiku
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Repository Dashboard
|
||||
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
|
||||
Fetch and display the following sections:
|
||||
|
||||
## 1. Open Issues
|
||||
|
||||
Run `tea issues` to list all open issues.
|
||||
|
||||
Format as a table showing:
|
||||
- Number
|
||||
- Title
|
||||
- Author
|
||||
|
||||
## 2. Open Pull Requests
|
||||
|
||||
Run `tea pulls` to list all open PRs.
|
||||
|
||||
Format as a table showing:
|
||||
- Number
|
||||
- Title
|
||||
- Author
|
||||
|
||||
## 3. CI Status (Recent Workflow Runs)
|
||||
|
||||
Run `tea actions runs` to list recent workflow runs.
|
||||
|
||||
**Output formatting:**
|
||||
- Show the most recent 10 workflow runs maximum
|
||||
- For each run, display:
|
||||
- Status (use indicators: [SUCCESS], [FAILURE], [RUNNING], [PENDING])
|
||||
- Workflow name
|
||||
- Branch or PR reference
|
||||
- Commit (short SHA)
|
||||
- Triggered time
|
||||
|
||||
**Highlighting:**
|
||||
- **Highlight failed runs** by prefixing with a warning indicator and ensuring they stand out visually
|
||||
- Example: "**[FAILURE]** build - PR #42 - abc1234 - 2h ago"
|
||||
|
||||
**Handling repos without CI:**
|
||||
- If `tea actions runs` returns "No workflow runs found" or similar, display:
|
||||
"No CI workflows configured for this repository."
|
||||
- Do not treat this as an error - simply note it and continue
|
||||
|
||||
## Output Format
|
||||
|
||||
Present each section with a clear header. Example:
|
||||
|
||||
```
|
||||
## Open Issues (3)
|
||||
|
||||
| # | Title | Author |
|
||||
|----|------------------------|--------|
|
||||
| 15 | Fix login timeout | alice |
|
||||
| 12 | Add dark mode | bob |
|
||||
| 8 | Update documentation | carol |
|
||||
|
||||
## Open Pull Requests (2)
|
||||
|
||||
| # | Title | Author |
|
||||
|----|------------------------|--------|
|
||||
| 16 | Fix login timeout | alice |
|
||||
| 14 | Refactor auth module | bob |
|
||||
|
||||
## CI Status
|
||||
|
||||
| Status | Workflow | Branch/PR | Commit | Time |
|
||||
|-------------|----------|-------------|---------|---------|
|
||||
| **[FAILURE]** | build | PR #16 | abc1234 | 2h ago |
|
||||
| [SUCCESS] | build | main | def5678 | 5h ago |
|
||||
| [SUCCESS] | lint | main | def5678 | 5h ago |
|
||||
```
|
||||
|
||||
If no CI is configured:
|
||||
```
|
||||
## CI Status
|
||||
|
||||
No CI workflows configured for this repository.
|
||||
```
|
||||
43
skills/groom/SKILL.md
Normal file
43
skills/groom/SKILL.md
Normal file
@@ -0,0 +1,43 @@
|
||||
---
|
||||
name: groom
|
||||
description: >
|
||||
Groom and improve issues. Without argument, reviews all open issues. With argument,
|
||||
grooms specific issue. Use when grooming backlog, improving issues, or when user
|
||||
says /groom.
|
||||
model: sonnet
|
||||
argument-hint: [issue-number]
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Groom Issues
|
||||
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
@~/.claude/skills/backlog-grooming/SKILL.md
|
||||
@~/.claude/skills/issue-writing/SKILL.md
|
||||
|
||||
## If issue number provided ($1):
|
||||
|
||||
1. **Fetch the issue** details with `tea issues <number> --comments`
|
||||
2. **Check dependencies** with `tea issues deps list <number>`
|
||||
3. **Evaluate** against grooming checklist
|
||||
4. **Suggest improvements** for:
|
||||
- Title clarity
|
||||
- Description completeness
|
||||
- Acceptance criteria quality
|
||||
- Scope definition
|
||||
- Missing or incorrect dependencies
|
||||
5. **Ask user** if they want to apply changes
|
||||
6. **Update issue** if approved
|
||||
7. **Link/unlink dependencies** if needed: `tea issues deps add/remove <issue> <dep>`
|
||||
|
||||
## If no argument (groom all):
|
||||
|
||||
1. **List open issues**
|
||||
2. **Review each** against grooming checklist (including dependencies)
|
||||
3. **Categorize**:
|
||||
- Ready: Well-defined, dependencies linked, can start work
|
||||
- Blocked: Has unresolved dependencies
|
||||
- Needs work: Missing info, unclear, or missing dependency links
|
||||
- Stale: No longer relevant
|
||||
4. **Present summary** table with dependency status
|
||||
5. **Offer to improve** issues that need work (including linking dependencies)
|
||||
89
skills/improve/SKILL.md
Normal file
89
skills/improve/SKILL.md
Normal file
@@ -0,0 +1,89 @@
|
||||
---
|
||||
name: improve
|
||||
description: >
|
||||
Identify improvement opportunities based on product vision. Analyzes gaps between
|
||||
vision goals and current backlog. Use when analyzing alignment, finding gaps, or
|
||||
when user says /improve.
|
||||
model: sonnet
|
||||
context: fork
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Improvement Analysis
|
||||
|
||||
@~/.claude/skills/vision-management/SKILL.md
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
@~/.claude/skills/issue-writing/SKILL.md
|
||||
@~/.claude/skills/roadmap-planning/SKILL.md
|
||||
|
||||
## Process
|
||||
|
||||
1. **Read the vision**: Load `vision.md` from the repo root.
|
||||
- If no vision exists, suggest running `/vision` first
|
||||
|
||||
2. **Fetch current backlog**: Get all open issues from Gitea using `tea issues`
|
||||
|
||||
3. **Analyze alignment**:
|
||||
|
||||
For each vision goal, check:
|
||||
- Are there issues supporting this goal?
|
||||
- Is there recent activity/progress?
|
||||
- Are issues blocked or stalled?
|
||||
|
||||
For each open issue, check:
|
||||
- Does it align with a vision goal?
|
||||
- Is it supporting the current focus?
|
||||
|
||||
4. **Identify gaps and opportunities**:
|
||||
|
||||
- **Unsupported goals**: Vision goals with no issues
|
||||
- **Stalled goals**: Goals with issues but no recent progress
|
||||
- **Orphan issues**: Issues that don't support any goal
|
||||
- **Focus misalignment**: Issues not aligned with current focus getting priority
|
||||
- **Missing non-goals**: Patterns suggesting things we should explicitly avoid
|
||||
|
||||
5. **Present findings**:
|
||||
|
||||
```
|
||||
## Vision Alignment Report
|
||||
|
||||
### Goals Coverage
|
||||
- Goal 1: [status] - N issues, [progress]
|
||||
- Goal 2: [status] - N issues, [progress]
|
||||
|
||||
### Gaps Identified
|
||||
1. [Gap description]
|
||||
Suggestion: [concrete action]
|
||||
|
||||
2. [Gap description]
|
||||
Suggestion: [concrete action]
|
||||
|
||||
### Orphan Issues
|
||||
- #N: [title] - No goal alignment
|
||||
|
||||
### Recommended Actions
|
||||
1. [Action with rationale]
|
||||
2. [Action with rationale]
|
||||
```
|
||||
|
||||
6. **Offer to take action**:
|
||||
|
||||
For unsupported goals:
|
||||
- Ask if user wants to plan issues for the gap
|
||||
- If yes, run the `/plan-issues` workflow for that goal
|
||||
- This breaks down the goal into concrete, actionable issues
|
||||
|
||||
For other findings:
|
||||
- Re-prioritize issues based on focus
|
||||
- Close or re-scope orphan issues
|
||||
- Update vision with suggested changes
|
||||
|
||||
Always ask for approval before making changes.
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Focus on actionable improvements, not just observations
|
||||
- Prioritize suggestions by impact on vision goals
|
||||
- Keep suggestions specific and concrete
|
||||
- One issue per improvement (don't bundle)
|
||||
- Reference specific goals when suggesting new issues
|
||||
77
skills/manifesto/SKILL.md
Normal file
77
skills/manifesto/SKILL.md
Normal file
@@ -0,0 +1,77 @@
|
||||
---
|
||||
name: manifesto
|
||||
description: >
|
||||
View and manage the organization manifesto. Shows identity, personas, beliefs,
|
||||
and principles. Use when viewing manifesto, checking organization identity, or
|
||||
when user says /manifesto.
|
||||
model: haiku
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Organization Manifesto
|
||||
|
||||
@~/.claude/skills/vision-management/SKILL.md
|
||||
|
||||
The manifesto defines the organization-level vision: who we are, who we serve, what we believe, and how we work. It is distinct from product-level vision (see `/vision`).
|
||||
|
||||
## Process
|
||||
|
||||
1. **Check for manifesto**: Look for `manifesto.md` in the current repo root.
|
||||
|
||||
2. **If no manifesto exists**:
|
||||
- Ask if the user wants to create one
|
||||
- Guide through defining:
|
||||
1. **Who We Are**: Organization identity
|
||||
2. **Who We Serve**: 2-4 specific personas with context and constraints
|
||||
3. **What They're Trying to Achieve**: Jobs to be done in their voice
|
||||
4. **What We Believe**: Core beliefs including stance on AI-augmented development
|
||||
5. **Guiding Principles**: Decision-making rules
|
||||
6. **Non-Goals**: What we explicitly don't do
|
||||
- Create `manifesto.md`
|
||||
|
||||
3. **If manifesto exists**:
|
||||
- Display formatted summary of the manifesto
|
||||
|
||||
## Output Format
|
||||
|
||||
When displaying an existing manifesto:
|
||||
|
||||
```
|
||||
## Who We Are
|
||||
|
||||
[Identity summary from manifesto]
|
||||
|
||||
## Who We Serve
|
||||
|
||||
- **[Persona 1]**: [Brief description]
|
||||
- **[Persona 2]**: [Brief description]
|
||||
- **[Persona 3]**: [Brief description]
|
||||
|
||||
## What They're Trying to Achieve
|
||||
|
||||
- "[Job to be done 1]"
|
||||
- "[Job to be done 2]"
|
||||
- "[Job to be done 3]"
|
||||
|
||||
## What We Believe
|
||||
|
||||
[Summary of key beliefs - especially AI-augmented development stance]
|
||||
|
||||
## Guiding Principles
|
||||
|
||||
1. [Principle 1]
|
||||
2. [Principle 2]
|
||||
3. [Principle 3]
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- [Non-goal 1]
|
||||
- [Non-goal 2]
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
|
||||
- The manifesto is the **organization-level** document - it applies across all products
|
||||
- Update rarely - this is foundational identity, not tactical direction
|
||||
- Product repos reference the manifesto but have their own `vision.md`
|
||||
- Use `/vision` for product-level vision management
|
||||
72
skills/plan-issues/SKILL.md
Normal file
72
skills/plan-issues/SKILL.md
Normal file
@@ -0,0 +1,72 @@
|
||||
---
|
||||
name: plan-issues
|
||||
description: >
|
||||
Plan and create issues for a feature or improvement. Breaks down work into
|
||||
well-structured issues with vision alignment. Use when planning a feature,
|
||||
creating a roadmap, breaking down large tasks, or when user says /plan-issues.
|
||||
model: sonnet
|
||||
argument-hint: <feature-description>
|
||||
context: fork
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Plan Feature: $1
|
||||
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
@~/.claude/skills/roadmap-planning/SKILL.md
|
||||
@~/.claude/skills/issue-writing/SKILL.md
|
||||
@~/.claude/skills/vision-management/SKILL.md
|
||||
|
||||
1. **Check vision context**: If `vision.md` exists, read it to understand personas, jobs to be done, and goals
|
||||
2. **Identify persona**: Which persona does "$1" serve?
|
||||
3. **Identify job**: Which job to be done does this enable?
|
||||
4. **Understand the feature**: Analyze what "$1" involves
|
||||
5. **Explore the codebase** if needed to understand context
|
||||
|
||||
6. **Discovery phase**: Before proposing issues, walk through the user workflow:
|
||||
- Who is the specific user?
|
||||
- What is their goal?
|
||||
- What is their step-by-step workflow to reach that goal?
|
||||
- What exists today?
|
||||
- Where does the workflow break or have gaps?
|
||||
- What's the MVP that delivers value?
|
||||
|
||||
Present this as a workflow walkthrough before proposing any issues.
|
||||
|
||||
7. **Break down** into discrete, actionable issues:
|
||||
- Derive issues from the workflow gaps identified in discovery
|
||||
- Each issue should be independently completable
|
||||
- Clear dependencies between issues
|
||||
- Appropriate scope (not too big, not too small)
|
||||
|
||||
8. **Present the plan** (include vision alignment if vision exists):
|
||||
```
|
||||
## Proposed Issues for: $1
|
||||
|
||||
For: [Persona name]
|
||||
Job: "[Job to be done this enables]"
|
||||
Supports: [Milestone/Goal name]
|
||||
|
||||
1. [Title] - Brief description
|
||||
Addresses gap: [which workflow gap this solves]
|
||||
Dependencies: none
|
||||
|
||||
2. [Title] - Brief description
|
||||
Addresses gap: [which workflow gap this solves]
|
||||
Dependencies: #1
|
||||
|
||||
3. [Title] - Brief description
|
||||
Addresses gap: [which workflow gap this solves]
|
||||
Dependencies: #1, #2
|
||||
```
|
||||
|
||||
If the feature doesn't align with any persona/job/goal, note this and ask if:
|
||||
- A new persona or job should be added to the vision
|
||||
- A new milestone should be created
|
||||
- This should be added as a non-goal
|
||||
- Proceed anyway (with justification)
|
||||
|
||||
9. **Ask for approval** before creating issues
|
||||
10. **Create issues** in dependency order (blockers first)
|
||||
11. **Link dependencies** using `tea issues deps add <issue> <blocker>` for each dependency
|
||||
12. **Present summary** with links to created issues and dependency graph
|
||||
153
skills/pr/SKILL.md
Normal file
153
skills/pr/SKILL.md
Normal file
@@ -0,0 +1,153 @@
|
||||
---
|
||||
name: pr
|
||||
description: >
|
||||
Create a PR from current branch. Auto-generates title and description from branch
|
||||
name and commits. Use when creating pull requests, submitting changes, or when
|
||||
user says /pr.
|
||||
model: haiku
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Create Pull Request
|
||||
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
|
||||
Quick PR creation from current branch - lighter than full `/work-issue` flow for when you're already on a branch with commits.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Current branch is NOT main/master
|
||||
- Branch has commits ahead of main
|
||||
- Changes have been pushed to origin (or will be pushed)
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Verify Branch State
|
||||
|
||||
```bash
|
||||
# Check current branch
|
||||
git branch --show-current
|
||||
|
||||
# Ensure we're not on main
|
||||
# If on main, abort with message: "Cannot create PR from main branch"
|
||||
|
||||
# Check for commits ahead of main
|
||||
git log main..HEAD --oneline
|
||||
```
|
||||
|
||||
### 2. Push if Needed
|
||||
|
||||
```bash
|
||||
# Check if branch is tracking remote
|
||||
git status -sb
|
||||
|
||||
# If not pushed or behind, push with upstream
|
||||
git push -u origin <branch-name>
|
||||
```
|
||||
|
||||
### 3. Generate PR Title
|
||||
|
||||
**Option A: Branch contains issue number** (e.g., `issue-42-add-feature`)
|
||||
|
||||
Extract issue number and use format: `[Issue #<number>] <issue-title>`
|
||||
|
||||
```bash
|
||||
tea issues <number> # Get the actual issue title
|
||||
```
|
||||
|
||||
**Option B: No issue number**
|
||||
|
||||
Generate from branch name or recent commit messages:
|
||||
- Convert branch name from kebab-case to title case: `add-user-auth` -> `Add user auth`
|
||||
- Or use the most recent commit subject line
|
||||
|
||||
### 4. Generate PR Description
|
||||
|
||||
Analyze the diff and commits to generate a description:
|
||||
|
||||
```bash
|
||||
# Get diff against main
|
||||
git diff main...HEAD --stat
|
||||
|
||||
# Get commit messages
|
||||
git log main..HEAD --format="- %s"
|
||||
```
|
||||
|
||||
Structure the description:
|
||||
|
||||
```markdown
|
||||
## Summary
|
||||
[1-2 sentences describing the overall change]
|
||||
|
||||
## Changes
|
||||
[Bullet points summarizing commits or key changes]
|
||||
|
||||
[If issue linked: "Closes #<number>"]
|
||||
```
|
||||
|
||||
### 5. Create PR
|
||||
|
||||
Use tea CLI to create the PR:
|
||||
|
||||
```bash
|
||||
tea pulls create --title "<generated-title>" --description "<generated-description>"
|
||||
```
|
||||
|
||||
Capture the PR number from the output (e.g., "Pull Request #42 created").
|
||||
|
||||
### 6. Auto-review
|
||||
|
||||
Inform the user that auto-review is starting, then spawn the `code-reviewer` agent in background:
|
||||
|
||||
```
|
||||
Task tool with:
|
||||
- subagent_type: "code-reviewer"
|
||||
- run_in_background: true
|
||||
- prompt: |
|
||||
Review PR #<PR_NUMBER> in the repository at <REPO_PATH>.
|
||||
|
||||
1. Checkout the PR: tea pulls checkout <PR_NUMBER>
|
||||
2. Get the diff: git diff main...HEAD
|
||||
3. Analyze for code quality, bugs, security, style, test coverage
|
||||
4. Post structured review comment with tea comment
|
||||
5. Merge with rebase if LGTM, otherwise leave for user
|
||||
```
|
||||
|
||||
### 7. Display Result
|
||||
|
||||
Show the user:
|
||||
- PR URL/number
|
||||
- Generated title and description
|
||||
- Status of auto-review (spawned in background)
|
||||
|
||||
## Issue Linking
|
||||
|
||||
To detect if branch is linked to an issue:
|
||||
|
||||
1. Check branch name for patterns:
|
||||
- `issue-<number>-*`
|
||||
- `<number>-*`
|
||||
- `*-#<number>`
|
||||
|
||||
2. If issue number found:
|
||||
- Fetch issue title from Gitea
|
||||
- Use `[Issue #N] <issue-title>` format for PR title
|
||||
- Add `Closes #N` to description
|
||||
|
||||
## Example Output
|
||||
|
||||
```
|
||||
Created PR #42: [Issue #15] Add /pr command
|
||||
|
||||
## Summary
|
||||
Adds /pr command for quick PR creation from current branch.
|
||||
|
||||
## Changes
|
||||
- Add commands/pr.md with auto-generation logic
|
||||
- Support issue linking from branch name
|
||||
|
||||
Closes #15
|
||||
|
||||
---
|
||||
Auto-review started in background. Check status with: tea pulls 42 --comments
|
||||
```
|
||||
@@ -17,8 +17,7 @@ All product repos should follow this structure relative to the architecture repo
|
||||
org/
|
||||
├── architecture/ # Organizational source of truth
|
||||
│ ├── manifesto.md # Organization identity and beliefs
|
||||
│ ├── commands/ # Claude Code workflows
|
||||
│ ├── skills/ # Knowledge modules
|
||||
│ ├── skills/ # User-invocable and background skills
|
||||
│ └── agents/ # Subtask handlers
|
||||
├── product-a/ # Product repository
|
||||
│ ├── vision.md # Product vision (extends manifesto)
|
||||
|
||||
120
skills/retro/SKILL.md
Normal file
120
skills/retro/SKILL.md
Normal file
@@ -0,0 +1,120 @@
|
||||
---
|
||||
name: retro
|
||||
description: >
|
||||
Run a retrospective on completed work. Captures insights as issues for later
|
||||
encoding into skills/agents. Use when capturing learnings, running retrospectives,
|
||||
or when user says /retro.
|
||||
model: haiku
|
||||
argument-hint: [task-description]
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Retrospective
|
||||
|
||||
Capture insights from completed work as issues on the architecture repo. Issues are later encoded into learnings and skills/agents.
|
||||
|
||||
@~/.claude/skills/vision-management/SKILL.md
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
|
||||
## Flow
|
||||
|
||||
```
|
||||
Retro (any repo) → Issue (architecture repo) → Encode: learning file + skill/agent
|
||||
```
|
||||
|
||||
The retro creates the issue. Encoding happens when the issue is worked on.
|
||||
|
||||
## Process
|
||||
|
||||
1. **Gather context**: If $1 is provided, use it as the task description. Otherwise, ask the user what task was just completed.
|
||||
|
||||
2. **Reflect on the work**: Ask the user (or summarize from conversation context if obvious):
|
||||
- What friction points were encountered?
|
||||
- What worked well?
|
||||
- Any specific improvement ideas?
|
||||
|
||||
3. **Identify insights**: For each insight, determine:
|
||||
- **What was learned**: The specific insight
|
||||
- **Where to encode it**: Which skill or agent should change?
|
||||
- **Governance impact**: What does this mean for how we work?
|
||||
|
||||
4. **Create issue on architecture repo**: Always create issues on `flowmade-one/architecture`:
|
||||
|
||||
```bash
|
||||
tea issues create -r flowmade-one/architecture \
|
||||
--title "[Learning] <brief description>" \
|
||||
--description "## Context
|
||||
[Task that triggered this insight]
|
||||
|
||||
## Insight
|
||||
[The specific learning - be concrete and actionable]
|
||||
|
||||
## Suggested Encoding
|
||||
- [ ] \`skills/xxx/SKILL.md\` - [what to add/change]
|
||||
- [ ] \`agents/xxx/agent.md\` - [what to add/change]
|
||||
|
||||
## Governance
|
||||
[What this means for how we work going forward]"
|
||||
```
|
||||
|
||||
5. **Connect to vision**: Check if insight affects vision:
|
||||
- **Architecture repo**: Does this affect `manifesto.md`? (beliefs, principles, non-goals)
|
||||
- **Product repo**: Does this affect `vision.md`? (product direction, goals)
|
||||
|
||||
If vision updates are needed, present suggested changes and ask for approval.
|
||||
|
||||
## When the Issue is Worked On
|
||||
|
||||
When encoding a learning issue, the implementer should:
|
||||
|
||||
1. **Create learning file**: `learnings/YYYY-MM-DD-short-title.md`
|
||||
|
||||
```markdown
|
||||
# [Learning Title]
|
||||
|
||||
**Date**: YYYY-MM-DD
|
||||
**Context**: [Task that triggered this learning]
|
||||
**Issue**: #XX
|
||||
|
||||
## Learning
|
||||
|
||||
[The specific insight]
|
||||
|
||||
## Encoded In
|
||||
|
||||
- `skills/xxx/SKILL.md` - [what was added/changed]
|
||||
|
||||
## Governance
|
||||
|
||||
[What this means for how we work]
|
||||
```
|
||||
|
||||
2. **Update skill/agent** with the encoded knowledge
|
||||
|
||||
3. **Close the issue** with reference to the learning file and changes made
|
||||
|
||||
## Encoding Destinations
|
||||
|
||||
| Insight Type | Encode In |
|
||||
|--------------|-----------|
|
||||
| How to use a tool | `skills/[tool]/SKILL.md` |
|
||||
| Workflow improvement | `skills/[skill]/SKILL.md` (user-invocable) |
|
||||
| Subtask behavior | `agents/[agent]/agent.md` |
|
||||
| Organization belief | `manifesto.md` |
|
||||
| Product direction | `vision.md` (in product repo) |
|
||||
|
||||
## Labels
|
||||
|
||||
Add appropriate labels to issues:
|
||||
- `learning` - Always add this
|
||||
- `prompt-improvement` - For skill text changes
|
||||
- `new-feature` - For new skills/agents
|
||||
- `bug` - For things that are broken
|
||||
|
||||
## Guidelines
|
||||
|
||||
- **Always create issues on architecture repo** - regardless of which repo the retro runs in
|
||||
- **Be specific**: Vague insights can't be encoded
|
||||
- **One issue per insight**: Don't bundle unrelated things
|
||||
- **Encoding happens later**: Retro captures the issue, encoding is separate work
|
||||
- **Skip one-offs**: Don't capture insights for edge cases that won't recur
|
||||
90
skills/review-pr/SKILL.md
Normal file
90
skills/review-pr/SKILL.md
Normal file
@@ -0,0 +1,90 @@
|
||||
---
|
||||
name: review-pr
|
||||
description: >
|
||||
Review a Gitea pull request. Fetches PR details, diff, and comments. Includes
|
||||
both code review and software architecture review. Use when reviewing pull requests,
|
||||
checking code quality, or when user says /review-pr.
|
||||
model: sonnet
|
||||
argument-hint: <pr-number>
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Review PR #$1
|
||||
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
@~/.claude/skills/software-architecture/SKILL.md
|
||||
|
||||
## 1. Gather Information
|
||||
|
||||
1. **View PR details** with `--comments` flag to see description, metadata, and discussion
|
||||
2. **Get the diff** to review the changes:
|
||||
```bash
|
||||
tea pulls checkout <number>
|
||||
git diff main...HEAD
|
||||
```
|
||||
|
||||
## 2. Code Review
|
||||
|
||||
Review the changes and provide feedback on:
|
||||
- Code quality and style
|
||||
- Potential bugs or logic errors
|
||||
- Test coverage
|
||||
- Documentation updates
|
||||
|
||||
## 3. Software Architecture Review
|
||||
|
||||
Spawn the software-architect agent for architectural analysis:
|
||||
|
||||
```
|
||||
Task tool with:
|
||||
- subagent_type: "software-architect"
|
||||
- prompt: |
|
||||
ANALYSIS_TYPE: pr-review
|
||||
TARGET: <pr-number>
|
||||
CONTEXT: [Include the PR diff and description]
|
||||
```
|
||||
|
||||
The architecture review checks:
|
||||
- **Pattern consistency**: Changes follow existing codebase patterns
|
||||
- **Dependency direction**: Dependencies flow correctly (toward domain layer)
|
||||
- **Breaking changes**: API changes are flagged and justified
|
||||
- **Module boundaries**: Changes respect existing package boundaries
|
||||
- **Error handling**: Errors wrapped with context, proper error types used
|
||||
|
||||
## 4. Present Findings
|
||||
|
||||
Structure the review with two sections:
|
||||
|
||||
### Code Review
|
||||
- Quality, bugs, style issues
|
||||
- Test coverage gaps
|
||||
- Documentation needs
|
||||
|
||||
### Architecture Review
|
||||
- Summary of architectural concerns from agent
|
||||
- Pattern violations or anti-patterns detected
|
||||
- Dependency or boundary issues
|
||||
- Breaking change assessment
|
||||
|
||||
## 5. User Actions
|
||||
|
||||
Ask the user what action to take:
|
||||
- **Merge**: Post review summary as comment, then merge with rebase style
|
||||
- **Request changes**: Leave feedback without merging
|
||||
- **Comment only**: Add a comment for discussion
|
||||
|
||||
## Merging
|
||||
|
||||
Always use tea CLI for merges to preserve user attribution:
|
||||
|
||||
```bash
|
||||
tea pulls merge <number> --style rebase
|
||||
```
|
||||
|
||||
For review comments, use `tea comment` since `tea pulls review` is interactive-only:
|
||||
|
||||
```bash
|
||||
tea comment <number> "<review summary>"
|
||||
```
|
||||
|
||||
> **Warning**: Never use the Gitea API with admin credentials for user-facing operations like merging. This causes the merge to be attributed to the admin account instead of the user.
|
||||
37
skills/roadmap/SKILL.md
Normal file
37
skills/roadmap/SKILL.md
Normal file
@@ -0,0 +1,37 @@
|
||||
---
|
||||
name: roadmap
|
||||
description: >
|
||||
View current issues as a roadmap. Shows open issues organized by status and
|
||||
dependencies. Use when viewing roadmap, checking issue status, or when user
|
||||
says /roadmap.
|
||||
model: haiku
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Roadmap View
|
||||
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
|
||||
1. **Fetch all open issues**
|
||||
2. **Analyze dependencies** from issue descriptions
|
||||
3. **Categorize issues**:
|
||||
- Blocked: Waiting on other issues
|
||||
- Ready: No blockers, can start
|
||||
- In Progress: Has assignee or WIP label
|
||||
4. **Present roadmap** as organized list:
|
||||
|
||||
```
|
||||
## Ready to Start
|
||||
- #5: Add user authentication
|
||||
- #8: Create dashboard layout
|
||||
|
||||
## In Progress
|
||||
- #3: Setup database schema
|
||||
|
||||
## Blocked
|
||||
- #7: User profile page (blocked by #5)
|
||||
- #9: Admin dashboard (blocked by #3, #8)
|
||||
```
|
||||
|
||||
5. **Highlight** any issues that seem stale or unclear
|
||||
6. **Suggest** next actions based on the roadmap state
|
||||
349
skills/spawn-issues/SKILL.md
Normal file
349
skills/spawn-issues/SKILL.md
Normal file
@@ -0,0 +1,349 @@
|
||||
---
|
||||
name: spawn-issues
|
||||
description: Orchestrate parallel issue implementation with review cycles
|
||||
model: haiku
|
||||
argument-hint: <issue-number> [<issue-number>...]
|
||||
allowed-tools: Bash, Task, Read, TaskOutput
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Spawn Issues (Orchestrator)
|
||||
|
||||
Orchestrate parallel issue implementation: spawn workers, review PRs, fix feedback, until all approved.
|
||||
|
||||
## Arguments
|
||||
|
||||
One or more issue numbers separated by spaces: `$ARGUMENTS`
|
||||
|
||||
Example: `/spawn-issues 42 43 44`
|
||||
|
||||
## Orchestration Flow
|
||||
|
||||
```
|
||||
Concurrent Pipeline - each issue flows independently:
|
||||
|
||||
Issue #42 ──► worker ──► PR #55 ──► review ──► fix? ──► ✓
|
||||
Issue #43 ──► worker ──► PR #56 ──► review ──► ✓
|
||||
Issue #44 ──► worker ──► PR #57 ──► review ──► fix ──► ✓
|
||||
|
||||
As each step completes, immediately:
|
||||
1. Print a status update
|
||||
2. Start the next step for that issue
|
||||
|
||||
Don't wait for all workers before reviewing - pipeline each issue.
|
||||
```
|
||||
|
||||
## Status Updates
|
||||
|
||||
Print a brief status update whenever any step completes:
|
||||
|
||||
```
|
||||
[#42] Worker completed → PR #55 created
|
||||
[#43] Worker completed → PR #56 created
|
||||
[#42] Review: needs work → spawning fixer
|
||||
[#43] Review: approved ✓
|
||||
[#42] Fix completed → re-reviewing
|
||||
[#44] Worker completed → PR #57 created
|
||||
[#42] Review: approved ✓
|
||||
[#44] Review: approved ✓
|
||||
|
||||
All done! Final summary:
|
||||
| Issue | PR | Status |
|
||||
|-------|-----|----------|
|
||||
| #42 | #55 | approved |
|
||||
| #43 | #56 | approved |
|
||||
| #44 | #57 | approved |
|
||||
```
|
||||
|
||||
## Implementation
|
||||
|
||||
### Step 1: Parse and Validate
|
||||
|
||||
Parse `$ARGUMENTS` into a list of issue numbers. If empty, inform the user:
|
||||
```
|
||||
Usage: /spawn-issues <issue-number> [<issue-number>...]
|
||||
Example: /spawn-issues 42 43 44
|
||||
```
|
||||
|
||||
### Step 2: Get Repository Info and Setup Worktrees
|
||||
|
||||
```bash
|
||||
REPO_PATH=$(pwd)
|
||||
REPO_NAME=$(basename $REPO_PATH)
|
||||
|
||||
# Create parent worktrees directory
|
||||
mkdir -p "${REPO_PATH}/../worktrees"
|
||||
WORKTREES_DIR="${REPO_PATH}/../worktrees"
|
||||
```
|
||||
|
||||
For each issue, create the worktree upfront:
|
||||
```bash
|
||||
# Fetch latest from origin
|
||||
cd "${REPO_PATH}"
|
||||
git fetch origin
|
||||
|
||||
# Get issue details for branch naming
|
||||
ISSUE_TITLE=$(tea issues <ISSUE_NUMBER> | grep "TITLE" | head -1)
|
||||
BRANCH_NAME="issue-<ISSUE_NUMBER>-<kebab-title>"
|
||||
|
||||
# Create worktree for this issue
|
||||
git worktree add "${WORKTREES_DIR}/${REPO_NAME}-issue-<ISSUE_NUMBER>" \
|
||||
-b "${BRANCH_NAME}" origin/main
|
||||
```
|
||||
|
||||
Track the worktree path for each issue.
|
||||
|
||||
### Step 3: Spawn All Issue Workers
|
||||
|
||||
For each issue number, spawn a background issue-worker agent and track its task_id:
|
||||
|
||||
```
|
||||
Task tool with:
|
||||
- subagent_type: "issue-worker"
|
||||
- run_in_background: true
|
||||
- prompt: <issue-worker prompt below>
|
||||
```
|
||||
|
||||
Track state for each issue:
|
||||
```
|
||||
issues = {
|
||||
42: { task_id: "xxx", stage: "implementing", pr: null, branch: null, review_iterations: 0 },
|
||||
43: { task_id: "yyy", stage: "implementing", pr: null, branch: null, review_iterations: 0 },
|
||||
44: { task_id: "zzz", stage: "implementing", pr: null, branch: null, review_iterations: 0 },
|
||||
}
|
||||
```
|
||||
|
||||
Print initial status:
|
||||
```
|
||||
Spawned 3 issue workers:
|
||||
[#42] implementing...
|
||||
[#43] implementing...
|
||||
[#44] implementing...
|
||||
```
|
||||
|
||||
**Issue Worker Prompt:**
|
||||
```
|
||||
You are an issue-worker agent. Implement issue #<NUMBER> autonomously.
|
||||
|
||||
Context:
|
||||
- Repository path: <REPO_PATH>
|
||||
- Repository name: <REPO_NAME>
|
||||
- Issue number: <NUMBER>
|
||||
- Worktree path: <WORKTREE_PATH>
|
||||
|
||||
Process:
|
||||
1. Setup worktree:
|
||||
cd <WORKTREE_PATH>
|
||||
|
||||
2. Get issue: tea issues <NUMBER> --comments
|
||||
|
||||
3. Plan with TodoWrite, implement the changes
|
||||
|
||||
4. Commit: git add -A && git commit -m "...\n\nCloses #<NUMBER>\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
|
||||
|
||||
5. Push: git push -u origin <branch-name>
|
||||
|
||||
6. Create PR: tea pulls create --title "[Issue #<NUMBER>] <title>" --description "Closes #<NUMBER>\n\n..."
|
||||
Capture the PR number.
|
||||
|
||||
7. Cleanup: No cleanup needed - orchestrator handles worktree removal
|
||||
|
||||
8. Output EXACTLY this format (orchestrator parses it):
|
||||
ISSUE_WORKER_RESULT
|
||||
issue: <NUMBER>
|
||||
pr: <PR_NUMBER>
|
||||
branch: <branch-name>
|
||||
status: <success|partial|failed>
|
||||
title: <issue title>
|
||||
summary: <1-2 sentence description>
|
||||
|
||||
Work autonomously. If blocked, note it in PR description and report status as partial/failed.
|
||||
```
|
||||
|
||||
### Step 4: Event-Driven Pipeline
|
||||
|
||||
**Do NOT poll.** Wait for `<task-notification>` messages that arrive automatically when background tasks complete.
|
||||
|
||||
When a notification arrives:
|
||||
1. Read the output file to get the result
|
||||
2. Parse the result and print status update
|
||||
3. Spawn the next stage (reviewer/fixer) in background
|
||||
4. Continue waiting for more notifications
|
||||
|
||||
```
|
||||
On <task-notification> for task_id X:
|
||||
- Find which issue this task belongs to
|
||||
- Read output file, parse result
|
||||
- Print status update
|
||||
- If not terminal state, spawn next agent in background
|
||||
- Update issue state
|
||||
- If all issues terminal, print final summary
|
||||
```
|
||||
|
||||
**State transitions:**
|
||||
|
||||
```
|
||||
implementing → (worker done) → reviewing → (approved) → DONE
|
||||
→ (needs-work) → fixing → reviewing...
|
||||
→ (3 iterations) → needs-manual-review
|
||||
→ (worker failed) → FAILED
|
||||
```
|
||||
|
||||
**On each notification, print status:**
|
||||
|
||||
```
|
||||
[#42] Worker completed → PR #55 created, starting review
|
||||
[#43] Worker completed → PR #56 created, starting review
|
||||
[#42] Review: needs work → spawning fixer
|
||||
[#43] Review: approved ✓
|
||||
[#42] Fix completed → re-reviewing
|
||||
[#44] Worker completed → PR #57 created, starting review
|
||||
[#42] Review: approved ✓
|
||||
[#44] Review: approved ✓
|
||||
```
|
||||
|
||||
### Step 5: Spawn Reviewers and Fixers
|
||||
|
||||
When spawning reviewers/fixers, create worktrees for them and pass the path.
|
||||
|
||||
For review, create a review worktree from the PR branch:
|
||||
```bash
|
||||
cd "${REPO_PATH}"
|
||||
git fetch origin
|
||||
git worktree add "${WORKTREES_DIR}/${REPO_NAME}-review-<PR_NUMBER>" \
|
||||
origin/<BRANCH_NAME>
|
||||
```
|
||||
|
||||
Pass this worktree path to the reviewer/fixer agents.
|
||||
|
||||
**Code Reviewer:**
|
||||
```
|
||||
Task tool with:
|
||||
- subagent_type: "code-reviewer"
|
||||
- run_in_background: true
|
||||
- prompt: <code-reviewer prompt below>
|
||||
```
|
||||
|
||||
**Code Reviewer Prompt:**
|
||||
```
|
||||
You are a code-reviewer agent. Review PR #<PR_NUMBER> autonomously.
|
||||
|
||||
Context:
|
||||
- Repository path: <REPO_PATH>
|
||||
- PR number: <PR_NUMBER>
|
||||
- Worktree path: <WORKTREE_PATH>
|
||||
|
||||
Process:
|
||||
1. Move to worktree:
|
||||
cd <WORKTREE_PATH>
|
||||
|
||||
2. Get PR details: tea pulls <PR_NUMBER> --comments
|
||||
|
||||
3. Review the diff: git diff origin/main...HEAD
|
||||
|
||||
4. Analyze changes for:
|
||||
- Code quality and style
|
||||
- Potential bugs or logic errors
|
||||
- Test coverage
|
||||
- Documentation
|
||||
|
||||
5. Post review comment: tea comment <PR_NUMBER> "<review summary>"
|
||||
|
||||
6. Cleanup: No cleanup needed - orchestrator handles worktree removal
|
||||
|
||||
7. Output EXACTLY this format:
|
||||
REVIEW_RESULT
|
||||
pr: <PR_NUMBER>
|
||||
verdict: <approved|needs-work>
|
||||
summary: <1-2 sentences>
|
||||
|
||||
Work autonomously. Be constructive but thorough.
|
||||
```
|
||||
|
||||
**PR Fixer Prompt:** (see below)
|
||||
|
||||
### Step 6: Final Report
|
||||
|
||||
When all issues reach terminal state, display summary:
|
||||
|
||||
```
|
||||
All done!
|
||||
|
||||
| Issue | PR | Status |
|
||||
|-------|-----|---------------------|
|
||||
| #42 | #55 | approved |
|
||||
| #43 | #56 | approved |
|
||||
| #44 | #57 | approved |
|
||||
|
||||
3 PRs created and approved
|
||||
```
|
||||
|
||||
## PR Fixer
|
||||
|
||||
When spawning pr-fixer for a PR that needs work:
|
||||
|
||||
```
|
||||
Task tool with:
|
||||
- subagent_type: "pr-fixer"
|
||||
- run_in_background: true
|
||||
- prompt: <pr-fixer prompt below>
|
||||
```
|
||||
|
||||
**PR Fixer Prompt:**
|
||||
```
|
||||
You are a pr-fixer agent. Address review feedback on PR #<NUMBER>.
|
||||
|
||||
Context:
|
||||
- Repository path: <REPO_PATH>
|
||||
- PR number: <NUMBER>
|
||||
- Worktree path: <WORKTREE_PATH>
|
||||
|
||||
Process:
|
||||
1. Move to worktree:
|
||||
cd <WORKTREE_PATH>
|
||||
|
||||
2. Get feedback: tea pulls <NUMBER> --comments
|
||||
|
||||
3. Address each piece of feedback
|
||||
|
||||
4. Commit and push:
|
||||
git add -A && git commit -m "Address review feedback\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
|
||||
git push
|
||||
|
||||
5. Cleanup: No cleanup needed - orchestrator handles worktree removal
|
||||
|
||||
6. Output EXACTLY:
|
||||
PR_FIXER_RESULT
|
||||
pr: <NUMBER>
|
||||
status: <fixed|partial|failed>
|
||||
changes: <summary of fixes>
|
||||
|
||||
Work autonomously. If feedback is unclear, make reasonable judgment calls.
|
||||
```
|
||||
|
||||
## Worktree Cleanup
|
||||
|
||||
After all issues reach terminal state, clean up all worktrees:
|
||||
|
||||
```bash
|
||||
# Remove all worktrees created for this run
|
||||
for worktree in "${WORKTREES_DIR}"/*; do
|
||||
if [ -d "$worktree" ]; then
|
||||
cd "${REPO_PATH}"
|
||||
git worktree remove "$worktree" --force
|
||||
fi
|
||||
done
|
||||
|
||||
# Remove worktrees directory if empty
|
||||
rmdir "${WORKTREES_DIR}" 2>/dev/null || true
|
||||
```
|
||||
|
||||
**Important:** Always clean up worktrees, even if the orchestration failed partway through.
|
||||
|
||||
## Error Handling
|
||||
|
||||
- If an issue-worker fails, continue with others
|
||||
- If a review fails, mark as "review-failed" and continue
|
||||
- If pr-fixer fails after 3 iterations, mark as "needs-manual-review"
|
||||
- Always report final status even if some items failed
|
||||
- Always clean up all worktrees before exiting
|
||||
124
skills/spawn-pr-fixes/SKILL.md
Normal file
124
skills/spawn-pr-fixes/SKILL.md
Normal file
@@ -0,0 +1,124 @@
|
||||
---
|
||||
name: spawn-pr-fixes
|
||||
description: Spawn parallel background agents to address PR review feedback
|
||||
model: haiku
|
||||
argument-hint: [pr-number...]
|
||||
allowed-tools: Bash, Task, Read
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Spawn PR Fixes
|
||||
|
||||
Spawn background agents to address review feedback on multiple PRs in parallel. Each agent works in an isolated git worktree.
|
||||
|
||||
## Arguments
|
||||
|
||||
Optional PR numbers separated by spaces: `$ARGUMENTS`
|
||||
|
||||
- With arguments: `/spawn-pr-fixes 12 15 18` - fix specific PRs
|
||||
- Without arguments: `/spawn-pr-fixes` - find and fix all PRs with requested changes
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Get Repository Info
|
||||
|
||||
```bash
|
||||
REPO_PATH=$(pwd)
|
||||
REPO_NAME=$(basename $REPO_PATH)
|
||||
```
|
||||
|
||||
### Step 2: Determine PRs to Fix
|
||||
|
||||
**If PR numbers provided**: Use those directly
|
||||
|
||||
**If no arguments**: Find PRs needing work
|
||||
```bash
|
||||
# List open PRs
|
||||
tea pulls --state open
|
||||
|
||||
# For each PR, check if it has review comments requesting changes
|
||||
tea pulls <number> --comments
|
||||
```
|
||||
|
||||
Look for PRs where:
|
||||
- Review comments exist that haven't been addressed
|
||||
- PR is not approved yet
|
||||
- PR is open (not merged/closed)
|
||||
|
||||
### Step 3: For Each PR
|
||||
|
||||
1. Fetch PR title using `tea pulls <number>`
|
||||
|
||||
2. Spawn background agent using Task tool:
|
||||
```
|
||||
Task tool with:
|
||||
- subagent_type: "pr-fixer"
|
||||
- run_in_background: true
|
||||
- prompt: See agent prompt below
|
||||
```
|
||||
|
||||
### Agent Prompt
|
||||
|
||||
For each PR, use this prompt:
|
||||
|
||||
```
|
||||
You are a pr-fixer agent. Address review feedback on PR #<NUMBER> autonomously.
|
||||
|
||||
Context:
|
||||
- Repository path: <REPO_PATH>
|
||||
- Repository name: <REPO_NAME>
|
||||
- PR number: <NUMBER>
|
||||
|
||||
Instructions from @agents/pr-fixer/agent.md:
|
||||
|
||||
1. Get PR details and review comments:
|
||||
cd <REPO_PATH>
|
||||
git fetch origin
|
||||
tea pulls <NUMBER> --comments
|
||||
|
||||
2. Setup worktree from PR branch:
|
||||
git worktree add ../<REPO_NAME>-pr-<NUMBER> origin/<branch-name>
|
||||
cd ../<REPO_NAME>-pr-<NUMBER>
|
||||
git checkout <branch-name>
|
||||
|
||||
3. Analyze feedback, create todos with TodoWrite
|
||||
|
||||
4. Address each piece of feedback
|
||||
|
||||
5. Commit and push:
|
||||
git add -A && git commit with message "Address review feedback\n\n...\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
|
||||
git push
|
||||
|
||||
6. Spawn code-reviewer synchronously (NOT in background) to re-review
|
||||
|
||||
7. If needs more work, fix and re-review (max 3 iterations)
|
||||
|
||||
8. Cleanup (ALWAYS do this):
|
||||
cd <REPO_PATH> && git worktree remove ../<REPO_NAME>-pr-<NUMBER> --force
|
||||
|
||||
9. Output concise summary (5-10 lines max):
|
||||
PR #<NUMBER>: <title>
|
||||
Status: <fixed|partial|blocked>
|
||||
Feedback addressed: <count> items
|
||||
Review: <approved|needs-work|skipped>
|
||||
|
||||
Work autonomously. Make judgment calls on ambiguous feedback. If blocked, note it in a commit message.
|
||||
```
|
||||
|
||||
### Step 4: Report
|
||||
|
||||
After spawning all agents, display:
|
||||
|
||||
```
|
||||
Spawned <N> pr-fixer agents:
|
||||
|
||||
| PR | Title | Status |
|
||||
|-----|--------------------------|------------|
|
||||
| #12 | Add /commit command | spawned |
|
||||
| #15 | Add /pr command | spawned |
|
||||
| #18 | Add CI status | spawned |
|
||||
|
||||
Agents working in background. Monitor with:
|
||||
- Check PR list: tea pulls
|
||||
- Check worktrees: git worktree list
|
||||
```
|
||||
171
skills/update-claude-md/SKILL.md
Normal file
171
skills/update-claude-md/SKILL.md
Normal file
@@ -0,0 +1,171 @@
|
||||
---
|
||||
name: update-claude-md
|
||||
description: >
|
||||
Update or create CLAUDE.md with current project context. Explores the project
|
||||
and ensures organization context is present. Use when updating project docs,
|
||||
adding CLAUDE.md, or when user says /update-claude-md.
|
||||
model: haiku
|
||||
context: fork
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Update CLAUDE.md
|
||||
|
||||
@~/.claude/skills/claude-md-writing/SKILL.md
|
||||
@~/.claude/skills/repo-conventions/SKILL.md
|
||||
|
||||
Update or create CLAUDE.md for the current repository with proper organization context and current project state.
|
||||
|
||||
## Process
|
||||
|
||||
1. **Check for existing CLAUDE.md**: Look for `CLAUDE.md` in repo root
|
||||
|
||||
2. **If CLAUDE.md exists**:
|
||||
- Read current content
|
||||
- Identify which sections exist
|
||||
- Note any custom content to preserve
|
||||
|
||||
3. **Explore the project**:
|
||||
- Scan directory structure
|
||||
- Identify language/framework (go.mod, package.json, Cargo.toml, etc.)
|
||||
- Find key patterns (look for common directories, config files)
|
||||
- Check for Makefile or build scripts
|
||||
|
||||
4. **Check organization context**:
|
||||
- Does it have the "Organization Context" section?
|
||||
- Does it link to `../architecture/manifesto.md`?
|
||||
- Does it link to `../architecture/repos.md`?
|
||||
- Does it link to `./vision.md`?
|
||||
|
||||
5. **Gather missing information**:
|
||||
- If no one-line description: Ask user
|
||||
- If no architecture section: Infer from code or ask user
|
||||
|
||||
6. **Update CLAUDE.md**:
|
||||
|
||||
**Always ensure these sections exist:**
|
||||
|
||||
```markdown
|
||||
# [Project Name]
|
||||
|
||||
[One-line description]
|
||||
|
||||
## Organization Context
|
||||
|
||||
This repo is part of Flowmade. See:
|
||||
- [Organization manifesto](../architecture/manifesto.md) - who we are, what we believe
|
||||
- [Repository map](../architecture/repos.md) - how this fits in the bigger picture
|
||||
- [Vision](./vision.md) - what this specific product does
|
||||
|
||||
## Setup
|
||||
|
||||
[From existing or ask user]
|
||||
|
||||
## Project Structure
|
||||
|
||||
[Generate from actual directory scan]
|
||||
|
||||
## Development
|
||||
|
||||
[From Makefile or existing]
|
||||
|
||||
## Architecture
|
||||
|
||||
[From existing or infer from code patterns]
|
||||
```
|
||||
|
||||
7. **Preserve custom content**:
|
||||
- Keep any additional sections the user added
|
||||
- Don't remove information, only add/update
|
||||
- If unsure, ask before removing
|
||||
|
||||
8. **Show diff and confirm**:
|
||||
- Show what will change
|
||||
- Ask user to confirm before writing
|
||||
|
||||
## Section-Specific Guidance
|
||||
|
||||
### Project Structure
|
||||
|
||||
Generate from actual directory scan:
|
||||
```bash
|
||||
# Scan top-level and key subdirectories
|
||||
ls -la
|
||||
ls pkg/ cmd/ internal/ src/ (as applicable)
|
||||
```
|
||||
|
||||
Format as tree showing purpose:
|
||||
```markdown
|
||||
## Project Structure
|
||||
|
||||
\`\`\`
|
||||
project/
|
||||
├── cmd/ # Entry points
|
||||
├── pkg/ # Shared packages
|
||||
│ ├── domain/ # Business logic
|
||||
│ └── infra/ # Infrastructure
|
||||
└── internal/ # Private packages
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### Development Commands
|
||||
|
||||
Extract from Makefile if present:
|
||||
```bash
|
||||
grep -E "^[a-zA-Z_-]+:" Makefile | head -10
|
||||
```
|
||||
|
||||
Or from package.json scripts, Cargo.toml, etc.
|
||||
|
||||
### Architecture
|
||||
|
||||
Look for patterns:
|
||||
- Event sourcing: Check for aggregates, events, projections
|
||||
- Clean architecture: Check for domain, application, infrastructure layers
|
||||
- API style: REST, gRPC, GraphQL
|
||||
|
||||
If unsure, ask: "What are the key architectural patterns in this project?"
|
||||
|
||||
## Output Example
|
||||
|
||||
```
|
||||
## Updating CLAUDE.md
|
||||
|
||||
### Current State
|
||||
- Has description: ✓
|
||||
- Has org context: ✗ (will add)
|
||||
- Has setup: ✓
|
||||
- Has structure: Outdated (will update)
|
||||
- Has development: ✓
|
||||
- Has architecture: ✗ (will add)
|
||||
|
||||
### Changes
|
||||
|
||||
+ Adding Organization Context section
|
||||
~ Updating Project Structure (new directories found)
|
||||
+ Adding Architecture section
|
||||
|
||||
### New Project Structure
|
||||
|
||||
\`\`\`
|
||||
arcadia/
|
||||
├── cmd/
|
||||
├── pkg/
|
||||
│ ├── aether/ # Event sourcing runtime
|
||||
│ ├── iris/ # WASM UI framework
|
||||
│ ├── adl/ # Domain language
|
||||
│ └── ...
|
||||
└── internal/
|
||||
\`\`\`
|
||||
|
||||
Proceed with update? [y/n]
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Always add Organization Context if missing
|
||||
- Preserve existing custom sections
|
||||
- Update Project Structure from actual filesystem
|
||||
- Don't guess at Architecture - ask if unclear
|
||||
- Show changes before writing
|
||||
- Reference claude-md-writing skill for best practices
|
||||
214
skills/vision/SKILL.md
Normal file
214
skills/vision/SKILL.md
Normal file
@@ -0,0 +1,214 @@
|
||||
---
|
||||
name: vision
|
||||
description: >
|
||||
View the product vision and goal progress. Manages vision.md and Gitea milestones.
|
||||
Use when viewing vision, managing goals, or when user says /vision.
|
||||
model: haiku
|
||||
argument-hint: [goals]
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Product Vision
|
||||
|
||||
@~/.claude/skills/vision-management/SKILL.md
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
|
||||
This skill manages **product-level** vision. For organization-level vision, use `/manifesto`.
|
||||
|
||||
## Architecture
|
||||
|
||||
| Level | Document | Purpose | Skill |
|
||||
|-------|----------|---------|-------|
|
||||
| **Organization** | `manifesto.md` | Who we are, shared personas, beliefs | `/manifesto` |
|
||||
| **Product** | `vision.md` | Product-specific personas, jobs, solution | `/vision` |
|
||||
| **Goals** | Gitea milestones | Measurable progress toward vision | `/vision goals` |
|
||||
|
||||
Product vision **inherits from and extends** the organization manifesto - it should never duplicate.
|
||||
|
||||
## Manifesto Location
|
||||
|
||||
The manifesto lives in the sibling `architecture` repo:
|
||||
|
||||
```
|
||||
org/
|
||||
├── architecture/
|
||||
│ └── manifesto.md ← organization manifesto
|
||||
├── product-a/
|
||||
│ └── vision.md ← extends ../architecture/manifesto.md
|
||||
└── product-b/
|
||||
└── vision.md
|
||||
```
|
||||
|
||||
Look for manifesto in this order:
|
||||
1. `./manifesto.md` (if this IS the architecture repo)
|
||||
2. `../architecture/manifesto.md` (sibling repo)
|
||||
|
||||
## Process
|
||||
|
||||
1. **Load organization context**: Find and read `manifesto.md` using the location rules above
|
||||
- Extract personas (Who We Serve)
|
||||
- Extract jobs to be done (What They're Trying to Achieve)
|
||||
- Extract guiding principles
|
||||
- Extract non-goals
|
||||
- If not found, warn and continue without inheritance context
|
||||
|
||||
2. **Check for product vision**: Look for `vision.md` in the current repo root
|
||||
|
||||
3. **If no vision exists**:
|
||||
- Show the organization manifesto summary
|
||||
- Ask if the user wants to create a product vision
|
||||
- Guide them through defining (with inheritance):
|
||||
|
||||
**Who This Product Serves**
|
||||
- Show manifesto personas first
|
||||
- Ask: "Which personas does this product serve? How does it extend or specialize them?"
|
||||
- Product personas should reference org personas with product-specific context
|
||||
|
||||
**What They're Trying to Achieve**
|
||||
- Show manifesto jobs first
|
||||
- Ask: "What product-specific jobs does this enable? How do they trace back to org jobs?"
|
||||
- Use a table format showing the connection
|
||||
|
||||
**The Problem**
|
||||
- What pain points does this product solve?
|
||||
|
||||
**The Solution**
|
||||
- How does this product address those jobs?
|
||||
|
||||
**Product Principles**
|
||||
- Show manifesto principles first
|
||||
- Ask: "Any product-specific principles? These should extend, not duplicate."
|
||||
- Each principle should note what org principle it extends
|
||||
|
||||
**Product Non-Goals**
|
||||
- Show manifesto non-goals first
|
||||
- Ask: "Any product-specific non-goals?"
|
||||
- Org non-goals apply automatically
|
||||
|
||||
- Create `vision.md` with proper inheritance markers
|
||||
- Ask about initial goals, create as Gitea milestones
|
||||
|
||||
4. **If vision exists**:
|
||||
- Display organization context summary
|
||||
- Display the product vision from `vision.md`
|
||||
- Validate inheritance (warn if vision duplicates rather than extends)
|
||||
- Show current milestones and their progress: `tea milestones`
|
||||
- Check if `$1` specifies an action:
|
||||
- `goals`: Manage milestones (add, close, view progress)
|
||||
- If no action specified, just display the current state
|
||||
|
||||
5. **Managing Goals (milestones)**:
|
||||
```bash
|
||||
# List milestones with progress
|
||||
tea milestones
|
||||
|
||||
# Create a new goal
|
||||
tea milestones create --title "<goal>" --description "For: <persona>
|
||||
Job: <job to be done>
|
||||
Success: <criteria>"
|
||||
|
||||
# View issues in a milestone
|
||||
tea milestones issues <milestone-name>
|
||||
|
||||
# Close a completed goal
|
||||
tea milestones close <milestone-name>
|
||||
```
|
||||
|
||||
## Vision Structure Template
|
||||
|
||||
```markdown
|
||||
# Vision
|
||||
|
||||
This product vision builds on the [organization manifesto](../architecture/manifesto.md).
|
||||
|
||||
## Who This Product Serves
|
||||
|
||||
### [Persona Name]
|
||||
|
||||
[Product-specific description]
|
||||
|
||||
*Extends: [Org persona] (from manifesto)*
|
||||
|
||||
## What They're Trying to Achieve
|
||||
|
||||
These trace back to organization-level jobs:
|
||||
|
||||
| Product Job | Enables Org Job |
|
||||
|-------------|-----------------|
|
||||
| "[Product-specific job]" | "[Org job from manifesto]" |
|
||||
|
||||
## The Problem
|
||||
|
||||
[Pain points this product addresses]
|
||||
|
||||
## The Solution
|
||||
|
||||
[How this product solves those problems]
|
||||
|
||||
## Product Principles
|
||||
|
||||
These extend the organization's guiding principles:
|
||||
|
||||
### [Principle Name]
|
||||
|
||||
[Description]
|
||||
|
||||
*Extends: "[Org principle]"*
|
||||
|
||||
## Non-Goals
|
||||
|
||||
These extend the organization's non-goals:
|
||||
|
||||
- **[Non-goal].** [Explanation]
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
```
|
||||
## Organization Context
|
||||
|
||||
From manifesto.md:
|
||||
- **Personas**: [list from manifesto]
|
||||
- **Core beliefs**: [key beliefs]
|
||||
- **Principles**: [list]
|
||||
|
||||
## Product: [Name]
|
||||
|
||||
### Who This Product Serves
|
||||
|
||||
- **[Persona 1]**: [Product-specific description]
|
||||
↳ Extends: [Org persona]
|
||||
|
||||
### What They're Trying to Achieve
|
||||
|
||||
| Product Job | → Org Job |
|
||||
|-------------|-----------|
|
||||
| [job] | [org job it enables] |
|
||||
|
||||
### Vision Summary
|
||||
|
||||
[Problem/solution from vision.md]
|
||||
|
||||
### Goals (Milestones)
|
||||
|
||||
| Goal | For | Progress | Due |
|
||||
|------|-----|----------|-----|
|
||||
| [title] | [Persona] | 3/5 issues | [date] |
|
||||
```
|
||||
|
||||
## Inheritance Rules
|
||||
|
||||
- **Personas**: Product personas extend org personas with product-specific context
|
||||
- **Jobs**: Product jobs trace back to org-level jobs (show the connection)
|
||||
- **Beliefs**: Inherited from manifesto, never duplicated in vision
|
||||
- **Principles**: Product adds specific principles that extend org principles
|
||||
- **Non-Goals**: Product adds its own; org non-goals apply automatically
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Product vision builds on organization manifesto - extend, don't duplicate
|
||||
- Every product persona should reference which org persona it extends
|
||||
- Every product job should show which org job it enables
|
||||
- Product principles should note which org principle they extend
|
||||
- Use `/manifesto` for organization-level identity and beliefs
|
||||
- Use `/vision` for product-specific direction and goals
|
||||
24
skills/work-issue/SKILL.md
Normal file
24
skills/work-issue/SKILL.md
Normal file
@@ -0,0 +1,24 @@
|
||||
---
|
||||
name: work-issue
|
||||
description: >
|
||||
Work on a Gitea issue. Fetches issue details and sets up branch for implementation.
|
||||
Use when working on issues, implementing features, or when user says /work-issue.
|
||||
model: haiku
|
||||
argument-hint: <issue-number>
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Work on Issue #$1
|
||||
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
@~/.claude/skills/software-architecture/SKILL.md
|
||||
|
||||
1. **View the issue** with `--comments` flag to understand requirements and context
|
||||
2. **Create a branch**: `git checkout -b issue-$1-<short-kebab-title>`
|
||||
3. **Plan**: Use TodoWrite to break down the work based on acceptance criteria
|
||||
4. **Check architecture**: Review the project's vision.md Architecture section for project-specific patterns and divergences
|
||||
5. **Implement** the changes following architectural patterns (DDD, event sourcing where appropriate)
|
||||
6. **Commit** with message referencing the issue
|
||||
7. **Push** the branch to origin
|
||||
8. **Create PR** with title "[Issue #$1] <title>" and body "Closes #$1"
|
||||
9. **Auto-review**: Inform the user that auto-review is starting, then spawn the `code-reviewer` agent in background (using `run_in_background: true`) with the PR number
|
||||
Reference in New Issue
Block a user