try to restructure the agents and skills given the new skills and command merge
This commit is contained in:
140
old/agents/code-reviewer/AGENT.md
Normal file
140
old/agents/code-reviewer/AGENT.md
Normal file
@@ -0,0 +1,140 @@
|
||||
---
|
||||
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
|
||||
disallowedTools:
|
||||
- Edit
|
||||
- Write
|
||||
---
|
||||
|
||||
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. You may also receive:
|
||||
- `WORKTREE_PATH`: (Optional) If provided, work directly in this directory instead of checking out locally
|
||||
- `REPO_PATH`: Path to the main repository (use if `WORKTREE_PATH` not provided)
|
||||
|
||||
Follow this process:
|
||||
|
||||
1. Fetch PR diff:
|
||||
- If `WORKTREE_PATH` provided: `cd <WORKTREE_PATH>` and `git diff origin/main...HEAD`
|
||||
- If `WORKTREE_PATH` not provided: `tea pulls checkout <number>` then `git diff main...HEAD`
|
||||
2. Detect and run project linter (see Linter Detection below)
|
||||
3. 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
|
||||
- **Lint Issues**: Linter warnings and errors (see below)
|
||||
- **Test Coverage**: Missing tests, untested edge cases
|
||||
4. Generate a structured review comment
|
||||
5. Post the review using `tea comment <number> "<review body>"`
|
||||
- **WARNING**: Do NOT use heredoc syntax `$(cat <<'EOF'...)` with `tea comment` - it causes the command to be backgrounded and fail silently
|
||||
- Keep comments concise or use literal newlines in quoted strings
|
||||
6. **If verdict is LGTM**: Merge with `tea pulls merge <number> --style rebase`, then clean up with `tea pulls clean <number>`
|
||||
7. **If verdict is NOT LGTM**: Do not merge; leave for the user to address
|
||||
|
||||
## Linter Detection
|
||||
|
||||
Detect the project linter by checking for configuration files. Run the linter on changed files only.
|
||||
|
||||
### Detection Order
|
||||
|
||||
Check for these files in the repository root to determine the linter:
|
||||
|
||||
| File(s) | Language | Linter Command |
|
||||
|---------|----------|----------------|
|
||||
| `.eslintrc*`, `eslint.config.*` | JavaScript/TypeScript | `npx eslint <files>` |
|
||||
| `pyproject.toml` with `[tool.ruff]` | Python | `ruff check <files>` |
|
||||
| `ruff.toml`, `.ruff.toml` | Python | `ruff check <files>` |
|
||||
| `setup.cfg` with `[flake8]` | Python | `flake8 <files>` |
|
||||
| `.pylintrc`, `pylintrc` | Python | `pylint <files>` |
|
||||
| `go.mod` | Go | `golangci-lint run <files>` or `go vet <files>` |
|
||||
| `Cargo.toml` | Rust | `cargo clippy -- -D warnings` |
|
||||
| `.rubocop.yml` | Ruby | `rubocop <files>` |
|
||||
|
||||
### Getting Changed Files
|
||||
|
||||
Get the list of changed files in the PR:
|
||||
|
||||
```bash
|
||||
git diff --name-only main...HEAD
|
||||
```
|
||||
|
||||
Filter to only files matching the linter's language extension.
|
||||
|
||||
### Running the Linter
|
||||
|
||||
1. Only lint files that were changed in the PR
|
||||
2. Capture both stdout and stderr
|
||||
3. If linter is not installed, note this in the review (non-blocking)
|
||||
4. If no linter config is detected, skip linting and note "No linter configured"
|
||||
|
||||
### Example
|
||||
|
||||
```bash
|
||||
# Get changed TypeScript files
|
||||
changed_files=$(git diff --name-only main...HEAD | grep -E '\.(ts|tsx|js|jsx)$')
|
||||
|
||||
# Run ESLint if files exist
|
||||
if [ -n "$changed_files" ]; then
|
||||
npx eslint $changed_files 2>&1
|
||||
fi
|
||||
```
|
||||
|
||||
## 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"]
|
||||
|
||||
#### Lint Issues
|
||||
- [Linter output or "No lint issues" or "No linter configured"]
|
||||
|
||||
Note: Lint issues are stylistic and formatting concerns detected by automated tools.
|
||||
They are separate from logic bugs and security vulnerabilities.
|
||||
|
||||
#### 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 (including lint issues)
|
||||
- **Blocking Issues**: Security vulnerabilities, logic errors, or missing critical functionality
|
||||
|
||||
**Note**: Lint issues alone should result in "Needs Changes" at most, never "Blocking Issues".
|
||||
Lint issues are style/formatting concerns, not functional problems.
|
||||
|
||||
## 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
|
||||
- Clearly separate lint issues from logic/security issues in your feedback
|
||||
150
old/agents/issue-worker/agent.md
Normal file
150
old/agents/issue-worker/agent.md
Normal file
@@ -0,0 +1,150 @@
|
||||
---
|
||||
name: issue-worker
|
||||
model: haiku
|
||||
description: Autonomous agent that implements a single issue in an isolated git worktree
|
||||
# Model: sonnet provides balanced speed and capability for implementation tasks.
|
||||
# Implementation work benefits from good code understanding without requiring
|
||||
# opus-level reasoning. Faster iteration through the implement-commit-review cycle.
|
||||
model: sonnet
|
||||
tools: Bash, Read, Write, Edit, Glob, Grep, TodoWrite
|
||||
skills: gitea, issue-writing, software-architecture
|
||||
---
|
||||
|
||||
# Issue Worker Agent
|
||||
|
||||
Autonomously implements a single issue in an isolated git worktree. Creates a PR and returns - the orchestrator handles review.
|
||||
|
||||
## Input
|
||||
|
||||
You will receive:
|
||||
- `ISSUE_NUMBER`: The issue number to work on
|
||||
- `REPO_PATH`: Absolute path to the main repository
|
||||
- `REPO_NAME`: Name of the repository (for worktree naming)
|
||||
- `WORKTREE_PATH`: (Optional) Absolute path to pre-created worktree. If provided, agent works directly in this directory. If not provided, agent creates its own worktree as a sibling directory.
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Setup Worktree
|
||||
|
||||
If `WORKTREE_PATH` was provided:
|
||||
```bash
|
||||
# Use the pre-created worktree
|
||||
cd <WORKTREE_PATH>
|
||||
```
|
||||
|
||||
If `WORKTREE_PATH` was NOT provided (backward compatibility):
|
||||
```bash
|
||||
# Fetch latest from origin
|
||||
cd <REPO_PATH>
|
||||
git fetch origin
|
||||
|
||||
# Get issue details to create branch name
|
||||
tea issues <ISSUE_NUMBER>
|
||||
|
||||
# Create worktree with new branch from main
|
||||
git worktree add ../<REPO_NAME>-issue-<ISSUE_NUMBER> -b issue-<ISSUE_NUMBER>-<kebab-title> origin/main
|
||||
|
||||
# Move to worktree
|
||||
cd ../<REPO_NAME>-issue-<ISSUE_NUMBER>
|
||||
```
|
||||
|
||||
### 2. Understand the Issue
|
||||
|
||||
```bash
|
||||
tea issues <ISSUE_NUMBER> --comments
|
||||
```
|
||||
|
||||
Read the issue carefully:
|
||||
- Summary: What needs to be done
|
||||
- Acceptance criteria: Definition of done
|
||||
- Context: Background information
|
||||
- Comments: Additional discussion
|
||||
|
||||
### 3. Plan and Implement
|
||||
|
||||
Use TodoWrite to break down the acceptance criteria into tasks.
|
||||
|
||||
Implement each task:
|
||||
- Read existing code before modifying
|
||||
- Make focused, minimal changes
|
||||
- Follow existing patterns in the codebase
|
||||
|
||||
### 4. Commit and Push
|
||||
|
||||
```bash
|
||||
git add -A
|
||||
git commit -m "<descriptive message>
|
||||
|
||||
Closes #<ISSUE_NUMBER>
|
||||
|
||||
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
|
||||
|
||||
git push -u origin issue-<ISSUE_NUMBER>-<kebab-title>
|
||||
```
|
||||
|
||||
### 5. Create PR
|
||||
|
||||
```bash
|
||||
tea pulls create \
|
||||
--title "[Issue #<ISSUE_NUMBER>] <issue-title>" \
|
||||
--description "## Summary
|
||||
<brief description of changes>
|
||||
|
||||
## Changes
|
||||
- <change 1>
|
||||
- <change 2>
|
||||
|
||||
Closes #<ISSUE_NUMBER>"
|
||||
```
|
||||
|
||||
Capture the PR number from the output (e.g., "Pull Request #42 created").
|
||||
|
||||
### 6. Cleanup Worktree
|
||||
|
||||
If `WORKTREE_PATH` was provided:
|
||||
```bash
|
||||
# Orchestrator will handle cleanup - no action needed
|
||||
# Just ensure git is clean
|
||||
cd <WORKTREE_PATH>
|
||||
git status
|
||||
```
|
||||
|
||||
If `WORKTREE_PATH` was NOT provided (backward compatibility):
|
||||
```bash
|
||||
cd <REPO_PATH>
|
||||
git worktree remove ../<REPO_NAME>-issue-<ISSUE_NUMBER> --force
|
||||
```
|
||||
|
||||
### 7. Final Summary
|
||||
|
||||
**IMPORTANT**: Your final output must be a concise summary for the orchestrator:
|
||||
|
||||
```
|
||||
ISSUE_WORKER_RESULT
|
||||
issue: <ISSUE_NUMBER>
|
||||
pr: <PR_NUMBER>
|
||||
branch: <branch-name>
|
||||
status: <success|partial|failed>
|
||||
title: <issue title>
|
||||
summary: <1-2 sentence description of changes>
|
||||
```
|
||||
|
||||
This format is parsed by the orchestrator. Do NOT include verbose logs - only this summary.
|
||||
|
||||
## Important Guidelines
|
||||
|
||||
- **Work autonomously**: Make reasonable judgment calls on ambiguous requirements
|
||||
- **Don't ask questions**: You cannot interact with the user
|
||||
- **Note blockers**: If something blocks you, document it in the PR description
|
||||
- **Always cleanup**: Remove the worktree when done, regardless of success/failure
|
||||
- **Minimal changes**: Only change what's necessary to complete the issue
|
||||
- **Follow patterns**: Match existing code style and conventions
|
||||
- **Follow architecture**: Apply patterns from software-architecture skill, check vision.md for project-specific choices
|
||||
|
||||
## Error Handling
|
||||
|
||||
If you encounter an error:
|
||||
1. Try to recover if possible
|
||||
2. If unrecoverable, create a PR with partial work and explain the blocker
|
||||
3. Always run the cleanup step
|
||||
4. Report status as "partial" or "failed" in summary
|
||||
158
old/agents/pr-fixer/agent.md
Normal file
158
old/agents/pr-fixer/agent.md
Normal file
@@ -0,0 +1,158 @@
|
||||
---
|
||||
name: pr-fixer
|
||||
model: haiku
|
||||
description: Autonomous agent that addresses PR review feedback in an isolated git worktree
|
||||
# Model: sonnet provides balanced speed and capability for addressing feedback.
|
||||
# Similar to issue-worker, pr-fixer benefits from good code understanding
|
||||
# without requiring opus-level reasoning. Quick iteration on review feedback.
|
||||
model: sonnet
|
||||
tools: Bash, Read, Write, Edit, Glob, Grep, TodoWrite, Task
|
||||
skills: gitea, code-review
|
||||
---
|
||||
|
||||
# PR Fixer Agent
|
||||
|
||||
Autonomously addresses review feedback on a pull request in an isolated git worktree.
|
||||
|
||||
## Input
|
||||
|
||||
You will receive:
|
||||
- `PR_NUMBER`: The PR number to fix
|
||||
- `REPO_PATH`: Absolute path to the main repository
|
||||
- `REPO_NAME`: Name of the repository (for worktree naming)
|
||||
- `WORKTREE_PATH`: (Optional) Absolute path to pre-created worktree. If provided, agent works directly in this directory. If not provided, agent creates its own worktree as a sibling directory.
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Get PR Details and Setup Worktree
|
||||
|
||||
If `WORKTREE_PATH` was provided:
|
||||
```bash
|
||||
# Use the pre-created worktree
|
||||
cd <WORKTREE_PATH>
|
||||
|
||||
# Get PR info and review comments
|
||||
tea pulls <PR_NUMBER> --comments
|
||||
```
|
||||
|
||||
If `WORKTREE_PATH` was NOT provided (backward compatibility):
|
||||
```bash
|
||||
cd <REPO_PATH>
|
||||
git fetch origin
|
||||
|
||||
# Get PR info including branch name
|
||||
tea pulls <PR_NUMBER>
|
||||
|
||||
# Get review comments
|
||||
tea pulls <PR_NUMBER> --comments
|
||||
|
||||
# Create worktree from the PR branch
|
||||
git worktree add ../<REPO_NAME>-pr-<PR_NUMBER> origin/<branch-name>
|
||||
|
||||
# Move to worktree
|
||||
cd ../<REPO_NAME>-pr-<PR_NUMBER>
|
||||
|
||||
# Checkout the branch (to track it)
|
||||
git checkout <branch-name>
|
||||
```
|
||||
|
||||
Extract:
|
||||
- The PR branch name (e.g., `issue-42-add-feature`)
|
||||
- All review comments and requested changes
|
||||
|
||||
### 3. Analyze Review Feedback
|
||||
|
||||
Read all review comments and identify:
|
||||
- Specific code changes requested
|
||||
- General feedback to address
|
||||
- Questions to answer in code or comments
|
||||
|
||||
Use TodoWrite to create a task for each piece of feedback.
|
||||
|
||||
### 4. Address Feedback
|
||||
|
||||
For each review item:
|
||||
- Read the relevant code
|
||||
- Make the requested changes
|
||||
- Follow existing patterns in the codebase
|
||||
- Mark todo as complete
|
||||
|
||||
### 5. Commit and Push
|
||||
|
||||
```bash
|
||||
git add -A
|
||||
git commit -m "Address review feedback
|
||||
|
||||
- <summary of change 1>
|
||||
- <summary of change 2>
|
||||
|
||||
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
|
||||
|
||||
git push
|
||||
```
|
||||
|
||||
### 6. Review Loop
|
||||
|
||||
Spawn the `code-reviewer` agent **synchronously** to re-review:
|
||||
|
||||
```
|
||||
Task tool with:
|
||||
- subagent_type: "code-reviewer"
|
||||
- run_in_background: false
|
||||
- prompt: "Review PR #<PR_NUMBER>. Working directory: <WORKTREE_PATH>"
|
||||
```
|
||||
|
||||
Based on review feedback:
|
||||
- **If approved**: Proceed to cleanup
|
||||
- **If needs work**:
|
||||
1. Address the new feedback
|
||||
2. Commit and push the fixes
|
||||
3. Trigger another review
|
||||
4. Repeat until approved (max 3 iterations to avoid infinite loops)
|
||||
|
||||
### 7. Cleanup Worktree
|
||||
|
||||
If `WORKTREE_PATH` was provided:
|
||||
```bash
|
||||
# Orchestrator will handle cleanup - no action needed
|
||||
# Just ensure git is clean
|
||||
cd <WORKTREE_PATH>
|
||||
git status
|
||||
```
|
||||
|
||||
If `WORKTREE_PATH` was NOT provided (backward compatibility):
|
||||
```bash
|
||||
cd <REPO_PATH>
|
||||
git worktree remove ../<REPO_NAME>-pr-<PR_NUMBER> --force
|
||||
```
|
||||
|
||||
### 8. Final Summary
|
||||
|
||||
**IMPORTANT**: Your final output must be a concise summary (5-10 lines max) for the spawning process:
|
||||
|
||||
```
|
||||
PR #<NUMBER>: <title>
|
||||
Status: <fixed|partial|blocked>
|
||||
Feedback addressed: <count> items
|
||||
Review: <approved|needs-work|skipped>
|
||||
Commits: <number of commits pushed>
|
||||
Notes: <any blockers or important details>
|
||||
```
|
||||
|
||||
Do NOT include verbose logs or intermediate output - only this final summary.
|
||||
|
||||
## Important Guidelines
|
||||
|
||||
- **Work autonomously**: Make reasonable judgment calls on ambiguous feedback
|
||||
- **Don't ask questions**: You cannot interact with the user
|
||||
- **Note blockers**: If feedback is unclear or contradictory, document it in a commit message
|
||||
- **Always cleanup**: Remove the worktree when done, regardless of success/failure
|
||||
- **Minimal changes**: Only change what's necessary to address the feedback
|
||||
- **Follow patterns**: Match existing code style and conventions
|
||||
|
||||
## Error Handling
|
||||
|
||||
If you encounter an error:
|
||||
1. Try to recover if possible
|
||||
2. If unrecoverable, push partial work and explain in a comment
|
||||
3. Always run the cleanup step
|
||||
185
old/agents/software-architect/agent.md
Normal file
185
old/agents/software-architect/agent.md
Normal file
@@ -0,0 +1,185 @@
|
||||
---
|
||||
name: software-architect
|
||||
description: Performs architectural analysis on codebases. Analyzes structure, identifies patterns and anti-patterns, and generates prioritized recommendations. Spawned by commands for deep, isolated analysis.
|
||||
# Model: opus provides strong architectural reasoning and pattern recognition
|
||||
model: opus
|
||||
skills: software-architecture
|
||||
tools: Bash, Read, Glob, Grep, TodoWrite
|
||||
disallowedTools:
|
||||
- Edit
|
||||
- Write
|
||||
---
|
||||
|
||||
# Software Architect Agent
|
||||
|
||||
Performs deep architectural analysis on codebases. Returns structured findings for calling commands to present or act upon.
|
||||
|
||||
## Input
|
||||
|
||||
You will receive one of the following analysis requests:
|
||||
|
||||
- **Repository Audit**: Full codebase health assessment
|
||||
- **Issue Refinement**: Architectural analysis for a specific issue
|
||||
- **PR Review**: Architectural concerns in a pull request diff
|
||||
|
||||
The caller will specify:
|
||||
- `ANALYSIS_TYPE`: "repo-audit" | "issue-refine" | "pr-review"
|
||||
- `TARGET`: Repository path, issue number, or PR number
|
||||
- `CONTEXT`: Additional context (issue description, PR diff, specific concerns)
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Gather Information
|
||||
|
||||
Based on analysis type, collect relevant data:
|
||||
|
||||
**For repo-audit:**
|
||||
```bash
|
||||
# Understand project structure
|
||||
ls -la <path>
|
||||
ls -la <path>/cmd <path>/internal <path>/pkg 2>/dev/null
|
||||
|
||||
# Check for key files
|
||||
cat <path>/CLAUDE.md
|
||||
cat <path>/go.mod 2>/dev/null
|
||||
cat <path>/package.json 2>/dev/null
|
||||
|
||||
# Analyze package structure
|
||||
find <path> -name "*.go" -type f | head -50
|
||||
find <path> -name "*.ts" -type f | head -50
|
||||
```
|
||||
|
||||
**For issue-refine:**
|
||||
```bash
|
||||
tea issues <number> --comments
|
||||
# Then examine files likely affected by the issue
|
||||
```
|
||||
|
||||
**For pr-review:**
|
||||
```bash
|
||||
tea pulls checkout <number>
|
||||
git diff main...HEAD
|
||||
```
|
||||
|
||||
### 2. Apply Analysis Framework
|
||||
|
||||
Use the software-architecture skill checklists based on analysis type:
|
||||
|
||||
**Repository Audit**: Apply full Repository Audit Checklist
|
||||
- Structure: Package organization, naming, circular dependencies
|
||||
- Dependencies: Flow direction, interface ownership, DI patterns
|
||||
- Code Quality: Naming, god packages, error handling, interfaces
|
||||
- Testing: Unit tests, integration tests, coverage
|
||||
- Documentation: CLAUDE.md, vision.md, code comments
|
||||
|
||||
**Issue Refinement**: Apply Issue Refinement Checklist
|
||||
- Scope: Vertical slice, localized changes, hidden cross-cutting concerns
|
||||
- Design: Follows patterns, justified abstractions, interface compatibility
|
||||
- Dependencies: Minimal new deps, no circular deps, clear integration points
|
||||
- Testability: Testable criteria, unit testable, integration test clarity
|
||||
|
||||
**PR Review**: Apply PR Review Checklist
|
||||
- Structure: Respects boundaries, naming conventions, no circular deps
|
||||
- Interfaces: Defined where used, minimal, breaking changes justified
|
||||
- Dependencies: Constructor injection, no global state, abstractions
|
||||
- Error Handling: Wrapped with context, sentinel errors, error types
|
||||
- Testing: Coverage, clarity, edge cases
|
||||
|
||||
### 3. Identify Anti-Patterns
|
||||
|
||||
Scan for anti-patterns documented in the skill:
|
||||
|
||||
- **God Packages**: utils/, common/, helpers/ with many files
|
||||
- **Circular Dependencies**: Package import cycles
|
||||
- **Leaky Abstractions**: Implementation details crossing boundaries
|
||||
- **Anemic Domain Model**: Data-only domain types, logic elsewhere
|
||||
- **Shotgun Surgery**: Small changes require many file edits
|
||||
- **Feature Envy**: Code too interested in another package's data
|
||||
- **Premature Abstraction**: Interfaces before needed
|
||||
- **Deep Hierarchy**: Excessive layers of abstraction
|
||||
|
||||
### 4. Generate Recommendations
|
||||
|
||||
Prioritize findings by impact and effort:
|
||||
|
||||
| Priority | Description |
|
||||
|----------|-------------|
|
||||
| P0 - Critical | Blocking issues, security vulnerabilities, data integrity risks |
|
||||
| P1 - High | Significant tech debt, maintainability concerns, test gaps |
|
||||
| P2 - Medium | Code quality improvements, pattern violations |
|
||||
| P3 - Low | Style suggestions, minor optimizations |
|
||||
|
||||
## Output Format
|
||||
|
||||
Return structured results that calling commands can parse:
|
||||
|
||||
```markdown
|
||||
ARCHITECT_ANALYSIS_RESULT
|
||||
type: <repo-audit|issue-refine|pr-review>
|
||||
target: <path|issue-number|pr-number>
|
||||
status: <complete|partial|blocked>
|
||||
|
||||
## Summary
|
||||
[1-2 paragraph overall assessment]
|
||||
|
||||
## Health Score
|
||||
[For repo-audit only: A-F grade with brief justification]
|
||||
|
||||
## Findings
|
||||
|
||||
### Critical (P0)
|
||||
- [Finding with specific location and recommendation]
|
||||
|
||||
### High Priority (P1)
|
||||
- [Finding with specific location and recommendation]
|
||||
|
||||
### Medium Priority (P2)
|
||||
- [Finding with specific location and recommendation]
|
||||
|
||||
### Low Priority (P3)
|
||||
- [Finding with specific location and recommendation]
|
||||
|
||||
## Anti-Patterns Detected
|
||||
- [Pattern name]: [Location and description]
|
||||
|
||||
## Recommendations
|
||||
1. [Specific, actionable recommendation]
|
||||
2. [Specific, actionable recommendation]
|
||||
|
||||
## Checklist Results
|
||||
[Relevant checklist from skill with pass/fail/na for each item]
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
|
||||
- **Be specific**: Reference exact files, packages, and line numbers
|
||||
- **Be actionable**: Every finding should have a clear path to resolution
|
||||
- **Be proportionate**: Match depth of analysis to scope of request
|
||||
- **Stay objective**: Focus on patterns and principles, not style preferences
|
||||
- **Acknowledge strengths**: Note what the codebase does well
|
||||
|
||||
## Example Invocations
|
||||
|
||||
**Repository Audit:**
|
||||
```
|
||||
Analyze the architecture of the repository at /path/to/repo
|
||||
ANALYSIS_TYPE: repo-audit
|
||||
TARGET: /path/to/repo
|
||||
CONTEXT: Focus on Go package organization and dependency flow
|
||||
```
|
||||
|
||||
**Issue Refinement:**
|
||||
```
|
||||
Review issue #42 for architectural concerns before implementation
|
||||
ANALYSIS_TYPE: issue-refine
|
||||
TARGET: 42
|
||||
CONTEXT: [Issue title and description]
|
||||
```
|
||||
|
||||
**PR Architectural Review:**
|
||||
```
|
||||
Check PR #15 for architectural concerns
|
||||
ANALYSIS_TYPE: pr-review
|
||||
TARGET: 15
|
||||
CONTEXT: [PR diff summary]
|
||||
```
|
||||
170
old/skills/arch-refine-issue/SKILL.md
Normal file
170
old/skills/arch-refine-issue/SKILL.md
Normal file
@@ -0,0 +1,170 @@
|
||||
---
|
||||
name: arch-refine-issue
|
||||
description: >
|
||||
Refine an issue with architectural perspective. Analyzes existing codebase patterns
|
||||
and provides implementation guidance. Use when refining issues, adding architectural
|
||||
context, or when user says /arch-refine-issue.
|
||||
model: opus
|
||||
argument-hint: <issue-number>
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Architecturally Refine Issue #$1
|
||||
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
@~/.claude/skills/issue-writing/SKILL.md
|
||||
|
||||
## Overview
|
||||
|
||||
Refine an issue in the context of the project's architecture. This command:
|
||||
1. Fetches the issue details
|
||||
2. Spawns the software-architect agent to analyze the codebase
|
||||
3. Identifies how the issue fits existing patterns
|
||||
4. Proposes refined description and acceptance criteria
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Fetch Issue Details
|
||||
|
||||
```bash
|
||||
tea issues $1 --comments
|
||||
```
|
||||
|
||||
Capture:
|
||||
- Title
|
||||
- Description
|
||||
- Acceptance criteria
|
||||
- Any existing discussion
|
||||
|
||||
### Step 2: Spawn Software-Architect Agent
|
||||
|
||||
Use the Task tool to spawn the software-architect agent for issue refinement analysis:
|
||||
|
||||
```
|
||||
Task tool with:
|
||||
- subagent_type: "software-architect"
|
||||
- prompt: See prompt below
|
||||
```
|
||||
|
||||
**Agent Prompt:**
|
||||
```
|
||||
Analyze the architecture for issue refinement.
|
||||
|
||||
ANALYSIS_TYPE: issue-refine
|
||||
TARGET: $1
|
||||
CONTEXT:
|
||||
<issue title and description from step 1>
|
||||
|
||||
Repository path: <current working directory>
|
||||
|
||||
Focus on:
|
||||
1. Understanding existing project structure and patterns
|
||||
2. Identifying packages/modules that will be affected
|
||||
3. Analyzing existing conventions and code style
|
||||
4. Detecting potential architectural concerns
|
||||
5. Suggesting implementation approach that fits existing patterns
|
||||
```
|
||||
|
||||
### Step 3: Parse Agent Analysis
|
||||
|
||||
The software-architect agent returns structured output with:
|
||||
- Summary of architectural findings
|
||||
- Affected packages/modules
|
||||
- Pattern recommendations
|
||||
- Potential concerns (breaking changes, tech debt, pattern violations)
|
||||
- Implementation suggestions
|
||||
|
||||
### Step 4: Present Refinement Proposal
|
||||
|
||||
Present the refined issue to the user with:
|
||||
|
||||
**1. Architectural Context**
|
||||
- Affected packages/modules
|
||||
- Existing patterns that apply
|
||||
- Dependency implications
|
||||
|
||||
**2. Concerns and Risks**
|
||||
- Breaking changes
|
||||
- Tech debt considerations
|
||||
- Pattern violations to avoid
|
||||
|
||||
**3. Proposed Refinement**
|
||||
- Refined description with architectural context
|
||||
- Updated acceptance criteria (if needed)
|
||||
- Technical notes section
|
||||
|
||||
**4. Implementation Guidance**
|
||||
- Suggested approach
|
||||
- Files likely to be modified
|
||||
- Recommended order of changes
|
||||
|
||||
### Step 5: User Decision
|
||||
|
||||
Ask the user what action to take:
|
||||
|
||||
- **Apply**: Update the issue with refined description and technical notes
|
||||
- **Edit**: Let user modify the proposal before applying
|
||||
- **Skip**: Keep the original issue unchanged
|
||||
|
||||
### Step 6: Update Issue (if approved)
|
||||
|
||||
If user approves, update the issue using tea CLI:
|
||||
|
||||
```bash
|
||||
tea issues edit $1 --description "<refined description>"
|
||||
```
|
||||
|
||||
Add a comment with the architectural analysis:
|
||||
|
||||
```bash
|
||||
tea comment $1 "## Architectural Analysis
|
||||
|
||||
<findings from software-architect agent>
|
||||
|
||||
---
|
||||
Generated by /arch-refine-issue"
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
Present findings in a clear, actionable format:
|
||||
|
||||
```markdown
|
||||
## Architectural Analysis for Issue #$1
|
||||
|
||||
### Affected Components
|
||||
- `package/name` - Description of impact
|
||||
- `another/package` - Description of impact
|
||||
|
||||
### Existing Patterns
|
||||
- Pattern 1: How it applies
|
||||
- Pattern 2: How it applies
|
||||
|
||||
### Concerns
|
||||
- [ ] Breaking change: description (if applicable)
|
||||
- [ ] Tech debt: description (if applicable)
|
||||
- [ ] Pattern violation risk: description (if applicable)
|
||||
|
||||
### Proposed Refinement
|
||||
|
||||
**Updated Description:**
|
||||
<refined description>
|
||||
|
||||
**Updated Acceptance Criteria:**
|
||||
- [ ] Original criteria (unchanged)
|
||||
- [ ] New criteria based on analysis
|
||||
|
||||
**Technical Notes:**
|
||||
<implementation guidance based on architecture>
|
||||
|
||||
### Recommended Approach
|
||||
1. Step 1
|
||||
2. Step 2
|
||||
3. Step 3
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
- If issue does not exist, inform user
|
||||
- If software-architect agent fails, report partial analysis
|
||||
- If tea CLI fails, show manual instructions
|
||||
79
old/skills/arch-review-repo/SKILL.md
Normal file
79
old/skills/arch-review-repo/SKILL.md
Normal file
@@ -0,0 +1,79 @@
|
||||
---
|
||||
name: arch-review-repo
|
||||
description: >
|
||||
Perform a full architecture review of the current repository. Analyzes structure,
|
||||
patterns, dependencies, and generates prioritized recommendations. Use when reviewing
|
||||
architecture, auditing codebase, or when user says /arch-review-repo.
|
||||
model: opus
|
||||
argument-hint:
|
||||
context: fork
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Architecture Review
|
||||
|
||||
@~/.claude/skills/software-architecture/SKILL.md
|
||||
|
||||
## Process
|
||||
|
||||
1. **Identify the repository**: Use the current working directory as the repository path.
|
||||
|
||||
2. **Spawn the software-architect agent** for deep analysis:
|
||||
|
||||
```
|
||||
ANALYSIS_TYPE: repo-audit
|
||||
TARGET: <repository-path>
|
||||
CONTEXT: Full repository architecture review
|
||||
```
|
||||
|
||||
The agent will:
|
||||
- Analyze directory structure and package organization
|
||||
- Identify patterns and anti-patterns in the codebase
|
||||
- Assess dependency graph and module boundaries
|
||||
- Review test coverage approach
|
||||
- Generate structured findings with prioritized recommendations
|
||||
|
||||
3. **Present the results** to the user in this format:
|
||||
|
||||
```markdown
|
||||
## Repository Architecture Review: <repo-name>
|
||||
|
||||
### Structure: <Good|Needs Work>
|
||||
- [Key observations about package organization]
|
||||
- [Directory structure assessment]
|
||||
- [Naming conventions evaluation]
|
||||
|
||||
### Patterns Identified
|
||||
- [Positive patterns found in the codebase]
|
||||
- [Architectural styles detected (layered, hexagonal, etc.)]
|
||||
|
||||
### Anti-Patterns Detected
|
||||
- [Anti-pattern name]: [Location and description]
|
||||
- [Anti-pattern name]: [Location and description]
|
||||
|
||||
### Concerns
|
||||
- [Specific issues that need attention]
|
||||
- [Technical debt areas]
|
||||
|
||||
### Recommendations (prioritized)
|
||||
1. **P0 - Critical**: [Most urgent recommendation]
|
||||
2. **P1 - High**: [Important improvement]
|
||||
3. **P2 - Medium**: [Nice-to-have improvement]
|
||||
4. **P3 - Low**: [Minor optimization]
|
||||
|
||||
### Health Score: <A|B|C|D|F>
|
||||
[Brief justification for the grade]
|
||||
```
|
||||
|
||||
4. **Offer follow-up actions**:
|
||||
- Create issues for critical findings
|
||||
- Generate a detailed report
|
||||
- Review specific components in more depth
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Be specific: Reference exact files, packages, and locations
|
||||
- Be actionable: Every finding should have a clear path to resolution
|
||||
- Be balanced: Acknowledge what the codebase does well
|
||||
- Be proportionate: Focus on high-impact issues first
|
||||
- Stay objective: Focus on patterns and principles, not style preferences
|
||||
100
old/skills/backlog-grooming/SKILL.md
Normal file
100
old/skills/backlog-grooming/SKILL.md
Normal file
@@ -0,0 +1,100 @@
|
||||
---
|
||||
name: backlog-grooming
|
||||
model: haiku
|
||||
description: Review and improve existing issues for clarity and actionability. Use when grooming the backlog, reviewing issue quality, cleaning up stale issues, or when the user wants to improve existing issues.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# 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 in description
|
||||
- [ ] Dependencies formally linked (`tea issues deps list <number>`)
|
||||
- [ ] No circular dependencies
|
||||
- [ ] Blocking issues are tracked
|
||||
|
||||
To check/fix dependencies:
|
||||
```bash
|
||||
tea issues deps list <number> # View current dependencies
|
||||
tea issues deps add <issue> <blocker> # Add missing dependency
|
||||
tea issues deps remove <issue> <dep> # Remove incorrect dependency
|
||||
```
|
||||
|
||||
### 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
|
||||
219
old/skills/claude-md-writing/SKILL.md
Normal file
219
old/skills/claude-md-writing/SKILL.md
Normal file
@@ -0,0 +1,219 @@
|
||||
---
|
||||
name: claude-md-writing
|
||||
model: haiku
|
||||
description: Write effective CLAUDE.md files that give AI assistants the context they need. Use when creating new repos, improving existing CLAUDE.md files, or setting up projects.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Writing Effective CLAUDE.md Files
|
||||
|
||||
CLAUDE.md is the project's context file for AI assistants. A good CLAUDE.md means Claude understands your project immediately without needing to explore.
|
||||
|
||||
## Purpose
|
||||
|
||||
CLAUDE.md answers: "What does Claude need to know to work effectively in this repo?"
|
||||
|
||||
- **Not a README** - README is for humans discovering the project
|
||||
- **Not documentation** - Docs explain how to use the product
|
||||
- **Context for AI** - What Claude needs to make good decisions
|
||||
|
||||
## Required Sections
|
||||
|
||||
### 1. One-Line Description
|
||||
|
||||
Start with what this repo is in one sentence.
|
||||
|
||||
```markdown
|
||||
# Project Name
|
||||
|
||||
Brief description of what this project does.
|
||||
```
|
||||
|
||||
### 2. Organization Context
|
||||
|
||||
Link to the bigger picture so Claude understands where this fits.
|
||||
|
||||
```markdown
|
||||
## Organization Context
|
||||
|
||||
This repo is part of Flowmade. See:
|
||||
- [Organization manifesto](../architecture/manifesto.md) - who we are, what we believe
|
||||
- [Repository map](../architecture/repos.md) - how this fits in the bigger picture
|
||||
- [Vision](./vision.md) - what this specific product does
|
||||
```
|
||||
|
||||
### 3. Setup
|
||||
|
||||
How to get the project running locally.
|
||||
|
||||
```markdown
|
||||
## Setup
|
||||
|
||||
\`\`\`bash
|
||||
# Clone and install
|
||||
git clone <url>
|
||||
cd <project>
|
||||
make install # or npm install, etc.
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### 4. Project Structure
|
||||
|
||||
Key directories and what they contain. Focus on what's non-obvious.
|
||||
|
||||
```markdown
|
||||
## Project Structure
|
||||
|
||||
\`\`\`
|
||||
project/
|
||||
├── cmd/ # Entry points
|
||||
├── pkg/ # Shared packages
|
||||
│ ├── domain/ # Business logic
|
||||
│ └── infra/ # Infrastructure adapters
|
||||
├── internal/ # Private packages
|
||||
└── api/ # API definitions
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### 5. Development Commands
|
||||
|
||||
The commands Claude will need to build, test, and run.
|
||||
|
||||
```markdown
|
||||
## Development
|
||||
|
||||
\`\`\`bash
|
||||
make build # Build the project
|
||||
make test # Run tests
|
||||
make lint # Run linters
|
||||
make run # Run locally
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### 6. Architecture Decisions
|
||||
|
||||
Key patterns and conventions specific to this repo.
|
||||
|
||||
```markdown
|
||||
## Architecture
|
||||
|
||||
### Patterns Used
|
||||
- Event sourcing for state management
|
||||
- CQRS for read/write separation
|
||||
- Hexagonal architecture
|
||||
|
||||
### Conventions
|
||||
- All commands go through the command bus
|
||||
- Events are immutable value objects
|
||||
- Projections rebuild from events
|
||||
```
|
||||
|
||||
## What Makes a Good CLAUDE.md
|
||||
|
||||
### Do Include
|
||||
|
||||
- **Enough context to skip exploration** - Claude shouldn't need to grep around
|
||||
- **Key architectural patterns** - How the code is organized and why
|
||||
- **Non-obvious conventions** - Things that aren't standard
|
||||
- **Important dependencies** - External services, APIs, databases
|
||||
- **Common tasks** - How to do things Claude will be asked to do
|
||||
|
||||
### Don't Include
|
||||
|
||||
- **Duplicated manifesto content** - Link to it instead
|
||||
- **Duplicated vision content** - Link to vision.md
|
||||
- **API documentation** - That belongs elsewhere
|
||||
- **User guides** - CLAUDE.md is for the AI, not end users
|
||||
- **Obvious things** - Don't explain what `go build` does
|
||||
|
||||
## Template
|
||||
|
||||
```markdown
|
||||
# [Project Name]
|
||||
|
||||
[One-line description]
|
||||
|
||||
## Organization Context
|
||||
|
||||
This repo is part of Flowmade. See:
|
||||
- [Organization manifesto](../architecture/manifesto.md) - who we are, what we believe
|
||||
- [Repository map](../architecture/repos.md) - how this fits in the bigger picture
|
||||
- [Vision](./vision.md) - what this specific product does
|
||||
|
||||
## Setup
|
||||
|
||||
\`\`\`bash
|
||||
# TODO: Add setup instructions
|
||||
\`\`\`
|
||||
|
||||
## Project Structure
|
||||
|
||||
\`\`\`
|
||||
project/
|
||||
├── ...
|
||||
\`\`\`
|
||||
|
||||
## Development
|
||||
|
||||
\`\`\`bash
|
||||
make build # Build the project
|
||||
make test # Run tests
|
||||
make lint # Run linters
|
||||
\`\`\`
|
||||
|
||||
## Architecture
|
||||
|
||||
### Patterns
|
||||
- [List key patterns]
|
||||
|
||||
### Conventions
|
||||
- [List important conventions]
|
||||
|
||||
### Key Components
|
||||
- [Describe main components and their responsibilities]
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Good: Enough Context
|
||||
|
||||
```markdown
|
||||
## Architecture
|
||||
|
||||
This service uses event sourcing. State is rebuilt from events, not stored directly.
|
||||
|
||||
### Key Types
|
||||
- `Aggregate` - Domain object that emits events
|
||||
- `Event` - Immutable fact that something happened
|
||||
- `Projection` - Read model built from events
|
||||
|
||||
### Adding a New Aggregate
|
||||
1. Create type in `pkg/domain/`
|
||||
2. Implement `HandleCommand()` and `ApplyEvent()`
|
||||
3. Register in `cmd/main.go`
|
||||
```
|
||||
|
||||
Claude can now work with aggregates without exploring the codebase.
|
||||
|
||||
### Bad: Too Vague
|
||||
|
||||
```markdown
|
||||
## Architecture
|
||||
|
||||
Uses standard Go patterns. See the code for details.
|
||||
```
|
||||
|
||||
Claude has to explore to understand anything.
|
||||
|
||||
## Maintenance
|
||||
|
||||
Update CLAUDE.md when:
|
||||
- Adding new architectural patterns
|
||||
- Changing project structure
|
||||
- Adding important dependencies
|
||||
- Discovering conventions that aren't documented
|
||||
|
||||
Don't update for:
|
||||
- Every code change
|
||||
- Bug fixes
|
||||
- Minor refactors
|
||||
206
old/skills/code-review/SKILL.md
Normal file
206
old/skills/code-review/SKILL.md
Normal file
@@ -0,0 +1,206 @@
|
||||
---
|
||||
name: code-review
|
||||
model: haiku
|
||||
description: Review code for quality, bugs, security, and style issues. Use when reviewing pull requests, checking code quality, looking for bugs or security vulnerabilities, or when the user asks for a code review.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# 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]
|
||||
```
|
||||
92
old/skills/commit/SKILL.md
Normal file
92
old/skills/commit/SKILL.md
Normal file
@@ -0,0 +1,92 @@
|
||||
---
|
||||
name: commit
|
||||
description: >
|
||||
Create a commit with an auto-generated conventional commit message. Analyzes staged
|
||||
changes and proposes a message for approval. Use when committing changes, creating
|
||||
commits, or when user says /commit.
|
||||
model: haiku
|
||||
argument-hint:
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Commit Changes
|
||||
|
||||
## Process
|
||||
|
||||
1. **Check for staged changes**:
|
||||
```bash
|
||||
git diff --staged --stat
|
||||
```
|
||||
|
||||
If no staged changes, inform the user and suggest staging files first:
|
||||
- Show unstaged changes with `git status`
|
||||
- Ask if they want to stage all changes (`git add -A`) or specific files
|
||||
|
||||
2. **Analyze staged changes**:
|
||||
```bash
|
||||
git diff --staged
|
||||
```
|
||||
|
||||
Examine the diff to understand:
|
||||
- What files were changed, added, or deleted
|
||||
- The nature of the changes (new feature, bug fix, refactor, docs, etc.)
|
||||
- Key details worth mentioning
|
||||
|
||||
3. **Generate commit message**:
|
||||
|
||||
Create a conventional commit message following this format:
|
||||
```
|
||||
<type>(<scope>): <description>
|
||||
|
||||
[optional body with more details]
|
||||
|
||||
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
|
||||
```
|
||||
|
||||
**Types:**
|
||||
- `feat`: New feature or capability
|
||||
- `fix`: Bug fix
|
||||
- `refactor`: Code restructuring without behavior change
|
||||
- `docs`: Documentation changes
|
||||
- `style`: Formatting, whitespace (no code change)
|
||||
- `test`: Adding or updating tests
|
||||
- `chore`: Maintenance tasks, dependencies, config
|
||||
|
||||
**Scope:** The component or area affected (optional, use when helpful)
|
||||
|
||||
**Description:**
|
||||
- Imperative mood ("add" not "added")
|
||||
- Lowercase first letter
|
||||
- No period at the end
|
||||
- Focus on the "why" when the "what" is obvious
|
||||
|
||||
4. **Present message for approval**:
|
||||
|
||||
Show the proposed message and ask the user to:
|
||||
- **Approve**: Use the message as-is
|
||||
- **Edit**: Let them modify the message
|
||||
- **Regenerate**: Create a new message with different focus
|
||||
|
||||
5. **Create the commit**:
|
||||
|
||||
Once approved, execute:
|
||||
```bash
|
||||
git commit -m "$(cat <<'EOF'
|
||||
<approved message>
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
6. **Confirm success**:
|
||||
|
||||
Show the commit result and suggest next steps:
|
||||
- Push to remote: `git push`
|
||||
- Continue working and commit more changes
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Only commits what's staged (respects partial staging)
|
||||
- Never auto-commits without user approval
|
||||
- Keep descriptions concise (50 chars or less for first line)
|
||||
- Include body for non-obvious changes
|
||||
- Always include Co-Authored-By attribution
|
||||
48
old/skills/create-issue/SKILL.md
Normal file
48
old/skills/create-issue/SKILL.md
Normal file
@@ -0,0 +1,48 @@
|
||||
---
|
||||
name: create-issue
|
||||
description: >
|
||||
Create a new Gitea issue. Can create single issues or batch create from a plan.
|
||||
Use when creating issues, adding tickets, or when user says /create-issue.
|
||||
model: haiku
|
||||
argument-hint: [title] or "batch"
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Create Issue(s)
|
||||
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
|
||||
## Milestone Assignment
|
||||
|
||||
Before creating issues, fetch available milestones:
|
||||
|
||||
```bash
|
||||
tea milestones -f title,description
|
||||
```
|
||||
|
||||
For each issue, automatically assign to the most relevant milestone by matching:
|
||||
- Issue content/problem area → Milestone title and description
|
||||
- If no clear match, ask the user which milestone (goal) the issue supports
|
||||
- If no milestones exist, skip milestone assignment
|
||||
|
||||
Include `--milestone "<milestone>"` in the create command when a milestone is assigned.
|
||||
|
||||
## Single Issue (default)
|
||||
|
||||
If title provided:
|
||||
1. Create an issue with that title
|
||||
2. Ask for description
|
||||
3. Assign to appropriate milestone (see above)
|
||||
4. Ask if this issue depends on any existing issues
|
||||
5. If dependencies exist, link them: `tea issues deps add <new-issue> <blocker>`
|
||||
|
||||
## Batch Mode
|
||||
|
||||
If $1 is "batch":
|
||||
1. Ask user for the plan/direction
|
||||
2. Fetch available milestones
|
||||
3. Generate list of issues with titles, descriptions, milestone assignments, and dependencies
|
||||
4. Show for approval
|
||||
5. Create each issue with milestone (in dependency order)
|
||||
6. Link dependencies between created issues: `tea issues deps add <issue> <blocker>`
|
||||
7. Display all created issue numbers with dependency graph
|
||||
214
old/skills/create-repo/SKILL.md
Normal file
214
old/skills/create-repo/SKILL.md
Normal file
@@ -0,0 +1,214 @@
|
||||
---
|
||||
name: create-repo
|
||||
description: >
|
||||
Create a new repository with standard structure. Scaffolds vision.md, CLAUDE.md,
|
||||
and CI configuration. Use when creating repos, initializing projects, or when user
|
||||
says /create-repo.
|
||||
model: haiku
|
||||
argument-hint: <repo-name>
|
||||
context: fork
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Create Repository
|
||||
|
||||
@~/.claude/skills/repo-conventions/SKILL.md
|
||||
@~/.claude/skills/vision-management/SKILL.md
|
||||
@~/.claude/skills/claude-md-writing/SKILL.md
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
|
||||
Create a new repository with Flowmade's standard structure.
|
||||
|
||||
## Process
|
||||
|
||||
1. **Get repository name**: Use `$1` or ask the user
|
||||
- Validate: lowercase, hyphens only, no `flowmade-` prefix
|
||||
- Check it doesn't already exist: `tea repos flowmade-one/<name>`
|
||||
|
||||
2. **Determine visibility**:
|
||||
- Ask: "Should this repo be public (open source) or private (proprietary)?"
|
||||
- Refer to repo-conventions skill for guidance on open vs proprietary
|
||||
|
||||
3. **Gather vision context**:
|
||||
- Read the organization manifesto: `../architecture/manifesto.md`
|
||||
- Ask: "What does this product do? (one sentence)"
|
||||
- Ask: "Which manifesto personas does it serve?"
|
||||
- Ask: "What problem does it solve?"
|
||||
|
||||
4. **Create the repository on Gitea**:
|
||||
```bash
|
||||
tea repos create --name <repo-name> --private/--public --description "<description>"
|
||||
```
|
||||
|
||||
5. **Clone and set up structure**:
|
||||
```bash
|
||||
# Clone the new repo
|
||||
git clone ssh://git@git.flowmade.one/flowmade-one/<repo-name>.git
|
||||
cd <repo-name>
|
||||
```
|
||||
|
||||
6. **Create vision.md**:
|
||||
- Use the vision structure template from vision-management skill
|
||||
- Link to `../architecture/manifesto.md`
|
||||
- Fill in based on user's answers
|
||||
|
||||
7. **Create CLAUDE.md** (following claude-md-writing skill):
|
||||
```markdown
|
||||
# <Repo Name>
|
||||
|
||||
<One-line description from step 3>
|
||||
|
||||
## Organization Context
|
||||
|
||||
This repo is part of Flowmade. See:
|
||||
- [Organization manifesto](../architecture/manifesto.md) - who we are, what we believe
|
||||
- [Repository map](../architecture/repos.md) - how this fits in the bigger picture
|
||||
- [Vision](./vision.md) - what this specific product does
|
||||
|
||||
## Setup
|
||||
|
||||
```bash
|
||||
# TODO: Add setup instructions
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
TODO: Document key directories once code exists.
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
make build # Build the project
|
||||
make test # Run tests
|
||||
make lint # Run linters
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
TODO: Document key patterns and conventions once established.
|
||||
```
|
||||
|
||||
8. **Create Makefile** (basic template):
|
||||
```makefile
|
||||
.PHONY: build test lint
|
||||
|
||||
build:
|
||||
@echo "TODO: Add build command"
|
||||
|
||||
test:
|
||||
@echo "TODO: Add test command"
|
||||
|
||||
lint:
|
||||
@echo "TODO: Add lint command"
|
||||
```
|
||||
|
||||
9. **Create CI workflow**:
|
||||
```bash
|
||||
mkdir -p .gitea/workflows
|
||||
```
|
||||
|
||||
Create `.gitea/workflows/ci.yaml`:
|
||||
```yaml
|
||||
name: CI
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
branches: [main]
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Build
|
||||
run: make build
|
||||
- name: Test
|
||||
run: make test
|
||||
- name: Lint
|
||||
run: make lint
|
||||
```
|
||||
|
||||
10. **Create .gitignore** (basic, expand based on language):
|
||||
```
|
||||
# IDE
|
||||
.idea/
|
||||
.vscode/
|
||||
*.swp
|
||||
|
||||
# OS
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
|
||||
# Build artifacts
|
||||
/dist/
|
||||
/build/
|
||||
/bin/
|
||||
|
||||
# Dependencies (language-specific, add as needed)
|
||||
/node_modules/
|
||||
/vendor/
|
||||
```
|
||||
|
||||
11. **Initial commit and push**:
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Initial repository structure
|
||||
|
||||
- vision.md linking to organization manifesto
|
||||
- CLAUDE.md with project instructions
|
||||
- CI workflow template
|
||||
- Basic Makefile
|
||||
|
||||
Generated with [Claude Code](https://claude.com/claude-code)
|
||||
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||||
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
12. **Report success**:
|
||||
```
|
||||
Repository created: https://git.flowmade.one/flowmade-one/<repo-name>
|
||||
|
||||
Next steps:
|
||||
1. cd ../<repo-name>
|
||||
2. Update CLAUDE.md with actual setup instructions
|
||||
3. Update Makefile with real build commands
|
||||
4. Start building!
|
||||
```
|
||||
|
||||
## Output Example
|
||||
|
||||
```
|
||||
## Creating Repository: my-service
|
||||
|
||||
Visibility: Private (proprietary)
|
||||
Description: Internal service for processing events
|
||||
|
||||
### Files Created
|
||||
|
||||
- vision.md (linked to manifesto)
|
||||
- CLAUDE.md (project instructions)
|
||||
- Makefile (build template)
|
||||
- .gitea/workflows/ci.yaml (CI pipeline)
|
||||
- .gitignore (standard ignores)
|
||||
|
||||
### Repository URL
|
||||
|
||||
https://git.flowmade.one/flowmade-one/my-service
|
||||
|
||||
### Next Steps
|
||||
|
||||
1. cd ../my-service
|
||||
2. Update CLAUDE.md with setup instructions
|
||||
3. Update Makefile with build commands
|
||||
4. Start coding!
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Always link vision.md to the sibling architecture repo
|
||||
- Keep initial structure minimal - add complexity as needed
|
||||
- CI should pass on empty repo (use placeholder commands)
|
||||
- Default to private unless explicitly open-sourcing
|
||||
90
old/skills/dashboard/SKILL.md
Normal file
90
old/skills/dashboard/SKILL.md
Normal file
@@ -0,0 +1,90 @@
|
||||
---
|
||||
name: dashboard
|
||||
description: >
|
||||
Show dashboard of open issues, PRs awaiting review, and CI status. Use when
|
||||
checking project status, viewing issues/PRs, or when user says /dashboard.
|
||||
model: haiku
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Repository Dashboard
|
||||
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
|
||||
Fetch and display the following sections:
|
||||
|
||||
## 1. Open Issues
|
||||
|
||||
Run `tea issues` to list all open issues.
|
||||
|
||||
Format as a table showing:
|
||||
- Number
|
||||
- Title
|
||||
- Author
|
||||
|
||||
## 2. Open Pull Requests
|
||||
|
||||
Run `tea pulls` to list all open PRs.
|
||||
|
||||
Format as a table showing:
|
||||
- Number
|
||||
- Title
|
||||
- Author
|
||||
|
||||
## 3. CI Status (Recent Workflow Runs)
|
||||
|
||||
Run `tea actions runs` to list recent workflow runs.
|
||||
|
||||
**Output formatting:**
|
||||
- Show the most recent 10 workflow runs maximum
|
||||
- For each run, display:
|
||||
- Status (use indicators: [SUCCESS], [FAILURE], [RUNNING], [PENDING])
|
||||
- Workflow name
|
||||
- Branch or PR reference
|
||||
- Commit (short SHA)
|
||||
- Triggered time
|
||||
|
||||
**Highlighting:**
|
||||
- **Highlight failed runs** by prefixing with a warning indicator and ensuring they stand out visually
|
||||
- Example: "**[FAILURE]** build - PR #42 - abc1234 - 2h ago"
|
||||
|
||||
**Handling repos without CI:**
|
||||
- If `tea actions runs` returns "No workflow runs found" or similar, display:
|
||||
"No CI workflows configured for this repository."
|
||||
- Do not treat this as an error - simply note it and continue
|
||||
|
||||
## Output Format
|
||||
|
||||
Present each section with a clear header. Example:
|
||||
|
||||
```
|
||||
## Open Issues (3)
|
||||
|
||||
| # | Title | Author |
|
||||
|----|------------------------|--------|
|
||||
| 15 | Fix login timeout | alice |
|
||||
| 12 | Add dark mode | bob |
|
||||
| 8 | Update documentation | carol |
|
||||
|
||||
## Open Pull Requests (2)
|
||||
|
||||
| # | Title | Author |
|
||||
|----|------------------------|--------|
|
||||
| 16 | Fix login timeout | alice |
|
||||
| 14 | Refactor auth module | bob |
|
||||
|
||||
## CI Status
|
||||
|
||||
| Status | Workflow | Branch/PR | Commit | Time |
|
||||
|-------------|----------|-------------|---------|---------|
|
||||
| **[FAILURE]** | build | PR #16 | abc1234 | 2h ago |
|
||||
| [SUCCESS] | build | main | def5678 | 5h ago |
|
||||
| [SUCCESS] | lint | main | def5678 | 5h ago |
|
||||
```
|
||||
|
||||
If no CI is configured:
|
||||
```
|
||||
## CI Status
|
||||
|
||||
No CI workflows configured for this repository.
|
||||
```
|
||||
43
old/skills/groom/SKILL.md
Normal file
43
old/skills/groom/SKILL.md
Normal file
@@ -0,0 +1,43 @@
|
||||
---
|
||||
name: groom
|
||||
description: >
|
||||
Groom and improve issues. Without argument, reviews all open issues. With argument,
|
||||
grooms specific issue. Use when grooming backlog, improving issues, or when user
|
||||
says /groom.
|
||||
model: sonnet
|
||||
argument-hint: [issue-number]
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Groom Issues
|
||||
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
@~/.claude/skills/backlog-grooming/SKILL.md
|
||||
@~/.claude/skills/issue-writing/SKILL.md
|
||||
|
||||
## If issue number provided ($1):
|
||||
|
||||
1. **Fetch the issue** details with `tea issues <number> --comments`
|
||||
2. **Check dependencies** with `tea issues deps list <number>`
|
||||
3. **Evaluate** against grooming checklist
|
||||
4. **Suggest improvements** for:
|
||||
- Title clarity
|
||||
- Description completeness
|
||||
- Acceptance criteria quality
|
||||
- Scope definition
|
||||
- Missing or incorrect dependencies
|
||||
5. **Ask user** if they want to apply changes
|
||||
6. **Update issue** if approved
|
||||
7. **Link/unlink dependencies** if needed: `tea issues deps add/remove <issue> <dep>`
|
||||
|
||||
## If no argument (groom all):
|
||||
|
||||
1. **List open issues**
|
||||
2. **Review each** against grooming checklist (including dependencies)
|
||||
3. **Categorize**:
|
||||
- Ready: Well-defined, dependencies linked, can start work
|
||||
- Blocked: Has unresolved dependencies
|
||||
- Needs work: Missing info, unclear, or missing dependency links
|
||||
- Stale: No longer relevant
|
||||
4. **Present summary** table with dependency status
|
||||
5. **Offer to improve** issues that need work (including linking dependencies)
|
||||
89
old/skills/improve/SKILL.md
Normal file
89
old/skills/improve/SKILL.md
Normal file
@@ -0,0 +1,89 @@
|
||||
---
|
||||
name: improve
|
||||
description: >
|
||||
Identify improvement opportunities based on product vision. Analyzes gaps between
|
||||
vision goals and current backlog. Use when analyzing alignment, finding gaps, or
|
||||
when user says /improve.
|
||||
model: sonnet
|
||||
context: fork
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Improvement Analysis
|
||||
|
||||
@~/.claude/skills/vision-management/SKILL.md
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
@~/.claude/skills/issue-writing/SKILL.md
|
||||
@~/.claude/skills/roadmap-planning/SKILL.md
|
||||
|
||||
## Process
|
||||
|
||||
1. **Read the vision**: Load `vision.md` from the repo root.
|
||||
- If no vision exists, suggest running `/vision` first
|
||||
|
||||
2. **Fetch current backlog**: Get all open issues from Gitea using `tea issues`
|
||||
|
||||
3. **Analyze alignment**:
|
||||
|
||||
For each vision goal, check:
|
||||
- Are there issues supporting this goal?
|
||||
- Is there recent activity/progress?
|
||||
- Are issues blocked or stalled?
|
||||
|
||||
For each open issue, check:
|
||||
- Does it align with a vision goal?
|
||||
- Is it supporting the current focus?
|
||||
|
||||
4. **Identify gaps and opportunities**:
|
||||
|
||||
- **Unsupported goals**: Vision goals with no issues
|
||||
- **Stalled goals**: Goals with issues but no recent progress
|
||||
- **Orphan issues**: Issues that don't support any goal
|
||||
- **Focus misalignment**: Issues not aligned with current focus getting priority
|
||||
- **Missing non-goals**: Patterns suggesting things we should explicitly avoid
|
||||
|
||||
5. **Present findings**:
|
||||
|
||||
```
|
||||
## Vision Alignment Report
|
||||
|
||||
### Goals Coverage
|
||||
- Goal 1: [status] - N issues, [progress]
|
||||
- Goal 2: [status] - N issues, [progress]
|
||||
|
||||
### Gaps Identified
|
||||
1. [Gap description]
|
||||
Suggestion: [concrete action]
|
||||
|
||||
2. [Gap description]
|
||||
Suggestion: [concrete action]
|
||||
|
||||
### Orphan Issues
|
||||
- #N: [title] - No goal alignment
|
||||
|
||||
### Recommended Actions
|
||||
1. [Action with rationale]
|
||||
2. [Action with rationale]
|
||||
```
|
||||
|
||||
6. **Offer to take action**:
|
||||
|
||||
For unsupported goals:
|
||||
- Ask if user wants to plan issues for the gap
|
||||
- If yes, run the `/plan-issues` workflow for that goal
|
||||
- This breaks down the goal into concrete, actionable issues
|
||||
|
||||
For other findings:
|
||||
- Re-prioritize issues based on focus
|
||||
- Close or re-scope orphan issues
|
||||
- Update vision with suggested changes
|
||||
|
||||
Always ask for approval before making changes.
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Focus on actionable improvements, not just observations
|
||||
- Prioritize suggestions by impact on vision goals
|
||||
- Keep suggestions specific and concrete
|
||||
- One issue per improvement (don't bundle)
|
||||
- Reference specific goals when suggesting new issues
|
||||
157
old/skills/issue-writing/SKILL.md
Normal file
157
old/skills/issue-writing/SKILL.md
Normal file
@@ -0,0 +1,157 @@
|
||||
---
|
||||
name: issue-writing
|
||||
model: haiku
|
||||
description: Write clear, actionable issues with proper structure and acceptance criteria. Use when creating issues, writing bug reports, feature requests, or when the user needs help structuring an issue.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# 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
|
||||
```
|
||||
|
||||
## Vertical Slices
|
||||
|
||||
Issues should be **vertical slices** that deliver user-visible value.
|
||||
|
||||
### The Demo Test
|
||||
|
||||
Before writing an issue, ask: **Can a user demo or test this independently?**
|
||||
|
||||
- **Yes** → Good issue scope
|
||||
- **No** → Rethink the breakdown
|
||||
|
||||
### Good vs Bad Issue Titles
|
||||
|
||||
| Good (Vertical) | Bad (Horizontal) |
|
||||
|-----------------|------------------|
|
||||
| "User can save and reload diagram" | "Add persistence layer" |
|
||||
| "Show error when login fails" | "Add error handling" |
|
||||
| "Domain expert can list orders" | "Add query syntax to ADL" |
|
||||
|
||||
### Writing User-Focused Issues
|
||||
|
||||
Frame issues around user capabilities:
|
||||
|
||||
```markdown
|
||||
# Bad: Technical task
|
||||
Title: Add email service integration
|
||||
|
||||
# Good: User capability
|
||||
Title: User receives confirmation email after signup
|
||||
```
|
||||
|
||||
The technical work is the same, but the good title makes success criteria clear.
|
||||
|
||||
## 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
|
||||
|
||||
Identify and link dependencies when creating issues:
|
||||
|
||||
1. **In the description**, document dependencies:
|
||||
```markdown
|
||||
## Dependencies
|
||||
- Depends on #12 (must complete first)
|
||||
- Related to #15 (informational)
|
||||
```
|
||||
|
||||
2. **After creating the issue**, formally link blockers using tea CLI:
|
||||
```bash
|
||||
tea issues deps add <this-issue> <blocker-issue>
|
||||
tea issues deps add 5 3 # Issue #5 is blocked by #3
|
||||
```
|
||||
|
||||
This creates a formal dependency graph that tools can query.
|
||||
77
old/skills/manifesto/SKILL.md
Normal file
77
old/skills/manifesto/SKILL.md
Normal file
@@ -0,0 +1,77 @@
|
||||
---
|
||||
name: manifesto
|
||||
description: >
|
||||
View and manage the organization manifesto. Shows identity, personas, beliefs,
|
||||
and principles. Use when viewing manifesto, checking organization identity, or
|
||||
when user says /manifesto.
|
||||
model: haiku
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Organization Manifesto
|
||||
|
||||
@~/.claude/skills/vision-management/SKILL.md
|
||||
|
||||
The manifesto defines the organization-level vision: who we are, who we serve, what we believe, and how we work. It is distinct from product-level vision (see `/vision`).
|
||||
|
||||
## Process
|
||||
|
||||
1. **Check for manifesto**: Look for `manifesto.md` in the current repo root.
|
||||
|
||||
2. **If no manifesto exists**:
|
||||
- Ask if the user wants to create one
|
||||
- Guide through defining:
|
||||
1. **Who We Are**: Organization identity
|
||||
2. **Who We Serve**: 2-4 specific personas with context and constraints
|
||||
3. **What They're Trying to Achieve**: Jobs to be done in their voice
|
||||
4. **What We Believe**: Core beliefs including stance on AI-augmented development
|
||||
5. **Guiding Principles**: Decision-making rules
|
||||
6. **Non-Goals**: What we explicitly don't do
|
||||
- Create `manifesto.md`
|
||||
|
||||
3. **If manifesto exists**:
|
||||
- Display formatted summary of the manifesto
|
||||
|
||||
## Output Format
|
||||
|
||||
When displaying an existing manifesto:
|
||||
|
||||
```
|
||||
## Who We Are
|
||||
|
||||
[Identity summary from manifesto]
|
||||
|
||||
## Who We Serve
|
||||
|
||||
- **[Persona 1]**: [Brief description]
|
||||
- **[Persona 2]**: [Brief description]
|
||||
- **[Persona 3]**: [Brief description]
|
||||
|
||||
## What They're Trying to Achieve
|
||||
|
||||
- "[Job to be done 1]"
|
||||
- "[Job to be done 2]"
|
||||
- "[Job to be done 3]"
|
||||
|
||||
## What We Believe
|
||||
|
||||
[Summary of key beliefs - especially AI-augmented development stance]
|
||||
|
||||
## Guiding Principles
|
||||
|
||||
1. [Principle 1]
|
||||
2. [Principle 2]
|
||||
3. [Principle 3]
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- [Non-goal 1]
|
||||
- [Non-goal 2]
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
|
||||
- The manifesto is the **organization-level** document - it applies across all products
|
||||
- Update rarely - this is foundational identity, not tactical direction
|
||||
- Product repos reference the manifesto but have their own `vision.md`
|
||||
- Use `/vision` for product-level vision management
|
||||
72
old/skills/plan-issues/SKILL.md
Normal file
72
old/skills/plan-issues/SKILL.md
Normal file
@@ -0,0 +1,72 @@
|
||||
---
|
||||
name: plan-issues
|
||||
description: >
|
||||
Plan and create issues for a feature or improvement. Breaks down work into
|
||||
well-structured issues with vision alignment. Use when planning a feature,
|
||||
creating a roadmap, breaking down large tasks, or when user says /plan-issues.
|
||||
model: sonnet
|
||||
argument-hint: <feature-description>
|
||||
context: fork
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Plan Feature: $1
|
||||
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
@~/.claude/skills/roadmap-planning/SKILL.md
|
||||
@~/.claude/skills/issue-writing/SKILL.md
|
||||
@~/.claude/skills/vision-management/SKILL.md
|
||||
|
||||
1. **Check vision context**: If `vision.md` exists, read it to understand personas, jobs to be done, and goals
|
||||
2. **Identify persona**: Which persona does "$1" serve?
|
||||
3. **Identify job**: Which job to be done does this enable?
|
||||
4. **Understand the feature**: Analyze what "$1" involves
|
||||
5. **Explore the codebase** if needed to understand context
|
||||
|
||||
6. **Discovery phase**: Before proposing issues, walk through the user workflow:
|
||||
- Who is the specific user?
|
||||
- What is their goal?
|
||||
- What is their step-by-step workflow to reach that goal?
|
||||
- What exists today?
|
||||
- Where does the workflow break or have gaps?
|
||||
- What's the MVP that delivers value?
|
||||
|
||||
Present this as a workflow walkthrough before proposing any issues.
|
||||
|
||||
7. **Break down** into discrete, actionable issues:
|
||||
- Derive issues from the workflow gaps identified in discovery
|
||||
- Each issue should be independently completable
|
||||
- Clear dependencies between issues
|
||||
- Appropriate scope (not too big, not too small)
|
||||
|
||||
8. **Present the plan** (include vision alignment if vision exists):
|
||||
```
|
||||
## Proposed Issues for: $1
|
||||
|
||||
For: [Persona name]
|
||||
Job: "[Job to be done this enables]"
|
||||
Supports: [Milestone/Goal name]
|
||||
|
||||
1. [Title] - Brief description
|
||||
Addresses gap: [which workflow gap this solves]
|
||||
Dependencies: none
|
||||
|
||||
2. [Title] - Brief description
|
||||
Addresses gap: [which workflow gap this solves]
|
||||
Dependencies: #1
|
||||
|
||||
3. [Title] - Brief description
|
||||
Addresses gap: [which workflow gap this solves]
|
||||
Dependencies: #1, #2
|
||||
```
|
||||
|
||||
If the feature doesn't align with any persona/job/goal, note this and ask if:
|
||||
- A new persona or job should be added to the vision
|
||||
- A new milestone should be created
|
||||
- This should be added as a non-goal
|
||||
- Proceed anyway (with justification)
|
||||
|
||||
9. **Ask for approval** before creating issues
|
||||
10. **Create issues** in dependency order (blockers first)
|
||||
11. **Link dependencies** using `tea issues deps add <issue> <blocker>` for each dependency
|
||||
12. **Present summary** with links to created issues and dependency graph
|
||||
153
old/skills/pr/SKILL.md
Normal file
153
old/skills/pr/SKILL.md
Normal file
@@ -0,0 +1,153 @@
|
||||
---
|
||||
name: pr
|
||||
description: >
|
||||
Create a PR from current branch. Auto-generates title and description from branch
|
||||
name and commits. Use when creating pull requests, submitting changes, or when
|
||||
user says /pr.
|
||||
model: haiku
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Create Pull Request
|
||||
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
|
||||
Quick PR creation from current branch - lighter than full `/work-issue` flow for when you're already on a branch with commits.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Current branch is NOT main/master
|
||||
- Branch has commits ahead of main
|
||||
- Changes have been pushed to origin (or will be pushed)
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Verify Branch State
|
||||
|
||||
```bash
|
||||
# Check current branch
|
||||
git branch --show-current
|
||||
|
||||
# Ensure we're not on main
|
||||
# If on main, abort with message: "Cannot create PR from main branch"
|
||||
|
||||
# Check for commits ahead of main
|
||||
git log main..HEAD --oneline
|
||||
```
|
||||
|
||||
### 2. Push if Needed
|
||||
|
||||
```bash
|
||||
# Check if branch is tracking remote
|
||||
git status -sb
|
||||
|
||||
# If not pushed or behind, push with upstream
|
||||
git push -u origin <branch-name>
|
||||
```
|
||||
|
||||
### 3. Generate PR Title
|
||||
|
||||
**Option A: Branch contains issue number** (e.g., `issue-42-add-feature`)
|
||||
|
||||
Extract issue number and use format: `[Issue #<number>] <issue-title>`
|
||||
|
||||
```bash
|
||||
tea issues <number> # Get the actual issue title
|
||||
```
|
||||
|
||||
**Option B: No issue number**
|
||||
|
||||
Generate from branch name or recent commit messages:
|
||||
- Convert branch name from kebab-case to title case: `add-user-auth` -> `Add user auth`
|
||||
- Or use the most recent commit subject line
|
||||
|
||||
### 4. Generate PR Description
|
||||
|
||||
Analyze the diff and commits to generate a description:
|
||||
|
||||
```bash
|
||||
# Get diff against main
|
||||
git diff main...HEAD --stat
|
||||
|
||||
# Get commit messages
|
||||
git log main..HEAD --format="- %s"
|
||||
```
|
||||
|
||||
Structure the description:
|
||||
|
||||
```markdown
|
||||
## Summary
|
||||
[1-2 sentences describing the overall change]
|
||||
|
||||
## Changes
|
||||
[Bullet points summarizing commits or key changes]
|
||||
|
||||
[If issue linked: "Closes #<number>"]
|
||||
```
|
||||
|
||||
### 5. Create PR
|
||||
|
||||
Use tea CLI to create the PR:
|
||||
|
||||
```bash
|
||||
tea pulls create --title "<generated-title>" --description "<generated-description>"
|
||||
```
|
||||
|
||||
Capture the PR number from the output (e.g., "Pull Request #42 created").
|
||||
|
||||
### 6. Auto-review
|
||||
|
||||
Inform the user that auto-review is starting, then spawn the `code-reviewer` agent in background:
|
||||
|
||||
```
|
||||
Task tool with:
|
||||
- subagent_type: "code-reviewer"
|
||||
- run_in_background: true
|
||||
- prompt: |
|
||||
Review PR #<PR_NUMBER> in the repository at <REPO_PATH>.
|
||||
|
||||
1. Checkout the PR: tea pulls checkout <PR_NUMBER>
|
||||
2. Get the diff: git diff main...HEAD
|
||||
3. Analyze for code quality, bugs, security, style, test coverage
|
||||
4. Post structured review comment with tea comment
|
||||
5. Merge with rebase if LGTM, otherwise leave for user
|
||||
```
|
||||
|
||||
### 7. Display Result
|
||||
|
||||
Show the user:
|
||||
- PR URL/number
|
||||
- Generated title and description
|
||||
- Status of auto-review (spawned in background)
|
||||
|
||||
## Issue Linking
|
||||
|
||||
To detect if branch is linked to an issue:
|
||||
|
||||
1. Check branch name for patterns:
|
||||
- `issue-<number>-*`
|
||||
- `<number>-*`
|
||||
- `*-#<number>`
|
||||
|
||||
2. If issue number found:
|
||||
- Fetch issue title from Gitea
|
||||
- Use `[Issue #N] <issue-title>` format for PR title
|
||||
- Add `Closes #N` to description
|
||||
|
||||
## Example Output
|
||||
|
||||
```
|
||||
Created PR #42: [Issue #15] Add /pr command
|
||||
|
||||
## Summary
|
||||
Adds /pr command for quick PR creation from current branch.
|
||||
|
||||
## Changes
|
||||
- Add commands/pr.md with auto-generation logic
|
||||
- Support issue linking from branch name
|
||||
|
||||
Closes #15
|
||||
|
||||
---
|
||||
Auto-review started in background. Check status with: tea pulls 42 --comments
|
||||
```
|
||||
204
old/skills/repo-conventions/SKILL.md
Normal file
204
old/skills/repo-conventions/SKILL.md
Normal file
@@ -0,0 +1,204 @@
|
||||
---
|
||||
name: repo-conventions
|
||||
model: haiku
|
||||
description: Standard structure and conventions for Flowmade repositories. Use when creating new repos, reviewing repo structure, or setting up projects.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Repository Conventions
|
||||
|
||||
Standard structure and conventions for Flowmade repositories.
|
||||
|
||||
## Repository Layout
|
||||
|
||||
All product repos should follow this structure relative to the architecture repo:
|
||||
|
||||
```
|
||||
org/
|
||||
├── architecture/ # Organizational source of truth
|
||||
│ ├── manifesto.md # Organization identity and beliefs
|
||||
│ ├── skills/ # User-invocable and background skills
|
||||
│ └── agents/ # Subtask handlers
|
||||
├── product-a/ # Product repository
|
||||
│ ├── vision.md # Product vision (extends manifesto)
|
||||
│ ├── CLAUDE.md # AI assistant instructions
|
||||
│ ├── .gitea/workflows/ # CI/CD pipelines
|
||||
│ └── ...
|
||||
└── product-b/
|
||||
└── ...
|
||||
```
|
||||
|
||||
## Required Files
|
||||
|
||||
### vision.md
|
||||
|
||||
Every product repo needs a vision that extends the organization manifesto.
|
||||
|
||||
```markdown
|
||||
# Vision
|
||||
|
||||
This product vision builds on the [organization manifesto](../architecture/manifesto.md).
|
||||
|
||||
## Who This Product Serves
|
||||
|
||||
### [Persona Name]
|
||||
|
||||
[Product-specific description]
|
||||
|
||||
*Extends: [Org persona] (from manifesto)*
|
||||
|
||||
## What They're Trying to Achieve
|
||||
|
||||
| Product Job | Enables Org Job |
|
||||
|-------------|-----------------|
|
||||
| "[Product job]" | "[Org job from manifesto]" |
|
||||
|
||||
## The Problem
|
||||
|
||||
[Pain points this product addresses]
|
||||
|
||||
## The Solution
|
||||
|
||||
[How this product solves those problems]
|
||||
|
||||
## Product Principles
|
||||
|
||||
### [Principle Name]
|
||||
|
||||
[Description]
|
||||
|
||||
*Extends: "[Org principle]"*
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- **[Non-goal].** [Explanation]
|
||||
```
|
||||
|
||||
### CLAUDE.md
|
||||
|
||||
Project-specific context for AI assistants. See [claude-md-writing skill](../claude-md-writing/SKILL.md) for detailed guidance.
|
||||
|
||||
```markdown
|
||||
# [Project Name]
|
||||
|
||||
[One-line description]
|
||||
|
||||
## Organization Context
|
||||
|
||||
This repo is part of Flowmade. See:
|
||||
- [Organization manifesto](../architecture/manifesto.md) - who we are, what we believe
|
||||
- [Repository map](../architecture/repos.md) - how this fits in the bigger picture
|
||||
- [Vision](./vision.md) - what this specific product does
|
||||
|
||||
## Setup
|
||||
|
||||
[How to get the project running locally]
|
||||
|
||||
## Project Structure
|
||||
|
||||
[Key directories and their purposes]
|
||||
|
||||
## Development
|
||||
|
||||
[How to build, test, run]
|
||||
|
||||
## Architecture
|
||||
|
||||
[Key architectural decisions and patterns]
|
||||
```
|
||||
|
||||
### .gitea/workflows/ci.yaml
|
||||
|
||||
Standard CI pipeline. Adapt based on language/framework.
|
||||
|
||||
```yaml
|
||||
name: CI
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
branches: [main]
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Build
|
||||
run: make build
|
||||
- name: Test
|
||||
run: make test
|
||||
- name: Lint
|
||||
run: make lint
|
||||
```
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
### Repository Names
|
||||
|
||||
- Lowercase with hyphens: `product-name`, `service-name`
|
||||
- Descriptive but concise
|
||||
- No prefixes like `flowmade-` (the org already provides context)
|
||||
|
||||
### Branch Names
|
||||
|
||||
- `main` - default branch, always deployable
|
||||
- `issue-<number>-<short-description>` - feature branches
|
||||
- No `develop` or `staging` branches - use main + feature flags
|
||||
|
||||
### Commit Messages
|
||||
|
||||
- Imperative mood: "Add feature" not "Added feature"
|
||||
- First line: summary (50 chars)
|
||||
- Body: explain why, not what (the diff shows what)
|
||||
- Reference issues: "Fixes #42" or "Closes #42"
|
||||
|
||||
## Open vs Proprietary
|
||||
|
||||
Decisions about what to open-source are guided by the manifesto:
|
||||
|
||||
| Type | Open Source? | Reason |
|
||||
|------|--------------|--------|
|
||||
| Infrastructure tooling | Yes | Builds community, low competitive risk |
|
||||
| Generic libraries | Yes | Ecosystem benefits, adoption |
|
||||
| Core platform IP | No | Differentiator, revenue source |
|
||||
| Domain-specific features | No | Product value |
|
||||
|
||||
When uncertain, default to proprietary. Opening later is easier than closing.
|
||||
|
||||
## CI/CD Conventions
|
||||
|
||||
### Runners
|
||||
|
||||
- Use self-hosted ARM64 runners where possible (resource efficiency)
|
||||
- KEDA-scaled runners for burst capacity
|
||||
- Cache dependencies aggressively
|
||||
|
||||
### Deployments
|
||||
|
||||
- Main branch auto-deploys to staging
|
||||
- Production requires manual approval or tag
|
||||
- Use GitOps (ArgoCD) for Kubernetes deployments
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Go Projects
|
||||
|
||||
- Use Go modules
|
||||
- Vendor dependencies for reproducibility
|
||||
- Pin major versions, allow minor updates
|
||||
|
||||
### General
|
||||
|
||||
- Prefer fewer, well-maintained dependencies
|
||||
- Audit transitive dependencies
|
||||
- Update regularly, don't let them rot
|
||||
|
||||
## Documentation
|
||||
|
||||
Following the manifesto principle "Encode, don't document":
|
||||
|
||||
- CLAUDE.md: How to work with this repo (for AI and humans)
|
||||
- vision.md: Why this product exists
|
||||
- Code comments: Only for non-obvious "why"
|
||||
- No separate docs folder unless user-facing documentation
|
||||
120
old/skills/retro/SKILL.md
Normal file
120
old/skills/retro/SKILL.md
Normal file
@@ -0,0 +1,120 @@
|
||||
---
|
||||
name: retro
|
||||
description: >
|
||||
Run a retrospective on completed work. Captures insights as issues for later
|
||||
encoding into skills/agents. Use when capturing learnings, running retrospectives,
|
||||
or when user says /retro.
|
||||
model: haiku
|
||||
argument-hint: [task-description]
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Retrospective
|
||||
|
||||
Capture insights from completed work as issues on the architecture repo. Issues are later encoded into learnings and skills/agents.
|
||||
|
||||
@~/.claude/skills/vision-management/SKILL.md
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
|
||||
## Flow
|
||||
|
||||
```
|
||||
Retro (any repo) → Issue (architecture repo) → Encode: learning file + skill/agent
|
||||
```
|
||||
|
||||
The retro creates the issue. Encoding happens when the issue is worked on.
|
||||
|
||||
## Process
|
||||
|
||||
1. **Gather context**: If $1 is provided, use it as the task description. Otherwise, ask the user what task was just completed.
|
||||
|
||||
2. **Reflect on the work**: Ask the user (or summarize from conversation context if obvious):
|
||||
- What friction points were encountered?
|
||||
- What worked well?
|
||||
- Any specific improvement ideas?
|
||||
|
||||
3. **Identify insights**: For each insight, determine:
|
||||
- **What was learned**: The specific insight
|
||||
- **Where to encode it**: Which skill or agent should change?
|
||||
- **Governance impact**: What does this mean for how we work?
|
||||
|
||||
4. **Create issue on architecture repo**: Always create issues on `flowmade-one/architecture`:
|
||||
|
||||
```bash
|
||||
tea issues create -r flowmade-one/architecture \
|
||||
--title "[Learning] <brief description>" \
|
||||
--description "## Context
|
||||
[Task that triggered this insight]
|
||||
|
||||
## Insight
|
||||
[The specific learning - be concrete and actionable]
|
||||
|
||||
## Suggested Encoding
|
||||
- [ ] \`skills/xxx/SKILL.md\` - [what to add/change]
|
||||
- [ ] \`agents/xxx/agent.md\` - [what to add/change]
|
||||
|
||||
## Governance
|
||||
[What this means for how we work going forward]"
|
||||
```
|
||||
|
||||
5. **Connect to vision**: Check if insight affects vision:
|
||||
- **Architecture repo**: Does this affect `manifesto.md`? (beliefs, principles, non-goals)
|
||||
- **Product repo**: Does this affect `vision.md`? (product direction, goals)
|
||||
|
||||
If vision updates are needed, present suggested changes and ask for approval.
|
||||
|
||||
## When the Issue is Worked On
|
||||
|
||||
When encoding a learning issue, the implementer should:
|
||||
|
||||
1. **Create learning file**: `learnings/YYYY-MM-DD-short-title.md`
|
||||
|
||||
```markdown
|
||||
# [Learning Title]
|
||||
|
||||
**Date**: YYYY-MM-DD
|
||||
**Context**: [Task that triggered this learning]
|
||||
**Issue**: #XX
|
||||
|
||||
## Learning
|
||||
|
||||
[The specific insight]
|
||||
|
||||
## Encoded In
|
||||
|
||||
- `skills/xxx/SKILL.md` - [what was added/changed]
|
||||
|
||||
## Governance
|
||||
|
||||
[What this means for how we work]
|
||||
```
|
||||
|
||||
2. **Update skill/agent** with the encoded knowledge
|
||||
|
||||
3. **Close the issue** with reference to the learning file and changes made
|
||||
|
||||
## Encoding Destinations
|
||||
|
||||
| Insight Type | Encode In |
|
||||
|--------------|-----------|
|
||||
| How to use a tool | `skills/[tool]/SKILL.md` |
|
||||
| Workflow improvement | `skills/[skill]/SKILL.md` (user-invocable) |
|
||||
| Subtask behavior | `agents/[agent]/agent.md` |
|
||||
| Organization belief | `manifesto.md` |
|
||||
| Product direction | `vision.md` (in product repo) |
|
||||
|
||||
## Labels
|
||||
|
||||
Add appropriate labels to issues:
|
||||
- `learning` - Always add this
|
||||
- `prompt-improvement` - For skill text changes
|
||||
- `new-feature` - For new skills/agents
|
||||
- `bug` - For things that are broken
|
||||
|
||||
## Guidelines
|
||||
|
||||
- **Always create issues on architecture repo** - regardless of which repo the retro runs in
|
||||
- **Be specific**: Vague insights can't be encoded
|
||||
- **One issue per insight**: Don't bundle unrelated things
|
||||
- **Encoding happens later**: Retro captures the issue, encoding is separate work
|
||||
- **Skip one-offs**: Don't capture insights for edge cases that won't recur
|
||||
90
old/skills/review-pr/SKILL.md
Normal file
90
old/skills/review-pr/SKILL.md
Normal file
@@ -0,0 +1,90 @@
|
||||
---
|
||||
name: review-pr
|
||||
description: >
|
||||
Review a Gitea pull request. Fetches PR details, diff, and comments. Includes
|
||||
both code review and software architecture review. Use when reviewing pull requests,
|
||||
checking code quality, or when user says /review-pr.
|
||||
model: sonnet
|
||||
argument-hint: <pr-number>
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Review PR #$1
|
||||
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
@~/.claude/skills/software-architecture/SKILL.md
|
||||
|
||||
## 1. Gather Information
|
||||
|
||||
1. **View PR details** with `--comments` flag to see description, metadata, and discussion
|
||||
2. **Get the diff** to review the changes:
|
||||
```bash
|
||||
tea pulls checkout <number>
|
||||
git diff main...HEAD
|
||||
```
|
||||
|
||||
## 2. Code Review
|
||||
|
||||
Review the changes and provide feedback on:
|
||||
- Code quality and style
|
||||
- Potential bugs or logic errors
|
||||
- Test coverage
|
||||
- Documentation updates
|
||||
|
||||
## 3. Software Architecture Review
|
||||
|
||||
Spawn the software-architect agent for architectural analysis:
|
||||
|
||||
```
|
||||
Task tool with:
|
||||
- subagent_type: "software-architect"
|
||||
- prompt: |
|
||||
ANALYSIS_TYPE: pr-review
|
||||
TARGET: <pr-number>
|
||||
CONTEXT: [Include the PR diff and description]
|
||||
```
|
||||
|
||||
The architecture review checks:
|
||||
- **Pattern consistency**: Changes follow existing codebase patterns
|
||||
- **Dependency direction**: Dependencies flow correctly (toward domain layer)
|
||||
- **Breaking changes**: API changes are flagged and justified
|
||||
- **Module boundaries**: Changes respect existing package boundaries
|
||||
- **Error handling**: Errors wrapped with context, proper error types used
|
||||
|
||||
## 4. Present Findings
|
||||
|
||||
Structure the review with two sections:
|
||||
|
||||
### Code Review
|
||||
- Quality, bugs, style issues
|
||||
- Test coverage gaps
|
||||
- Documentation needs
|
||||
|
||||
### Architecture Review
|
||||
- Summary of architectural concerns from agent
|
||||
- Pattern violations or anti-patterns detected
|
||||
- Dependency or boundary issues
|
||||
- Breaking change assessment
|
||||
|
||||
## 5. User Actions
|
||||
|
||||
Ask the user what action to take:
|
||||
- **Merge**: Post review summary as comment, then merge with rebase style
|
||||
- **Request changes**: Leave feedback without merging
|
||||
- **Comment only**: Add a comment for discussion
|
||||
|
||||
## Merging
|
||||
|
||||
Always use tea CLI for merges to preserve user attribution:
|
||||
|
||||
```bash
|
||||
tea pulls merge <number> --style rebase
|
||||
```
|
||||
|
||||
For review comments, use `tea comment` since `tea pulls review` is interactive-only:
|
||||
|
||||
```bash
|
||||
tea comment <number> "<review summary>"
|
||||
```
|
||||
|
||||
> **Warning**: Never use the Gitea API with admin credentials for user-facing operations like merging. This causes the merge to be attributed to the admin account instead of the user.
|
||||
190
old/skills/roadmap-planning/SKILL.md
Normal file
190
old/skills/roadmap-planning/SKILL.md
Normal file
@@ -0,0 +1,190 @@
|
||||
---
|
||||
name: roadmap-planning
|
||||
model: haiku
|
||||
description: Plan features and break down work into implementable issues. Use when planning a feature, creating a roadmap, breaking down large tasks, or when the user needs help organizing work into issues.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# 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. Discovery Phase
|
||||
|
||||
Before breaking down work into issues, understand the user's workflow:
|
||||
|
||||
| Question | Why It Matters |
|
||||
|----------|----------------|
|
||||
| **Who** is the user? | Specific persona, not "users" |
|
||||
| **What's their goal?** | The job they're trying to accomplish |
|
||||
| **What's their workflow?** | Step-by-step actions to reach the goal |
|
||||
| **What exists today?** | Current state and gaps |
|
||||
| **What's the MVP?** | Minimum to deliver value |
|
||||
|
||||
**Walk through the workflow step by step:**
|
||||
1. User starts at: [starting point]
|
||||
2. User does: [action 1]
|
||||
3. System responds: [what happens]
|
||||
4. User does: [action 2]
|
||||
5. ... continue until goal is reached
|
||||
|
||||
**Identify the gaps:**
|
||||
- Where does the workflow break today?
|
||||
- Which steps are missing or painful?
|
||||
- What's the smallest change that unblocks value?
|
||||
|
||||
**Derive issues from workflow gaps** - not from guessing what might be needed. Each issue should address a specific gap in the user's workflow.
|
||||
|
||||
### 3. 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
|
||||
|
||||
### 4. Identify Dependencies
|
||||
- Which pieces must come first?
|
||||
- What can be parallelized?
|
||||
- Are there external blockers?
|
||||
|
||||
### 5. Create Issues
|
||||
- Follow issue-writing patterns
|
||||
- Reference dependencies explicitly
|
||||
- Use consistent labeling
|
||||
|
||||
## Vertical vs Horizontal Slices
|
||||
|
||||
**Prefer vertical slices** - each issue should deliver user-visible value.
|
||||
|
||||
| Vertical (Good) | Horizontal (Bad) |
|
||||
|-----------------|------------------|
|
||||
| "User can save and reload their diagram" | "Add persistence layer" + "Add save API" + "Add load API" |
|
||||
| "Domain expert can list all orders" | "Add query syntax to ADL" + "Add query runtime" + "Add query UI" |
|
||||
| "User can reset forgotten password" | "Add email service" + "Add reset token model" + "Add reset form" |
|
||||
|
||||
### The Demo Test
|
||||
|
||||
Ask: **Can a user demo or test this issue independently?**
|
||||
|
||||
- **Yes** → Good vertical slice
|
||||
- **No** → Probably a horizontal slice, break differently
|
||||
|
||||
### Break by User Capability, Not Technical Layer
|
||||
|
||||
Instead of thinking "what technical components do we need?", think "what can the user do after this issue is done?"
|
||||
|
||||
```
|
||||
# Bad: Technical layers
|
||||
├── Add database schema
|
||||
├── Add API endpoint
|
||||
├── Add frontend form
|
||||
|
||||
# Good: User capabilities
|
||||
├── User can create a draft
|
||||
├── User can publish the draft
|
||||
├── User can edit published content
|
||||
```
|
||||
|
||||
### When Horizontal Slices Are Acceptable
|
||||
|
||||
Sometimes horizontal slices are necessary:
|
||||
- **Infrastructure setup** - Database, CI/CD, deployment (do once, enables everything)
|
||||
- **Security foundations** - Auth system before any protected features
|
||||
- **Shared libraries** - When multiple features need the same foundation
|
||||
|
||||
Even then, keep them minimal and follow immediately with vertical slices that use them.
|
||||
|
||||
## 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)
|
||||
```
|
||||
|
||||
After creating issues, formally link dependencies:
|
||||
```bash
|
||||
tea issues deps add <issue> <blocker>
|
||||
tea issues deps add 14 12 # Issue #14 depends on #12
|
||||
tea issues deps add 14 13 # Issue #14 depends on #13
|
||||
```
|
||||
|
||||
## 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?"
|
||||
37
old/skills/roadmap/SKILL.md
Normal file
37
old/skills/roadmap/SKILL.md
Normal file
@@ -0,0 +1,37 @@
|
||||
---
|
||||
name: roadmap
|
||||
description: >
|
||||
View current issues as a roadmap. Shows open issues organized by status and
|
||||
dependencies. Use when viewing roadmap, checking issue status, or when user
|
||||
says /roadmap.
|
||||
model: haiku
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Roadmap View
|
||||
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
|
||||
1. **Fetch all open issues**
|
||||
2. **Analyze dependencies** from issue descriptions
|
||||
3. **Categorize issues**:
|
||||
- Blocked: Waiting on other issues
|
||||
- Ready: No blockers, can start
|
||||
- In Progress: Has assignee or WIP label
|
||||
4. **Present roadmap** as organized list:
|
||||
|
||||
```
|
||||
## Ready to Start
|
||||
- #5: Add user authentication
|
||||
- #8: Create dashboard layout
|
||||
|
||||
## In Progress
|
||||
- #3: Setup database schema
|
||||
|
||||
## Blocked
|
||||
- #7: User profile page (blocked by #5)
|
||||
- #9: Admin dashboard (blocked by #3, #8)
|
||||
```
|
||||
|
||||
5. **Highlight** any issues that seem stale or unclear
|
||||
6. **Suggest** next actions based on the roadmap state
|
||||
633
old/skills/software-architecture/SKILL.md
Normal file
633
old/skills/software-architecture/SKILL.md
Normal file
@@ -0,0 +1,633 @@
|
||||
---
|
||||
name: software-architecture
|
||||
model: haiku
|
||||
description: >
|
||||
Architectural patterns for building systems: DDD, Event Sourcing, event-driven communication.
|
||||
Use when implementing features, reviewing code, planning issues, refining architecture,
|
||||
or making design decisions. Ensures alignment with organizational beliefs about
|
||||
auditability, domain modeling, and independent evolution.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Software Architecture
|
||||
|
||||
Architectural patterns and best practices. This skill is auto-triggered when implementing, reviewing, or planning work that involves architectural decisions.
|
||||
|
||||
## Architecture Beliefs
|
||||
|
||||
These outcome-focused beliefs (from our organization manifesto) guide architectural decisions:
|
||||
|
||||
| Belief | Why It Matters |
|
||||
|--------|----------------|
|
||||
| **Auditability by default** | Systems should remember what happened, not just current state |
|
||||
| **Business language in code** | Domain experts' words should appear in the codebase |
|
||||
| **Independent evolution** | Parts should change without breaking other parts |
|
||||
| **Explicit over implicit** | Intent and side effects should be visible and traceable |
|
||||
|
||||
## Beliefs → Patterns
|
||||
|
||||
| Belief | Primary Pattern | Supporting Patterns |
|
||||
|--------|-----------------|---------------------|
|
||||
| Auditability by default | Event Sourcing | Immutable events, temporal queries |
|
||||
| Business language in code | Domain-Driven Design | Ubiquitous language, aggregates, bounded contexts |
|
||||
| Independent evolution | Event-driven communication | Bounded contexts, published language |
|
||||
| Explicit over implicit | Commands and Events | Domain events, clear intent |
|
||||
|
||||
## Event Sourcing
|
||||
|
||||
**Achieves:** Auditability by default
|
||||
|
||||
Instead of storing current state, store the sequence of events that led to it.
|
||||
|
||||
**Core concepts:**
|
||||
- **Events** are immutable facts about what happened, named in past tense: `OrderPlaced`, `PaymentReceived`
|
||||
- **State** is derived by replaying events, not stored directly
|
||||
- **Event store** is append-only - history is never modified
|
||||
|
||||
**Why this matters:**
|
||||
- Complete audit trail for free
|
||||
- Debug by replaying history
|
||||
- Answer "what was the state at time X?"
|
||||
- Recover from bugs by fixing logic and replaying
|
||||
|
||||
**Trade-offs:**
|
||||
- More complex than CRUD for simple cases
|
||||
- Requires thinking in events, not state
|
||||
- Eventually consistent read models
|
||||
|
||||
## Domain-Driven Design
|
||||
|
||||
**Achieves:** Business language in code
|
||||
|
||||
The domain model reflects how the business thinks and talks.
|
||||
|
||||
**Core concepts:**
|
||||
- **Ubiquitous language** - same terms in code, conversations, and documentation
|
||||
- **Bounded contexts** - explicit boundaries where terms have consistent meaning
|
||||
- **Aggregates** - clusters of objects that change together, with one root entity
|
||||
- **Domain events** - capture what happened in business terms
|
||||
|
||||
**Why this matters:**
|
||||
- Domain experts can read and validate the model
|
||||
- New team members learn the domain through code
|
||||
- Changes in business rules map clearly to code changes
|
||||
|
||||
**Trade-offs:**
|
||||
- Upfront investment in understanding the domain
|
||||
- Boundaries may need to shift as understanding grows
|
||||
- Overkill for pure technical/infrastructure code
|
||||
|
||||
## Event-Driven Communication
|
||||
|
||||
**Achieves:** Independent evolution
|
||||
|
||||
Services communicate by publishing events, not calling each other directly.
|
||||
|
||||
**Core concepts:**
|
||||
- **Publish events** when something important happens
|
||||
- **Subscribe to events** you care about
|
||||
- **No direct dependencies** between publisher and subscriber
|
||||
- **Eventual consistency** - accept that not everything updates instantly
|
||||
|
||||
**Why this matters:**
|
||||
- Add new services without changing existing ones
|
||||
- Services can be deployed independently
|
||||
- Natural resilience - if a subscriber is down, events queue
|
||||
|
||||
**Trade-offs:**
|
||||
- Harder to trace request flow
|
||||
- Eventual consistency requires different thinking
|
||||
- Need infrastructure for reliable event delivery
|
||||
|
||||
## Commands and Events
|
||||
|
||||
**Achieves:** Explicit over implicit
|
||||
|
||||
Distinguish between requests (commands) and facts (events).
|
||||
|
||||
**Core concepts:**
|
||||
- **Commands** express intent: `PlaceOrder`, `CancelSubscription`
|
||||
- Commands can be rejected (validation, business rules)
|
||||
- **Events** express facts: `OrderPlaced`, `SubscriptionCancelled`
|
||||
- Events are immutable - what happened, happened
|
||||
|
||||
**Why this matters:**
|
||||
- Clear separation of "trying to do X" vs "X happened"
|
||||
- Commands validate, events just record
|
||||
- Enables replay - reprocess events with new logic
|
||||
|
||||
## When to Diverge
|
||||
|
||||
These patterns are defaults, not mandates. Diverge intentionally when:
|
||||
|
||||
- **Simplicity wins** - a simple CRUD endpoint doesn't need event sourcing
|
||||
- **Performance requires it** - sometimes synchronous calls are necessary
|
||||
- **Team context** - patterns the team doesn't understand cause more harm than good
|
||||
- **Prototyping** - validate ideas before investing in full architecture
|
||||
|
||||
When diverging, document the decision in the project's `vision.md` Architecture section.
|
||||
|
||||
## Project-Level Architecture
|
||||
|
||||
Each project documents architectural choices in `vision.md`:
|
||||
|
||||
```markdown
|
||||
## Architecture
|
||||
|
||||
This project follows organization architecture patterns.
|
||||
|
||||
### Alignment
|
||||
- Event sourcing for [which aggregates/domains]
|
||||
- Bounded contexts: [list contexts and their responsibilities]
|
||||
- Event-driven communication between [which services]
|
||||
|
||||
### Intentional Divergences
|
||||
| Area | Standard Pattern | What We Do Instead | Why |
|
||||
|------|------------------|-------------------|-----|
|
||||
```
|
||||
|
||||
## Go-Specific Best Practices
|
||||
|
||||
### Package Organization
|
||||
|
||||
**Good package structure:**
|
||||
```
|
||||
project/
|
||||
├── cmd/ # Application entry points
|
||||
│ └── server/
|
||||
│ └── main.go
|
||||
├── internal/ # Private packages
|
||||
│ ├── domain/ # Core business logic
|
||||
│ │ ├── user/
|
||||
│ │ └── order/
|
||||
│ ├── service/ # Application services
|
||||
│ ├── repository/ # Data access
|
||||
│ └── handler/ # HTTP/gRPC handlers
|
||||
├── pkg/ # Public, reusable packages
|
||||
└── go.mod
|
||||
```
|
||||
|
||||
**Package naming:**
|
||||
- Short, concise, lowercase: `user`, `order`, `auth`
|
||||
- Avoid generic names: `util`, `common`, `helpers`, `misc`
|
||||
- Name after what it provides, not what it contains
|
||||
- One package per concept, not per file
|
||||
|
||||
**Package cohesion:**
|
||||
- A package should have a single, focused responsibility
|
||||
- Package internal files can use internal types freely
|
||||
- Minimize exported types - export interfaces, hide implementations
|
||||
|
||||
### Interfaces
|
||||
|
||||
**Accept interfaces, return structs:**
|
||||
```go
|
||||
// Good: Accept interface, return concrete type
|
||||
func NewUserService(repo UserRepository) *UserService {
|
||||
return &UserService{repo: repo}
|
||||
}
|
||||
|
||||
// Bad: Accept and return interface
|
||||
func NewUserService(repo UserRepository) UserService {
|
||||
return &userService{repo: repo}
|
||||
}
|
||||
```
|
||||
|
||||
**Define interfaces at point of use:**
|
||||
```go
|
||||
// Good: Interface defined where it's used (consumer owns the interface)
|
||||
package service
|
||||
|
||||
type UserRepository interface {
|
||||
FindByID(ctx context.Context, id string) (*User, error)
|
||||
}
|
||||
|
||||
// Bad: Interface defined with implementation (producer owns the interface)
|
||||
package repository
|
||||
|
||||
type UserRepository interface {
|
||||
FindByID(ctx context.Context, id string) (*User, error)
|
||||
}
|
||||
```
|
||||
|
||||
**Keep interfaces small:**
|
||||
- Prefer single-method interfaces
|
||||
- Large interfaces indicate missing abstraction
|
||||
- Compose small interfaces when needed
|
||||
|
||||
### Error Handling
|
||||
|
||||
**Wrap errors with context:**
|
||||
```go
|
||||
// Good: Wrap with context
|
||||
if err != nil {
|
||||
return fmt.Errorf("fetching user %s: %w", id, err)
|
||||
}
|
||||
|
||||
// Bad: Return bare error
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
```
|
||||
|
||||
**Use sentinel errors for expected conditions:**
|
||||
```go
|
||||
var ErrNotFound = errors.New("not found")
|
||||
var ErrConflict = errors.New("conflict")
|
||||
|
||||
// Check with errors.Is
|
||||
if errors.Is(err, ErrNotFound) {
|
||||
// handle not found
|
||||
}
|
||||
```
|
||||
|
||||
**Error types for rich errors:**
|
||||
```go
|
||||
type ValidationError struct {
|
||||
Field string
|
||||
Message string
|
||||
}
|
||||
|
||||
func (e *ValidationError) Error() string {
|
||||
return fmt.Sprintf("%s: %s", e.Field, e.Message)
|
||||
}
|
||||
|
||||
// Check with errors.As
|
||||
var valErr *ValidationError
|
||||
if errors.As(err, &valErr) {
|
||||
// handle validation error
|
||||
}
|
||||
```
|
||||
|
||||
### Dependency Injection
|
||||
|
||||
**Constructor injection:**
|
||||
```go
|
||||
type UserService struct {
|
||||
repo UserRepository
|
||||
logger Logger
|
||||
}
|
||||
|
||||
func NewUserService(repo UserRepository, logger Logger) *UserService {
|
||||
return &UserService{
|
||||
repo: repo,
|
||||
logger: logger,
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Wire dependencies in main:**
|
||||
```go
|
||||
func main() {
|
||||
// Create dependencies
|
||||
db := database.Connect()
|
||||
logger := slog.Default()
|
||||
|
||||
// Wire up services
|
||||
userRepo := repository.NewUserRepository(db)
|
||||
userService := service.NewUserService(userRepo, logger)
|
||||
userHandler := handler.NewUserHandler(userService)
|
||||
|
||||
// Start server
|
||||
http.Handle("/users", userHandler)
|
||||
http.ListenAndServe(":8080", nil)
|
||||
}
|
||||
```
|
||||
|
||||
**Avoid global state:**
|
||||
- No `init()` for service initialization
|
||||
- No package-level variables for dependencies
|
||||
- Pass context explicitly, don't store in structs
|
||||
|
||||
### Testing
|
||||
|
||||
**Table-driven tests:**
|
||||
```go
|
||||
func TestUserService_Create(t *testing.T) {
|
||||
tests := []struct {
|
||||
name string
|
||||
input CreateUserInput
|
||||
want *User
|
||||
wantErr error
|
||||
}{
|
||||
{
|
||||
name: "valid user",
|
||||
input: CreateUserInput{Email: "test@example.com"},
|
||||
want: &User{Email: "test@example.com"},
|
||||
},
|
||||
{
|
||||
name: "invalid email",
|
||||
input: CreateUserInput{Email: "invalid"},
|
||||
wantErr: ErrInvalidEmail,
|
||||
},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
// arrange, act, assert
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Test doubles:**
|
||||
- Use interfaces for test doubles
|
||||
- Prefer hand-written mocks over generated ones for simple cases
|
||||
- Use `testify/mock` or `gomock` for complex mocking needs
|
||||
|
||||
**Test package naming:**
|
||||
- `package user_test` for black-box testing (preferred)
|
||||
- `package user` for white-box testing when needed
|
||||
|
||||
## Generic Architecture Patterns
|
||||
|
||||
### Layered Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────┐
|
||||
│ Presentation │ HTTP handlers, CLI, gRPC
|
||||
├─────────────────────────────────┤
|
||||
│ Application │ Use cases, orchestration
|
||||
├─────────────────────────────────┤
|
||||
│ Domain │ Business logic, entities
|
||||
├─────────────────────────────────┤
|
||||
│ Infrastructure │ Database, external services
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Dependencies point downward only
|
||||
- Upper layers depend on interfaces, not implementations
|
||||
- Domain layer has no external dependencies
|
||||
|
||||
### SOLID Principles
|
||||
|
||||
**Single Responsibility (S):**
|
||||
- Each module has one reason to change
|
||||
- Split code that changes for different reasons
|
||||
|
||||
**Open/Closed (O):**
|
||||
- Open for extension, closed for modification
|
||||
- Add new behavior through new types, not changing existing ones
|
||||
|
||||
**Liskov Substitution (L):**
|
||||
- Subtypes must be substitutable for their base types
|
||||
- Interfaces should be implementable without surprises
|
||||
|
||||
**Interface Segregation (I):**
|
||||
- Clients shouldn't depend on interfaces they don't use
|
||||
- Prefer many small interfaces over few large ones
|
||||
|
||||
**Dependency Inversion (D):**
|
||||
- High-level modules shouldn't depend on low-level modules
|
||||
- Both should depend on abstractions
|
||||
|
||||
### Dependency Direction
|
||||
|
||||
```
|
||||
┌──────────────┐
|
||||
│ Domain │
|
||||
│ (no deps) │
|
||||
└──────────────┘
|
||||
▲
|
||||
┌────────────┴────────────┐
|
||||
│ │
|
||||
┌───────┴───────┐ ┌───────┴───────┐
|
||||
│ Application │ │Infrastructure │
|
||||
│ (uses domain) │ │(implements │
|
||||
└───────────────┘ │ domain intf) │
|
||||
▲ └───────────────┘
|
||||
│
|
||||
┌───────┴───────┐
|
||||
│ Presentation │
|
||||
│(calls app) │
|
||||
└───────────────┘
|
||||
```
|
||||
|
||||
**Key insight:** Infrastructure implements domain interfaces, doesn't define them. This inverts the "natural" dependency direction.
|
||||
|
||||
### Module Boundaries
|
||||
|
||||
**Signs of good boundaries:**
|
||||
- Modules can be understood in isolation
|
||||
- Changes are localized within modules
|
||||
- Clear, minimal public API
|
||||
- Dependencies flow in one direction
|
||||
|
||||
**Signs of bad boundaries:**
|
||||
- Circular dependencies between modules
|
||||
- "Shotgun surgery" - small changes require many file edits
|
||||
- Modules reach into each other's internals
|
||||
- Unclear ownership of concepts
|
||||
|
||||
## Repository Health Indicators
|
||||
|
||||
### Positive Indicators
|
||||
|
||||
| Indicator | What to Look For |
|
||||
|-----------|------------------|
|
||||
| Clear structure | Obvious package organization, consistent naming |
|
||||
| Small interfaces | Most interfaces have 1-3 methods |
|
||||
| Explicit dependencies | Constructor injection, no globals |
|
||||
| Test coverage | Unit tests for business logic, integration tests for boundaries |
|
||||
| Error handling | Wrapped errors, typed errors for expected cases |
|
||||
| Documentation | CLAUDE.md accurate, code comments explain "why" |
|
||||
|
||||
### Warning Signs
|
||||
|
||||
| Indicator | What to Look For |
|
||||
|-----------|------------------|
|
||||
| God packages | `utils/`, `common/`, `helpers/` with 20+ files |
|
||||
| Circular deps | Package A imports B, B imports A |
|
||||
| Deep nesting | 4+ levels of directory nesting |
|
||||
| Huge files | Files with 500+ lines |
|
||||
| Interface pollution | Interfaces for everything, even single implementations |
|
||||
| Global state | Package-level variables, `init()` for setup |
|
||||
|
||||
### Metrics to Track
|
||||
|
||||
- **Package fan-out:** How many packages does each package import?
|
||||
- **Cyclomatic complexity:** How complex are the functions?
|
||||
- **Test coverage:** What percentage of code is tested?
|
||||
- **Import depth:** How deep is the import tree?
|
||||
|
||||
## Review Checklists
|
||||
|
||||
### Repository Audit Checklist
|
||||
|
||||
Use this when evaluating overall repository health.
|
||||
|
||||
**Structure:**
|
||||
- [ ] Clear package organization following Go conventions
|
||||
- [ ] No circular dependencies between packages
|
||||
- [ ] Appropriate use of `internal/` for private packages
|
||||
- [ ] `cmd/` for application entry points
|
||||
|
||||
**Dependencies:**
|
||||
- [ ] Dependencies flow inward (toward domain)
|
||||
- [ ] Interfaces defined at point of use (not with implementation)
|
||||
- [ ] No global state or package-level dependencies
|
||||
- [ ] Constructor injection throughout
|
||||
|
||||
**Code Quality:**
|
||||
- [ ] Consistent naming conventions
|
||||
- [ ] No "god" packages (utils, common, helpers)
|
||||
- [ ] Errors wrapped with context
|
||||
- [ ] Small, focused interfaces
|
||||
|
||||
**Testing:**
|
||||
- [ ] Unit tests for domain logic
|
||||
- [ ] Integration tests for boundaries (DB, HTTP)
|
||||
- [ ] Tests are readable and maintainable
|
||||
- [ ] Test coverage for critical paths
|
||||
|
||||
**Documentation:**
|
||||
- [ ] CLAUDE.md is accurate and helpful
|
||||
- [ ] vision.md explains the product purpose
|
||||
- [ ] Code comments explain "why", not "what"
|
||||
|
||||
### Issue Refinement Checklist
|
||||
|
||||
Use this when reviewing issues for architecture impact.
|
||||
|
||||
**Scope:**
|
||||
- [ ] Issue is a vertical slice (user-visible value)
|
||||
- [ ] Changes are localized to specific packages
|
||||
- [ ] No cross-cutting concerns hidden in implementation
|
||||
|
||||
**Design:**
|
||||
- [ ] Follows existing patterns in the codebase
|
||||
- [ ] New abstractions are justified
|
||||
- [ ] Interface changes are backward compatible (or breaking change is documented)
|
||||
|
||||
**Dependencies:**
|
||||
- [ ] New dependencies are minimal and justified
|
||||
- [ ] No new circular dependencies introduced
|
||||
- [ ] Integration points are clearly defined
|
||||
|
||||
**Testability:**
|
||||
- [ ] Acceptance criteria are testable
|
||||
- [ ] New code can be unit tested in isolation
|
||||
- [ ] Integration test requirements are clear
|
||||
|
||||
### PR Review Checklist
|
||||
|
||||
Use this when reviewing pull requests for architecture concerns.
|
||||
|
||||
**Structure:**
|
||||
- [ ] Changes respect existing package boundaries
|
||||
- [ ] New packages follow naming conventions
|
||||
- [ ] No new circular dependencies
|
||||
|
||||
**Interfaces:**
|
||||
- [ ] Interfaces are defined where used
|
||||
- [ ] Interfaces are minimal and focused
|
||||
- [ ] Breaking interface changes are justified
|
||||
|
||||
**Dependencies:**
|
||||
- [ ] Dependencies injected via constructors
|
||||
- [ ] No new global state
|
||||
- [ ] External dependencies properly abstracted
|
||||
|
||||
**Error Handling:**
|
||||
- [ ] Errors wrapped with context
|
||||
- [ ] Sentinel errors for expected conditions
|
||||
- [ ] Error types for rich error information
|
||||
|
||||
**Testing:**
|
||||
- [ ] New code has appropriate test coverage
|
||||
- [ ] Tests are clear and maintainable
|
||||
- [ ] Edge cases covered
|
||||
|
||||
## Anti-Patterns to Flag
|
||||
|
||||
### God Packages
|
||||
|
||||
**Problem:** Packages like `utils/`, `common/`, `helpers/` become dumping grounds.
|
||||
|
||||
**Symptoms:**
|
||||
- 20+ files in one package
|
||||
- Unrelated functions grouped together
|
||||
- Package imported by everything
|
||||
|
||||
**Fix:** Extract cohesive packages based on what they provide: `validation`, `httputil`, `timeutil`.
|
||||
|
||||
### Circular Dependencies
|
||||
|
||||
**Problem:** Package A imports B, and B imports A (directly or transitively).
|
||||
|
||||
**Symptoms:**
|
||||
- Import cycle compile errors
|
||||
- Difficulty understanding code flow
|
||||
- Changes cascade unexpectedly
|
||||
|
||||
**Fix:**
|
||||
- Extract shared types to a third package
|
||||
- Use interfaces to invert dependency
|
||||
- Merge packages if truly coupled
|
||||
|
||||
### Leaky Abstractions
|
||||
|
||||
**Problem:** Implementation details leak through abstraction boundaries.
|
||||
|
||||
**Symptoms:**
|
||||
- Database types in domain layer
|
||||
- HTTP types in service layer
|
||||
- Framework types in business logic
|
||||
|
||||
**Fix:** Define types at each layer, map between them explicitly.
|
||||
|
||||
### Anemic Domain Model
|
||||
|
||||
**Problem:** Domain objects are just data containers, logic is elsewhere.
|
||||
|
||||
**Symptoms:**
|
||||
- Domain types have only getters/setters
|
||||
- All logic in "service" classes
|
||||
- Domain types can be in invalid states
|
||||
|
||||
**Fix:** Put behavior with data. Domain types should enforce their own invariants.
|
||||
|
||||
### Shotgun Surgery
|
||||
|
||||
**Problem:** Small changes require editing many files across packages.
|
||||
|
||||
**Symptoms:**
|
||||
- Feature adds touch 10+ files
|
||||
- Similar changes in multiple places
|
||||
- Copy-paste between packages
|
||||
|
||||
**Fix:** Consolidate related code. If things change together, they belong together.
|
||||
|
||||
### Feature Envy
|
||||
|
||||
**Problem:** Code in one package is more interested in another package's data.
|
||||
|
||||
**Symptoms:**
|
||||
- Many calls to another package's methods
|
||||
- Pulling data just to compute something
|
||||
- Logic that belongs elsewhere
|
||||
|
||||
**Fix:** Move the code to where the data lives, or extract the behavior to a shared place.
|
||||
|
||||
### Premature Abstraction
|
||||
|
||||
**Problem:** Creating interfaces and abstractions before they're needed.
|
||||
|
||||
**Symptoms:**
|
||||
- Interfaces with single implementations
|
||||
- "Factory" and "Manager" classes everywhere
|
||||
- Configuration for things that never change
|
||||
|
||||
**Fix:** Write concrete code first. Extract abstractions when you have multiple implementations or need to break dependencies.
|
||||
|
||||
### Deep Hierarchy
|
||||
|
||||
**Problem:** Excessive layers of abstraction or inheritance.
|
||||
|
||||
**Symptoms:**
|
||||
- 5+ levels of embedding/composition
|
||||
- Hard to trace code flow
|
||||
- Changes require understanding many layers
|
||||
|
||||
**Fix:** Prefer composition over inheritance. Flatten hierarchies where possible.
|
||||
349
old/skills/spawn-issues/SKILL.md
Normal file
349
old/skills/spawn-issues/SKILL.md
Normal file
@@ -0,0 +1,349 @@
|
||||
---
|
||||
name: spawn-issues
|
||||
description: Orchestrate parallel issue implementation with review cycles
|
||||
model: haiku
|
||||
argument-hint: <issue-number> [<issue-number>...]
|
||||
allowed-tools: Bash, Task, Read, TaskOutput
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Spawn Issues (Orchestrator)
|
||||
|
||||
Orchestrate parallel issue implementation: spawn workers, review PRs, fix feedback, until all approved.
|
||||
|
||||
## Arguments
|
||||
|
||||
One or more issue numbers separated by spaces: `$ARGUMENTS`
|
||||
|
||||
Example: `/spawn-issues 42 43 44`
|
||||
|
||||
## Orchestration Flow
|
||||
|
||||
```
|
||||
Concurrent Pipeline - each issue flows independently:
|
||||
|
||||
Issue #42 ──► worker ──► PR #55 ──► review ──► fix? ──► ✓
|
||||
Issue #43 ──► worker ──► PR #56 ──► review ──► ✓
|
||||
Issue #44 ──► worker ──► PR #57 ──► review ──► fix ──► ✓
|
||||
|
||||
As each step completes, immediately:
|
||||
1. Print a status update
|
||||
2. Start the next step for that issue
|
||||
|
||||
Don't wait for all workers before reviewing - pipeline each issue.
|
||||
```
|
||||
|
||||
## Status Updates
|
||||
|
||||
Print a brief status update whenever any step completes:
|
||||
|
||||
```
|
||||
[#42] Worker completed → PR #55 created
|
||||
[#43] Worker completed → PR #56 created
|
||||
[#42] Review: needs work → spawning fixer
|
||||
[#43] Review: approved ✓
|
||||
[#42] Fix completed → re-reviewing
|
||||
[#44] Worker completed → PR #57 created
|
||||
[#42] Review: approved ✓
|
||||
[#44] Review: approved ✓
|
||||
|
||||
All done! Final summary:
|
||||
| Issue | PR | Status |
|
||||
|-------|-----|----------|
|
||||
| #42 | #55 | approved |
|
||||
| #43 | #56 | approved |
|
||||
| #44 | #57 | approved |
|
||||
```
|
||||
|
||||
## Implementation
|
||||
|
||||
### Step 1: Parse and Validate
|
||||
|
||||
Parse `$ARGUMENTS` into a list of issue numbers. If empty, inform the user:
|
||||
```
|
||||
Usage: /spawn-issues <issue-number> [<issue-number>...]
|
||||
Example: /spawn-issues 42 43 44
|
||||
```
|
||||
|
||||
### Step 2: Get Repository Info and Setup Worktrees
|
||||
|
||||
```bash
|
||||
REPO_PATH=$(pwd)
|
||||
REPO_NAME=$(basename $REPO_PATH)
|
||||
|
||||
# Create parent worktrees directory
|
||||
mkdir -p "${REPO_PATH}/../worktrees"
|
||||
WORKTREES_DIR="${REPO_PATH}/../worktrees"
|
||||
```
|
||||
|
||||
For each issue, create the worktree upfront:
|
||||
```bash
|
||||
# Fetch latest from origin
|
||||
cd "${REPO_PATH}"
|
||||
git fetch origin
|
||||
|
||||
# Get issue details for branch naming
|
||||
ISSUE_TITLE=$(tea issues <ISSUE_NUMBER> | grep "TITLE" | head -1)
|
||||
BRANCH_NAME="issue-<ISSUE_NUMBER>-<kebab-title>"
|
||||
|
||||
# Create worktree for this issue
|
||||
git worktree add "${WORKTREES_DIR}/${REPO_NAME}-issue-<ISSUE_NUMBER>" \
|
||||
-b "${BRANCH_NAME}" origin/main
|
||||
```
|
||||
|
||||
Track the worktree path for each issue.
|
||||
|
||||
### Step 3: Spawn All Issue Workers
|
||||
|
||||
For each issue number, spawn a background issue-worker agent and track its task_id:
|
||||
|
||||
```
|
||||
Task tool with:
|
||||
- subagent_type: "issue-worker"
|
||||
- run_in_background: true
|
||||
- prompt: <issue-worker prompt below>
|
||||
```
|
||||
|
||||
Track state for each issue:
|
||||
```
|
||||
issues = {
|
||||
42: { task_id: "xxx", stage: "implementing", pr: null, branch: null, review_iterations: 0 },
|
||||
43: { task_id: "yyy", stage: "implementing", pr: null, branch: null, review_iterations: 0 },
|
||||
44: { task_id: "zzz", stage: "implementing", pr: null, branch: null, review_iterations: 0 },
|
||||
}
|
||||
```
|
||||
|
||||
Print initial status:
|
||||
```
|
||||
Spawned 3 issue workers:
|
||||
[#42] implementing...
|
||||
[#43] implementing...
|
||||
[#44] implementing...
|
||||
```
|
||||
|
||||
**Issue Worker Prompt:**
|
||||
```
|
||||
You are an issue-worker agent. Implement issue #<NUMBER> autonomously.
|
||||
|
||||
Context:
|
||||
- Repository path: <REPO_PATH>
|
||||
- Repository name: <REPO_NAME>
|
||||
- Issue number: <NUMBER>
|
||||
- Worktree path: <WORKTREE_PATH>
|
||||
|
||||
Process:
|
||||
1. Setup worktree:
|
||||
cd <WORKTREE_PATH>
|
||||
|
||||
2. Get issue: tea issues <NUMBER> --comments
|
||||
|
||||
3. Plan with TodoWrite, implement the changes
|
||||
|
||||
4. Commit: git add -A && git commit -m "...\n\nCloses #<NUMBER>\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
|
||||
|
||||
5. Push: git push -u origin <branch-name>
|
||||
|
||||
6. Create PR: tea pulls create --title "[Issue #<NUMBER>] <title>" --description "Closes #<NUMBER>\n\n..."
|
||||
Capture the PR number.
|
||||
|
||||
7. Cleanup: No cleanup needed - orchestrator handles worktree removal
|
||||
|
||||
8. Output EXACTLY this format (orchestrator parses it):
|
||||
ISSUE_WORKER_RESULT
|
||||
issue: <NUMBER>
|
||||
pr: <PR_NUMBER>
|
||||
branch: <branch-name>
|
||||
status: <success|partial|failed>
|
||||
title: <issue title>
|
||||
summary: <1-2 sentence description>
|
||||
|
||||
Work autonomously. If blocked, note it in PR description and report status as partial/failed.
|
||||
```
|
||||
|
||||
### Step 4: Event-Driven Pipeline
|
||||
|
||||
**Do NOT poll.** Wait for `<task-notification>` messages that arrive automatically when background tasks complete.
|
||||
|
||||
When a notification arrives:
|
||||
1. Read the output file to get the result
|
||||
2. Parse the result and print status update
|
||||
3. Spawn the next stage (reviewer/fixer) in background
|
||||
4. Continue waiting for more notifications
|
||||
|
||||
```
|
||||
On <task-notification> for task_id X:
|
||||
- Find which issue this task belongs to
|
||||
- Read output file, parse result
|
||||
- Print status update
|
||||
- If not terminal state, spawn next agent in background
|
||||
- Update issue state
|
||||
- If all issues terminal, print final summary
|
||||
```
|
||||
|
||||
**State transitions:**
|
||||
|
||||
```
|
||||
implementing → (worker done) → reviewing → (approved) → DONE
|
||||
→ (needs-work) → fixing → reviewing...
|
||||
→ (3 iterations) → needs-manual-review
|
||||
→ (worker failed) → FAILED
|
||||
```
|
||||
|
||||
**On each notification, print status:**
|
||||
|
||||
```
|
||||
[#42] Worker completed → PR #55 created, starting review
|
||||
[#43] Worker completed → PR #56 created, starting review
|
||||
[#42] Review: needs work → spawning fixer
|
||||
[#43] Review: approved ✓
|
||||
[#42] Fix completed → re-reviewing
|
||||
[#44] Worker completed → PR #57 created, starting review
|
||||
[#42] Review: approved ✓
|
||||
[#44] Review: approved ✓
|
||||
```
|
||||
|
||||
### Step 5: Spawn Reviewers and Fixers
|
||||
|
||||
When spawning reviewers/fixers, create worktrees for them and pass the path.
|
||||
|
||||
For review, create a review worktree from the PR branch:
|
||||
```bash
|
||||
cd "${REPO_PATH}"
|
||||
git fetch origin
|
||||
git worktree add "${WORKTREES_DIR}/${REPO_NAME}-review-<PR_NUMBER>" \
|
||||
origin/<BRANCH_NAME>
|
||||
```
|
||||
|
||||
Pass this worktree path to the reviewer/fixer agents.
|
||||
|
||||
**Code Reviewer:**
|
||||
```
|
||||
Task tool with:
|
||||
- subagent_type: "code-reviewer"
|
||||
- run_in_background: true
|
||||
- prompt: <code-reviewer prompt below>
|
||||
```
|
||||
|
||||
**Code Reviewer Prompt:**
|
||||
```
|
||||
You are a code-reviewer agent. Review PR #<PR_NUMBER> autonomously.
|
||||
|
||||
Context:
|
||||
- Repository path: <REPO_PATH>
|
||||
- PR number: <PR_NUMBER>
|
||||
- Worktree path: <WORKTREE_PATH>
|
||||
|
||||
Process:
|
||||
1. Move to worktree:
|
||||
cd <WORKTREE_PATH>
|
||||
|
||||
2. Get PR details: tea pulls <PR_NUMBER> --comments
|
||||
|
||||
3. Review the diff: git diff origin/main...HEAD
|
||||
|
||||
4. Analyze changes for:
|
||||
- Code quality and style
|
||||
- Potential bugs or logic errors
|
||||
- Test coverage
|
||||
- Documentation
|
||||
|
||||
5. Post review comment: tea comment <PR_NUMBER> "<review summary>"
|
||||
|
||||
6. Cleanup: No cleanup needed - orchestrator handles worktree removal
|
||||
|
||||
7. Output EXACTLY this format:
|
||||
REVIEW_RESULT
|
||||
pr: <PR_NUMBER>
|
||||
verdict: <approved|needs-work>
|
||||
summary: <1-2 sentences>
|
||||
|
||||
Work autonomously. Be constructive but thorough.
|
||||
```
|
||||
|
||||
**PR Fixer Prompt:** (see below)
|
||||
|
||||
### Step 6: Final Report
|
||||
|
||||
When all issues reach terminal state, display summary:
|
||||
|
||||
```
|
||||
All done!
|
||||
|
||||
| Issue | PR | Status |
|
||||
|-------|-----|---------------------|
|
||||
| #42 | #55 | approved |
|
||||
| #43 | #56 | approved |
|
||||
| #44 | #57 | approved |
|
||||
|
||||
3 PRs created and approved
|
||||
```
|
||||
|
||||
## PR Fixer
|
||||
|
||||
When spawning pr-fixer for a PR that needs work:
|
||||
|
||||
```
|
||||
Task tool with:
|
||||
- subagent_type: "pr-fixer"
|
||||
- run_in_background: true
|
||||
- prompt: <pr-fixer prompt below>
|
||||
```
|
||||
|
||||
**PR Fixer Prompt:**
|
||||
```
|
||||
You are a pr-fixer agent. Address review feedback on PR #<NUMBER>.
|
||||
|
||||
Context:
|
||||
- Repository path: <REPO_PATH>
|
||||
- PR number: <NUMBER>
|
||||
- Worktree path: <WORKTREE_PATH>
|
||||
|
||||
Process:
|
||||
1. Move to worktree:
|
||||
cd <WORKTREE_PATH>
|
||||
|
||||
2. Get feedback: tea pulls <NUMBER> --comments
|
||||
|
||||
3. Address each piece of feedback
|
||||
|
||||
4. Commit and push:
|
||||
git add -A && git commit -m "Address review feedback\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
|
||||
git push
|
||||
|
||||
5. Cleanup: No cleanup needed - orchestrator handles worktree removal
|
||||
|
||||
6. Output EXACTLY:
|
||||
PR_FIXER_RESULT
|
||||
pr: <NUMBER>
|
||||
status: <fixed|partial|failed>
|
||||
changes: <summary of fixes>
|
||||
|
||||
Work autonomously. If feedback is unclear, make reasonable judgment calls.
|
||||
```
|
||||
|
||||
## Worktree Cleanup
|
||||
|
||||
After all issues reach terminal state, clean up all worktrees:
|
||||
|
||||
```bash
|
||||
# Remove all worktrees created for this run
|
||||
for worktree in "${WORKTREES_DIR}"/*; do
|
||||
if [ -d "$worktree" ]; then
|
||||
cd "${REPO_PATH}"
|
||||
git worktree remove "$worktree" --force
|
||||
fi
|
||||
done
|
||||
|
||||
# Remove worktrees directory if empty
|
||||
rmdir "${WORKTREES_DIR}" 2>/dev/null || true
|
||||
```
|
||||
|
||||
**Important:** Always clean up worktrees, even if the orchestration failed partway through.
|
||||
|
||||
## Error Handling
|
||||
|
||||
- If an issue-worker fails, continue with others
|
||||
- If a review fails, mark as "review-failed" and continue
|
||||
- If pr-fixer fails after 3 iterations, mark as "needs-manual-review"
|
||||
- Always report final status even if some items failed
|
||||
- Always clean up all worktrees before exiting
|
||||
124
old/skills/spawn-pr-fixes/SKILL.md
Normal file
124
old/skills/spawn-pr-fixes/SKILL.md
Normal file
@@ -0,0 +1,124 @@
|
||||
---
|
||||
name: spawn-pr-fixes
|
||||
description: Spawn parallel background agents to address PR review feedback
|
||||
model: haiku
|
||||
argument-hint: [pr-number...]
|
||||
allowed-tools: Bash, Task, Read
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Spawn PR Fixes
|
||||
|
||||
Spawn background agents to address review feedback on multiple PRs in parallel. Each agent works in an isolated git worktree.
|
||||
|
||||
## Arguments
|
||||
|
||||
Optional PR numbers separated by spaces: `$ARGUMENTS`
|
||||
|
||||
- With arguments: `/spawn-pr-fixes 12 15 18` - fix specific PRs
|
||||
- Without arguments: `/spawn-pr-fixes` - find and fix all PRs with requested changes
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Get Repository Info
|
||||
|
||||
```bash
|
||||
REPO_PATH=$(pwd)
|
||||
REPO_NAME=$(basename $REPO_PATH)
|
||||
```
|
||||
|
||||
### Step 2: Determine PRs to Fix
|
||||
|
||||
**If PR numbers provided**: Use those directly
|
||||
|
||||
**If no arguments**: Find PRs needing work
|
||||
```bash
|
||||
# List open PRs
|
||||
tea pulls --state open
|
||||
|
||||
# For each PR, check if it has review comments requesting changes
|
||||
tea pulls <number> --comments
|
||||
```
|
||||
|
||||
Look for PRs where:
|
||||
- Review comments exist that haven't been addressed
|
||||
- PR is not approved yet
|
||||
- PR is open (not merged/closed)
|
||||
|
||||
### Step 3: For Each PR
|
||||
|
||||
1. Fetch PR title using `tea pulls <number>`
|
||||
|
||||
2. Spawn background agent using Task tool:
|
||||
```
|
||||
Task tool with:
|
||||
- subagent_type: "pr-fixer"
|
||||
- run_in_background: true
|
||||
- prompt: See agent prompt below
|
||||
```
|
||||
|
||||
### Agent Prompt
|
||||
|
||||
For each PR, use this prompt:
|
||||
|
||||
```
|
||||
You are a pr-fixer agent. Address review feedback on PR #<NUMBER> autonomously.
|
||||
|
||||
Context:
|
||||
- Repository path: <REPO_PATH>
|
||||
- Repository name: <REPO_NAME>
|
||||
- PR number: <NUMBER>
|
||||
|
||||
Instructions from @agents/pr-fixer/agent.md:
|
||||
|
||||
1. Get PR details and review comments:
|
||||
cd <REPO_PATH>
|
||||
git fetch origin
|
||||
tea pulls <NUMBER> --comments
|
||||
|
||||
2. Setup worktree from PR branch:
|
||||
git worktree add ../<REPO_NAME>-pr-<NUMBER> origin/<branch-name>
|
||||
cd ../<REPO_NAME>-pr-<NUMBER>
|
||||
git checkout <branch-name>
|
||||
|
||||
3. Analyze feedback, create todos with TodoWrite
|
||||
|
||||
4. Address each piece of feedback
|
||||
|
||||
5. Commit and push:
|
||||
git add -A && git commit with message "Address review feedback\n\n...\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
|
||||
git push
|
||||
|
||||
6. Spawn code-reviewer synchronously (NOT in background) to re-review
|
||||
|
||||
7. If needs more work, fix and re-review (max 3 iterations)
|
||||
|
||||
8. Cleanup (ALWAYS do this):
|
||||
cd <REPO_PATH> && git worktree remove ../<REPO_NAME>-pr-<NUMBER> --force
|
||||
|
||||
9. Output concise summary (5-10 lines max):
|
||||
PR #<NUMBER>: <title>
|
||||
Status: <fixed|partial|blocked>
|
||||
Feedback addressed: <count> items
|
||||
Review: <approved|needs-work|skipped>
|
||||
|
||||
Work autonomously. Make judgment calls on ambiguous feedback. If blocked, note it in a commit message.
|
||||
```
|
||||
|
||||
### Step 4: Report
|
||||
|
||||
After spawning all agents, display:
|
||||
|
||||
```
|
||||
Spawned <N> pr-fixer agents:
|
||||
|
||||
| PR | Title | Status |
|
||||
|-----|--------------------------|------------|
|
||||
| #12 | Add /commit command | spawned |
|
||||
| #15 | Add /pr command | spawned |
|
||||
| #18 | Add CI status | spawned |
|
||||
|
||||
Agents working in background. Monitor with:
|
||||
- Check PR list: tea pulls
|
||||
- Check worktrees: git worktree list
|
||||
```
|
||||
171
old/skills/update-claude-md/SKILL.md
Normal file
171
old/skills/update-claude-md/SKILL.md
Normal file
@@ -0,0 +1,171 @@
|
||||
---
|
||||
name: update-claude-md
|
||||
description: >
|
||||
Update or create CLAUDE.md with current project context. Explores the project
|
||||
and ensures organization context is present. Use when updating project docs,
|
||||
adding CLAUDE.md, or when user says /update-claude-md.
|
||||
model: haiku
|
||||
context: fork
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Update CLAUDE.md
|
||||
|
||||
@~/.claude/skills/claude-md-writing/SKILL.md
|
||||
@~/.claude/skills/repo-conventions/SKILL.md
|
||||
|
||||
Update or create CLAUDE.md for the current repository with proper organization context and current project state.
|
||||
|
||||
## Process
|
||||
|
||||
1. **Check for existing CLAUDE.md**: Look for `CLAUDE.md` in repo root
|
||||
|
||||
2. **If CLAUDE.md exists**:
|
||||
- Read current content
|
||||
- Identify which sections exist
|
||||
- Note any custom content to preserve
|
||||
|
||||
3. **Explore the project**:
|
||||
- Scan directory structure
|
||||
- Identify language/framework (go.mod, package.json, Cargo.toml, etc.)
|
||||
- Find key patterns (look for common directories, config files)
|
||||
- Check for Makefile or build scripts
|
||||
|
||||
4. **Check organization context**:
|
||||
- Does it have the "Organization Context" section?
|
||||
- Does it link to `../architecture/manifesto.md`?
|
||||
- Does it link to `../architecture/repos.md`?
|
||||
- Does it link to `./vision.md`?
|
||||
|
||||
5. **Gather missing information**:
|
||||
- If no one-line description: Ask user
|
||||
- If no architecture section: Infer from code or ask user
|
||||
|
||||
6. **Update CLAUDE.md**:
|
||||
|
||||
**Always ensure these sections exist:**
|
||||
|
||||
```markdown
|
||||
# [Project Name]
|
||||
|
||||
[One-line description]
|
||||
|
||||
## Organization Context
|
||||
|
||||
This repo is part of Flowmade. See:
|
||||
- [Organization manifesto](../architecture/manifesto.md) - who we are, what we believe
|
||||
- [Repository map](../architecture/repos.md) - how this fits in the bigger picture
|
||||
- [Vision](./vision.md) - what this specific product does
|
||||
|
||||
## Setup
|
||||
|
||||
[From existing or ask user]
|
||||
|
||||
## Project Structure
|
||||
|
||||
[Generate from actual directory scan]
|
||||
|
||||
## Development
|
||||
|
||||
[From Makefile or existing]
|
||||
|
||||
## Architecture
|
||||
|
||||
[From existing or infer from code patterns]
|
||||
```
|
||||
|
||||
7. **Preserve custom content**:
|
||||
- Keep any additional sections the user added
|
||||
- Don't remove information, only add/update
|
||||
- If unsure, ask before removing
|
||||
|
||||
8. **Show diff and confirm**:
|
||||
- Show what will change
|
||||
- Ask user to confirm before writing
|
||||
|
||||
## Section-Specific Guidance
|
||||
|
||||
### Project Structure
|
||||
|
||||
Generate from actual directory scan:
|
||||
```bash
|
||||
# Scan top-level and key subdirectories
|
||||
ls -la
|
||||
ls pkg/ cmd/ internal/ src/ (as applicable)
|
||||
```
|
||||
|
||||
Format as tree showing purpose:
|
||||
```markdown
|
||||
## Project Structure
|
||||
|
||||
\`\`\`
|
||||
project/
|
||||
├── cmd/ # Entry points
|
||||
├── pkg/ # Shared packages
|
||||
│ ├── domain/ # Business logic
|
||||
│ └── infra/ # Infrastructure
|
||||
└── internal/ # Private packages
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### Development Commands
|
||||
|
||||
Extract from Makefile if present:
|
||||
```bash
|
||||
grep -E "^[a-zA-Z_-]+:" Makefile | head -10
|
||||
```
|
||||
|
||||
Or from package.json scripts, Cargo.toml, etc.
|
||||
|
||||
### Architecture
|
||||
|
||||
Look for patterns:
|
||||
- Event sourcing: Check for aggregates, events, projections
|
||||
- Clean architecture: Check for domain, application, infrastructure layers
|
||||
- API style: REST, gRPC, GraphQL
|
||||
|
||||
If unsure, ask: "What are the key architectural patterns in this project?"
|
||||
|
||||
## Output Example
|
||||
|
||||
```
|
||||
## Updating CLAUDE.md
|
||||
|
||||
### Current State
|
||||
- Has description: ✓
|
||||
- Has org context: ✗ (will add)
|
||||
- Has setup: ✓
|
||||
- Has structure: Outdated (will update)
|
||||
- Has development: ✓
|
||||
- Has architecture: ✗ (will add)
|
||||
|
||||
### Changes
|
||||
|
||||
+ Adding Organization Context section
|
||||
~ Updating Project Structure (new directories found)
|
||||
+ Adding Architecture section
|
||||
|
||||
### New Project Structure
|
||||
|
||||
\`\`\`
|
||||
arcadia/
|
||||
├── cmd/
|
||||
├── pkg/
|
||||
│ ├── aether/ # Event sourcing runtime
|
||||
│ ├── iris/ # WASM UI framework
|
||||
│ ├── adl/ # Domain language
|
||||
│ └── ...
|
||||
└── internal/
|
||||
\`\`\`
|
||||
|
||||
Proceed with update? [y/n]
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Always add Organization Context if missing
|
||||
- Preserve existing custom sections
|
||||
- Update Project Structure from actual filesystem
|
||||
- Don't guess at Architecture - ask if unclear
|
||||
- Show changes before writing
|
||||
- Reference claude-md-writing skill for best practices
|
||||
284
old/skills/vision-management/SKILL.md
Normal file
284
old/skills/vision-management/SKILL.md
Normal file
@@ -0,0 +1,284 @@
|
||||
---
|
||||
name: vision-management
|
||||
model: haiku
|
||||
description: Create, maintain, and evolve organization manifesto and product visions. Use when working with manifesto.md, vision.md, milestones, or aligning work with organizational direction.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Vision Management
|
||||
|
||||
How to create, maintain, and evolve organizational direction at two levels: manifesto (organization) and vision (product).
|
||||
|
||||
## Architecture
|
||||
|
||||
| Level | Document | Purpose | Command | Location |
|
||||
|-------|----------|---------|---------|----------|
|
||||
| **Organization** | `manifesto.md` | Identity, shared personas, beliefs, principles | `/manifesto` | `../architecture/` (sibling repo) |
|
||||
| **Product** | `vision.md` | Product-specific personas, jobs, solution | `/vision` | Product repo root |
|
||||
| **Goals** | Gitea milestones | Measurable progress toward vision | `/vision goals` | Per repo |
|
||||
|
||||
Product vision **inherits from and extends** the organization manifesto - it should never duplicate.
|
||||
|
||||
---
|
||||
|
||||
## Manifesto (Organization Level)
|
||||
|
||||
The manifesto defines who we are as an organization. It lives in the architecture repo and applies across all products.
|
||||
|
||||
### Manifesto Structure
|
||||
|
||||
```markdown
|
||||
# Manifesto
|
||||
|
||||
## Who We Are
|
||||
Organization identity - what makes us unique.
|
||||
|
||||
## Who We Serve
|
||||
Shared personas across all products.
|
||||
- **Persona Name**: Description, context, constraints
|
||||
|
||||
## What They're Trying to Achieve
|
||||
Jobs to be done at the organization level.
|
||||
- "Help me [outcome] without [pain]"
|
||||
|
||||
## What We Believe
|
||||
Core beliefs that guide how we work.
|
||||
### [Belief Category]
|
||||
- Belief point
|
||||
- Belief point
|
||||
|
||||
## Guiding Principles
|
||||
Decision-making rules that apply everywhere.
|
||||
1. **Principle**: Explanation
|
||||
|
||||
## Non-Goals
|
||||
What the organization explicitly does NOT do.
|
||||
- **Non-goal**: Why
|
||||
```
|
||||
|
||||
### When to Update Manifesto
|
||||
|
||||
- **Rarely** - this is foundational identity
|
||||
- When core beliefs change
|
||||
- When adding/removing personas served
|
||||
- When adding non-goals based on learnings
|
||||
|
||||
### Creating a Manifesto
|
||||
|
||||
1. Define organization identity (Who We Are)
|
||||
2. Identify shared personas (2-4 max)
|
||||
3. Articulate organization-level jobs to be done
|
||||
4. Document core beliefs (especially about AI/development)
|
||||
5. Establish guiding principles
|
||||
6. Define non-goals
|
||||
|
||||
---
|
||||
|
||||
## Vision (Product Level)
|
||||
|
||||
The vision defines what a specific product does. It lives in each product repo and **extends the manifesto**.
|
||||
|
||||
### Vision Structure
|
||||
|
||||
```markdown
|
||||
# Vision
|
||||
|
||||
This product vision builds on the [organization manifesto](../architecture/manifesto.md).
|
||||
|
||||
## Who This Product Serves
|
||||
|
||||
### [Persona Name]
|
||||
|
||||
[Product-specific description]
|
||||
|
||||
*Extends: [Org persona] (from manifesto)*
|
||||
|
||||
## What They're Trying to Achieve
|
||||
|
||||
These trace back to organization-level jobs:
|
||||
|
||||
| Product Job | Enables Org Job |
|
||||
|-------------|-----------------|
|
||||
| "[Product-specific job]" | "[Org job from manifesto]" |
|
||||
|
||||
## The Problem
|
||||
|
||||
[Pain points this product addresses]
|
||||
|
||||
## The Solution
|
||||
|
||||
[How this product solves those problems]
|
||||
|
||||
## Product Principles
|
||||
|
||||
These extend the organization's guiding principles:
|
||||
|
||||
### [Principle Name]
|
||||
|
||||
[Description]
|
||||
|
||||
*Extends: "[Org principle]"*
|
||||
|
||||
## Non-Goals
|
||||
|
||||
These extend the organization's non-goals:
|
||||
|
||||
- **[Non-goal].** [Explanation]
|
||||
|
||||
## Architecture
|
||||
|
||||
This project follows organization architecture patterns (see software-architecture skill).
|
||||
|
||||
### Alignment
|
||||
- [Which patterns we use and where]
|
||||
|
||||
### Intentional Divergences
|
||||
| Area | Standard Pattern | What We Do Instead | Why |
|
||||
|------|------------------|-------------------|-----|
|
||||
```
|
||||
|
||||
### When to Update Vision
|
||||
|
||||
- When product direction shifts
|
||||
- When adding/changing personas served by this product
|
||||
- When discovering new non-goals
|
||||
- After major learnings from retros
|
||||
|
||||
### Creating a Product Vision
|
||||
|
||||
1. **Start with the manifesto** - read it first
|
||||
2. Define product personas that extend org personas
|
||||
3. Identify product jobs that trace back to org jobs
|
||||
4. Articulate the problem this product solves
|
||||
5. Define the solution approach
|
||||
6. Set product-specific principles (noting what they extend)
|
||||
7. Document product non-goals
|
||||
8. Create initial milestones
|
||||
|
||||
---
|
||||
|
||||
## Inheritance Model
|
||||
|
||||
```
|
||||
Manifesto (org) Vision (product)
|
||||
├── Personas → Product Personas (extend with specifics)
|
||||
├── Jobs → Product Jobs (trace back to org jobs)
|
||||
├── Beliefs → (inherited, never duplicated)
|
||||
├── Principles → Product Principles (extend, note source)
|
||||
└── Non-Goals → Product Non-Goals (additive)
|
||||
```
|
||||
|
||||
### Inheritance Rules
|
||||
|
||||
| Component | Rule | Format |
|
||||
|-----------|------|--------|
|
||||
| **Personas** | Extend with product-specific context | `*Extends: [Org persona] (from manifesto)*` |
|
||||
| **Jobs** | Trace back to org-level jobs | Table with Product Job → Org Job columns |
|
||||
| **Beliefs** | Inherited automatically | Never include in vision |
|
||||
| **Principles** | Add product-specific, note what they extend | `*Extends: "[Org principle]"*` |
|
||||
| **Non-Goals** | Additive | Org non-goals apply automatically |
|
||||
|
||||
### Example
|
||||
|
||||
**Manifesto** (organization):
|
||||
```markdown
|
||||
## Who We Serve
|
||||
- **Agencies & Consultancies**: Teams building solutions for clients
|
||||
```
|
||||
|
||||
**Vision** (product - architecture tooling):
|
||||
```markdown
|
||||
## Who This Product Serves
|
||||
|
||||
### Flowmade Developers
|
||||
|
||||
The team building Flowmade's platform. They need efficient, consistent AI workflows.
|
||||
|
||||
*Extends: Agencies & Consultancies (from manifesto) - we are our own first customer.*
|
||||
```
|
||||
|
||||
The product persona extends the org persona with product-specific context and explicitly notes the connection.
|
||||
|
||||
---
|
||||
|
||||
## Milestones (Goals)
|
||||
|
||||
Milestones are product-level goals that track progress toward the vision.
|
||||
|
||||
### Good Milestones
|
||||
|
||||
- Specific and measurable
|
||||
- Tied to a persona and job to be done
|
||||
- Outcome-focused (not activity-focused)
|
||||
- Include success criteria in description
|
||||
|
||||
```bash
|
||||
tea milestones create --title "Automate routine git workflows" \
|
||||
--description "For: Solo developer
|
||||
Job: Ship without context switching to git commands
|
||||
Success: /commit and /pr commands handle 80% of workflows"
|
||||
```
|
||||
|
||||
### Milestone-to-Vision Alignment
|
||||
|
||||
Every milestone should trace to:
|
||||
- A persona (from vision, which extends manifesto)
|
||||
- A job to be done (from vision, which traces to manifesto)
|
||||
- A measurable outcome
|
||||
|
||||
---
|
||||
|
||||
## Aligning Issues with Vision
|
||||
|
||||
When creating or reviewing issues:
|
||||
|
||||
1. **Check persona alignment**: Which persona does this serve?
|
||||
2. **Check job alignment**: Which job to be done does this enable?
|
||||
3. **Check milestone alignment**: Does this issue support a goal?
|
||||
4. **Assign to milestone**: Link the issue to the relevant goal
|
||||
|
||||
Every issue should trace back to: "This helps [persona] achieve [job] by [outcome]."
|
||||
|
||||
### Identifying Gaps
|
||||
|
||||
- **Underserved personas**: Which personas have few milestones/issues?
|
||||
- **Unaddressed jobs**: Which jobs to be done have no work toward them?
|
||||
- **Empty milestones**: Which milestones have no issues?
|
||||
- **Orphan issues**: Issues without a milestone need justification
|
||||
|
||||
---
|
||||
|
||||
## Continuous Improvement Loop
|
||||
|
||||
```
|
||||
Manifesto → Vision → Milestones → Issues → Work → Retro → (updates)
|
||||
↓
|
||||
Architecture repo issues
|
||||
↓
|
||||
Encoded into learnings +
|
||||
skills/commands/agents
|
||||
```
|
||||
|
||||
1. **Manifesto** defines organizational identity (very stable)
|
||||
2. **Vision** defines product direction, extends manifesto (stable)
|
||||
3. **Milestones** define measurable goals (evolve)
|
||||
4. **Issues** are work items toward goals
|
||||
5. **Work** implements the issues
|
||||
6. **Retros** create issues on architecture repo
|
||||
7. **Encoding** turns insights into learnings and system improvements
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Question | Answer |
|
||||
|----------|--------|
|
||||
| Where do shared personas live? | `manifesto.md` in architecture repo |
|
||||
| Where do product personas live? | `vision.md` in product repo (extend org personas) |
|
||||
| Where do beliefs live? | `manifesto.md` only (inherited, never duplicated) |
|
||||
| Where do goals live? | Gitea milestones (per repo) |
|
||||
| What command for org vision? | `/manifesto` |
|
||||
| What command for product vision? | `/vision` |
|
||||
| What repo for learnings? | Architecture repo |
|
||||
| How do product jobs relate to org jobs? | They trace back (show in table) |
|
||||
| How do product principles relate? | They extend (note the source) |
|
||||
214
old/skills/vision/SKILL.md
Normal file
214
old/skills/vision/SKILL.md
Normal file
@@ -0,0 +1,214 @@
|
||||
---
|
||||
name: vision
|
||||
description: >
|
||||
View the product vision and goal progress. Manages vision.md and Gitea milestones.
|
||||
Use when viewing vision, managing goals, or when user says /vision.
|
||||
model: haiku
|
||||
argument-hint: [goals]
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Product Vision
|
||||
|
||||
@~/.claude/skills/vision-management/SKILL.md
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
|
||||
This skill manages **product-level** vision. For organization-level vision, use `/manifesto`.
|
||||
|
||||
## Architecture
|
||||
|
||||
| Level | Document | Purpose | Skill |
|
||||
|-------|----------|---------|-------|
|
||||
| **Organization** | `manifesto.md` | Who we are, shared personas, beliefs | `/manifesto` |
|
||||
| **Product** | `vision.md` | Product-specific personas, jobs, solution | `/vision` |
|
||||
| **Goals** | Gitea milestones | Measurable progress toward vision | `/vision goals` |
|
||||
|
||||
Product vision **inherits from and extends** the organization manifesto - it should never duplicate.
|
||||
|
||||
## Manifesto Location
|
||||
|
||||
The manifesto lives in the sibling `architecture` repo:
|
||||
|
||||
```
|
||||
org/
|
||||
├── architecture/
|
||||
│ └── manifesto.md ← organization manifesto
|
||||
├── product-a/
|
||||
│ └── vision.md ← extends ../architecture/manifesto.md
|
||||
└── product-b/
|
||||
└── vision.md
|
||||
```
|
||||
|
||||
Look for manifesto in this order:
|
||||
1. `./manifesto.md` (if this IS the architecture repo)
|
||||
2. `../architecture/manifesto.md` (sibling repo)
|
||||
|
||||
## Process
|
||||
|
||||
1. **Load organization context**: Find and read `manifesto.md` using the location rules above
|
||||
- Extract personas (Who We Serve)
|
||||
- Extract jobs to be done (What They're Trying to Achieve)
|
||||
- Extract guiding principles
|
||||
- Extract non-goals
|
||||
- If not found, warn and continue without inheritance context
|
||||
|
||||
2. **Check for product vision**: Look for `vision.md` in the current repo root
|
||||
|
||||
3. **If no vision exists**:
|
||||
- Show the organization manifesto summary
|
||||
- Ask if the user wants to create a product vision
|
||||
- Guide them through defining (with inheritance):
|
||||
|
||||
**Who This Product Serves**
|
||||
- Show manifesto personas first
|
||||
- Ask: "Which personas does this product serve? How does it extend or specialize them?"
|
||||
- Product personas should reference org personas with product-specific context
|
||||
|
||||
**What They're Trying to Achieve**
|
||||
- Show manifesto jobs first
|
||||
- Ask: "What product-specific jobs does this enable? How do they trace back to org jobs?"
|
||||
- Use a table format showing the connection
|
||||
|
||||
**The Problem**
|
||||
- What pain points does this product solve?
|
||||
|
||||
**The Solution**
|
||||
- How does this product address those jobs?
|
||||
|
||||
**Product Principles**
|
||||
- Show manifesto principles first
|
||||
- Ask: "Any product-specific principles? These should extend, not duplicate."
|
||||
- Each principle should note what org principle it extends
|
||||
|
||||
**Product Non-Goals**
|
||||
- Show manifesto non-goals first
|
||||
- Ask: "Any product-specific non-goals?"
|
||||
- Org non-goals apply automatically
|
||||
|
||||
- Create `vision.md` with proper inheritance markers
|
||||
- Ask about initial goals, create as Gitea milestones
|
||||
|
||||
4. **If vision exists**:
|
||||
- Display organization context summary
|
||||
- Display the product vision from `vision.md`
|
||||
- Validate inheritance (warn if vision duplicates rather than extends)
|
||||
- Show current milestones and their progress: `tea milestones`
|
||||
- Check if `$1` specifies an action:
|
||||
- `goals`: Manage milestones (add, close, view progress)
|
||||
- If no action specified, just display the current state
|
||||
|
||||
5. **Managing Goals (milestones)**:
|
||||
```bash
|
||||
# List milestones with progress
|
||||
tea milestones
|
||||
|
||||
# Create a new goal
|
||||
tea milestones create --title "<goal>" --description "For: <persona>
|
||||
Job: <job to be done>
|
||||
Success: <criteria>"
|
||||
|
||||
# View issues in a milestone
|
||||
tea milestones issues <milestone-name>
|
||||
|
||||
# Close a completed goal
|
||||
tea milestones close <milestone-name>
|
||||
```
|
||||
|
||||
## Vision Structure Template
|
||||
|
||||
```markdown
|
||||
# Vision
|
||||
|
||||
This product vision builds on the [organization manifesto](../architecture/manifesto.md).
|
||||
|
||||
## Who This Product Serves
|
||||
|
||||
### [Persona Name]
|
||||
|
||||
[Product-specific description]
|
||||
|
||||
*Extends: [Org persona] (from manifesto)*
|
||||
|
||||
## What They're Trying to Achieve
|
||||
|
||||
These trace back to organization-level jobs:
|
||||
|
||||
| Product Job | Enables Org Job |
|
||||
|-------------|-----------------|
|
||||
| "[Product-specific job]" | "[Org job from manifesto]" |
|
||||
|
||||
## The Problem
|
||||
|
||||
[Pain points this product addresses]
|
||||
|
||||
## The Solution
|
||||
|
||||
[How this product solves those problems]
|
||||
|
||||
## Product Principles
|
||||
|
||||
These extend the organization's guiding principles:
|
||||
|
||||
### [Principle Name]
|
||||
|
||||
[Description]
|
||||
|
||||
*Extends: "[Org principle]"*
|
||||
|
||||
## Non-Goals
|
||||
|
||||
These extend the organization's non-goals:
|
||||
|
||||
- **[Non-goal].** [Explanation]
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
```
|
||||
## Organization Context
|
||||
|
||||
From manifesto.md:
|
||||
- **Personas**: [list from manifesto]
|
||||
- **Core beliefs**: [key beliefs]
|
||||
- **Principles**: [list]
|
||||
|
||||
## Product: [Name]
|
||||
|
||||
### Who This Product Serves
|
||||
|
||||
- **[Persona 1]**: [Product-specific description]
|
||||
↳ Extends: [Org persona]
|
||||
|
||||
### What They're Trying to Achieve
|
||||
|
||||
| Product Job | → Org Job |
|
||||
|-------------|-----------|
|
||||
| [job] | [org job it enables] |
|
||||
|
||||
### Vision Summary
|
||||
|
||||
[Problem/solution from vision.md]
|
||||
|
||||
### Goals (Milestones)
|
||||
|
||||
| Goal | For | Progress | Due |
|
||||
|------|-----|----------|-----|
|
||||
| [title] | [Persona] | 3/5 issues | [date] |
|
||||
```
|
||||
|
||||
## Inheritance Rules
|
||||
|
||||
- **Personas**: Product personas extend org personas with product-specific context
|
||||
- **Jobs**: Product jobs trace back to org-level jobs (show the connection)
|
||||
- **Beliefs**: Inherited from manifesto, never duplicated in vision
|
||||
- **Principles**: Product adds specific principles that extend org principles
|
||||
- **Non-Goals**: Product adds its own; org non-goals apply automatically
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Product vision builds on organization manifesto - extend, don't duplicate
|
||||
- Every product persona should reference which org persona it extends
|
||||
- Every product job should show which org job it enables
|
||||
- Product principles should note which org principle they extend
|
||||
- Use `/manifesto` for organization-level identity and beliefs
|
||||
- Use `/vision` for product-specific direction and goals
|
||||
24
old/skills/work-issue/SKILL.md
Normal file
24
old/skills/work-issue/SKILL.md
Normal file
@@ -0,0 +1,24 @@
|
||||
---
|
||||
name: work-issue
|
||||
description: >
|
||||
Work on a Gitea issue. Fetches issue details and sets up branch for implementation.
|
||||
Use when working on issues, implementing features, or when user says /work-issue.
|
||||
model: haiku
|
||||
argument-hint: <issue-number>
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Work on Issue #$1
|
||||
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
@~/.claude/skills/software-architecture/SKILL.md
|
||||
|
||||
1. **View the issue** with `--comments` flag to understand requirements and context
|
||||
2. **Create a branch**: `git checkout -b issue-$1-<short-kebab-title>`
|
||||
3. **Plan**: Use TodoWrite to break down the work based on acceptance criteria
|
||||
4. **Check architecture**: Review the project's vision.md Architecture section for project-specific patterns and divergences
|
||||
5. **Implement** the changes following architectural patterns (DDD, event sourcing where appropriate)
|
||||
6. **Commit** with message referencing the issue
|
||||
7. **Push** the branch to origin
|
||||
8. **Create PR** with title "[Issue #$1] <title>" and body "Closes #$1"
|
||||
9. **Auto-review**: Inform the user that auto-review is starting, then spawn the `code-reviewer` agent in background (using `run_in_background: true`) with the PR number
|
||||
Reference in New Issue
Block a user