Compare commits
34
Commits
@@ -16,11 +16,3 @@
|
||||
secrets/
|
||||
*.pem
|
||||
*.key
|
||||
|
||||
# opencode
|
||||
.opencode/opencode.json
|
||||
.opencode/package-lock.json
|
||||
|
||||
node_modules
|
||||
bun.lock
|
||||
package-lock.json
|
||||
@@ -1,13 +0,0 @@
|
||||
import { tool } from "@opencode-ai/plugin"
|
||||
import { $ } from "bun"
|
||||
|
||||
export default tool({
|
||||
description: "Create a git worktree for a branch or PR",
|
||||
args: {
|
||||
branch: tool.schema.string().describe("Branch name or PR number"),
|
||||
},
|
||||
async execute(args) {
|
||||
const result = await $`git worktree add ../worktrees/${args.branch}`.text()
|
||||
return result.trim()
|
||||
},
|
||||
})
|
||||
@@ -1,23 +0,0 @@
|
||||
import { tool } from "@opencode-ai/plugin"
|
||||
import { $ } from "bun"
|
||||
|
||||
export default tool({
|
||||
description: "List workflow runs for Gitea actions with optional filters",
|
||||
args: {
|
||||
status: tool.schema.string().optional().describe("Filter by status (success, failure, pending, queued, in_progress, skipped, canceled)"),
|
||||
branch: tool.schema.string().optional().describe("Filter by branch name"),
|
||||
event: tool.schema.string().optional().describe("Filter by event type (push, pull_request, etc.)"),
|
||||
limit: tool.schema.number().optional().describe("Number of results to return (default: 30)"),
|
||||
since: tool.schema.string().optional().describe("Show runs started after this time (e.g., '24h', '7d')"),
|
||||
},
|
||||
async execute(args) {
|
||||
let cmd = [`tea`, `actions`, `runs`, `list`, `-o`, `json`]
|
||||
if (args.status) cmd = [...cmd, `--status`, args.status]
|
||||
if (args.branch) cmd = [...cmd, `--branch`, args.branch]
|
||||
if (args.event) cmd = [...cmd, `--event`, args.event]
|
||||
if (args.limit) cmd = [...cmd, `--limit`, String(args.limit)]
|
||||
if (args.since) cmd = [...cmd, `--since`, args.since]
|
||||
const result = await $`${cmd}`.text()
|
||||
return result.trim()
|
||||
},
|
||||
})
|
||||
@@ -1,17 +0,0 @@
|
||||
import { tool } from "@opencode-ai/plugin"
|
||||
import { $ } from "bun"
|
||||
|
||||
export default tool({
|
||||
description: "Get logs for a specific Gitea actions workflow run to diagnose failures",
|
||||
args: {
|
||||
runId: tool.schema.number().describe("Workflow run ID to get logs for"),
|
||||
job: tool.schema.string().optional().describe("Specific job ID to view (if omitted, shows all jobs)"),
|
||||
},
|
||||
async execute(args) {
|
||||
let cmd = [`tea`, `actions`, `runs`, `logs`]
|
||||
if (args.job) cmd = [...cmd, `--job`, args.job]
|
||||
cmd = [...cmd, String(args.runId), `-o`, `simple`]
|
||||
const result = await $`${cmd}`.text()
|
||||
return result.trim()
|
||||
},
|
||||
})
|
||||
@@ -1,14 +0,0 @@
|
||||
import { tool } from "@opencode-ai/plugin"
|
||||
import { $ } from "bun"
|
||||
|
||||
export default tool({
|
||||
description: "Add a comment to a specific issue using tea CLI",
|
||||
args: {
|
||||
issueNumber: tool.schema.number().describe("Issue number/index"),
|
||||
body: tool.schema.string().describe("Comment body"),
|
||||
},
|
||||
async execute(args) {
|
||||
const result = await $`tea comment ${args.issueNumber} ${args.body}`.text()
|
||||
return result.trim()
|
||||
},
|
||||
})
|
||||
@@ -1,14 +0,0 @@
|
||||
import { tool } from "@opencode-ai/plugin"
|
||||
import { $ } from "bun"
|
||||
|
||||
export default tool({
|
||||
description: "Create a new issue in the GitHub repository using tea CLI",
|
||||
args: {
|
||||
title: tool.schema.string().describe("Issue title"),
|
||||
description: tool.schema.string().optional().describe("Issue description (supports markdown)"),
|
||||
},
|
||||
async execute(args) {
|
||||
const result = await $`tea issues create -t ${args.title} -d ${args.description}`.text()
|
||||
return result.trim()
|
||||
},
|
||||
})
|
||||
@@ -1,13 +0,0 @@
|
||||
import { tool } from "@opencode-ai/plugin"
|
||||
import { $ } from "bun"
|
||||
|
||||
export default tool({
|
||||
description: "Get a specific issue with all details and comments using tea CLI",
|
||||
args: {
|
||||
issueNumber: tool.schema.number().describe("Issue number/index"),
|
||||
},
|
||||
async execute(args) {
|
||||
const result = await $`tea issues ${args.issueNumber} --comments --output json`.text()
|
||||
return result.trim()
|
||||
},
|
||||
})
|
||||
@@ -1,11 +0,0 @@
|
||||
import { tool } from "@opencode-ai/plugin"
|
||||
import { $ } from "bun"
|
||||
|
||||
export default tool({
|
||||
description: "List all issues in the project using tea CLI",
|
||||
args: {},
|
||||
async execute(args, context) {
|
||||
const result = await $`tea issues list`.text()
|
||||
return result.trim()
|
||||
},
|
||||
})
|
||||
@@ -1,24 +0,0 @@
|
||||
import { tool } from "@opencode-ai/plugin"
|
||||
import { $ } from "bun"
|
||||
|
||||
export default tool({
|
||||
description: "Create a pull request in the repository using tea CLI",
|
||||
args: {
|
||||
title: tool.schema.string().describe("PR title"),
|
||||
head: tool.schema.string().optional().describe("Branch name of the PR source (defaults to current branch)"),
|
||||
base: tool.schema.string().optional().describe("Branch name of the PR target (defaults to repository default branch)"),
|
||||
description: tool.schema.string().optional().describe("PR description (supports markdown)"),
|
||||
assignees: tool.schema.string().optional().describe("Comma-separated list of usernames to assign"),
|
||||
labels: tool.schema.string().optional().describe("Comma-separated list of labels to assign"),
|
||||
},
|
||||
async execute(args) {
|
||||
let cmd = [`tea`, `pulls`, `create`, `-t`, args.title]
|
||||
if (args.head) cmd = [...cmd, `--head`, args.head]
|
||||
if (args.base) cmd = [...cmd, `-b`, args.base]
|
||||
if (args.description) cmd = [...cmd, `-d`, args.description]
|
||||
if (args.assignees) cmd = [...cmd, `-a`, args.assignees]
|
||||
if (args.labels) cmd = [...cmd, `-L`, args.labels]
|
||||
const result = await $`${cmd}`.text()
|
||||
return result.trim()
|
||||
},
|
||||
})
|
||||
@@ -1,13 +0,0 @@
|
||||
import { tool } from "@opencode-ai/plugin"
|
||||
import { $ } from "bun"
|
||||
|
||||
export default tool({
|
||||
description: "Get a specific pull request with all details and comments using tea CLI",
|
||||
args: {
|
||||
pullNumber: tool.schema.number().describe("Pull request number/index"),
|
||||
},
|
||||
async execute(args) {
|
||||
const result = await $`tea pulls ${args.pullNumber} --comments --output json`.text()
|
||||
return result.trim()
|
||||
},
|
||||
})
|
||||
@@ -1,14 +0,0 @@
|
||||
import { tool } from "@opencode-ai/plugin"
|
||||
import { $ } from "bun"
|
||||
|
||||
export default tool({
|
||||
description: "List pull requests in the repository using tea CLI",
|
||||
args: {
|
||||
state: tool.schema.string().optional().describe("Filter by state (all|open|closed)"),
|
||||
},
|
||||
async execute(args) {
|
||||
const state = args.state || "open"
|
||||
const result = await $`tea pulls --state ${state} --output json`.text()
|
||||
return result.trim()
|
||||
},
|
||||
})
|
||||
+426
@@ -0,0 +1,426 @@
|
||||
# Architecture
|
||||
|
||||
This document explains how the three component types—Commands, Skills, and Agents—work together to create a composable AI workflow system.
|
||||
|
||||
## Overview
|
||||
|
||||
The architecture follows a layered composition model where each component type serves a distinct purpose:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ USER │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐ │
|
||||
│ │ COMMANDS │ │
|
||||
│ │ User-facing entry points │ │
|
||||
│ │ /work-issue /dashboard /plan-issues /groom │ │
|
||||
│ └─────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌────────────┼────────────┐ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ AGENTS │ │ SKILLS │ │
|
||||
│ │ Specialized │ │ Knowledge modules │ │
|
||||
│ │ subagents │ │ │ │
|
||||
│ │ │ │ issue-writing gitea │ │
|
||||
│ │ product-manager │ │ backlog-grooming roadmap-planning │ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
│ │ ▲ │
|
||||
│ └────────────────────┘ │
|
||||
│ Agents use skills │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Components
|
||||
|
||||
### Commands
|
||||
|
||||
**Location:** `commands/*.md`
|
||||
|
||||
Commands are user-facing entry points that trigger workflows. They define *what* to do, not *how* to do it.
|
||||
|
||||
#### Structure
|
||||
|
||||
Each command file contains:
|
||||
- **Frontmatter**: Metadata including description and argument hints
|
||||
- **Instructions**: Step-by-step workflow for Claude to follow
|
||||
- **Tool references**: Which CLI tools or skills to invoke
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: Work on a Gitea issue
|
||||
argument-hint: <issue-number>
|
||||
---
|
||||
|
||||
# Work on Issue #$1
|
||||
|
||||
1. **View the issue**: `tea issues $1`
|
||||
2. **Create a branch**: `git checkout -b issue-$1-<title>`
|
||||
...
|
||||
```
|
||||
|
||||
#### Characteristics
|
||||
|
||||
- **Invoked explicitly** by users via `/command-name`
|
||||
- **Self-contained workflows** with clear start and end
|
||||
- **May use skills** for domain knowledge
|
||||
- **May spawn agents** for complex subtasks
|
||||
- **Request approval** before significant actions
|
||||
|
||||
#### When to Create a Command
|
||||
|
||||
Create a command when you have:
|
||||
- A repeatable workflow with clear steps
|
||||
- User-initiated action (not automatic)
|
||||
- Need for consistent behavior across sessions
|
||||
|
||||
#### Current Commands
|
||||
|
||||
| Command | Purpose | Skills Used |
|
||||
|---------|---------|-------------|
|
||||
| `/work-issue` | Implement an issue end-to-end | gitea |
|
||||
| `/dashboard` | View open issues and PRs | gitea |
|
||||
| `/review-pr` | Review and act on a PR | gitea |
|
||||
| `/create-issue` | Create single or batch issues | gitea, issue-writing |
|
||||
| `/groom` | Improve issue quality | backlog-grooming, issue-writing |
|
||||
| `/roadmap` | View issues organized by status | gitea, roadmap-planning |
|
||||
| `/plan-issues` | Break down features into issues | roadmap-planning, issue-writing, gitea |
|
||||
|
||||
---
|
||||
|
||||
### Skills
|
||||
|
||||
**Location:** `skills/<skill-name>/SKILL.md`
|
||||
|
||||
Skills are knowledge modules—focused documents that teach Claude how to do something well. They encode domain expertise and best practices.
|
||||
|
||||
#### Structure
|
||||
|
||||
Each skill file contains:
|
||||
- **Conceptual knowledge**: What Claude needs to understand
|
||||
- **Patterns and templates**: Reusable structures
|
||||
- **Guidelines and checklists**: Quality standards
|
||||
- **Examples**: Concrete illustrations
|
||||
|
||||
```markdown
|
||||
# Issue Writing
|
||||
|
||||
How to write clear, actionable issues.
|
||||
|
||||
## Issue Structure
|
||||
### Title
|
||||
- Start with action verb: "Add", "Fix", "Update"
|
||||
- Be specific: "Add user authentication" not "Auth stuff"
|
||||
...
|
||||
```
|
||||
|
||||
#### Characteristics
|
||||
|
||||
- **Passive knowledge** that doesn't act on its own
|
||||
- **Focused scope**: one domain, one concern
|
||||
- **Composable**: multiple skills can be combined
|
||||
- **Referenced** by commands and agents
|
||||
- **No side effects**: information only
|
||||
|
||||
#### When to Create a Skill
|
||||
|
||||
Create a skill when you find yourself:
|
||||
- Explaining the same concepts repeatedly
|
||||
- Wanting consistent quality in a specific area
|
||||
- Building up domain expertise that should persist
|
||||
|
||||
#### Current Skills
|
||||
|
||||
| Skill | Purpose |
|
||||
|-------|---------|
|
||||
| `gitea` | How to use the Gitea CLI for issues and PRs |
|
||||
| `issue-writing` | How to structure clear, actionable issues |
|
||||
| `backlog-grooming` | How to review and improve existing issues |
|
||||
| `roadmap-planning` | How to plan features and create issue breakdowns |
|
||||
| `code-review` | How to review code for quality, bugs, security, and style |
|
||||
|
||||
---
|
||||
|
||||
### Agents
|
||||
|
||||
**Location:** `agents/<agent-name>/AGENT.md`
|
||||
|
||||
Agents are specialized subagents that combine multiple skills into focused personas. They can work autonomously on complex tasks with isolated context.
|
||||
|
||||
#### Structure
|
||||
|
||||
Each agent file uses YAML frontmatter followed by a system prompt:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: agent-name
|
||||
description: When this agent should be invoked (used for automatic delegation)
|
||||
model: inherit
|
||||
skills: skill1, skill2, skill3
|
||||
---
|
||||
|
||||
You are a [role] specializing in [domain].
|
||||
|
||||
## Capabilities
|
||||
|
||||
You can:
|
||||
- Do thing one
|
||||
- Do thing two
|
||||
|
||||
## Behavior
|
||||
|
||||
- Guideline one
|
||||
- Guideline two
|
||||
```
|
||||
|
||||
#### Frontmatter Fields
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `name` | Yes | Unique identifier (lowercase, hyphens) |
|
||||
| `description` | Yes | When to use this agent (enables auto-delegation) |
|
||||
| `model` | No | `sonnet`, `opus`, `haiku`, or `inherit` |
|
||||
| `skills` | No | Comma-separated skill names to auto-load |
|
||||
| `tools` | No | Limit available tools (inherits all if omitted) |
|
||||
|
||||
#### Characteristics
|
||||
|
||||
- **Isolated context**: Each agent maintains separate conversation state
|
||||
- **Skill composition**: Combines multiple skills for complex tasks
|
||||
- **Autonomous operation**: Can work with minimal intervention
|
||||
- **Spawned by commands**: Commands decide when to use agents
|
||||
- **Returns results**: Reports back to the main conversation
|
||||
|
||||
#### When to Create an Agent
|
||||
|
||||
Create an agent when you need:
|
||||
- To combine multiple skills for a role
|
||||
- Parallel processing of independent tasks
|
||||
- Isolated context to prevent pollution
|
||||
- Autonomous handling of complex workflows
|
||||
|
||||
#### Current Agents
|
||||
|
||||
| Agent | Skills | Use Case |
|
||||
|-------|--------|----------|
|
||||
| `product-manager` | gitea, issue-writing, backlog-grooming, roadmap-planning | Batch issue operations, backlog reviews, feature planning |
|
||||
| `code-reviewer` | gitea, code-review | Automated PR review, quality checks |
|
||||
|
||||
---
|
||||
|
||||
## Data and Control Flow
|
||||
|
||||
### Invocation Flow
|
||||
|
||||
```
|
||||
User invokes command
|
||||
│
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ Command executes │
|
||||
│ workflow steps │
|
||||
└───────────────────┘
|
||||
│
|
||||
├─── Direct action (git, tea CLI)
|
||||
│
|
||||
├─── Reference skill for knowledge
|
||||
│ │
|
||||
│ ▼
|
||||
│ ┌─────────────────┐
|
||||
│ │ Skill provides │
|
||||
│ │ patterns and │
|
||||
│ │ guidelines │
|
||||
│ └─────────────────┘
|
||||
│
|
||||
└─── Spawn agent for complex subtask
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Agent works │
|
||||
│ autonomously │
|
||||
│ with its skills │
|
||||
└─────────────────┘
|
||||
│
|
||||
▼
|
||||
Results return to command
|
||||
```
|
||||
|
||||
### Example: `/plan-issues add dark mode`
|
||||
|
||||
1. **Command invoked**: User runs `/plan-issues add dark mode`
|
||||
|
||||
2. **Skills consulted**:
|
||||
- `roadmap-planning`: How to break down features
|
||||
- `issue-writing`: How to structure each issue
|
||||
- `gitea`: How to create issues via CLI
|
||||
|
||||
3. **Workflow executed**:
|
||||
- Analyze what "dark mode" involves
|
||||
- Break down into discrete issues
|
||||
- Present plan for approval
|
||||
- Create issues in dependency order
|
||||
|
||||
4. **Output**: Issues created with proper structure and references
|
||||
|
||||
### Example: `/groom` (batch mode)
|
||||
|
||||
1. **Command invoked**: User runs `/groom` with no argument
|
||||
|
||||
2. **Skills consulted**:
|
||||
- `backlog-grooming`: Checklist and evaluation criteria
|
||||
- `issue-writing`: Standards for improvements
|
||||
|
||||
3. **Potential agent spawn**: For many issues, could spawn `product-manager` agent
|
||||
|
||||
4. **Agent workflow**:
|
||||
- Fetches all open issues
|
||||
- Evaluates each against grooming checklist
|
||||
- Categorizes as ready/needs-work/stale
|
||||
- Proposes improvements
|
||||
|
||||
5. **Output**: Summary table with suggestions, optional issue updates
|
||||
|
||||
---
|
||||
|
||||
## Component Relationships
|
||||
|
||||
### How Commands Use Skills
|
||||
|
||||
Commands reference skills by name in their instructions:
|
||||
|
||||
```markdown
|
||||
# Groom Issues
|
||||
|
||||
Use the backlog-grooming and issue-writing skills.
|
||||
```
|
||||
|
||||
Claude reads the referenced skill files to gain the necessary knowledge before executing the command workflow.
|
||||
|
||||
### How Agents Use Skills
|
||||
|
||||
Agents declare their skills in the YAML frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: product-manager
|
||||
skills: gitea, issue-writing, backlog-grooming
|
||||
---
|
||||
```
|
||||
|
||||
When spawned, the agent has access to all listed skills as part of its context.
|
||||
|
||||
### How Commands Spawn Agents
|
||||
|
||||
Commands can delegate to agents for complex subtasks:
|
||||
|
||||
```markdown
|
||||
For comprehensive backlog review, spawn the product-manager agent.
|
||||
```
|
||||
|
||||
The agent works autonomously and returns results to the command.
|
||||
|
||||
---
|
||||
|
||||
## Design Principles
|
||||
|
||||
### Separation of Concerns
|
||||
|
||||
- **Commands**: Define workflows (what to do)
|
||||
- **Skills**: Encode knowledge (how to do it well)
|
||||
- **Agents**: Execute complex tasks (who does it)
|
||||
|
||||
### Composability
|
||||
|
||||
Small, focused components combine to handle complex scenarios:
|
||||
|
||||
```
|
||||
/plan-issues = roadmap-planning + issue-writing + gitea
|
||||
product-manager = all four skills combined
|
||||
```
|
||||
|
||||
### Single Responsibility
|
||||
|
||||
Each component has one clear purpose:
|
||||
- One command = one workflow
|
||||
- One skill = one domain
|
||||
- One agent = one role
|
||||
|
||||
### Progressive Enhancement
|
||||
|
||||
Start simple, add complexity as needed:
|
||||
1. Use skills directly for simple tasks
|
||||
2. Create commands for repeatable workflows
|
||||
3. Add agents for complex parallel work
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
ai/
|
||||
├── commands/ # User-invoked workflows
|
||||
│ ├── work-issue.md
|
||||
│ ├── dashboard.md
|
||||
│ ├── review-pr.md
|
||||
│ ├── create-issue.md
|
||||
│ ├── groom.md
|
||||
│ ├── roadmap.md
|
||||
│ └── plan-issues.md
|
||||
├── skills/ # Knowledge modules
|
||||
│ ├── gitea/
|
||||
│ │ └── SKILL.md
|
||||
│ ├── issue-writing/
|
||||
│ │ └── SKILL.md
|
||||
│ ├── backlog-grooming/
|
||||
│ │ └── SKILL.md
|
||||
│ ├── roadmap-planning/
|
||||
│ │ └── SKILL.md
|
||||
│ └── code-review/
|
||||
│ └── SKILL.md
|
||||
├── agents/ # Specialized subagents
|
||||
│ ├── product-manager/
|
||||
│ │ └── AGENT.md
|
||||
│ └── code-reviewer/
|
||||
│ └── AGENT.md
|
||||
├── scripts/ # Hook scripts
|
||||
│ └── pre-commit-checks.sh
|
||||
├── settings.json # Claude Code configuration
|
||||
├── CLAUDE.md # Project instructions
|
||||
├── VISION.md # Why this project exists
|
||||
└── ARCHITECTURE.md # This document
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Adding New Components
|
||||
|
||||
### Adding a Command
|
||||
|
||||
1. Create `commands/<name>.md`
|
||||
2. Add frontmatter with description and argument hints
|
||||
3. Define the workflow steps
|
||||
4. Reference any needed skills
|
||||
5. Test the workflow
|
||||
|
||||
### Adding a Skill
|
||||
|
||||
1. Create `skills/<name>/SKILL.md`
|
||||
2. Document the domain knowledge
|
||||
3. Include patterns, templates, and examples
|
||||
4. Reference from commands or agents as needed
|
||||
|
||||
### Adding an Agent
|
||||
|
||||
1. Create `agents/<name>/AGENT.md`
|
||||
2. Add YAML frontmatter with `name`, `description`, and `skills`
|
||||
3. Write system prompt defining capabilities and behavior
|
||||
4. Update commands to use the agent where appropriate
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [VISION.md](VISION.md): The philosophy and goals behind this project
|
||||
- [CLAUDE.md](CLAUDE.md): Setup and configuration instructions
|
||||
- [README.md](README.md): Project overview and quick start
|
||||
@@ -0,0 +1,52 @@
|
||||
# Claude Code AI Workflow
|
||||
|
||||
This repository contains configurations, prompts, and tools to improve the Claude Code AI workflow.
|
||||
|
||||
## Setup
|
||||
|
||||
```bash
|
||||
# Clone and install symlinks
|
||||
git clone ssh://git@code.flowmade.one/flowmade-one/ai.git
|
||||
cd ai
|
||||
make install
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
ai/
|
||||
├── commands/ # Slash commands (/work-issue, /dashboard)
|
||||
├── skills/ # Auto-triggered capabilities
|
||||
├── agents/ # Subagents with isolated context
|
||||
├── scripts/ # Hook scripts (pre-commit, token loading)
|
||||
├── settings.json # Claude Code settings
|
||||
└── Makefile # Install/uninstall symlinks
|
||||
```
|
||||
|
||||
All files symlink to `~/.claude/` via `make install`.
|
||||
|
||||
## Gitea Integration
|
||||
|
||||
Uses `tea` CLI for issue/PR management:
|
||||
|
||||
```bash
|
||||
# Setup (one-time)
|
||||
brew install tea
|
||||
tea logins add --name flowmade --url https://git.flowmade.one --token <your-token>
|
||||
|
||||
# Create token at: https://git.flowmade.one/user/settings/applications
|
||||
```
|
||||
|
||||
### Available Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/work-issue <n>` | Fetch issue, create branch, implement, create PR |
|
||||
| `/dashboard` | Show open issues and PRs |
|
||||
| `/review-pr <n>` | Review PR with diff and comments |
|
||||
| `/create-issue` | Create single or batch issues |
|
||||
| `/retro` | Capture learnings from completed work, create improvement issues |
|
||||
|
||||
## Usage
|
||||
|
||||
This project is meant to be used alongside Claude Code to enhance productivity and maintain consistent workflows.
|
||||
@@ -1,71 +1,54 @@
|
||||
.PHONY: install uninstall status start-llm stop-llm restart-llm
|
||||
.PHONY: install uninstall status
|
||||
|
||||
OPENCODE_DIR := $(HOME)/.config/opencode
|
||||
CLAUDE_DIR := $(HOME)/.claude
|
||||
REPO_DIR := $(shell pwd)
|
||||
|
||||
# Items to symlink
|
||||
ITEMS := skills tools agents
|
||||
|
||||
# LLM services to manage
|
||||
LLM_SERVICES := odin
|
||||
|
||||
PLIST_PATH := ~/Library/LaunchAgents
|
||||
ITEMS := commands scripts skills agents settings.json
|
||||
|
||||
install:
|
||||
@echo "Installing OpenCode config symlinks..."
|
||||
@mkdir -p $(OPENCODE_DIR)
|
||||
@echo "Installing Claude Code config symlinks..."
|
||||
@mkdir -p $(CLAUDE_DIR)
|
||||
@for item in $(ITEMS); do \
|
||||
if [ -e "$(REPO_DIR)/.opencode/$$item" ]; then \
|
||||
if [ -L "$(OPENCODE_DIR)/$$item" ]; then \
|
||||
if [ -e "$(REPO_DIR)/$$item" ]; then \
|
||||
if [ -L "$(CLAUDE_DIR)/$$item" ]; then \
|
||||
echo " $$item: already symlinked"; \
|
||||
elif [ -e "$(CLAUDE_DIR)/$$item" ]; then \
|
||||
echo " $$item: backing up existing to $$item.bak"; \
|
||||
mv "$(CLAUDE_DIR)/$$item" "$(CLAUDE_DIR)/$$item.bak"; \
|
||||
ln -s "$(REPO_DIR)/$$item" "$(CLAUDE_DIR)/$$item"; \
|
||||
echo " $$item: symlinked"; \
|
||||
else \
|
||||
ln -s "$(REPO_DIR)/.opencode/$$item" "$(OPENCODE_DIR)/$$item"; \
|
||||
ln -s "$(REPO_DIR)/$$item" "$(CLAUDE_DIR)/$$item"; \
|
||||
echo " $$item: symlinked"; \
|
||||
fi \
|
||||
else \
|
||||
echo " $$item: skipped (not found)"; \
|
||||
fi \
|
||||
done
|
||||
@echo "Done!"
|
||||
@echo "Done! Restart Claude Code to apply changes."
|
||||
|
||||
uninstall:
|
||||
@echo "Removing OpenCode config symlinks..."
|
||||
@echo "Removing Claude Code config symlinks..."
|
||||
@for item in $(ITEMS); do \
|
||||
if [ -L "$(OPENCODE_DIR)/$$item" ]; then \
|
||||
rm "$(OPENCODE_DIR)/$$item"; \
|
||||
if [ -L "$(CLAUDE_DIR)/$$item" ]; then \
|
||||
rm "$(CLAUDE_DIR)/$$item"; \
|
||||
echo " $$item: removed symlink"; \
|
||||
if [ -e "$(CLAUDE_DIR)/$$item.bak" ]; then \
|
||||
mv "$(CLAUDE_DIR)/$$item.bak" "$(CLAUDE_DIR)/$$item"; \
|
||||
echo " $$item: restored backup"; \
|
||||
fi \
|
||||
fi \
|
||||
done
|
||||
@echo "Done!"
|
||||
|
||||
status:
|
||||
@echo "OpenCode config status:"
|
||||
@echo "Claude Code config status:"
|
||||
@for item in $(ITEMS); do \
|
||||
if [ -L "$(OPENCODE_DIR)/$$item" ]; then \
|
||||
target=$$(readlink "$(OPENCODE_DIR)/$$item"); \
|
||||
if [ -L "$(CLAUDE_DIR)/$$item" ]; then \
|
||||
target=$$(readlink "$(CLAUDE_DIR)/$$item"); \
|
||||
echo " $$item: symlink -> $$target"; \
|
||||
elif [ -e "$(OPENCODE_DIR)/$$item" ]; then \
|
||||
elif [ -e "$(CLAUDE_DIR)/$$item" ]; then \
|
||||
echo " $$item: exists (not symlinked)"; \
|
||||
else \
|
||||
echo " $$item: not found"; \
|
||||
fi \
|
||||
done
|
||||
|
||||
stop-llm-%:
|
||||
@echo "Stopping com.vllm-mlx-$*..."
|
||||
@launchctl bootout gui/$$(id -u) $(PLIST_PATH)/com.vllm-mlx.$*.plist 2>/dev/null || true
|
||||
|
||||
stop-llm: $(patsubst %,stop-llm-%,$(LLM_SERVICES))
|
||||
|
||||
start-llm-%:
|
||||
@echo "Starting com.vllm-mlx-$*..."
|
||||
@launchctl bootstrap gui/$$(id -u) $(PLIST_PATH)/com.vllm-mlx.$*.plist
|
||||
|
||||
start-llm: $(patsubst %,start-llm-%,$(LLM_SERVICES))
|
||||
|
||||
restart-llm-%:
|
||||
@echo "Restarting com.vllm-mlx-$*..."
|
||||
@launchctl bootout gui/$$(id -u) $(PLIST_PATH)/com.vllm-mlx.$*.plist || true
|
||||
@launchctl bootstrap gui/$$(id -u) $(PLIST_PATH)/com.vllm-mlx.$*.plist
|
||||
|
||||
restart-llm: $(patsubst %,restart-llm-%,$(LLM_SERVICES))
|
||||
|
||||
@@ -1,154 +1,178 @@
|
||||
# Architecture
|
||||
# Claude Code AI Workflow
|
||||
|
||||
The organizational source of truth for how we build software with OpenCode.
|
||||
A composable toolkit for enhancing [Claude Code](https://claude.ai/claude-code) with structured workflows, issue management, and AI-assisted development practices.
|
||||
|
||||
This repository contains the structure for our OpenCode configuration: skills, tools, and agents that make AI-assisted development predictable and effective.
|
||||
## Why This Project?
|
||||
|
||||
Claude Code is powerful, but its effectiveness depends on how you use it. This project provides:
|
||||
|
||||
- **Structured workflows** for common development tasks (issue tracking, PR reviews, planning)
|
||||
- **Composable components** that build on each other (skills, agents, commands)
|
||||
- **Forgejo integration** for seamless issue and PR management
|
||||
- **Consistent patterns** that make AI assistance more predictable and effective
|
||||
|
||||
## Core Concepts
|
||||
|
||||
OpenCode uses three component types:
|
||||
The project is built around three composable component types:
|
||||
|
||||
| Component | Location | Purpose | Example |
|
||||
|-----------|----------|---------|---------|
|
||||
| **Skills** | `.opencode/skills/` | Reference knowledge | `issue-writing` knows how to structure good issues |
|
||||
| **Tools** | `.opencode/tools/` | Custom functions | `spawn_issues` implements multiple issues in parallel |
|
||||
| **Agents** | `.opencode/agents/` | Specialized subagents | `code-reviewer` handles PR reviews |
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ COMMANDS │
|
||||
│ User-facing entry points (/work-issue) │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────┐ │
|
||||
│ │ AGENTS │ │
|
||||
│ │ Subprocesses with isolated context │ │
|
||||
│ │ (parallel processing, complex workflows) │ │
|
||||
│ │ │ │ │
|
||||
│ │ ▼ │ │
|
||||
│ │ ┌───────────────────────────────────────────┐ │ │
|
||||
│ │ │ SKILLS │ │ │
|
||||
│ │ │ Reusable knowledge modules │ │ │
|
||||
│ │ │ (gitea, issue-writing, planning) │ │ │
|
||||
│ │ └───────────────────────────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
| Component | Purpose | Example |
|
||||
|-----------|---------|---------|
|
||||
| **Commands** | Entry points users invoke directly | `/work-issue 42` starts implementation workflow |
|
||||
| **Skills** | Domain knowledge modules | `issue-writing` knows how to structure good issues |
|
||||
| **Agents** | Autonomous subprocesses | `product-manager` combines skills for complex planning |
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- [Claude Code CLI](https://claude.ai/claude-code) installed
|
||||
- [Forgejo CLI](https://code.gitea.org/gitea/gitea-cli) (`tea`) for issue/PR management
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone ssh://git@code.flowmade.one/flowmade-one/architecture.git
|
||||
cd architecture
|
||||
git clone ssh://git@code.flowmade.one/flowmade-one/ai.git
|
||||
cd ai
|
||||
|
||||
# Install symlinks to ~/.config/opencode/
|
||||
# Install symlinks to ~/.claude/
|
||||
make install
|
||||
```
|
||||
|
||||
This creates symlinks at:
|
||||
- `~/.config/opencode/skills/` → `.opencode/skills/`
|
||||
- `~/.config/opencode/tools/` → `.opencode/tools/`
|
||||
- `~/.config/opencode/agents/` → `.opencode/agents/`
|
||||
### Forgejo Setup
|
||||
|
||||
### Uninstallation
|
||||
```bash
|
||||
# Install gitea-cli
|
||||
brew install gitea-cli
|
||||
|
||||
# Authenticate (one-time)
|
||||
echo "YOUR_TOKEN" | tea -H code.flowmade.one auth add-key username
|
||||
|
||||
# Required token scopes: read:user, read:repository, write:issue, write:repository
|
||||
```
|
||||
|
||||
## Available Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/dashboard` | Show open issues and PRs for the current repo |
|
||||
| `/work-issue <n>` | Fetch issue, create branch, implement, and create PR |
|
||||
| `/review-pr <n>` | Review a PR with diff analysis and feedback |
|
||||
| `/create-issue` | Create single or batch issues interactively |
|
||||
| `/plan-issues <desc>` | Break down a feature into discrete issues |
|
||||
| `/groom [n]` | Improve issue quality (single or batch) |
|
||||
| `/roadmap` | Visualize issues by status and dependencies |
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
ai/
|
||||
├── commands/ # Slash commands invoked by users
|
||||
│ ├── work-issue.md
|
||||
│ ├── dashboard.md
|
||||
│ ├── review-pr.md
|
||||
│ ├── create-issue.md
|
||||
│ ├── plan-issues.md
|
||||
│ ├── groom.md
|
||||
│ └── roadmap.md
|
||||
├── skills/ # Reusable knowledge modules
|
||||
│ ├── gitea/ # Forgejo CLI integration
|
||||
│ ├── issue-writing/ # Issue structure best practices
|
||||
│ ├── backlog-grooming/ # Backlog maintenance
|
||||
│ ├── roadmap-planning/ # Feature breakdown
|
||||
│ └── code-review/ # Code review best practices
|
||||
├── agents/ # Specialized subagents
|
||||
│ ├── product-manager/ # Combines skills for PM tasks
|
||||
│ └── code-reviewer/ # Automated PR code review
|
||||
├── scripts/ # Git hooks and utilities
|
||||
│ └── pre-commit-checks.sh
|
||||
├── settings.json # Claude Code configuration
|
||||
├── Makefile # Symlink management
|
||||
└── CLAUDE.md # Instructions for Claude Code
|
||||
```
|
||||
|
||||
## Example Workflows
|
||||
|
||||
### Working on an Issue
|
||||
|
||||
```
|
||||
> /work-issue 42
|
||||
|
||||
Fetching issue #42: "Add user authentication"
|
||||
Creating branch: feature/42-add-user-authentication
|
||||
Planning implementation...
|
||||
[Claude implements the feature]
|
||||
Creating PR with reference to issue...
|
||||
```
|
||||
|
||||
### Planning a Feature
|
||||
|
||||
```
|
||||
> /plan-issues Add dark mode support
|
||||
|
||||
Proposed Issues:
|
||||
1. Create theme context and provider
|
||||
2. Add theme toggle component
|
||||
3. Update components to use theme variables
|
||||
4. Add system preference detection
|
||||
|
||||
Create these issues? [y/n]
|
||||
```
|
||||
|
||||
### Daily Standup
|
||||
|
||||
```
|
||||
> /dashboard
|
||||
|
||||
Open Issues (3):
|
||||
| # | Title | Labels |
|
||||
|----|--------------------------|-------------|
|
||||
| 42 | Add user authentication | feature |
|
||||
| 38 | Fix login redirect | bug |
|
||||
| 35 | Update dependencies | maintenance |
|
||||
|
||||
Open PRs (1):
|
||||
| # | Title | Status |
|
||||
|----|--------------------------|-------------|
|
||||
| 41 | Add password reset flow | review |
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
The `settings.json` configures Claude Code behavior:
|
||||
|
||||
- **Model selection**: Uses Opus for complex tasks
|
||||
- **Status line**: Shows git branch and status
|
||||
- **Hooks**: Pre-commit validation for secrets and YAML
|
||||
|
||||
## Uninstall
|
||||
|
||||
```bash
|
||||
make uninstall
|
||||
```
|
||||
|
||||
### Status
|
||||
|
||||
```bash
|
||||
make status
|
||||
```
|
||||
|
||||
Shows current symlink state for each component.
|
||||
|
||||
### Restart LLMs
|
||||
|
||||
```bash
|
||||
make restart-llm
|
||||
```
|
||||
|
||||
Restarts all local LLM services (atlas, forge, swift).
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
architecture/
|
||||
├── legacy/ # Historical Claude Code content
|
||||
│ ├── old/ # Early Claude Code structure
|
||||
│ ├── old2/ # Most recent Claude Code structure
|
||||
│ ├── docs/ # Documentation
|
||||
│ ├── learnings/ # Governance learnings
|
||||
│ └── scripts/ # Bash scripts
|
||||
│
|
||||
├── .opencode/ # OpenCode configuration
|
||||
│ ├── skills/ # Reference knowledge (SKILL.md files)
|
||||
│ ├── tools/ # Custom tools (TypeScript/JS)
|
||||
│ └── agents/ # Specialized subagents (AGENT.md files)
|
||||
│
|
||||
├── Makefile # Symlink management
|
||||
├── settings.json # Historical reference (Claude Code)
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## Adding Components
|
||||
|
||||
### Skills
|
||||
|
||||
Create `.opencode/skills/<name>/SKILL.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: skill-name
|
||||
description: What this skill does and when to use it
|
||||
---
|
||||
|
||||
# Skill Title
|
||||
|
||||
Content goes here...
|
||||
```
|
||||
|
||||
Skills are auto-discovered by OpenCode and available via the `skill` tool.
|
||||
|
||||
### Tools
|
||||
|
||||
Create `.opencode/tools/<name>.ts`:
|
||||
|
||||
```typescript
|
||||
import { tool } from "@opencode-ai/plugin"
|
||||
|
||||
export default tool({
|
||||
description: "What this tool does",
|
||||
args: {
|
||||
param: tool.schema.string().describe("Parameter description"),
|
||||
},
|
||||
async execute(args) {
|
||||
// Your implementation
|
||||
return "result"
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
Tools are auto-discovered and available to the LLM.
|
||||
|
||||
### Agents
|
||||
|
||||
Create `.opencode/agents/<name>.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: What this agent does and when to use it
|
||||
mode: subagent
|
||||
permission:
|
||||
edit: deny
|
||||
bash: deny
|
||||
---
|
||||
|
||||
You are an agent that specializes in...
|
||||
```
|
||||
|
||||
Agents can be invoked with `@agent-name` or automatically by primary agents.
|
||||
|
||||
## Referencing Legacy Content
|
||||
|
||||
The `legacy/` folder contains the original Claude Code structure for reference:
|
||||
|
||||
- **`legacy/old2/`** - Most recent Claude Code structure with skills, agents, commands
|
||||
- **`legacy/old2/manifesto.md`** - Organization vision and beliefs
|
||||
- **`legacy/old2/software-architecture.md`** - Architectural patterns and principles
|
||||
- **`legacy/old2/learnings/`** - Historical learnings (if any)
|
||||
|
||||
These are preserved for historical reference but not actively used by OpenCode.
|
||||
|
||||
## Existing OpenCode Configuration
|
||||
|
||||
Your global OpenCode configuration is at `~/.config/opencode/opencode.json`. This repository does not manage that file.
|
||||
|
||||
The `settings.json` in this repository is kept for historical reference (it was used with Claude Code).
|
||||
This removes symlinks from `~/.claude/` and restores any backed-up files.
|
||||
|
||||
## License
|
||||
|
||||
|
||||
@@ -0,0 +1,102 @@
|
||||
# Vision
|
||||
|
||||
## The Problem
|
||||
|
||||
AI-assisted development is powerful but inconsistent. Claude Code can help with nearly any task, but without structure:
|
||||
|
||||
- Workflows vary between sessions and team members
|
||||
- Knowledge about good practices stays in heads, not systems
|
||||
- Context gets lost when switching between tasks
|
||||
- There's no shared vocabulary for common patterns
|
||||
|
||||
The gap isn't in AI capability—it's in how we use it.
|
||||
|
||||
## The Solution
|
||||
|
||||
This project provides a **composable toolkit** for Claude Code that turns ad-hoc AI assistance into structured, repeatable workflows.
|
||||
|
||||
Instead of asking Claude to "help with issues" differently each time, you run `/work-issue 42` and get a consistent workflow: fetch the issue, create a branch, plan the work, implement, commit with proper references, and create a PR.
|
||||
|
||||
The key insight: **encode your team's best practices into reusable components** that Claude can apply consistently.
|
||||
|
||||
## Composable Components
|
||||
|
||||
The system is built from three types of components that stack together:
|
||||
|
||||
### Skills
|
||||
|
||||
Skills are knowledge modules—focused documents that teach Claude how to do something well.
|
||||
|
||||
Examples:
|
||||
- `issue-writing`: How to structure clear, actionable issues
|
||||
- `gitea`: How to use the Gitea CLI for issue/PR management
|
||||
- `backlog-grooming`: What makes a healthy backlog
|
||||
|
||||
Skills don't do anything on their own. They're building blocks.
|
||||
|
||||
### Agents
|
||||
|
||||
Agents combine multiple skills into specialized personas that can work autonomously.
|
||||
|
||||
The `product-manager` agent combines issue-writing, backlog-grooming, and roadmap-planning skills to handle complex PM tasks. It can explore the codebase, plan features, and create well-structured issues—all with isolated context so it doesn't pollute the main conversation.
|
||||
|
||||
Agents enable:
|
||||
- **Parallel processing**: Multiple agents can work simultaneously
|
||||
- **Context preservation**: Each agent maintains its own focused context
|
||||
- **Complex workflows**: Combine skills for multi-step tasks
|
||||
|
||||
### Commands
|
||||
|
||||
Commands are the user-facing entry points—what you actually invoke.
|
||||
|
||||
When you run `/plan-issues add dark mode`, the command:
|
||||
1. Understands what you're asking for
|
||||
2. Invokes the right agents and skills
|
||||
3. Guides you through the workflow with approvals
|
||||
4. Takes action (creates issues, PRs, etc.)
|
||||
|
||||
Commands make the power of skills and agents accessible through simple invocations.
|
||||
|
||||
## Target Users
|
||||
|
||||
This toolkit is for:
|
||||
|
||||
- **Developers using Claude Code** who want consistent, efficient workflows
|
||||
- **Teams** who want to encode and share their best practices
|
||||
- **Gitea/Git users** who want seamless issue and PR management integrated into their AI workflow
|
||||
|
||||
You should have:
|
||||
- Claude Code CLI installed
|
||||
- A Gitea instance (or adapt the tooling for GitHub/GitLab)
|
||||
- Interest in treating AI assistance as a structured tool, not just a chat interface
|
||||
|
||||
## Guiding Principles
|
||||
|
||||
### Encode, Don't Repeat
|
||||
|
||||
If you find yourself explaining the same thing to Claude repeatedly, that's a skill waiting to be written. Capture it once, use it everywhere.
|
||||
|
||||
### Composability Over Complexity
|
||||
|
||||
Small, focused components that combine well beat large, monolithic solutions. A skill should do one thing. An agent should serve one role. A command should trigger one workflow.
|
||||
|
||||
### Approval Before Action
|
||||
|
||||
Destructive or significant actions should require user approval. Commands should show what they're about to do and ask before doing it. This builds trust and catches mistakes.
|
||||
|
||||
### Use the Tools to Build the Tools
|
||||
|
||||
This project uses its own commands to manage itself. Issues are created with `/create-issue`. Features are planned with `/plan-issues`. PRs are reviewed with `/review-pr`. Dogfooding ensures the tools actually work.
|
||||
|
||||
### Progressive Disclosure
|
||||
|
||||
Simple things should be simple. `/dashboard` just shows your issues and PRs. But the system supports complex workflows when you need them. Don't require users to understand the full architecture to get value.
|
||||
|
||||
## What This Is Not
|
||||
|
||||
This is not:
|
||||
- A replacement for Claude Code—it enhances it
|
||||
- A rigid framework—adapt it to your needs
|
||||
- Complete—it grows as we discover new patterns
|
||||
|
||||
It's a starting point for treating AI-assisted development as a first-class engineering concern.
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
name: code-reviewer
|
||||
description: Automated code review of pull requests. Reviews PRs for quality, bugs, security, style, and test coverage. Spawn after PR creation or for on-demand review.
|
||||
# Model: sonnet provides good code understanding for review tasks.
|
||||
# The structured output format doesn't require opus-level reasoning.
|
||||
model: sonnet
|
||||
skills: gitea, code-review
|
||||
---
|
||||
|
||||
You are a code review specialist that provides immediate, structured feedback on pull request changes.
|
||||
|
||||
## When Invoked
|
||||
|
||||
You will receive a PR number to review. Follow this process:
|
||||
|
||||
1. Fetch PR diff using `tea pulls <number> -f diff`
|
||||
2. Analyze the diff for issues in these categories:
|
||||
- **Code Quality**: Readability, maintainability, complexity
|
||||
- **Bugs**: Logic errors, edge cases, null checks
|
||||
- **Security**: Injection vulnerabilities, auth issues, data exposure
|
||||
- **Style**: Naming conventions, formatting, consistency
|
||||
- **Test Coverage**: Missing tests, untested edge cases
|
||||
3. Generate a structured review comment
|
||||
4. Post the review using `tea comment <number> "<review body>"`
|
||||
5. **If verdict is LGTM**: Approve with `tea pulls approve <number>`, then auto-merge with `tea pulls merge <number> --style rebase`
|
||||
6. **If verdict is NOT LGTM**: Do not merge; leave for the user to address
|
||||
|
||||
## Review Comment Format
|
||||
|
||||
Post reviews in this structured format:
|
||||
|
||||
```markdown
|
||||
## AI Code Review
|
||||
|
||||
> This is an automated review generated by the code-reviewer agent.
|
||||
|
||||
### Summary
|
||||
[Brief overall assessment]
|
||||
|
||||
### Findings
|
||||
|
||||
#### Code Quality
|
||||
- [Finding 1]
|
||||
- [Finding 2]
|
||||
|
||||
#### Potential Bugs
|
||||
- [Finding or "No issues found"]
|
||||
|
||||
#### Security Concerns
|
||||
- [Finding or "No issues found"]
|
||||
|
||||
#### Style Notes
|
||||
- [Finding or "Consistent with codebase"]
|
||||
|
||||
#### Test Coverage
|
||||
- [Finding or "Adequate coverage"]
|
||||
|
||||
### Verdict
|
||||
[LGTM / Needs Changes / Blocking Issues]
|
||||
```
|
||||
|
||||
## Verdict Criteria
|
||||
|
||||
- **LGTM**: No blocking issues, code meets quality standards, ready to merge
|
||||
- **Needs Changes**: Minor issues worth addressing before merge
|
||||
- **Blocking Issues**: Security vulnerabilities, logic errors, or missing critical functionality
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Be specific: Reference exact lines and explain *why* something is an issue
|
||||
- Be constructive: Suggest alternatives when pointing out problems
|
||||
- Be kind: Distinguish between blocking issues and suggestions
|
||||
- Acknowledge good solutions when you see them
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
name: product-manager
|
||||
description: Backlog management and roadmap planning specialist. Use for batch issue operations, comprehensive backlog reviews, or feature planning that requires codebase exploration.
|
||||
# Model: sonnet handles planning and issue-writing well.
|
||||
# Tasks follow structured patterns from skills; opus not required.
|
||||
model: sonnet
|
||||
skills: gitea, issue-writing, backlog-grooming, roadmap-planning
|
||||
---
|
||||
|
||||
You are a product manager specializing in backlog management and roadmap planning.
|
||||
|
||||
## Capabilities
|
||||
|
||||
You can:
|
||||
- Review and improve existing issues
|
||||
- Create new well-structured issues
|
||||
- Analyze the backlog for gaps and priorities
|
||||
- Plan feature breakdowns
|
||||
- Maintain roadmap clarity
|
||||
|
||||
## Behavior
|
||||
|
||||
- Always fetch current issue state before making changes
|
||||
- Ask for approval before creating or modifying issues
|
||||
- Provide clear summaries of actions taken
|
||||
- Use the gitea skill for all issue/PR operations
|
||||
@@ -0,0 +1,19 @@
|
||||
---
|
||||
description: Create a new Gitea issue. Can create single issues or batch create from a plan.
|
||||
argument-hint: [title] or "batch"
|
||||
---
|
||||
|
||||
# Create Issue(s)
|
||||
|
||||
Use the gitea skill.
|
||||
|
||||
## Single Issue (default)
|
||||
If title provided, create an issue with that title and ask for description.
|
||||
|
||||
## Batch Mode
|
||||
If $1 is "batch":
|
||||
1. Ask user for the plan/direction
|
||||
2. Generate list of issues with titles and descriptions
|
||||
3. Show for approval
|
||||
4. Create each issue
|
||||
5. Display all created issue numbers
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
description: Show dashboard of open issues, PRs awaiting review, and CI status.
|
||||
---
|
||||
|
||||
# Repository Dashboard
|
||||
|
||||
Use the gitea skill.
|
||||
|
||||
Fetch and display:
|
||||
1. All open issues
|
||||
2. All open PRs
|
||||
|
||||
Format as tables showing number, title, and author.
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
description: Groom and improve issues. Without argument, reviews all open issues. With argument, grooms specific issue.
|
||||
argument-hint: [issue-number]
|
||||
---
|
||||
|
||||
# Groom Issues
|
||||
|
||||
Use the gitea, backlog-grooming, and issue-writing skills.
|
||||
|
||||
## If issue number provided ($1):
|
||||
|
||||
1. **Fetch the issue** details
|
||||
2. **Evaluate** against grooming checklist
|
||||
3. **Suggest improvements** for:
|
||||
- Title clarity
|
||||
- Description completeness
|
||||
- Acceptance criteria quality
|
||||
- Scope definition
|
||||
4. **Ask user** if they want to apply changes
|
||||
5. **Update issue** if approved
|
||||
|
||||
## If no argument (groom all):
|
||||
|
||||
1. **List open issues**
|
||||
2. **Review each** against grooming checklist
|
||||
3. **Categorize**:
|
||||
- Ready: Well-defined, can start work
|
||||
- Needs work: Missing info or unclear
|
||||
- Stale: No longer relevant
|
||||
4. **Present summary** table
|
||||
5. **Offer to improve** issues that need work
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
description: Plan and create issues for a feature or improvement. Breaks down work into well-structured issues.
|
||||
argument-hint: <feature-description>
|
||||
---
|
||||
|
||||
# Plan Feature: $1
|
||||
|
||||
Use the gitea, roadmap-planning, and issue-writing skills.
|
||||
|
||||
1. **Understand the feature**: Analyze what "$1" involves
|
||||
2. **Explore the codebase** if needed to understand context
|
||||
3. **Break down** into discrete, actionable issues:
|
||||
- Each issue should be independently completable
|
||||
- Clear dependencies between issues
|
||||
- Appropriate scope (not too big, not too small)
|
||||
|
||||
4. **Present the plan**:
|
||||
```
|
||||
## Proposed Issues for: $1
|
||||
|
||||
1. [Title] - Brief description
|
||||
Dependencies: none
|
||||
|
||||
2. [Title] - Brief description
|
||||
Dependencies: #1
|
||||
|
||||
3. [Title] - Brief description
|
||||
Dependencies: #1, #2
|
||||
```
|
||||
|
||||
5. **Ask for approval** before creating issues
|
||||
6. **Create issues** in order
|
||||
7. **Update dependencies** with actual issue numbers after creation
|
||||
8. **Present summary** with links to created issues
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
description: Run a retrospective on completed work. Captures learnings and creates improvement issues in the AI repo.
|
||||
argument-hint: [task-description]
|
||||
---
|
||||
|
||||
# Retrospective
|
||||
|
||||
Capture learnings from completed AI-assisted work to improve the workflow.
|
||||
|
||||
## 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. **Analyze and categorize**: Group learnings into:
|
||||
- **Prompt improvements**: Better instructions for commands/skills
|
||||
- **Missing capabilities**: New commands or skills needed
|
||||
- **Tool issues**: Problems with tea CLI, git, or other tools
|
||||
- **Context gaps**: Missing documentation or skills
|
||||
|
||||
4. **Generate improvement issues**: For each actionable improvement, create an issue in the AI repo using:
|
||||
|
||||
```bash
|
||||
tea issues create -r flowmade-one/ai --title "<title>" --description "<body>"
|
||||
```
|
||||
|
||||
## Issue Format
|
||||
|
||||
Use this structure for retrospective issues:
|
||||
|
||||
```markdown
|
||||
## Context
|
||||
What task triggered this learning (brief).
|
||||
|
||||
## Problem / Observation
|
||||
What was the friction point or insight.
|
||||
|
||||
## Suggested Improvement
|
||||
Concrete, actionable change to make.
|
||||
|
||||
## Affected Files
|
||||
- commands/xxx.md
|
||||
- skills/xxx/SKILL.md
|
||||
```
|
||||
|
||||
## Labels
|
||||
|
||||
Add appropriate labels:
|
||||
- `retrospective` - Always add this
|
||||
- `prompt-improvement` - For command/skill text changes
|
||||
- `new-feature` - For new commands/skills
|
||||
- `bug` - For things that are broken
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Be specific and actionable - vague issues won't get fixed
|
||||
- One issue per improvement (don't bundle unrelated things)
|
||||
- Reference specific commands/skills when relevant
|
||||
- Keep issues small and focused
|
||||
- Skip creating issues for one-off edge cases that won't recur
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
description: Review a Gitea pull request. Fetches PR details, diff, and comments.
|
||||
argument-hint: <pr-number>
|
||||
---
|
||||
|
||||
# Review PR #$1
|
||||
|
||||
Use the gitea skill.
|
||||
|
||||
1. **View PR details** including description and metadata
|
||||
2. **Get the diff** to review the changes
|
||||
|
||||
Review the changes and provide feedback on:
|
||||
- Code quality
|
||||
- Potential bugs
|
||||
- Test coverage
|
||||
- Documentation
|
||||
|
||||
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
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
description: View current issues as a roadmap. Shows open issues organized by status and dependencies.
|
||||
---
|
||||
|
||||
# Roadmap View
|
||||
|
||||
Use the gitea skill.
|
||||
|
||||
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
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
description: Work on a Gitea issue. Fetches issue details and sets up branch for implementation.
|
||||
argument-hint: <issue-number>
|
||||
---
|
||||
|
||||
# Work on Issue #$1
|
||||
|
||||
Use the gitea skill.
|
||||
|
||||
1. **View the issue** to understand requirements
|
||||
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. **Implement** the changes
|
||||
5. **Commit** with message referencing the issue
|
||||
6. **Push** the branch to origin
|
||||
7. **Create PR** with title "[Issue #$1] <title>" and body "Closes #$1"
|
||||
8. **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
|
||||
@@ -0,0 +1,591 @@
|
||||
# Writing Agents
|
||||
|
||||
A guide to creating specialized subagents that combine multiple skills for complex, context-isolated tasks.
|
||||
|
||||
## What is an Agent?
|
||||
|
||||
Agents are **specialized subprocesses** that combine multiple skills into focused personas. Unlike commands (which define workflows) or skills (which encode knowledge), agents are autonomous workers that can handle complex tasks independently.
|
||||
|
||||
Think of agents as specialists you can delegate work to. They have their own context, their own expertise (via skills), and they report back when finished.
|
||||
|
||||
## File Structure
|
||||
|
||||
Agents live in the `agents/` directory, each in its own folder:
|
||||
|
||||
```
|
||||
agents/
|
||||
└── product-manager/
|
||||
└── AGENT.md
|
||||
```
|
||||
|
||||
### Why AGENT.md?
|
||||
|
||||
The uppercase `AGENT.md` filename:
|
||||
- Makes the agent file immediately visible in directory listings
|
||||
- Follows a consistent convention across all agents
|
||||
- Clearly identifies the primary file in an agent folder
|
||||
|
||||
### Supporting Files (Optional)
|
||||
|
||||
An agent folder can contain additional files if needed:
|
||||
|
||||
```
|
||||
agents/
|
||||
└── code-reviewer/
|
||||
├── AGENT.md # Main agent document (required)
|
||||
└── checklists/ # Supporting materials
|
||||
└── security.md
|
||||
```
|
||||
|
||||
However, prefer keeping everything in `AGENT.md` when possible—agent definitions should be concise.
|
||||
|
||||
## Agent Document Structure
|
||||
|
||||
A well-structured `AGENT.md` follows this pattern:
|
||||
|
||||
```markdown
|
||||
# Agent Name
|
||||
|
||||
Brief description of what this agent does.
|
||||
|
||||
## Skills
|
||||
List of skills this agent has access to.
|
||||
|
||||
## Capabilities
|
||||
What the agent can do—its areas of competence.
|
||||
|
||||
## When to Use
|
||||
Guidance on when to spawn this agent.
|
||||
|
||||
## Behavior
|
||||
How the agent should operate—rules and constraints.
|
||||
```
|
||||
|
||||
All sections are important:
|
||||
- **Skills**: Defines what knowledge the agent has
|
||||
- **Capabilities**: Tells spawners what to expect
|
||||
- **When to Use**: Prevents misuse and guides selection
|
||||
- **Behavior**: Sets expectations for operation
|
||||
|
||||
## How Agents Combine Skills
|
||||
|
||||
Agents gain their expertise by combining multiple skills. Each skill contributes domain knowledge to the agent's overall capability.
|
||||
|
||||
### Skill Composition
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────┐
|
||||
│ Product Manager Agent │
|
||||
│ │
|
||||
│ ┌──────────┐ ┌──────────────┐ │
|
||||
│ │ gitea │ │issue-writing │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ CLI │ │ Structure │ │
|
||||
│ │ commands │ │ patterns │ │
|
||||
│ └──────────┘ └──────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────┐ ┌─────────────────┐ │
|
||||
│ │backlog-grooming │ │roadmap-planning │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ Review │ │ Feature │ │
|
||||
│ │ checklists │ │ breakdown │ │
|
||||
│ └──────────────────┘ └─────────────────┘ │
|
||||
│ │
|
||||
└────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
The agent can:
|
||||
- Use **gitea** to interact with issues and PRs
|
||||
- Apply **issue-writing** patterns when creating content
|
||||
- Follow **backlog-grooming** checklists when reviewing
|
||||
- Use **roadmap-planning** strategies when breaking down features
|
||||
|
||||
### Emergent Capabilities
|
||||
|
||||
When skills combine, new capabilities emerge:
|
||||
|
||||
| Skills Combined | Emergent Capability |
|
||||
|-----------------|---------------------|
|
||||
| gitea + issue-writing | Create well-structured issues programmatically |
|
||||
| backlog-grooming + issue-writing | Improve existing issues systematically |
|
||||
| roadmap-planning + gitea | Plan and create linked issue hierarchies |
|
||||
| All four skills | Full backlog management lifecycle |
|
||||
|
||||
## Use Cases for Agents
|
||||
|
||||
### 1. Parallel Processing
|
||||
|
||||
Agents work independently with their own context. Spawn multiple agents to work on separate tasks simultaneously.
|
||||
|
||||
```
|
||||
Command: /groom (batch mode)
|
||||
│
|
||||
├─── Spawn Agent: Review issues #1-5
|
||||
│
|
||||
├─── Spawn Agent: Review issues #6-10
|
||||
│
|
||||
└─── Spawn Agent: Review issues #11-15
|
||||
|
||||
↓ (agents work in parallel)
|
||||
|
||||
Results aggregated by command
|
||||
```
|
||||
|
||||
**Use when:**
|
||||
- Tasks are independent and don't need to share state
|
||||
- Workload can be divided into discrete chunks
|
||||
- Speed matters more than sequential consistency
|
||||
|
||||
### 2. Context Isolation
|
||||
|
||||
Each agent maintains separate conversation state. This prevents context pollution when handling complex, unrelated subtasks.
|
||||
|
||||
```
|
||||
Main Context Agent Context
|
||||
┌─────────────────┐ ┌─────────────────┐
|
||||
│ User working on │ │ Isolated work │
|
||||
│ feature X │ spawn │ on backlog │
|
||||
│ │ ─────────► │ review │
|
||||
│ (preserves │ │ │
|
||||
│ feature X │ return │ (doesn't know │
|
||||
│ context) │ ◄───────── │ about X) │
|
||||
└─────────────────┘ └─────────────────┘
|
||||
```
|
||||
|
||||
**Use when:**
|
||||
- Subtask requires deep exploration that would pollute main context
|
||||
- Work involves many files or concepts unrelated to main task
|
||||
- You want clean separation between different concerns
|
||||
|
||||
### 3. Complex Workflows
|
||||
|
||||
Some workflows are better handled by a specialized agent than by inline execution. Agents can make decisions, iterate, and adapt.
|
||||
|
||||
```
|
||||
Command: /plan-issues "add user authentication"
|
||||
│
|
||||
└─── Spawn product-manager agent
|
||||
│
|
||||
├── Explore codebase to understand structure
|
||||
├── Research authentication patterns
|
||||
├── Design issue breakdown
|
||||
├── Create issues in dependency order
|
||||
└── Return summary to command
|
||||
```
|
||||
|
||||
**Use when:**
|
||||
- Task requires iterative decision-making
|
||||
- Workflow has many steps that depend on intermediate results
|
||||
- Specialist expertise (via combined skills) adds value
|
||||
|
||||
### 4. Autonomous Exploration
|
||||
|
||||
Agents can explore codebases independently, building understanding without polluting the main conversation.
|
||||
|
||||
**Use when:**
|
||||
- You need to understand a new part of the codebase
|
||||
- Exploration might involve many file reads and searches
|
||||
- Results should be summarized, not shown in full
|
||||
|
||||
## When to Use an Agent vs Direct Skill Invocation
|
||||
|
||||
### Use Direct Skill Invocation When:
|
||||
|
||||
- **Simple, single-skill task**: Writing one issue doesn't need an agent
|
||||
- **Main context is relevant**: The current conversation context helps
|
||||
- **Quick reference needed**: Just need to check a pattern or command
|
||||
- **Sequential workflow**: Command can orchestrate step-by-step
|
||||
|
||||
Example: Creating a single issue with `/create-issue`
|
||||
```
|
||||
Command reads issue-writing skill directly
|
||||
│
|
||||
└── Creates one issue following patterns
|
||||
```
|
||||
|
||||
### Use an Agent When:
|
||||
|
||||
- **Multiple skills needed together**: Complex tasks benefit from composition
|
||||
- **Context isolation required**: Don't want to pollute main conversation
|
||||
- **Parallel execution possible**: Can divide and conquer
|
||||
- **Autonomous exploration needed**: Agent can figure things out independently
|
||||
- **Specialist persona helps**: "Product manager" framing improves outputs
|
||||
|
||||
Example: Grooming entire backlog with `/groom`
|
||||
```
|
||||
Command spawns product-manager agent
|
||||
│
|
||||
└── Agent iterates through all issues
|
||||
using multiple skills
|
||||
```
|
||||
|
||||
### Decision Matrix
|
||||
|
||||
| Scenario | Agent? | Reason |
|
||||
|----------|--------|--------|
|
||||
| Create one issue | No | Single skill, simple task |
|
||||
| Review 20 issues | Yes | Batch processing, isolation |
|
||||
| Quick CLI lookup | No | Just need gitea reference |
|
||||
| Plan new feature | Yes | Multiple skills, exploration |
|
||||
| Fix issue title | No | Trivial edit |
|
||||
| Reorganize backlog | Yes | Complex, multi-skill workflow |
|
||||
|
||||
## Annotated Example: Product Manager Agent
|
||||
|
||||
Let's examine the `product-manager` agent in detail:
|
||||
|
||||
```markdown
|
||||
# Product Manager Agent
|
||||
|
||||
Specialized agent for backlog management and roadmap planning.
|
||||
```
|
||||
|
||||
**The opening** identifies the agent's role clearly. "Product Manager" is a recognizable persona that sets expectations.
|
||||
|
||||
```markdown
|
||||
## Skills
|
||||
|
||||
- gitea
|
||||
- issue-writing
|
||||
- backlog-grooming
|
||||
- roadmap-planning
|
||||
```
|
||||
|
||||
**Skills section** lists all knowledge the agent has access to. These skills are loaded into the agent's context when spawned. The combination enables:
|
||||
- Reading/writing issues (gitea)
|
||||
- Creating quality content (issue-writing)
|
||||
- Evaluating existing issues (backlog-grooming)
|
||||
- Planning work strategically (roadmap-planning)
|
||||
|
||||
```markdown
|
||||
## Capabilities
|
||||
|
||||
This agent can:
|
||||
- Review and improve existing issues
|
||||
- Create new well-structured issues
|
||||
- Analyze the backlog for gaps and priorities
|
||||
- Plan feature breakdowns
|
||||
- Maintain roadmap clarity
|
||||
```
|
||||
|
||||
**Capabilities section** tells spawners what to expect. Each capability maps to skill combinations:
|
||||
- "Review and improve" = backlog-grooming + issue-writing
|
||||
- "Create new issues" = gitea + issue-writing
|
||||
- "Analyze backlog" = backlog-grooming + roadmap-planning
|
||||
- "Plan breakdowns" = roadmap-planning + issue-writing
|
||||
|
||||
```markdown
|
||||
## When to Use
|
||||
|
||||
Spawn this agent for:
|
||||
- Batch operations on multiple issues
|
||||
- Comprehensive backlog reviews
|
||||
- Feature planning that requires codebase exploration
|
||||
- Complex issue creation with dependencies
|
||||
```
|
||||
|
||||
**When to Use section** guides appropriate usage. Note the criteria:
|
||||
- "Batch operations" → Parallel/isolation benefit
|
||||
- "Comprehensive reviews" → Complex workflow benefit
|
||||
- "Requires exploration" → Context isolation benefit
|
||||
- "Complex with dependencies" → Multi-skill benefit
|
||||
|
||||
```markdown
|
||||
## Behavior
|
||||
|
||||
- Always fetches current issue state before making changes
|
||||
- Asks for approval before creating or modifying issues
|
||||
- Provides clear summaries of actions taken
|
||||
- Uses the tea CLI for all Forgejo operations
|
||||
```
|
||||
|
||||
**Behavior section** sets operational rules. These ensure:
|
||||
- Accuracy: Fetches current state, doesn't assume
|
||||
- Safety: Asks before acting
|
||||
- Transparency: Summarizes what happened
|
||||
- Consistency: Uses standard tooling
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
### Agent Folder Names
|
||||
|
||||
- Use **kebab-case**: `product-manager`, `code-reviewer`
|
||||
- Name by **role or persona**: what the agent "is"
|
||||
- Keep **recognizable**: familiar roles are easier to understand
|
||||
|
||||
Good names:
|
||||
- `product-manager` - Recognizable role
|
||||
- `code-reviewer` - Clear function
|
||||
- `security-auditor` - Specific expertise
|
||||
- `documentation-writer` - Focused purpose
|
||||
|
||||
Avoid:
|
||||
- `helper` - Too vague
|
||||
- `do-stuff` - Not a role
|
||||
- `issue-thing` - Not recognizable
|
||||
|
||||
### Agent Titles
|
||||
|
||||
The H1 title in `AGENT.md` should be the role name in Title Case:
|
||||
|
||||
| Folder | Title |
|
||||
|--------|-------|
|
||||
| `product-manager` | Product Manager Agent |
|
||||
| `code-reviewer` | Code Reviewer Agent |
|
||||
| `security-auditor` | Security Auditor Agent |
|
||||
|
||||
## Model Selection
|
||||
|
||||
Agents can specify which Claude model to use via the `model` field in YAML frontmatter. Choosing the right model balances capability, speed, and cost.
|
||||
|
||||
### Available Models
|
||||
|
||||
| Model | Characteristics | Best For |
|
||||
|-------|-----------------|----------|
|
||||
| `haiku` | Fastest, most cost-effective | Simple structured tasks, formatting, basic transformations |
|
||||
| `sonnet` | Balanced speed and capability | Most agent tasks, code review, issue management |
|
||||
| `opus` | Most capable, best reasoning | Complex analysis, architectural decisions, nuanced judgment |
|
||||
| `inherit` | Uses parent context's model | When agent should match caller's capability level |
|
||||
|
||||
### Decision Matrix
|
||||
|
||||
| Agent Task Type | Recommended Model | Reasoning |
|
||||
|-----------------|-------------------|-----------|
|
||||
| Structured output formatting | `haiku` | Pattern-following, no complex reasoning |
|
||||
| Code review (style/conventions) | `sonnet` | Needs code understanding, not deep analysis |
|
||||
| Security vulnerability analysis | `opus` | Requires nuanced judgment, high stakes |
|
||||
| Issue triage and labeling | `haiku` or `sonnet` | Mostly classification tasks |
|
||||
| Feature planning and breakdown | `sonnet` or `opus` | Needs strategic thinking |
|
||||
| Batch processing (many items) | `haiku` or `sonnet` | Speed and cost matter at scale |
|
||||
| Architectural exploration | `opus` | Complex reasoning about tradeoffs |
|
||||
|
||||
### Examples
|
||||
|
||||
These examples show recommended model configurations for different agent types:
|
||||
|
||||
**Code Reviewer Agent** - Use `sonnet`:
|
||||
```yaml
|
||||
---
|
||||
name: code-reviewer
|
||||
model: sonnet
|
||||
skills: gitea, code-review
|
||||
---
|
||||
```
|
||||
Code review requires understanding code patterns and conventions but rarely needs the deepest reasoning. Sonnet provides good balance.
|
||||
|
||||
**Security Auditor Agent** (hypothetical) - Use `opus`:
|
||||
```yaml
|
||||
---
|
||||
name: security-auditor
|
||||
model: opus
|
||||
skills: code-review # would add security-specific skills
|
||||
---
|
||||
```
|
||||
Security analysis requires careful, nuanced judgment where missing issues have real consequences. Worth the extra capability.
|
||||
|
||||
**Formatting Agent** (hypothetical) - Use `haiku`:
|
||||
```yaml
|
||||
---
|
||||
name: markdown-formatter
|
||||
model: haiku
|
||||
skills: documentation
|
||||
---
|
||||
```
|
||||
Pure formatting tasks follow patterns and don't require complex reasoning. Haiku is fast and sufficient.
|
||||
|
||||
### Best Practices for Model Selection
|
||||
|
||||
1. **Start with `sonnet`** - It handles most agent tasks well
|
||||
2. **Use `haiku` for volume** - When processing many items, speed and cost add up
|
||||
3. **Reserve `opus` for judgment** - Use when errors are costly or reasoning is complex
|
||||
4. **Avoid `inherit` by default** - Make a deliberate choice; `inherit` obscures the decision
|
||||
5. **Consider the stakes** - Higher consequence tasks warrant more capable models
|
||||
6. **Test with real tasks** - Verify the chosen model performs adequately
|
||||
|
||||
### When to Use `inherit`
|
||||
|
||||
The `inherit` option has legitimate uses:
|
||||
|
||||
- **Utility agents**: Small helpers that should match their caller's capability
|
||||
- **Delegation chains**: When an agent spawns sub-agents that should stay consistent
|
||||
- **Testing/development**: When you want to control model from the top level
|
||||
|
||||
However, most production agents should specify an explicit model.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Choose Skills Deliberately
|
||||
|
||||
Include only skills the agent needs. More skills = more context = potential confusion.
|
||||
|
||||
**Too many skills:**
|
||||
```markdown
|
||||
## Skills
|
||||
- gitea
|
||||
- issue-writing
|
||||
- backlog-grooming
|
||||
- roadmap-planning
|
||||
- code-review
|
||||
- testing
|
||||
- documentation
|
||||
- deployment
|
||||
```
|
||||
|
||||
**Right-sized:**
|
||||
```markdown
|
||||
## Skills
|
||||
- gitea
|
||||
- issue-writing
|
||||
- backlog-grooming
|
||||
- roadmap-planning
|
||||
```
|
||||
|
||||
### 2. Define Clear Boundaries
|
||||
|
||||
Agents should know what they can and cannot do.
|
||||
|
||||
**Vague:**
|
||||
```markdown
|
||||
## Capabilities
|
||||
This agent can help with project management.
|
||||
```
|
||||
|
||||
**Clear:**
|
||||
```markdown
|
||||
## Capabilities
|
||||
This agent can:
|
||||
- Review and improve existing issues
|
||||
- Create new well-structured issues
|
||||
- Analyze the backlog for gaps
|
||||
|
||||
This agent cannot:
|
||||
- Merge pull requests
|
||||
- Deploy code
|
||||
- Make architectural decisions
|
||||
```
|
||||
|
||||
### 3. Set Behavioral Guardrails
|
||||
|
||||
Prevent agents from causing problems by setting explicit rules.
|
||||
|
||||
**Important behaviors to specify:**
|
||||
- When to ask for approval
|
||||
- What to do before making changes
|
||||
- How to report results
|
||||
- Error handling expectations
|
||||
|
||||
### 4. Match Persona to Purpose
|
||||
|
||||
The agent's name and description should align with its skills and capabilities.
|
||||
|
||||
**Mismatched:**
|
||||
```markdown
|
||||
# Security Agent
|
||||
|
||||
## Skills
|
||||
- issue-writing
|
||||
- documentation
|
||||
```
|
||||
|
||||
**Aligned:**
|
||||
```markdown
|
||||
# Security Auditor Agent
|
||||
|
||||
## Skills
|
||||
- security-scanning
|
||||
- vulnerability-assessment
|
||||
- code-review
|
||||
```
|
||||
|
||||
### 5. Keep Agents Focused
|
||||
|
||||
One agent = one role. If an agent does too many unrelated things, split it.
|
||||
|
||||
**Too broad:**
|
||||
```markdown
|
||||
# Everything Agent
|
||||
Handles issues, code review, deployment, and customer support.
|
||||
```
|
||||
|
||||
**Focused:**
|
||||
```markdown
|
||||
# Product Manager Agent
|
||||
Specialized for backlog management and roadmap planning.
|
||||
```
|
||||
|
||||
## When to Create a New Agent
|
||||
|
||||
Create an agent when you need:
|
||||
|
||||
1. **Role-based expertise**: A recognizable persona improves outputs
|
||||
2. **Skill composition**: Multiple skills work better together
|
||||
3. **Context isolation**: Work shouldn't pollute main conversation
|
||||
4. **Parallel capability**: Tasks can run independently
|
||||
5. **Autonomous operation**: Agent should figure things out on its own
|
||||
|
||||
### Signs You Need a New Agent
|
||||
|
||||
- Commands repeatedly spawn similar skill combinations
|
||||
- Tasks require deep exploration that pollutes context
|
||||
- Work benefits from a specialist "persona"
|
||||
- Batch processing would help
|
||||
|
||||
### Signs You Don't Need a New Agent
|
||||
|
||||
- Single skill is sufficient
|
||||
- Task is simple and sequential
|
||||
- Main context is helpful, not harmful
|
||||
- No clear persona or role emerges
|
||||
|
||||
## Agent Lifecycle
|
||||
|
||||
### 1. Design
|
||||
|
||||
Define the agent's role:
|
||||
- What persona makes sense?
|
||||
- Which skills does it need?
|
||||
- What can it do (and not do)?
|
||||
- When should it be spawned?
|
||||
|
||||
### 2. Implement
|
||||
|
||||
Create the agent file:
|
||||
- Clear name and description
|
||||
- Appropriate skill list
|
||||
- Specific capabilities
|
||||
- Usage guidance
|
||||
- Behavioral rules
|
||||
|
||||
### 3. Integrate
|
||||
|
||||
Connect the agent to workflows:
|
||||
- Update commands that should spawn it
|
||||
- Document in ARCHITECTURE.md
|
||||
- Test with real tasks
|
||||
|
||||
### 4. Refine
|
||||
|
||||
Improve based on usage:
|
||||
- Add/remove skills as needed
|
||||
- Clarify capabilities
|
||||
- Strengthen behavioral rules
|
||||
- Update documentation
|
||||
|
||||
## Checklist: Before Submitting a New Agent
|
||||
|
||||
- [ ] File is at `agents/<name>/AGENT.md`
|
||||
- [ ] Name follows kebab-case convention
|
||||
- [ ] Agent has a clear, recognizable role
|
||||
- [ ] Skills list is deliberate (not too many, not too few)
|
||||
- [ ] Model selection is deliberate (not just `inherit` by default)
|
||||
- [ ] Capabilities are specific and achievable
|
||||
- [ ] "When to Use" guidance is clear
|
||||
- [ ] Behavioral rules prevent problems
|
||||
- [ ] Agent is referenced by at least one command
|
||||
- [ ] ARCHITECTURE.md is updated
|
||||
|
||||
## See Also
|
||||
|
||||
- [ARCHITECTURE.md](../ARCHITECTURE.md): How agents fit into the overall system
|
||||
- [writing-skills.md](writing-skills.md): Creating the skills that agents use
|
||||
- [VISION.md](../VISION.md): The philosophy behind composable components
|
||||
@@ -0,0 +1,655 @@
|
||||
# Writing Commands
|
||||
|
||||
A guide to creating user-facing entry points that trigger workflows.
|
||||
|
||||
## What is a Command?
|
||||
|
||||
Commands are **user-facing entry points** that trigger workflows. Unlike skills (which encode knowledge) or agents (which execute tasks autonomously), commands define *what* to do—they orchestrate the workflow that users invoke directly.
|
||||
|
||||
Think of commands as the interface between users and the system. Users type `/work-issue 42` and the command defines the entire workflow: fetch issue, create branch, implement, commit, push, create PR.
|
||||
|
||||
## File Structure
|
||||
|
||||
Commands live directly in the `commands/` directory as markdown files:
|
||||
|
||||
```
|
||||
commands/
|
||||
├── work-issue.md
|
||||
├── dashboard.md
|
||||
├── review-pr.md
|
||||
├── create-issue.md
|
||||
├── groom.md
|
||||
├── roadmap.md
|
||||
└── plan-issues.md
|
||||
```
|
||||
|
||||
### Why Flat Files?
|
||||
|
||||
Unlike skills and agents (which use folders), commands are single files because:
|
||||
- Commands are self-contained workflow definitions
|
||||
- No supporting files needed
|
||||
- Simple naming: `/work-issue` maps to `work-issue.md`
|
||||
|
||||
## Command Document Structure
|
||||
|
||||
A well-structured command file has two parts:
|
||||
|
||||
### 1. Frontmatter (YAML Header)
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: Brief description shown in command listings
|
||||
argument-hint: <required-arg> [optional-arg]
|
||||
---
|
||||
```
|
||||
|
||||
| Field | Purpose | Required |
|
||||
|-------|---------|----------|
|
||||
| `description` | One-line summary for help/listings | Yes |
|
||||
| `argument-hint` | Shows expected arguments | If arguments needed |
|
||||
|
||||
### 2. Body (Markdown Instructions)
|
||||
|
||||
```markdown
|
||||
# Command Title
|
||||
|
||||
Brief intro if needed.
|
||||
|
||||
1. **Step one**: What to do
|
||||
2. **Step two**: What to do next
|
||||
...
|
||||
```
|
||||
|
||||
The body contains the workflow steps that Claude follows when the command is invoked.
|
||||
|
||||
## Complete Command Example
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Work on a Gitea issue. Fetches issue details and sets up branch.
|
||||
argument-hint: <issue-number>
|
||||
---
|
||||
|
||||
# Work on Issue #$1
|
||||
|
||||
Use the gitea skill.
|
||||
|
||||
1. **View the issue** to understand requirements
|
||||
2. **Create a branch**: `git checkout -b issue-$1-<short-kebab-title>`
|
||||
3. **Plan**: Use TodoWrite to break down the work
|
||||
4. **Implement** the changes
|
||||
5. **Commit** with message referencing the issue
|
||||
6. **Push** the branch to origin
|
||||
7. **Create PR** with title "[Issue #$1] <title>" and body "Closes #$1"
|
||||
```
|
||||
|
||||
## Argument Handling
|
||||
|
||||
Commands can accept arguments from the user. Arguments are passed via positional variables: `$1`, `$2`, etc.
|
||||
|
||||
### The ARGUMENTS Pattern
|
||||
|
||||
When users invoke a command with arguments:
|
||||
```
|
||||
/work-issue 42
|
||||
```
|
||||
|
||||
The system provides the arguments via the `$1`, `$2`, etc. placeholders in the command body:
|
||||
```markdown
|
||||
# Work on Issue #$1
|
||||
1. **View the issue** to understand requirements
|
||||
```
|
||||
|
||||
Becomes:
|
||||
```markdown
|
||||
# Work on Issue #42
|
||||
1. **View the issue** to understand requirements
|
||||
```
|
||||
|
||||
### Argument Hints
|
||||
|
||||
Use `argument-hint` in frontmatter to document expected arguments:
|
||||
|
||||
| Pattern | Meaning |
|
||||
|---------|---------|
|
||||
| `<arg>` | Required argument |
|
||||
| `[arg]` | Optional argument |
|
||||
| `<arg1> <arg2>` | Multiple required |
|
||||
| `[arg1] [arg2]` | Multiple optional |
|
||||
| `<required> [optional]` | Mix of both |
|
||||
|
||||
Examples:
|
||||
```yaml
|
||||
argument-hint: <issue-number> # One required
|
||||
argument-hint: [issue-number] # One optional
|
||||
argument-hint: <title> [description] # Required + optional
|
||||
argument-hint: [title] or "batch" # Choice of modes
|
||||
```
|
||||
|
||||
### Handling Optional Arguments
|
||||
|
||||
Commands often have different behavior based on whether arguments are provided:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Groom issues. Without argument, reviews all. With argument, grooms specific issue.
|
||||
argument-hint: [issue-number]
|
||||
---
|
||||
|
||||
# Groom Issues
|
||||
|
||||
Use the gitea skill.
|
||||
|
||||
## If issue number provided ($1):
|
||||
1. **Fetch the issue** details
|
||||
2. **Evaluate** against checklist
|
||||
...
|
||||
|
||||
## If no argument (groom all):
|
||||
1. **List open issues**
|
||||
2. **Review each** against checklist
|
||||
...
|
||||
```
|
||||
|
||||
### Multiple Modes
|
||||
|
||||
Some commands support distinct modes based on the first argument:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Create issues. Single or batch mode.
|
||||
argument-hint: [title] or "batch"
|
||||
---
|
||||
|
||||
# Create Issue(s)
|
||||
|
||||
Use the gitea skill.
|
||||
|
||||
## Single Issue (default)
|
||||
If title provided, create an issue with that title.
|
||||
|
||||
## Batch Mode
|
||||
If $1 is "batch":
|
||||
1. Ask user for the plan
|
||||
2. Generate list of issues
|
||||
3. Show for approval
|
||||
4. Create each issue
|
||||
```
|
||||
|
||||
## Invoking Skills
|
||||
|
||||
Commands reference skills by name to gain domain knowledge. When a skill is referenced, Claude reads the skill file before proceeding.
|
||||
|
||||
### Explicit Reference
|
||||
|
||||
```markdown
|
||||
# Groom Issues
|
||||
|
||||
Use the **gitea**, **backlog-grooming**, and **issue-writing** skills.
|
||||
|
||||
1. **Fetch the issue** details
|
||||
2. **Evaluate** against grooming checklist
|
||||
...
|
||||
```
|
||||
|
||||
The phrase "Use the gitea, backlog-grooming and issue-writing skills" tells Claude to read and apply knowledge from those skill files.
|
||||
|
||||
### Skill-Based Approach
|
||||
|
||||
Commands should reference skills rather than embedding CLI commands directly:
|
||||
|
||||
```markdown
|
||||
1. **Fetch the issue** details
|
||||
```
|
||||
|
||||
This relies on the `gitea` skill to provide the CLI knowledge.
|
||||
|
||||
### When to Reference Skills
|
||||
|
||||
| Reference explicitly | Reference implicitly |
|
||||
|---------------------|---------------------|
|
||||
| Core methodology is needed | Just using a tool |
|
||||
| Quality standards matter | Simple operations |
|
||||
| Patterns should be followed | Well-known commands |
|
||||
|
||||
## Invoking Agents
|
||||
|
||||
Commands can spawn agents for complex subtasks that benefit from skill composition or context isolation.
|
||||
|
||||
### Spawning Agents
|
||||
|
||||
```markdown
|
||||
For comprehensive backlog review, spawn the **product-manager** agent to:
|
||||
- Review all open issues
|
||||
- Categorize by readiness
|
||||
- Propose improvements
|
||||
```
|
||||
|
||||
### When to Spawn Agents
|
||||
|
||||
Spawn an agent when the command needs:
|
||||
- **Parallel processing**: Multiple independent tasks
|
||||
- **Context isolation**: Deep exploration that would pollute main context
|
||||
- **Skill composition**: Multiple skills working together
|
||||
- **Autonomous operation**: Let the agent figure out details
|
||||
|
||||
### Example: Conditional Agent Spawning
|
||||
|
||||
```markdown
|
||||
# Groom Issues
|
||||
|
||||
## If no argument (groom all):
|
||||
For large backlogs (>10 issues), consider spawning the
|
||||
product-manager agent to handle the review autonomously.
|
||||
```
|
||||
|
||||
## Interactive Patterns
|
||||
|
||||
Commands often require user interaction for confirmation, choices, or input.
|
||||
|
||||
### Approval Workflows
|
||||
|
||||
Always ask for approval before significant actions:
|
||||
|
||||
```markdown
|
||||
5. **Ask for approval** before creating issues
|
||||
6. **Create issues** in order
|
||||
```
|
||||
|
||||
Common approval points:
|
||||
- Before creating/modifying resources (issues, PRs, files)
|
||||
- Before executing destructive operations
|
||||
- When presenting a plan that will be executed
|
||||
|
||||
### Presenting Choices
|
||||
|
||||
When the command leads to multiple possible actions:
|
||||
|
||||
```markdown
|
||||
Ask the user what action to take:
|
||||
- **Merge**: Approve and merge the PR
|
||||
- **Request changes**: Leave feedback without merging
|
||||
- **Comment only**: Add a comment for discussion
|
||||
```
|
||||
|
||||
### Gathering Input
|
||||
|
||||
Some commands need to gather information from the user:
|
||||
|
||||
```markdown
|
||||
## Batch Mode
|
||||
If $1 is "batch":
|
||||
1. **Ask user** for the plan/direction
|
||||
2. Generate list of issues with titles and descriptions
|
||||
3. Show for approval
|
||||
```
|
||||
|
||||
### Presenting Results
|
||||
|
||||
Commands should clearly show what was done:
|
||||
|
||||
```markdown
|
||||
7. **Update dependencies** with actual issue numbers after creation
|
||||
8. **Present summary** with links to created issues
|
||||
```
|
||||
|
||||
Good result presentations include:
|
||||
- Tables for lists of items
|
||||
- Links for created resources
|
||||
- Summaries of changes made
|
||||
- Next step suggestions
|
||||
|
||||
## Annotated Examples
|
||||
|
||||
Let's examine existing commands to understand effective patterns.
|
||||
|
||||
### Example 1: work-issue (Linear Workflow)
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Work on a Gitea issue. Fetches issue details and sets up branch.
|
||||
argument-hint: <issue-number>
|
||||
---
|
||||
|
||||
# Work on Issue #$1
|
||||
|
||||
Use the gitea skill.
|
||||
|
||||
1. **View the issue** to understand requirements
|
||||
2. **Create a branch**: `git checkout -b issue-$1-<short-kebab-title>`
|
||||
3. **Plan**: Use TodoWrite to break down the work
|
||||
4. **Implement** the changes
|
||||
5. **Commit** with message referencing the issue
|
||||
6. **Push** the branch to origin
|
||||
7. **Create PR** with title "[Issue #$1] <title>" and body "Closes #$1"
|
||||
```
|
||||
|
||||
**Key patterns:**
|
||||
- **Linear workflow**: Clear numbered steps in order
|
||||
- **Required argument**: `<issue-number>` means must provide
|
||||
- **Variable substitution**: `$1` used throughout
|
||||
- **Skill reference**: Uses gitea skill for CLI knowledge
|
||||
- **Git integration**: Branch and push steps specified
|
||||
|
||||
### Example 2: dashboard (No Arguments)
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Show dashboard of open issues, PRs awaiting review, and CI status.
|
||||
---
|
||||
|
||||
# Repository Dashboard
|
||||
|
||||
Use the gitea skill.
|
||||
|
||||
Fetch and display:
|
||||
1. All open issues
|
||||
2. All open PRs
|
||||
|
||||
Format as tables showing issue/PR number, title, and author.
|
||||
```
|
||||
|
||||
**Key patterns:**
|
||||
- **No argument-hint**: Command takes no arguments
|
||||
- **Output formatting**: Specifies how to present results
|
||||
- **Aggregation**: Combines multiple data sources
|
||||
- **Simple workflow**: Just fetch and display
|
||||
|
||||
### Example 3: groom (Optional Argument with Modes)
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Groom and improve issues. Without argument, reviews all. With argument, grooms specific issue.
|
||||
argument-hint: [issue-number]
|
||||
---
|
||||
|
||||
# Groom Issues
|
||||
|
||||
Use the gitea, backlog-grooming, and issue-writing skills.
|
||||
|
||||
## If issue number provided ($1):
|
||||
1. **Fetch the issue** details
|
||||
2. **Evaluate** against grooming checklist
|
||||
3. **Suggest improvements** for:
|
||||
- Title clarity
|
||||
- Description completeness
|
||||
- Acceptance criteria quality
|
||||
4. **Ask user** if they want to apply changes
|
||||
5. **Update issue** if approved
|
||||
|
||||
## If no argument (groom all):
|
||||
1. **List open issues**
|
||||
2. **Review each** against grooming checklist
|
||||
3. **Categorize**: Ready / Needs work / Stale
|
||||
4. **Present summary** table
|
||||
5. **Offer to improve** issues that need work
|
||||
```
|
||||
|
||||
**Key patterns:**
|
||||
- **Optional argument**: `[issue-number]` with brackets
|
||||
- **Mode switching**: Different behavior based on argument presence
|
||||
- **Explicit skill reference**: "Use the gitea, backlog-grooming and issue-writing skills"
|
||||
- **Approval workflow**: "Ask user if they want to apply changes"
|
||||
- **Categorization**: Groups items for presentation
|
||||
|
||||
### Example 4: plan-issues (Complex Workflow)
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Plan and create issues for a feature. Breaks down work into well-structured issues.
|
||||
argument-hint: <feature-description>
|
||||
---
|
||||
|
||||
# Plan Feature: $1
|
||||
|
||||
Use the gitea, roadmap-planning, and issue-writing skills.
|
||||
|
||||
1. **Understand the feature**: Analyze what "$1" involves
|
||||
2. **Explore the codebase** if needed to understand context
|
||||
3. **Break down** into discrete, actionable issues
|
||||
4. **Present the plan**:
|
||||
```
|
||||
## Proposed Issues for: $1
|
||||
|
||||
1. [Title] - Brief description
|
||||
Dependencies: none
|
||||
...
|
||||
```
|
||||
5. **Ask for approval** before creating issues
|
||||
6. **Create issues** in order
|
||||
7. **Update dependencies** with actual issue numbers
|
||||
8. **Present summary** with links to created issues
|
||||
```
|
||||
|
||||
**Key patterns:**
|
||||
- **Multi-skill composition**: References three skills together
|
||||
- **Codebase exploration**: May need to understand context
|
||||
- **Structured output**: Template for presenting the plan
|
||||
- **Two-phase execution**: Plan first, then execute after approval
|
||||
- **Dependency management**: Creates issues in order, updates references
|
||||
|
||||
### Example 5: review-pr (Action Choices)
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Review a Gitea pull request. Fetches PR details, diff, and comments.
|
||||
argument-hint: <pr-number>
|
||||
---
|
||||
|
||||
# Review PR #$1
|
||||
|
||||
Use the gitea skill.
|
||||
|
||||
1. **View PR details** including description and metadata
|
||||
2. **Get the diff** to review the changes
|
||||
|
||||
Review the changes and provide feedback on:
|
||||
- Code quality
|
||||
- Potential bugs
|
||||
- Test coverage
|
||||
- Documentation
|
||||
|
||||
Ask the user what action to take:
|
||||
- **Merge**: Approve and merge the PR
|
||||
- **Request changes**: Leave feedback without merging
|
||||
- **Comment only**: Add a comment for discussion
|
||||
```
|
||||
|
||||
**Key patterns:**
|
||||
- **Information gathering**: Fetches context before analysis
|
||||
- **Review criteria**: Checklist of what to examine
|
||||
- **Action menu**: Clear choices with explanations
|
||||
- **User decides outcome**: Command presents options, user chooses
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
### Command File Names
|
||||
|
||||
- Use **kebab-case**: `work-issue.md`, `plan-issues.md`
|
||||
- Use **verbs or verb phrases**: Commands are actions
|
||||
- Be **concise**: 1-3 words is ideal
|
||||
- Match the **invocation**: `/work-issue` → `work-issue.md`
|
||||
|
||||
Good names:
|
||||
- `work-issue` - Action + target
|
||||
- `dashboard` - What it shows
|
||||
- `review-pr` - Action + target
|
||||
- `plan-issues` - Action + target
|
||||
- `groom` - Action (target implied)
|
||||
|
||||
Avoid:
|
||||
- `issue-work` - Noun-first is awkward
|
||||
- `do-stuff` - Too vague
|
||||
- `manage-issues-and-prs` - Too long
|
||||
|
||||
### Command Titles
|
||||
|
||||
The H1 title can be more descriptive than the filename:
|
||||
|
||||
| Filename | Title |
|
||||
|----------|-------|
|
||||
| `work-issue.md` | Work on Issue #$1 |
|
||||
| `dashboard.md` | Repository Dashboard |
|
||||
| `plan-issues.md` | Plan Feature: $1 |
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Design Clear Workflows
|
||||
|
||||
Each step should be unambiguous:
|
||||
|
||||
**Vague:**
|
||||
```markdown
|
||||
1. Handle the issue
|
||||
2. Do the work
|
||||
3. Finish up
|
||||
```
|
||||
|
||||
**Clear:**
|
||||
```markdown
|
||||
1. **View the issue** to understand requirements
|
||||
2. **Create a branch**: `git checkout -b issue-$1-<title>`
|
||||
3. **Plan**: Use TodoWrite to break down the work
|
||||
```
|
||||
|
||||
### 2. Show Don't Tell
|
||||
|
||||
Include actual commands and expected outputs:
|
||||
|
||||
**Telling:**
|
||||
```markdown
|
||||
List the open issues.
|
||||
```
|
||||
|
||||
**Showing:**
|
||||
```markdown
|
||||
Fetch all open issues and format as table:
|
||||
| # | Title | Author |
|
||||
|---|-------|--------|
|
||||
```
|
||||
|
||||
### 3. Always Ask Before Acting
|
||||
|
||||
Never modify resources without user approval:
|
||||
|
||||
```markdown
|
||||
4. **Present plan** for approval
|
||||
5. **If approved**, create the issues
|
||||
```
|
||||
|
||||
### 4. Handle Edge Cases
|
||||
|
||||
Consider what happens when things are empty or unexpected:
|
||||
|
||||
```markdown
|
||||
## If no argument (groom all):
|
||||
1. **List open issues**
|
||||
2. If no issues found, report "No open issues to groom"
|
||||
3. Otherwise, **review each** against checklist
|
||||
```
|
||||
|
||||
### 5. Provide Helpful Output
|
||||
|
||||
End with useful information:
|
||||
|
||||
```markdown
|
||||
8. **Present summary** with:
|
||||
- Links to created issues
|
||||
- Dependency graph
|
||||
- Suggested next steps
|
||||
```
|
||||
|
||||
### 6. Keep Commands Focused
|
||||
|
||||
One command = one workflow. If doing multiple unrelated things, split into separate commands.
|
||||
|
||||
**Too broad:**
|
||||
```markdown
|
||||
# Manage Everything
|
||||
Handle issues, PRs, deployments, and documentation...
|
||||
```
|
||||
|
||||
**Focused:**
|
||||
```markdown
|
||||
# Review PR #$1
|
||||
Review and take action on a pull request...
|
||||
```
|
||||
|
||||
## When to Create a Command
|
||||
|
||||
Create a command when you have:
|
||||
|
||||
1. **Repeatable workflow**: Same steps used multiple times
|
||||
2. **User-initiated action**: User explicitly triggers it
|
||||
3. **Clear start and end**: Workflow has defined boundaries
|
||||
4. **Consistent behavior needed**: Should work the same every time
|
||||
|
||||
### Signs You Need a New Command
|
||||
|
||||
- You're explaining the same workflow repeatedly
|
||||
- Users would benefit from a single invocation
|
||||
- Multiple tools need orchestration
|
||||
- Approval checkpoints are needed
|
||||
|
||||
### Signs You Don't Need a Command
|
||||
|
||||
- It's a one-time action
|
||||
- No workflow orchestration needed
|
||||
- A skill reference is sufficient
|
||||
- An agent could handle it autonomously
|
||||
|
||||
## Command Lifecycle
|
||||
|
||||
### 1. Design
|
||||
|
||||
Define the workflow:
|
||||
- What triggers it?
|
||||
- What arguments does it need?
|
||||
- What steps are involved?
|
||||
- Where are approval points?
|
||||
- What does success look like?
|
||||
|
||||
### 2. Implement
|
||||
|
||||
Create the command file:
|
||||
- Clear frontmatter
|
||||
- Step-by-step workflow
|
||||
- Skill references where needed
|
||||
- Approval checkpoints
|
||||
- Output formatting
|
||||
|
||||
### 3. Test
|
||||
|
||||
Verify the workflow:
|
||||
- Run with typical arguments
|
||||
- Test edge cases (no args, invalid args)
|
||||
- Confirm approval points work
|
||||
- Check output formatting
|
||||
|
||||
### 4. Document
|
||||
|
||||
Update references:
|
||||
- Add to ARCHITECTURE.md table
|
||||
- Update README if user-facing
|
||||
- Note any skill/agent dependencies
|
||||
|
||||
## Checklist: Before Submitting a New Command
|
||||
|
||||
- [ ] File is at `commands/<name>.md`
|
||||
- [ ] Name follows kebab-case verb convention
|
||||
- [ ] Frontmatter includes description
|
||||
- [ ] Frontmatter includes argument-hint (if arguments needed)
|
||||
- [ ] Workflow steps are clear and numbered
|
||||
- [ ] Commands and tools are specified explicitly
|
||||
- [ ] Skills are referenced where methodology matters
|
||||
- [ ] Approval points exist before significant actions
|
||||
- [ ] Edge cases are handled (no data, invalid input)
|
||||
- [ ] Output formatting is specified
|
||||
- [ ] ARCHITECTURE.md is updated with new command
|
||||
|
||||
## See Also
|
||||
|
||||
- [ARCHITECTURE.md](../ARCHITECTURE.md): How commands fit into the overall system
|
||||
- [writing-skills.md](writing-skills.md): Creating skills that commands reference
|
||||
- [writing-agents.md](writing-agents.md): Creating agents that commands spawn
|
||||
- [VISION.md](../VISION.md): The philosophy behind composable components
|
||||
@@ -0,0 +1,445 @@
|
||||
# Writing Skills
|
||||
|
||||
A guide to creating reusable knowledge modules for the Claude Code AI workflow system.
|
||||
|
||||
## What is a Skill?
|
||||
|
||||
Skills are **knowledge modules**—focused documents that teach Claude how to do something well. Unlike commands (which define workflows) or agents (which execute tasks), skills are passive: they encode domain expertise, patterns, and best practices that can be referenced when needed.
|
||||
|
||||
Think of skills as the "how-to guides" that inform Claude's work. A skill doesn't act on its own—it provides the knowledge that commands and agents use to complete their tasks effectively.
|
||||
|
||||
## File Structure
|
||||
|
||||
Skills live in the `skills/` directory, each in its own folder:
|
||||
|
||||
```
|
||||
skills/
|
||||
├── gitea/
|
||||
│ └── SKILL.md
|
||||
├── issue-writing/
|
||||
│ └── SKILL.md
|
||||
├── backlog-grooming/
|
||||
│ └── SKILL.md
|
||||
└── roadmap-planning/
|
||||
└── SKILL.md
|
||||
```
|
||||
|
||||
### Why SKILL.md?
|
||||
|
||||
The uppercase `SKILL.md` filename:
|
||||
- Makes the skill file immediately visible in directory listings
|
||||
- Follows a consistent convention across all skills
|
||||
- Clearly identifies the primary file in a skill folder
|
||||
|
||||
### Supporting Files (Optional)
|
||||
|
||||
A skill folder can contain additional files if needed:
|
||||
|
||||
```
|
||||
skills/
|
||||
└── complex-skill/
|
||||
├── SKILL.md # Main skill document (required)
|
||||
├── templates/ # Template files
|
||||
│ └── example.md
|
||||
└── examples/ # Extended examples
|
||||
└── case-study.md
|
||||
```
|
||||
|
||||
However, prefer keeping everything in `SKILL.md` when possible—it's easier to maintain and reference.
|
||||
|
||||
## Skill Document Structure
|
||||
|
||||
A well-structured `SKILL.md` follows this pattern:
|
||||
|
||||
```markdown
|
||||
# Skill Name
|
||||
|
||||
Brief description of what this skill covers.
|
||||
|
||||
## Core Concepts
|
||||
Explain the fundamental ideas Claude needs to understand.
|
||||
|
||||
## Patterns and Templates
|
||||
Provide reusable structures and formats.
|
||||
|
||||
## Guidelines
|
||||
List rules, best practices, and quality standards.
|
||||
|
||||
## Examples
|
||||
Show concrete illustrations of the skill in action.
|
||||
|
||||
## Common Mistakes
|
||||
Document pitfalls to avoid.
|
||||
|
||||
## Reference
|
||||
Quick-reference tables, checklists, or commands.
|
||||
```
|
||||
|
||||
Not every skill needs all sections—include what's relevant. Some skills are primarily patterns (like `issue-writing`), others are reference-heavy (like `gitea`).
|
||||
|
||||
## How Skills are Loaded
|
||||
|
||||
Skills are loaded by **explicit reference**. When a command or agent mentions a skill by name, Claude reads the skill file to gain that knowledge.
|
||||
|
||||
### Referenced by Commands
|
||||
|
||||
Commands reference skills in their instructions:
|
||||
|
||||
```markdown
|
||||
# Groom Issues
|
||||
|
||||
Use the **backlog-grooming** and **issue-writing** skills to review and improve issues.
|
||||
|
||||
1. Fetch open issues...
|
||||
```
|
||||
|
||||
When this command runs, Claude reads both referenced skills before proceeding.
|
||||
|
||||
### Referenced by Agents
|
||||
|
||||
Agents list their skills explicitly:
|
||||
|
||||
```markdown
|
||||
# Product Manager Agent
|
||||
|
||||
## Skills
|
||||
- gitea
|
||||
- issue-writing
|
||||
- backlog-grooming
|
||||
- roadmap-planning
|
||||
```
|
||||
|
||||
When spawned, the agent has access to all listed skills as part of its context.
|
||||
|
||||
### Skills Can Reference Other Skills
|
||||
|
||||
Skills can mention other skills for related knowledge:
|
||||
|
||||
```markdown
|
||||
# Roadmap Planning
|
||||
|
||||
...
|
||||
|
||||
When creating issues, follow the patterns in the **issue-writing** skill.
|
||||
Use **gitea** commands to create the issues.
|
||||
```
|
||||
|
||||
This creates a natural knowledge hierarchy without duplicating content.
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
### Skill Folder Names
|
||||
|
||||
- Use **kebab-case**: `issue-writing`, `backlog-grooming`
|
||||
- Be **descriptive**: name should indicate the skill's domain
|
||||
- Be **concise**: 2-3 words is ideal
|
||||
- Avoid generic names: `utils`, `helpers`, `common`
|
||||
|
||||
Good names:
|
||||
- `gitea` - Tool-specific knowledge
|
||||
- `issue-writing` - Activity-focused
|
||||
- `backlog-grooming` - Process-focused
|
||||
- `roadmap-planning` - Task-focused
|
||||
|
||||
### Skill Titles
|
||||
|
||||
The H1 title in `SKILL.md` should match the folder name in Title Case:
|
||||
|
||||
| Folder | Title |
|
||||
|--------|-------|
|
||||
| `gitea` | Forgejo CLI (fj) |
|
||||
| `issue-writing` | Issue Writing |
|
||||
| `backlog-grooming` | Backlog Grooming |
|
||||
| `roadmap-planning` | Roadmap Planning |
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Keep Skills Focused
|
||||
|
||||
Each skill should cover **one domain, one concern**. If your skill document is getting long or covers multiple unrelated topics, consider splitting it.
|
||||
|
||||
**Too broad:**
|
||||
```markdown
|
||||
# Project Management
|
||||
How to manage issues, PRs, releases, and documentation...
|
||||
```
|
||||
|
||||
**Better:**
|
||||
```markdown
|
||||
# Issue Writing
|
||||
How to write clear, actionable issues.
|
||||
```
|
||||
|
||||
### 2. Be Specific, Not Vague
|
||||
|
||||
Provide concrete patterns, not abstract principles.
|
||||
|
||||
**Vague:**
|
||||
```markdown
|
||||
## Writing Good Titles
|
||||
Titles should be clear and descriptive.
|
||||
```
|
||||
|
||||
**Specific:**
|
||||
```markdown
|
||||
## Writing Good Titles
|
||||
- Start with action verb: "Add", "Fix", "Update", "Remove"
|
||||
- Be specific: "Add user authentication" not "Auth stuff"
|
||||
- Keep under 60 characters
|
||||
```
|
||||
|
||||
### 3. Include Actionable Examples
|
||||
|
||||
Every guideline should have an example showing what it looks like in practice.
|
||||
|
||||
```markdown
|
||||
### Acceptance Criteria
|
||||
|
||||
Good criteria are:
|
||||
- **Specific**: "User sees error message" not "Handle errors"
|
||||
- **Testable**: Can verify pass/fail
|
||||
- **User-focused**: What the user experiences
|
||||
|
||||
Examples:
|
||||
- [ ] Login form validates email format before submission
|
||||
- [ ] Invalid credentials show "Invalid email or password" message
|
||||
- [ ] Successful login redirects to dashboard
|
||||
```
|
||||
|
||||
### 4. Use Templates for Repeatability
|
||||
|
||||
When the skill involves creating structured content, provide copy-paste templates:
|
||||
|
||||
```markdown
|
||||
### Feature Request Template
|
||||
|
||||
\```markdown
|
||||
## Summary
|
||||
What feature and why it's valuable.
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] Criterion 1
|
||||
- [ ] Criterion 2
|
||||
|
||||
## Context
|
||||
Additional background or references.
|
||||
\```
|
||||
```
|
||||
|
||||
### 5. Include Checklists for Verification
|
||||
|
||||
Checklists help ensure consistent quality:
|
||||
|
||||
```markdown
|
||||
## Grooming Checklist
|
||||
|
||||
For each issue, verify:
|
||||
- [ ] Starts with action verb
|
||||
- [ ] Has acceptance criteria
|
||||
- [ ] Scope is clear
|
||||
- [ ] Dependencies identified
|
||||
```
|
||||
|
||||
### 6. Document Common Mistakes
|
||||
|
||||
Help avoid pitfalls by documenting what goes wrong:
|
||||
|
||||
```markdown
|
||||
## Common Mistakes
|
||||
|
||||
### Vague Titles
|
||||
- Bad: "Fix bug"
|
||||
- Good: "Fix login form validation on empty email"
|
||||
|
||||
### Missing Acceptance Criteria
|
||||
Every issue needs specific, testable criteria.
|
||||
```
|
||||
|
||||
### 7. Keep It Current
|
||||
|
||||
Skills should reflect current practices. When workflows change:
|
||||
- Update the skill document
|
||||
- Remove obsolete patterns
|
||||
- Add new best practices
|
||||
|
||||
## Annotated Examples
|
||||
|
||||
Let's examine the existing skills to understand effective patterns.
|
||||
|
||||
### Example 1: gitea (Tool Reference)
|
||||
|
||||
The `gitea` skill is a **tool reference**—it documents how to use a specific CLI tool.
|
||||
|
||||
```markdown
|
||||
# Forgejo CLI (fj)
|
||||
|
||||
Command-line interface for interacting with Forgejo repositories.
|
||||
|
||||
## Authentication
|
||||
The `tea` CLI authenticates via `tea auth login`. Credentials are stored locally.
|
||||
|
||||
## Common Commands
|
||||
|
||||
### Issues
|
||||
\```bash
|
||||
# List issues
|
||||
tea issue search -s open # Open issues
|
||||
tea issue search -s closed # Closed issues
|
||||
...
|
||||
\```
|
||||
```
|
||||
|
||||
**Key patterns:**
|
||||
- Organized by feature area (Issues, Pull Requests, Repository)
|
||||
- Includes actual command syntax with comments
|
||||
- Covers common use cases, not exhaustive documentation
|
||||
- Tips section for non-obvious behaviors
|
||||
|
||||
### Example 2: issue-writing (Process Knowledge)
|
||||
|
||||
The `issue-writing` skill is **process knowledge**—it teaches how to do something well.
|
||||
|
||||
```markdown
|
||||
# Issue Writing
|
||||
|
||||
How to write clear, actionable issues.
|
||||
|
||||
## Issue Structure
|
||||
|
||||
### Title
|
||||
- Start with action verb: "Add", "Fix", "Update", "Remove"
|
||||
- Be specific: "Add user authentication" not "Auth stuff"
|
||||
- Keep under 60 characters
|
||||
|
||||
### Description
|
||||
\```markdown
|
||||
## Summary
|
||||
One paragraph explaining what and why.
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] Specific, testable requirement
|
||||
...
|
||||
\```
|
||||
```
|
||||
|
||||
**Key patterns:**
|
||||
- Clear guidelines with specific rules
|
||||
- Templates for different issue types
|
||||
- Good/bad examples for each guideline
|
||||
- Covers the full lifecycle (structure, criteria, labels, dependencies)
|
||||
|
||||
### Example 3: backlog-grooming (Workflow Checklist)
|
||||
|
||||
The `backlog-grooming` skill is a **workflow checklist**—it provides a systematic process.
|
||||
|
||||
```markdown
|
||||
# Backlog Grooming
|
||||
|
||||
How to review and improve existing issues.
|
||||
|
||||
## Grooming Checklist
|
||||
|
||||
For each issue, verify:
|
||||
|
||||
### 1. Title Clarity
|
||||
- [ ] Starts with action verb
|
||||
- [ ] Specific and descriptive
|
||||
- [ ] Understandable without reading description
|
||||
...
|
||||
```
|
||||
|
||||
**Key patterns:**
|
||||
- Structured as a checklist with categories
|
||||
- Each item is a yes/no verification
|
||||
- Includes workflow steps (Grooming Workflow section)
|
||||
- Questions to guide decision-making
|
||||
|
||||
### Example 4: roadmap-planning (Strategy Guide)
|
||||
|
||||
The `roadmap-planning` skill is a **strategy guide**—it teaches how to think about a problem.
|
||||
|
||||
```markdown
|
||||
# Roadmap Planning
|
||||
|
||||
How to plan features and create issues for implementation.
|
||||
|
||||
## Planning Process
|
||||
|
||||
### 1. Understand the Goal
|
||||
- What capability or improvement is needed?
|
||||
- Who benefits and how?
|
||||
- What's the success criteria?
|
||||
|
||||
### 2. Break Down the Work
|
||||
- Identify distinct components
|
||||
- Define boundaries between pieces
|
||||
...
|
||||
```
|
||||
|
||||
**Key patterns:**
|
||||
- Process-oriented with numbered steps
|
||||
- Multiple breakdown strategies (by layer, by user story, by component)
|
||||
- Concrete examples showing the pattern applied
|
||||
- Questions to guide planning decisions
|
||||
|
||||
## When to Create a New Skill
|
||||
|
||||
Create a skill when you find yourself:
|
||||
|
||||
1. **Explaining the same concepts repeatedly** across different conversations
|
||||
2. **Wanting consistent quality** in a specific area
|
||||
3. **Building up domain expertise** that should persist
|
||||
4. **Needing a reusable reference** for commands or agents
|
||||
|
||||
### Signs You Need a New Skill
|
||||
|
||||
- You're copy-pasting the same guidelines
|
||||
- Multiple commands need the same knowledge
|
||||
- Quality is inconsistent without explicit guidance
|
||||
- There's a clear domain that doesn't fit existing skills
|
||||
|
||||
### Signs You Don't Need a New Skill
|
||||
|
||||
- The knowledge is only used once
|
||||
- It's already covered by an existing skill
|
||||
- It's too generic to be actionable
|
||||
- It's better as part of a command's instructions
|
||||
|
||||
## Skill Lifecycle
|
||||
|
||||
### 1. Draft
|
||||
|
||||
Start with the essential content:
|
||||
- Core patterns and templates
|
||||
- Key guidelines
|
||||
- A few examples
|
||||
|
||||
### 2. Refine
|
||||
|
||||
As you use the skill, improve it:
|
||||
- Add examples from real usage
|
||||
- Clarify ambiguous guidelines
|
||||
- Remove unused content
|
||||
|
||||
### 3. Maintain
|
||||
|
||||
Keep skills current:
|
||||
- Update when practices change
|
||||
- Remove obsolete patterns
|
||||
- Add newly discovered best practices
|
||||
|
||||
## Checklist: Before Submitting a New Skill
|
||||
|
||||
- [ ] File is at `skills/<name>/SKILL.md`
|
||||
- [ ] Name follows kebab-case convention
|
||||
- [ ] Skill focuses on a single domain
|
||||
- [ ] Guidelines are specific and actionable
|
||||
- [ ] Examples illustrate each major point
|
||||
- [ ] Templates are provided where appropriate
|
||||
- [ ] Common mistakes are documented
|
||||
- [ ] Skill is referenced by at least one command or agent
|
||||
|
||||
## See Also
|
||||
|
||||
- [ARCHITECTURE.md](../ARCHITECTURE.md): How skills fit into the overall system
|
||||
- [VISION.md](../VISION.md): The philosophy behind composable components
|
||||
-26
@@ -1,26 +0,0 @@
|
||||
manager:
|
||||
memory_budget: 450
|
||||
contention_policy:
|
||||
strategy: wait_then_preempt
|
||||
wait_timeout_s: 45
|
||||
preempt_after_s: 15
|
||||
|
||||
models:
|
||||
- name: Qwen-Coder-Next
|
||||
model: mlx-community/Qwen3-Coder-Next-4bit
|
||||
estimated_memory_gb: 50
|
||||
reasoning_parser: qwen3
|
||||
|
||||
- name: Qwen3.6
|
||||
model: mlx-community/Qwen3.6-35B-A3B-6bit
|
||||
estimated_memory_gb: 40
|
||||
reasoning_parser: qwen3
|
||||
|
||||
- name: gemma
|
||||
model: mlx-community/gemma-4-31b-it-8bit
|
||||
estimated_memory_gb: 40
|
||||
reasoning_parser: gemma4
|
||||
|
||||
- name: MiniMax-M3
|
||||
model: pipenetwork/MiniMax-M3-MLX-mixed-3_6bit
|
||||
estimated_memory_gb: 200
|
||||
@@ -1,12 +0,0 @@
|
||||
{
|
||||
"name": "architecture",
|
||||
"module": "index.ts",
|
||||
"type": "module",
|
||||
"private": true,
|
||||
"devDependencies": {
|
||||
"@types/bun": "latest"
|
||||
},
|
||||
"peerDependencies": {
|
||||
"typescript": "^5"
|
||||
}
|
||||
}
|
||||
@@ -1,35 +0,0 @@
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"provider": {
|
||||
"odin": {
|
||||
"npm": "@ai-sdk/anthropic",
|
||||
"name": "Odin",
|
||||
"options": {
|
||||
"baseURL": "http://192.168.2.49:12000/v1",
|
||||
"apiKey": "changeme"
|
||||
},
|
||||
"models": {
|
||||
"Qwen-Coder-Next": {
|
||||
"name": "Qwen-Coder-Next",
|
||||
"tool_call": true,
|
||||
"options": {
|
||||
"temperature": 1.0,
|
||||
"top_p": 0.95
|
||||
}
|
||||
},
|
||||
"Qwen3.6": {
|
||||
"name": "Qwen3.6",
|
||||
"tool_call": true
|
||||
},
|
||||
"gemma": {
|
||||
"name": "gemma",
|
||||
"tool_call": true
|
||||
},
|
||||
"MiniMax-M3": {
|
||||
"name": "MiniMax-M3",
|
||||
"tool_call": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Executable
+50
@@ -0,0 +1,50 @@
|
||||
#!/bin/bash
|
||||
# Pre-commit validation script for Claude Code
|
||||
# Validates YAML, checks for secrets, validates K8s manifests
|
||||
|
||||
set -e
|
||||
|
||||
# Get staged files
|
||||
STAGED_FILES=$(git diff --cached --name-only 2>/dev/null || echo "")
|
||||
|
||||
if [ -z "$STAGED_FILES" ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Check for potential secrets in staged files
|
||||
echo "Checking for potential secrets..."
|
||||
SECRET_PATTERN='(password|secret|token|api_key|apikey|private_key).*[=:].{20,}'
|
||||
if echo "$STAGED_FILES" | xargs grep -l -iE "$SECRET_PATTERN" 2>/dev/null | grep -v '.sops.yaml' | grep -v 'secret.*\.enc\.yaml'; then
|
||||
echo "WARNING: Potential secrets detected in staged files (excluding SOPS-encrypted files)"
|
||||
echo "Please verify these are encrypted or not actual secrets."
|
||||
fi
|
||||
|
||||
# Validate YAML syntax
|
||||
echo "Validating YAML syntax..."
|
||||
for file in $(echo "$STAGED_FILES" | grep -E '\.ya?ml$'); do
|
||||
if [ -f "$file" ]; then
|
||||
if ! python3 -c "import yaml; yaml.safe_load(open('$file'))" 2>/dev/null; then
|
||||
echo "ERROR: Invalid YAML syntax: $file"
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
done
|
||||
|
||||
# Validate Kubernetes manifests (if kubectl available)
|
||||
if command -v kubectl &>/dev/null; then
|
||||
echo "Validating Kubernetes manifests..."
|
||||
for file in $(echo "$STAGED_FILES" | grep -E '\.ya?ml$'); do
|
||||
if [ -f "$file" ] && grep -q "^kind:" "$file" 2>/dev/null; then
|
||||
# Skip SOPS-encrypted files and kustomization files
|
||||
if echo "$file" | grep -qE '(\.sops\.yaml|\.enc\.yaml|kustomization\.yaml)$'; then
|
||||
continue
|
||||
fi
|
||||
if ! kubectl apply --dry-run=client -f "$file" 2>/dev/null; then
|
||||
echo "WARNING: Kubernetes validation failed: $file (may be expected for partial manifests)"
|
||||
fi
|
||||
fi
|
||||
done
|
||||
fi
|
||||
|
||||
echo "Pre-commit checks passed."
|
||||
exit 0
|
||||
+9
-10
@@ -1,4 +1,5 @@
|
||||
{
|
||||
"model": "opus",
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Bash(git:*)",
|
||||
@@ -9,6 +10,13 @@
|
||||
"WebSearch"
|
||||
]
|
||||
},
|
||||
"statusLine": {
|
||||
"type": "command",
|
||||
"command": "input=$(cat); current_dir=$(echo \"$input\" | jq -r '.workspace.current_dir'); model=$(echo \"$input\" | jq -r '.model.display_name'); style=$(echo \"$input\" | jq -r '.output_style.name'); git_info=\"\"; if [ -d \"$current_dir/.git\" ]; then cd \"$current_dir\" && branch=$(git branch --show-current 2>/dev/null) && status=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ') && git_info=\" [$branch$([ \"$status\" != \"0\" ] && echo \"*\")]\"; fi; printf \"\\033[2m$(whoami)@$(hostname -s) $(basename \"$current_dir\")$git_info | $model ($style)\\033[0m\""
|
||||
},
|
||||
"enabledPlugins": {
|
||||
"gopls-lsp@claude-plugins-official": true
|
||||
},
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
@@ -22,14 +30,5 @@
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
"statusLine": {
|
||||
"type": "command",
|
||||
"command": "input=$(cat); current_dir=$(echo \"$input\" | jq -r '.workspace.current_dir'); model=$(echo \"$input\" | jq -r '.model.display_name'); style=$(echo \"$input\" | jq -r '.output_style.name'); git_info=\"\"; if [ -d \"$current_dir/.git\" ]; then cd \"$current_dir\" && branch=$(git branch --show-current 2>/dev/null) && status=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ') && git_info=\" [$branch$([ \"$status\" != \"0\" ] && echo \"*\")]\"; fi; printf \"\\033[2m$(whoami)@$(hostname -s) $(basename \"$current_dir\")$git_info | $model ($style)\\033[0m\"",
|
||||
"padding": 0
|
||||
},
|
||||
"enabledPlugins": {
|
||||
"gopls-lsp@claude-plugins-official": true
|
||||
},
|
||||
"model": "opus"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,90 @@
|
||||
---
|
||||
name: backlog-grooming
|
||||
description: How to review and improve existing issues for clarity and actionability
|
||||
---
|
||||
|
||||
# Backlog Grooming
|
||||
|
||||
How to review and improve existing issues.
|
||||
|
||||
## Grooming Checklist
|
||||
|
||||
For each issue, verify:
|
||||
|
||||
### 1. Title Clarity
|
||||
- [ ] Starts with action verb
|
||||
- [ ] Specific and descriptive
|
||||
- [ ] Understandable without reading description
|
||||
|
||||
### 2. Description Quality
|
||||
- [ ] Has clear summary
|
||||
- [ ] Explains the "why"
|
||||
- [ ] Provides enough context
|
||||
|
||||
### 3. Acceptance Criteria
|
||||
- [ ] Criteria exist
|
||||
- [ ] Each criterion is testable
|
||||
- [ ] Criteria are specific (not vague)
|
||||
- [ ] Complete set (nothing missing)
|
||||
|
||||
### 4. Scope
|
||||
- [ ] Not too broad (can complete in reasonable time)
|
||||
- [ ] Not too narrow (meaningful unit of work)
|
||||
- [ ] Clear boundaries (what's included/excluded)
|
||||
|
||||
### 5. Dependencies
|
||||
- [ ] Dependencies identified
|
||||
- [ ] No circular dependencies
|
||||
- [ ] Blocking issues are tracked
|
||||
|
||||
### 6. Labels
|
||||
- [ ] Type label (bug/feature/etc)
|
||||
- [ ] Priority if applicable
|
||||
- [ ] Component labels if applicable
|
||||
|
||||
## Common Issues to Fix
|
||||
|
||||
### Vague Titles
|
||||
- Bad: "Fix bug"
|
||||
- Good: "Fix login form validation on empty email"
|
||||
|
||||
### Missing Acceptance Criteria
|
||||
Add specific, testable criteria based on the description.
|
||||
|
||||
### Scope Creep
|
||||
If issue covers multiple features, split into separate issues.
|
||||
|
||||
### Stale Issues
|
||||
- Close if no longer relevant
|
||||
- Update if context has changed
|
||||
- Add "needs-triage" label if unclear
|
||||
|
||||
### Duplicate Issues
|
||||
- Close duplicate with reference to original
|
||||
- Merge relevant details into original
|
||||
|
||||
## Grooming Workflow
|
||||
|
||||
Use the gitea skill for issue operations.
|
||||
|
||||
1. **Fetch open issues**
|
||||
2. **Review each issue** against checklist
|
||||
3. **Improve or flag** issues that need work
|
||||
4. **Update issue** with improvements
|
||||
5. **Add labels** as needed
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
When grooming, consider:
|
||||
- "Could a developer start work on this today?"
|
||||
- "How will we know when this is done?"
|
||||
- "Is the scope clear?"
|
||||
- "Are dependencies explicit?"
|
||||
|
||||
## Batch Grooming
|
||||
|
||||
When grooming multiple issues:
|
||||
1. List all open issues
|
||||
2. Categorize by quality (ready, needs-work, stale)
|
||||
3. Focus on "needs-work" issues
|
||||
4. Present summary of changes made
|
||||
@@ -0,0 +1,204 @@
|
||||
---
|
||||
name: code-review
|
||||
description: Guidelines and templates for reviewing code changes in pull requests
|
||||
---
|
||||
|
||||
# Code Review
|
||||
|
||||
Guidelines for reviewing code changes in pull requests.
|
||||
|
||||
## Review Categories
|
||||
|
||||
### Code Quality
|
||||
|
||||
Look for:
|
||||
- **Readability**: Clear naming, logical structure, appropriate comments
|
||||
- **Maintainability**: Easy to modify, follows DRY, single responsibility
|
||||
- **Complexity**: Avoid deep nesting, overly long functions, complex conditionals
|
||||
- **Dead code**: Unused variables, unreachable code, commented-out blocks
|
||||
|
||||
Questions to ask:
|
||||
- Can someone unfamiliar with this code understand it quickly?
|
||||
- Would I be comfortable maintaining this code?
|
||||
- Does this follow existing patterns in the codebase?
|
||||
|
||||
### Potential Bugs
|
||||
|
||||
Look for:
|
||||
- **Edge cases**: Empty arrays, null values, boundary conditions
|
||||
- **Logic errors**: Off-by-one, incorrect operators, inverted conditions
|
||||
- **Race conditions**: Async operations, shared state
|
||||
- **Resource leaks**: Unclosed connections, missing cleanup
|
||||
- **Error handling**: Unhandled exceptions, silent failures
|
||||
|
||||
Questions to ask:
|
||||
- What happens with unexpected input?
|
||||
- Are all error paths handled appropriately?
|
||||
- Could concurrent execution cause issues?
|
||||
|
||||
### Security Concerns
|
||||
|
||||
Look for:
|
||||
- **Injection**: SQL, command, XSS vulnerabilities
|
||||
- **Authentication**: Bypasses, weak validation
|
||||
- **Authorization**: Missing permission checks
|
||||
- **Data exposure**: Logging secrets, exposing internals
|
||||
- **Dependencies**: Known vulnerabilities in imports
|
||||
|
||||
Questions to ask:
|
||||
- Could an attacker exploit this?
|
||||
- Is user input properly validated and sanitized?
|
||||
- Are secrets properly protected?
|
||||
|
||||
### Style & Consistency
|
||||
|
||||
Look for:
|
||||
- **Naming conventions**: Match existing codebase style
|
||||
- **Formatting**: Consistent indentation, spacing
|
||||
- **File organization**: Logical grouping, appropriate location
|
||||
- **Import order**: Following project conventions
|
||||
|
||||
Note: Style issues are lower priority than functional concerns.
|
||||
|
||||
### Test Coverage
|
||||
|
||||
Look for:
|
||||
- **Missing tests**: New functionality without tests
|
||||
- **Edge cases**: Boundary conditions not tested
|
||||
- **Error paths**: Exception handling not verified
|
||||
- **Integration**: Component interactions not covered
|
||||
|
||||
Questions to ask:
|
||||
- Would these tests catch a regression?
|
||||
- Are the assertions meaningful?
|
||||
- Do tests cover the acceptance criteria?
|
||||
|
||||
## Review Process
|
||||
|
||||
1. **Understand context**: Read PR description and linked issues
|
||||
2. **High-level scan**: Understand overall structure and approach
|
||||
3. **Detailed review**: Go through changes file by file
|
||||
4. **Consider impact**: Think about side effects and dependencies
|
||||
5. **Provide feedback**: Be constructive and specific
|
||||
|
||||
## Writing Review Comments
|
||||
|
||||
### Be Constructive
|
||||
- Explain *why* something is an issue
|
||||
- Suggest alternatives when possible
|
||||
- Distinguish between blocking issues and suggestions
|
||||
|
||||
### Be Specific
|
||||
- Reference exact lines or code blocks
|
||||
- Provide concrete examples
|
||||
- Link to relevant documentation or patterns
|
||||
|
||||
### Be Kind
|
||||
- Phrase feedback as questions when appropriate
|
||||
- Acknowledge good solutions
|
||||
- Remember there's a person receiving this feedback
|
||||
|
||||
## Example Review Comments
|
||||
|
||||
### Code Quality
|
||||
|
||||
**Good:**
|
||||
> `src/utils/parser.ts:45` - This function is doing three things: parsing, validating, and transforming. Consider splitting into `parse()`, `validate()`, and `transform()` to improve testability and make each responsibility clear.
|
||||
|
||||
**Bad:**
|
||||
> This code is messy, please clean it up.
|
||||
|
||||
### Potential Bugs
|
||||
|
||||
**Good:**
|
||||
> `src/api/users.ts:23` - `users.find()` returns `undefined` when no match is found, but line 25 accesses `user.id` without a null check. This will throw when the user doesn't exist. Consider: `const user = users.find(...); if (!user) return null;`
|
||||
|
||||
**Bad:**
|
||||
> This might crash.
|
||||
|
||||
### Security
|
||||
|
||||
**Good:**
|
||||
> `src/routes/search.ts:12` - The query parameter is interpolated directly into the SQL string, which allows SQL injection. Use parameterized queries instead: `db.query('SELECT * FROM items WHERE name = ?', [query])`
|
||||
|
||||
**Bad:**
|
||||
> Security issue here.
|
||||
|
||||
### Style
|
||||
|
||||
**Good:**
|
||||
> `src/components/Button.tsx:8` - Minor: The codebase uses `camelCase` for event handlers (e.g., `handleClick`), but this uses `on_click`. Consider renaming for consistency.
|
||||
|
||||
**Bad:**
|
||||
> Wrong naming convention.
|
||||
|
||||
### Test Coverage
|
||||
|
||||
**Good:**
|
||||
> The happy path is well tested. Consider adding a test for when `fetchUser()` rejects - the error handling in line 34 isn't currently covered.
|
||||
|
||||
**Bad:**
|
||||
> Need more tests.
|
||||
|
||||
### Positive Feedback
|
||||
|
||||
**Good:**
|
||||
> Nice use of the builder pattern here - it makes the configuration much more readable than the previous approach with multiple boolean flags.
|
||||
|
||||
## Verdict Criteria
|
||||
|
||||
### LGTM (Looks Good To Me)
|
||||
- No blocking issues
|
||||
- Code meets quality standards
|
||||
- Tests are adequate
|
||||
- Ready to merge
|
||||
|
||||
### Needs Changes
|
||||
- Minor issues that should be addressed
|
||||
- Style improvements
|
||||
- Missing tests for edge cases
|
||||
- Not blocking, but worth fixing
|
||||
|
||||
### Blocking Issues
|
||||
- Security vulnerabilities
|
||||
- Logic errors that would cause bugs
|
||||
- Missing critical functionality
|
||||
- Breaking changes without migration
|
||||
|
||||
## Review Comment Template
|
||||
|
||||
```markdown
|
||||
## AI Code Review
|
||||
|
||||
> This is an automated review generated by the code-reviewer agent.
|
||||
|
||||
### Summary
|
||||
[1-2 sentence overall assessment of the changes]
|
||||
|
||||
### Findings
|
||||
|
||||
#### Code Quality
|
||||
- [Issue with specific file:line reference and explanation]
|
||||
- [Or "Code is well-structured and readable"]
|
||||
|
||||
#### Potential Bugs
|
||||
- [Bug risk with explanation]
|
||||
- [Or "No obvious issues found"]
|
||||
|
||||
#### Security Concerns
|
||||
- [Security issue with severity]
|
||||
- [Or "No security concerns identified"]
|
||||
|
||||
#### Style Notes
|
||||
- [Style improvement suggestion]
|
||||
- [Or "Consistent with codebase conventions"]
|
||||
|
||||
#### Test Coverage
|
||||
- [Missing test scenario]
|
||||
- [Or "Tests adequately cover changes"]
|
||||
|
||||
### Verdict
|
||||
**[LGTM / Needs Changes / Blocking Issues]**
|
||||
|
||||
[Brief explanation of verdict]
|
||||
```
|
||||
@@ -0,0 +1,188 @@
|
||||
---
|
||||
name: gitea
|
||||
description: Gitea CLI (tea) for issues, pull requests, and repository management
|
||||
---
|
||||
|
||||
# Gitea CLI (tea)
|
||||
|
||||
Command-line interface for interacting with Gitea repositories.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
brew install tea
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
The `tea` CLI authenticates via `tea logins add`. Credentials are stored locally by tea.
|
||||
|
||||
```bash
|
||||
tea logins add # Interactive login
|
||||
tea logins add --url <url> --token <token> --name <name> # Non-interactive
|
||||
tea logins list # Show configured logins
|
||||
tea logins default <name> # Set default login
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Config is stored at `~/Library/Application Support/tea/config.yml` (macOS).
|
||||
|
||||
To avoid needing `--login` on every command, set defaults:
|
||||
|
||||
```yaml
|
||||
preferences:
|
||||
editor: false
|
||||
flag_defaults:
|
||||
remote: origin
|
||||
login: git.flowmade.one
|
||||
```
|
||||
|
||||
## Repository Detection
|
||||
|
||||
`tea` automatically detects the repository from git remotes when run inside a git repository. Use `--remote <name>` to specify which remote to use.
|
||||
|
||||
## Common Commands
|
||||
|
||||
### Issues
|
||||
|
||||
```bash
|
||||
# List issues
|
||||
tea issues # Open issues (default)
|
||||
tea issues --state all # All issues
|
||||
tea issues --state closed # Closed issues
|
||||
|
||||
# View issue details
|
||||
tea issues <number> # Full issue details
|
||||
tea issues <number> --comments # Include comments
|
||||
|
||||
# Create issue
|
||||
tea issues create --title "<title>" --description "<body>"
|
||||
tea issues create -t "<title>" -d "<body>"
|
||||
|
||||
# Edit issue
|
||||
tea issues edit <number> --title "<new-title>"
|
||||
tea issues edit <number> --description "<new-body>"
|
||||
|
||||
# Close/reopen
|
||||
tea issues close <number>
|
||||
tea issues reopen <number>
|
||||
|
||||
# Labels
|
||||
tea issues edit <number> --labels "bug,help wanted"
|
||||
```
|
||||
|
||||
### Pull Requests
|
||||
|
||||
```bash
|
||||
# List PRs
|
||||
tea pulls # Open PRs (default)
|
||||
tea pulls --state all # All PRs
|
||||
tea pulls --state closed # Closed/merged PRs
|
||||
|
||||
# View PR
|
||||
tea pulls <number> # PR details
|
||||
tea pulls <number> --comments # Include comments
|
||||
tea pulls <number> -f diff # PR diff
|
||||
|
||||
# Create PR
|
||||
tea pulls create --title "<title>" --description "<body>"
|
||||
tea pulls create -t "<title>" -d "<body>"
|
||||
tea pulls create -t "<title>" -d "Closes #<issue>"
|
||||
tea pulls create --head <branch> --base main -t "<title>"
|
||||
|
||||
# Checkout PR locally
|
||||
tea pulls checkout <number>
|
||||
|
||||
# Review/Approve
|
||||
tea pulls approve <number> # Approve PR (LGTM)
|
||||
tea pulls reject <number> # Request changes
|
||||
tea pulls review <number> # Interactive review
|
||||
|
||||
# Merge
|
||||
tea pulls merge <number> # Default merge
|
||||
tea pulls merge <number> --style squash # Squash commits
|
||||
tea pulls merge <number> --style rebase # Rebase commits
|
||||
tea pulls merge <number> --style rebase-merge # Rebase then merge
|
||||
|
||||
# Clean up after merge
|
||||
tea pulls clean <number> # Delete local & remote branch
|
||||
```
|
||||
|
||||
### Repository
|
||||
|
||||
```bash
|
||||
tea repos # List repos
|
||||
tea repos <owner>/<repo> # Repository info
|
||||
tea clone <owner>/<repo> # Clone repository
|
||||
```
|
||||
|
||||
### Comments
|
||||
|
||||
```bash
|
||||
# Add comment to issue or PR
|
||||
tea comment <number> "<comment body>"
|
||||
tea comment 3 "LGTM, ready to merge"
|
||||
|
||||
# Multiline comments (use quoted strings with literal newlines)
|
||||
tea comment 3 "## Review Summary
|
||||
|
||||
- Code looks good
|
||||
- Tests pass"
|
||||
```
|
||||
|
||||
> **Warning**: Do not use heredoc syntax `$(cat <<'EOF'...EOF)` with `tea comment` - it causes the command to be backgrounded and fail silently.
|
||||
|
||||
### Notifications
|
||||
|
||||
```bash
|
||||
tea notifications # List notifications
|
||||
tea notifications --mine # Only participating
|
||||
```
|
||||
|
||||
## Output Formatting
|
||||
|
||||
Most commands support `--output` or `-o` flag:
|
||||
- `-o simple` - Plain text
|
||||
- `-o table` - Tabular format (default)
|
||||
- `-o json` - Machine-readable JSON
|
||||
- `-o yaml` - YAML format
|
||||
- `-o csv` - CSV format
|
||||
|
||||
## Specifying Remote/Login
|
||||
|
||||
```bash
|
||||
tea issues --remote gitea # Use specific git remote
|
||||
tea issues --login myserver # Use specific login
|
||||
tea issues -r owner/repo # Specify repo directly
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
- **View single issue**: Use `tea issues <number>` (NOT `tea issues view <number>` - there is no `view` subcommand)
|
||||
- **PR description flag**: Use `--description` or `-d` (NOT `--body` like gh CLI)
|
||||
- Always verify you're in the correct repository before running commands
|
||||
- Use `tea issues` to find issue numbers before viewing/editing
|
||||
- Reference issues in PR bodies with `Closes #N` for auto-linking
|
||||
- Use `--remote gitea` when you have multiple remotes (e.g., origin + gitea)
|
||||
- The `tea pulls checkout` command is handy for reviewing PRs locally
|
||||
|
||||
## Actions / CI
|
||||
|
||||
```bash
|
||||
# List workflow runs
|
||||
tea actions runs # List all workflow runs
|
||||
tea actions runs -o json # JSON output for parsing
|
||||
|
||||
# List jobs for a run
|
||||
tea actions jobs <run-id> # Show jobs for a specific run
|
||||
tea actions jobs <run-id> -o json # JSON output
|
||||
|
||||
# Get job logs
|
||||
tea actions logs <job-id> # Display logs for a job
|
||||
|
||||
# Full workflow: find failed job logs
|
||||
tea actions runs # Find the run ID
|
||||
tea actions jobs <run-id> # Find the job ID
|
||||
tea actions logs <job-id> # View the logs
|
||||
```
|
||||
@@ -0,0 +1,110 @@
|
||||
---
|
||||
name: issue-writing
|
||||
description: How to write clear, actionable issues with proper structure and acceptance criteria
|
||||
---
|
||||
|
||||
# Issue Writing
|
||||
|
||||
How to write clear, actionable issues.
|
||||
|
||||
## Issue Structure
|
||||
|
||||
### Title
|
||||
- Start with action verb: "Add", "Fix", "Update", "Remove", "Refactor"
|
||||
- Be specific: "Add user authentication" not "Auth stuff"
|
||||
- Keep under 60 characters when possible
|
||||
|
||||
### Description
|
||||
|
||||
```markdown
|
||||
## Summary
|
||||
One paragraph explaining what and why.
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] Specific, testable requirement
|
||||
- [ ] Another requirement
|
||||
- [ ] User can verify this works
|
||||
|
||||
## Context
|
||||
Additional background, links, or references.
|
||||
|
||||
## Technical Notes (optional)
|
||||
Implementation hints or constraints.
|
||||
```
|
||||
|
||||
## Writing Acceptance Criteria
|
||||
|
||||
Good criteria are:
|
||||
- **Specific**: "User sees error message" not "Handle errors"
|
||||
- **Testable**: Can verify pass/fail
|
||||
- **User-focused**: What the user experiences
|
||||
- **Independent**: Each stands alone
|
||||
|
||||
Examples:
|
||||
```markdown
|
||||
- [ ] Login form validates email format before submission
|
||||
- [ ] Invalid credentials show "Invalid email or password" message
|
||||
- [ ] Successful login redirects to dashboard
|
||||
- [ ] Session persists across browser refresh
|
||||
```
|
||||
|
||||
## Issue Types
|
||||
|
||||
### Bug Report
|
||||
```markdown
|
||||
## Summary
|
||||
Description of the bug.
|
||||
|
||||
## Steps to Reproduce
|
||||
1. Go to...
|
||||
2. Click...
|
||||
3. Observe...
|
||||
|
||||
## Expected Behavior
|
||||
What should happen.
|
||||
|
||||
## Actual Behavior
|
||||
What happens instead.
|
||||
|
||||
## Environment
|
||||
- Browser/OS/Version
|
||||
```
|
||||
|
||||
### Feature Request
|
||||
```markdown
|
||||
## Summary
|
||||
What feature and why it's valuable.
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] ...
|
||||
|
||||
## User Story (optional)
|
||||
As a [role], I want [capability] so that [benefit].
|
||||
```
|
||||
|
||||
### Technical Task
|
||||
```markdown
|
||||
## Summary
|
||||
What technical work needs to be done.
|
||||
|
||||
## Scope
|
||||
- Include: ...
|
||||
- Exclude: ...
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] ...
|
||||
```
|
||||
|
||||
## Labels
|
||||
|
||||
Use labels to categorize:
|
||||
- `bug`, `feature`, `enhancement`, `refactor`
|
||||
- `priority/high`, `priority/low`
|
||||
- Component labels specific to project
|
||||
|
||||
## Dependencies
|
||||
|
||||
Reference related issues:
|
||||
- "Depends on #N" - Must complete first
|
||||
- "Blocks #N" - This blocks another
|
||||
- "Related to #N" - Informational link
|
||||
@@ -0,0 +1,113 @@
|
||||
---
|
||||
name: roadmap-planning
|
||||
description: How to plan features and create issues for implementation
|
||||
---
|
||||
|
||||
# Roadmap Planning
|
||||
|
||||
How to plan features and create issues for implementation.
|
||||
|
||||
## Planning Process
|
||||
|
||||
### 1. Understand the Goal
|
||||
- What capability or improvement is needed?
|
||||
- Who benefits and how?
|
||||
- What's the success criteria?
|
||||
|
||||
### 2. Break Down the Work
|
||||
- Identify distinct components
|
||||
- Define boundaries between pieces
|
||||
- Aim for issues that are:
|
||||
- Completable in 1-3 focused sessions
|
||||
- Independently testable
|
||||
- Clear in scope
|
||||
|
||||
### 3. Identify Dependencies
|
||||
- Which pieces must come first?
|
||||
- What can be parallelized?
|
||||
- Are there external blockers?
|
||||
|
||||
### 4. Create Issues
|
||||
- Follow issue-writing patterns
|
||||
- Reference dependencies explicitly
|
||||
- Use consistent labeling
|
||||
|
||||
## Breaking Down Features
|
||||
|
||||
### By Layer
|
||||
```
|
||||
Feature: User Authentication
|
||||
├── Data layer: User model, password hashing
|
||||
├── API layer: Login/logout endpoints
|
||||
├── UI layer: Login form, session display
|
||||
└── Integration: Connect all layers
|
||||
```
|
||||
|
||||
### By User Story
|
||||
```
|
||||
Feature: Shopping Cart
|
||||
├── Add item to cart
|
||||
├── View cart contents
|
||||
├── Update quantities
|
||||
├── Remove items
|
||||
└── Proceed to checkout
|
||||
```
|
||||
|
||||
### By Technical Component
|
||||
```
|
||||
Feature: Real-time Updates
|
||||
├── WebSocket server setup
|
||||
├── Client connection handling
|
||||
├── Message protocol
|
||||
├── Reconnection logic
|
||||
└── Integration tests
|
||||
```
|
||||
|
||||
## Issue Ordering
|
||||
|
||||
### Dependency Chain
|
||||
Create issues in implementation order:
|
||||
1. Foundation (models, types, interfaces)
|
||||
2. Core logic (business rules)
|
||||
3. Integration (connecting pieces)
|
||||
4. Polish (error handling, edge cases)
|
||||
|
||||
### Reference Pattern
|
||||
In issue descriptions:
|
||||
```markdown
|
||||
## Dependencies
|
||||
- Depends on #12 (user model)
|
||||
- Depends on #13 (API setup)
|
||||
```
|
||||
|
||||
## Creating Issues
|
||||
|
||||
Use the gitea skill for issue operations.
|
||||
|
||||
### Single Issue
|
||||
Create with a descriptive title and structured body:
|
||||
- Summary section
|
||||
- Acceptance criteria (testable checkboxes)
|
||||
- Dependencies section referencing blocking issues
|
||||
|
||||
### Batch Creation
|
||||
When creating multiple related issues:
|
||||
1. Plan all issues first
|
||||
2. Create in dependency order
|
||||
3. Update earlier issues with forward references
|
||||
|
||||
## Roadmap View
|
||||
|
||||
To see current roadmap:
|
||||
1. List open issues using the gitea skill
|
||||
2. Group by labels/milestones
|
||||
3. Identify blocked vs ready issues
|
||||
4. Prioritize based on dependencies and value
|
||||
|
||||
## Planning Questions
|
||||
|
||||
Before creating issues, answer:
|
||||
- "What's the minimum viable version?"
|
||||
- "What can we defer?"
|
||||
- "What are the riskiest parts?"
|
||||
- "How will we validate each piece?"
|
||||
@@ -1,29 +0,0 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
// Environment setup & latest features
|
||||
"lib": ["ESNext"],
|
||||
"target": "ESNext",
|
||||
"module": "Preserve",
|
||||
"moduleDetection": "force",
|
||||
"jsx": "react-jsx",
|
||||
"allowJs": true,
|
||||
|
||||
// Bundler mode
|
||||
"moduleResolution": "bundler",
|
||||
"allowImportingTsExtensions": true,
|
||||
"verbatimModuleSyntax": true,
|
||||
"noEmit": true,
|
||||
|
||||
// Best practices
|
||||
"strict": true,
|
||||
"skipLibCheck": true,
|
||||
"noFallthroughCasesInSwitch": true,
|
||||
"noUncheckedIndexedAccess": true,
|
||||
"noImplicitOverride": true,
|
||||
|
||||
// Some stricter flags (disabled by default)
|
||||
"noUnusedLocals": false,
|
||||
"noUnusedParameters": false,
|
||||
"noPropertyAccessFromIndexSignature": false
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user