chore: move agents and skills to old2 folder
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
156
old2/skills/SKILL.md
Normal file
156
old2/skills/SKILL.md
Normal file
@@ -0,0 +1,156 @@
|
||||
---
|
||||
name: gitea
|
||||
model: claude-haiku-4-5
|
||||
description: View, create, and manage Gitea issues and pull requests using tea CLI. Use when working with issues, PRs, viewing issue details, creating pull requests, adding comments, merging PRs, or when the user mentions tea, gitea, issue numbers, or PR numbers.
|
||||
user-invocable: false
|
||||
allowed-tools:
|
||||
- Bash(tea*)
|
||||
- Bash(jq*)
|
||||
---
|
||||
|
||||
# Gitea CLI (tea)
|
||||
|
||||
Command-line interface for Gitea repositories. Use `tea` for issue/PR management in Gitea instances.
|
||||
|
||||
**Setup required?** See [reference/setup.md](reference/setup.md) for installation and authentication.
|
||||
|
||||
## Repository Detection
|
||||
|
||||
`tea` automatically detects the repository from git remotes when run inside a git repository. Use `--remote <name>` to specify which remote to use.
|
||||
|
||||
## Issues
|
||||
|
||||
```bash
|
||||
# List issues
|
||||
tea issues # Open issues (default)
|
||||
tea issues --state all # All issues
|
||||
tea issues --state closed # Closed issues
|
||||
|
||||
# View issue details
|
||||
tea issues <number> # Full issue details
|
||||
tea issues <number> --comments # Include comments
|
||||
|
||||
# Create issue
|
||||
tea issues create --title "<title>" --description "<body>"
|
||||
tea issues create -t "<title>" -d "<body>"
|
||||
|
||||
# Edit issue
|
||||
tea issues edit <number> --title "<new-title>"
|
||||
tea issues edit <number> --description "<new-body>"
|
||||
|
||||
# Close/reopen
|
||||
tea issues close <number>
|
||||
tea issues reopen <number>
|
||||
|
||||
# Labels
|
||||
tea issues edit <number> --labels "bug,help wanted"
|
||||
|
||||
# Dependencies
|
||||
tea issues deps list <number> # List blockers for an issue
|
||||
tea issues deps add <issue> <blocker> # Add dependency (issue is blocked by blocker)
|
||||
tea issues deps add 5 3 # Issue #5 depends on #3
|
||||
tea issues deps add 5 owner/repo#3 # Cross-repo dependency
|
||||
tea issues deps remove <issue> <blocker> # Remove a dependency
|
||||
```
|
||||
|
||||
## Pull Requests
|
||||
|
||||
```bash
|
||||
# List PRs
|
||||
tea pulls # Open PRs (default)
|
||||
tea pulls --state all # All PRs
|
||||
tea pulls --state closed # Closed/merged PRs
|
||||
|
||||
# View PR
|
||||
tea pulls <number> # PR details
|
||||
tea pulls <number> --comments # Include comments
|
||||
|
||||
# View PR diff (tea doesn't have a diff command, use git)
|
||||
tea pulls checkout <number> # First checkout the PR branch
|
||||
git diff main...HEAD # Diff against main branch
|
||||
|
||||
# Create PR
|
||||
tea pulls create --title "<title>" --description "<body>"
|
||||
tea pulls create -t "<title>" -d "<body>"
|
||||
tea pulls create -t "<title>" -d "Closes #<issue>"
|
||||
tea pulls create --head <branch> --base main -t "<title>"
|
||||
|
||||
# Checkout PR locally
|
||||
tea pulls checkout <number>
|
||||
|
||||
# Review/Approve
|
||||
tea pulls approve <number> # Approve PR (LGTM)
|
||||
tea pulls reject <number> # Request changes
|
||||
tea pulls review <number> # Interactive review
|
||||
|
||||
# Merge
|
||||
tea pulls merge <number> # Default merge
|
||||
tea pulls merge <number> --style squash # Squash commits
|
||||
tea pulls merge <number> --style rebase # Rebase commits
|
||||
tea pulls merge <number> --style rebase-merge # Rebase then merge
|
||||
|
||||
# Clean up after merge
|
||||
tea pulls clean <number> # Delete local & remote branch
|
||||
```
|
||||
|
||||
## Comments
|
||||
|
||||
```bash
|
||||
# Add comment to issue or PR
|
||||
tea comment <number> "<comment body>"
|
||||
tea comment 3 "LGTM, ready to merge"
|
||||
|
||||
# Multiline comments (use quoted strings with literal newlines)
|
||||
tea comment 3 "## Review Summary
|
||||
|
||||
- Code looks good
|
||||
- Tests pass"
|
||||
```
|
||||
|
||||
> **Warning**: Do not use heredoc syntax `$(cat <<'EOF'...EOF)` with `tea comment` - it causes the command to be backgrounded and fail silently.
|
||||
|
||||
## Repository
|
||||
|
||||
```bash
|
||||
tea repos # List repos
|
||||
tea repos <owner>/<repo> # Repository info
|
||||
tea clone <owner>/<repo> # Clone repository
|
||||
```
|
||||
|
||||
## Notifications
|
||||
|
||||
```bash
|
||||
tea notifications # List notifications
|
||||
tea notifications --mine # Only participating
|
||||
```
|
||||
|
||||
## Output Formatting
|
||||
|
||||
Most commands support `--output` or `-o` flag:
|
||||
- `-o simple` - Plain text
|
||||
- `-o table` - Tabular format (default)
|
||||
- `-o json` - Machine-readable JSON
|
||||
- `-o yaml` - YAML format
|
||||
- `-o csv` - CSV format
|
||||
|
||||
## Specifying Remote/Login
|
||||
|
||||
```bash
|
||||
tea issues --remote gitea # Use specific git remote
|
||||
tea issues --login myserver # Use specific login
|
||||
tea issues -r owner/repo # Specify repo directly
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
- **View single issue**: Use `tea issues <number>` (NOT `tea issues view <number>` - there is no `view` subcommand)
|
||||
- **PR description flag**: Use `--description` or `-d` (NOT `--body` like gh CLI)
|
||||
- Always verify you're in the correct repository before running commands
|
||||
- Use `tea issues` to find issue numbers before viewing/editing
|
||||
- Reference issues in PR bodies with `Closes #N` for auto-linking
|
||||
- Use `--remote gitea` when you have multiple remotes (e.g., origin + gitea)
|
||||
- The `tea pulls checkout` command is handy for reviewing PRs locally
|
||||
|
||||
## Advanced Topics
|
||||
|
||||
- **CI/Actions debugging**: See [reference/actions-ci.md](reference/actions-ci.md)
|
||||
45
old2/skills/actions-ci.md
Normal file
45
old2/skills/actions-ci.md
Normal file
@@ -0,0 +1,45 @@
|
||||
# Gitea Actions / CI
|
||||
|
||||
Commands for debugging CI/Actions workflow failures in Gitea.
|
||||
|
||||
## Workflow Runs
|
||||
|
||||
```bash
|
||||
# List workflow runs
|
||||
tea actions runs # List all workflow runs
|
||||
tea actions runs -o json # JSON output for parsing
|
||||
```
|
||||
|
||||
## Jobs
|
||||
|
||||
```bash
|
||||
# List jobs for a run
|
||||
tea actions jobs <run-id> # Show jobs for a specific run
|
||||
tea actions jobs <run-id> -o json # JSON output
|
||||
```
|
||||
|
||||
## Logs
|
||||
|
||||
```bash
|
||||
# Get job logs
|
||||
tea actions logs <job-id> # Display logs for a job
|
||||
```
|
||||
|
||||
## Full Workflow: Find Failed Job Logs
|
||||
|
||||
```bash
|
||||
# 1. Find the run ID
|
||||
tea actions runs
|
||||
|
||||
# 2. Find the job ID from that run
|
||||
tea actions jobs <run-id>
|
||||
|
||||
# 3. View the logs
|
||||
tea actions logs <job-id>
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
- Use `-o json` with runs/jobs for programmatic parsing
|
||||
- Run IDs and Job IDs are shown in the output of the respective commands
|
||||
- Logs are displayed directly to stdout (can pipe to `grep` or save to file)
|
||||
500
old2/skills/best-practices.md
Normal file
500
old2/skills/best-practices.md
Normal file
@@ -0,0 +1,500 @@
|
||||
# Skill Authoring Best Practices
|
||||
|
||||
Based on Anthropic's latest agent skills documentation (January 2025).
|
||||
|
||||
## Core Principles
|
||||
|
||||
### Concise is Key
|
||||
|
||||
> "The context window is a public good. Default assumption: Claude is already very smart."
|
||||
|
||||
**Only add context Claude doesn't already have.**
|
||||
|
||||
**Challenge each piece of information:**
|
||||
- "Does Claude really need this explanation?"
|
||||
- "Can I assume Claude knows this?"
|
||||
- "Does this paragraph justify its token cost?"
|
||||
|
||||
**Good example (concise):**
|
||||
```markdown
|
||||
## Extract PDF text
|
||||
|
||||
Use pdfplumber:
|
||||
|
||||
\`\`\`python
|
||||
import pdfplumber
|
||||
with pdfplumber.open("file.pdf") as pdf:
|
||||
text = pdf.pages[0].extract_text()
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
**Bad example (verbose):**
|
||||
```markdown
|
||||
## Extract PDF text
|
||||
|
||||
PDF (Portable Document Format) files are a common file format that contains text,
|
||||
images, and other content. To extract text from a PDF, you'll need to use a library.
|
||||
There are many libraries available for PDF processing, but we recommend pdfplumber
|
||||
because it's easy to use and handles most cases well. First, you'll need to install
|
||||
it using pip. Then you can use the code below...
|
||||
```
|
||||
|
||||
The concise version assumes Claude knows what PDFs are and how libraries work.
|
||||
|
||||
### Set Appropriate Degrees of Freedom
|
||||
|
||||
Match the level of specificity to the task's fragility and variability.
|
||||
|
||||
#### High Freedom (Text-Based Instructions)
|
||||
|
||||
Use when multiple approaches are valid:
|
||||
|
||||
```markdown
|
||||
## Code Review Process
|
||||
|
||||
1. Analyze code structure and organization
|
||||
2. Check for potential bugs or edge cases
|
||||
3. Suggest improvements for readability
|
||||
4. Verify adherence to project conventions
|
||||
```
|
||||
|
||||
#### Medium Freedom (Templates/Pseudocode)
|
||||
|
||||
Use when there's a preferred pattern but variation is acceptable:
|
||||
|
||||
```markdown
|
||||
## Generate Report
|
||||
|
||||
Use this template and customize as needed:
|
||||
|
||||
\`\`\`python
|
||||
def generate_report(data, format="markdown", include_charts=True):
|
||||
# Process data
|
||||
# Generate output in specified format
|
||||
# Optionally include visualizations
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
#### Low Freedom (Exact Scripts)
|
||||
|
||||
Use when operations are fragile and error-prone:
|
||||
|
||||
```markdown
|
||||
## Database Migration
|
||||
|
||||
Run exactly this script:
|
||||
|
||||
\`\`\`bash
|
||||
python scripts/migrate.py --verify --backup
|
||||
\`\`\`
|
||||
|
||||
Do not modify the command or add additional flags.
|
||||
```
|
||||
|
||||
**Analogy:** Think of Claude as a robot exploring a path:
|
||||
- **Narrow bridge with cliffs**: One safe way forward. Provide specific guardrails (low freedom)
|
||||
- **Open field**: Many paths lead to success. Give general direction (high freedom)
|
||||
|
||||
### Progressive Disclosure
|
||||
|
||||
Split large skills into layers that load on-demand.
|
||||
|
||||
#### Three Levels of Loading
|
||||
|
||||
| Level | When Loaded | Token Cost | Content |
|
||||
|-------|------------|------------|---------|
|
||||
| **Level 1: Metadata** | Always (at startup) | ~100 tokens | `name` and `description` from frontmatter |
|
||||
| **Level 2: Instructions** | When skill is triggered | Under 5k tokens | SKILL.md body with instructions |
|
||||
| **Level 3: Resources** | As needed | Unlimited | Referenced files, scripts |
|
||||
|
||||
#### Organizing Large Skills
|
||||
|
||||
**Pattern 1: High-level guide with references**
|
||||
|
||||
```markdown
|
||||
# PDF Processing
|
||||
|
||||
## Quick Start
|
||||
\`\`\`python
|
||||
import pdfplumber
|
||||
with pdfplumber.open("file.pdf") as pdf:
|
||||
text = pdf.pages[0].extract_text()
|
||||
\`\`\`
|
||||
|
||||
## Advanced Features
|
||||
**Form filling**: See [FORMS.md](FORMS.md)
|
||||
**API reference**: See [REFERENCE.md](REFERENCE.md)
|
||||
**Examples**: See [EXAMPLES.md](EXAMPLES.md)
|
||||
```
|
||||
|
||||
Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
|
||||
|
||||
**Pattern 2: Domain-specific organization**
|
||||
|
||||
For skills with multiple domains:
|
||||
|
||||
```
|
||||
bigquery-skill/
|
||||
├── SKILL.md (overview and navigation)
|
||||
└── reference/
|
||||
├── finance.md (revenue, billing metrics)
|
||||
├── sales.md (opportunities, pipeline)
|
||||
├── product.md (API usage, features)
|
||||
└── marketing.md (campaigns, attribution)
|
||||
```
|
||||
|
||||
When user asks about revenue, Claude reads only `reference/finance.md`.
|
||||
|
||||
**Pattern 3: Conditional details**
|
||||
|
||||
```markdown
|
||||
# DOCX Processing
|
||||
|
||||
## Creating Documents
|
||||
Use docx-js. See [DOCX-JS.md](DOCX-JS.md).
|
||||
|
||||
## Editing Documents
|
||||
For simple edits, modify XML directly.
|
||||
|
||||
**For tracked changes**: See [REDLINING.md](REDLINING.md)
|
||||
**For OOXML details**: See [OOXML.md](OOXML.md)
|
||||
```
|
||||
|
||||
#### Avoid Deeply Nested References
|
||||
|
||||
**Keep references one level deep from SKILL.md.**
|
||||
|
||||
**Bad (too deep):**
|
||||
```
|
||||
SKILL.md → advanced.md → details.md → actual info
|
||||
```
|
||||
|
||||
**Good (one level):**
|
||||
```
|
||||
SKILL.md → {advanced.md, reference.md, examples.md}
|
||||
```
|
||||
|
||||
#### Structure Longer Files with TOC
|
||||
|
||||
For reference files >100 lines, include a table of contents:
|
||||
|
||||
```markdown
|
||||
# API Reference
|
||||
|
||||
## Contents
|
||||
- Authentication and setup
|
||||
- Core methods (create, read, update, delete)
|
||||
- Advanced features (batch operations, webhooks)
|
||||
- Error handling patterns
|
||||
- Code examples
|
||||
|
||||
## Authentication and Setup
|
||||
...
|
||||
```
|
||||
|
||||
This ensures Claude can see the full scope even with partial reads.
|
||||
|
||||
## Script Bundling
|
||||
|
||||
### When to Bundle Scripts
|
||||
|
||||
Bundle scripts for:
|
||||
- **Error-prone operations**: Complex bash with retry logic
|
||||
- **Fragile sequences**: Operations requiring exact order
|
||||
- **Validation steps**: Checking conditions before proceeding
|
||||
- **Reusable utilities**: Operations used in multiple steps
|
||||
|
||||
**Benefits of bundled scripts:**
|
||||
- More reliable than generated code
|
||||
- Save tokens (no code in context)
|
||||
- Save time (no code generation)
|
||||
- Ensure consistency
|
||||
|
||||
### Script Structure
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# script-name.sh - Brief description
|
||||
#
|
||||
# Usage: script-name.sh <param1> <param2>
|
||||
#
|
||||
# Example: script-name.sh issue-42 "Fix bug"
|
||||
|
||||
set -e # Exit on error
|
||||
|
||||
# Input validation
|
||||
if [ $# -lt 2 ]; then
|
||||
echo "Usage: $0 <param1> <param2>"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
param1=$1
|
||||
param2=$2
|
||||
|
||||
# Main logic with error handling
|
||||
if ! some_command; then
|
||||
echo "ERROR: Command failed"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Success output
|
||||
echo "SUCCESS: Operation completed"
|
||||
```
|
||||
|
||||
### Referencing Scripts in Skills
|
||||
|
||||
**Make clear whether to execute or read:**
|
||||
|
||||
**Execute (most common):**
|
||||
```markdown
|
||||
7. **Create PR**: `./scripts/create-pr.sh $1 "$title"`
|
||||
```
|
||||
|
||||
**Read as reference (for understanding complex logic):**
|
||||
```markdown
|
||||
See `./scripts/analyze-form.py` for the field extraction algorithm
|
||||
```
|
||||
|
||||
### Solving, Not Punting
|
||||
|
||||
Scripts should handle error conditions, not punt to Claude.
|
||||
|
||||
**Good (handles errors):**
|
||||
```python
|
||||
def process_file(path):
|
||||
try:
|
||||
with open(path) as f:
|
||||
return f.read()
|
||||
except FileNotFoundError:
|
||||
print(f"File {path} not found, creating default")
|
||||
with open(path, 'w') as f:
|
||||
f.write('')
|
||||
return ''
|
||||
except PermissionError:
|
||||
print(f"Cannot access {path}, using default")
|
||||
return ''
|
||||
```
|
||||
|
||||
**Bad (punts to Claude):**
|
||||
```python
|
||||
def process_file(path):
|
||||
return open(path).read() # Fails, Claude has to figure it out
|
||||
```
|
||||
|
||||
## Workflow Patterns
|
||||
|
||||
### Plan-Validate-Execute
|
||||
|
||||
Add verification checkpoints to catch errors early.
|
||||
|
||||
**Example: Workflow with validation**
|
||||
|
||||
```markdown
|
||||
## PDF Form Filling
|
||||
|
||||
Copy this checklist:
|
||||
|
||||
\`\`\`
|
||||
Progress:
|
||||
- [ ] Step 1: Analyze form (run analyze_form.py)
|
||||
- [ ] Step 2: Create field mapping (edit fields.json)
|
||||
- [ ] Step 3: Validate mapping (run validate_fields.py)
|
||||
- [ ] Step 4: Fill form (run fill_form.py)
|
||||
- [ ] Step 5: Verify output (run verify_output.py)
|
||||
\`\`\`
|
||||
|
||||
**Step 1: Analyze**
|
||||
Run: `python scripts/analyze_form.py input.pdf`
|
||||
|
||||
**Step 2: Create Mapping**
|
||||
Edit `fields.json`
|
||||
|
||||
**Step 3: Validate**
|
||||
Run: `python scripts/validate_fields.py fields.json`
|
||||
Fix any errors before continuing.
|
||||
|
||||
**Step 4: Fill**
|
||||
Run: `python scripts/fill_form.py input.pdf fields.json output.pdf`
|
||||
|
||||
**Step 5: Verify**
|
||||
Run: `python scripts/verify_output.py output.pdf`
|
||||
If verification fails, return to Step 2.
|
||||
```
|
||||
|
||||
### Feedback Loops
|
||||
|
||||
**Pattern:** Run validator → fix errors → repeat
|
||||
|
||||
**Example: Document editing**
|
||||
|
||||
```markdown
|
||||
1. Make edits to `word/document.xml`
|
||||
2. **Validate**: `python scripts/validate.py unpacked_dir/`
|
||||
3. If validation fails:
|
||||
- Review error message
|
||||
- Fix issues
|
||||
- Run validation again
|
||||
4. **Only proceed when validation passes**
|
||||
5. Rebuild: `python scripts/pack.py unpacked_dir/ output.docx`
|
||||
6. Test output document
|
||||
```
|
||||
|
||||
## Model Selection
|
||||
|
||||
### Decision Framework
|
||||
|
||||
```
|
||||
Start with Haiku
|
||||
|
|
||||
v
|
||||
Test on 3-5 representative tasks
|
||||
|
|
||||
+-- Success rate ≥80%? ---------> Use Haiku ✓
|
||||
|
|
||||
+-- Success rate <80%? --------> Try Sonnet
|
||||
|
|
||||
v
|
||||
Test on same tasks
|
||||
|
|
||||
+-- Success ≥80%? --> Use Sonnet
|
||||
|
|
||||
+-- Still failing? --> Opus or redesign task
|
||||
```
|
||||
|
||||
### Haiku Works Well When
|
||||
|
||||
- **Steps are simple and validated**
|
||||
- **Instructions are concise** (no verbose explanations)
|
||||
- **Error-prone operations use scripts** (deterministic)
|
||||
- **Outputs have structured templates**
|
||||
- **Checklists replace open-ended judgment**
|
||||
|
||||
### Testing with Multiple Models
|
||||
|
||||
Test skills with all models you plan to use:
|
||||
|
||||
1. **Create test cases:** 3-5 representative scenarios
|
||||
2. **Run with Haiku:** Measure success rate, response quality
|
||||
3. **Run with Sonnet:** Compare results
|
||||
4. **Adjust instructions:** If Haiku struggles, add clarity or scripts
|
||||
|
||||
What works for Opus might need more detail for Haiku.
|
||||
|
||||
## Common Anti-Patterns
|
||||
|
||||
### Offering Too Many Options
|
||||
|
||||
**Bad (confusing):**
|
||||
```markdown
|
||||
You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or...
|
||||
```
|
||||
|
||||
**Good (provide default):**
|
||||
```markdown
|
||||
Use pdfplumber for text extraction:
|
||||
\`\`\`python
|
||||
import pdfplumber
|
||||
\`\`\`
|
||||
|
||||
For scanned PDFs requiring OCR, use pdf2image with pytesseract instead.
|
||||
```
|
||||
|
||||
### Time-Sensitive Information
|
||||
|
||||
**Bad (will become wrong):**
|
||||
```markdown
|
||||
If you're doing this before August 2025, use the old API.
|
||||
After August 2025, use the new API.
|
||||
```
|
||||
|
||||
**Good (use "old patterns" section):**
|
||||
```markdown
|
||||
## Current Method
|
||||
Use the v2 API: `api.example.com/v2/messages`
|
||||
|
||||
## Old Patterns
|
||||
<details>
|
||||
<summary>Legacy v1 API (deprecated 2025-08)</summary>
|
||||
|
||||
The v1 API used: `api.example.com/v1/messages`
|
||||
This endpoint is no longer supported.
|
||||
</details>
|
||||
```
|
||||
|
||||
### Inconsistent Terminology
|
||||
|
||||
**Good (consistent):**
|
||||
- Always "API endpoint"
|
||||
- Always "field"
|
||||
- Always "extract"
|
||||
|
||||
**Bad (inconsistent):**
|
||||
- Mix "API endpoint", "URL", "API route", "path"
|
||||
- Mix "field", "box", "element", "control"
|
||||
- Mix "extract", "pull", "get", "retrieve"
|
||||
|
||||
### Windows-Style Paths
|
||||
|
||||
Always use forward slashes:
|
||||
|
||||
- ✓ **Good**: `scripts/helper.py`, `reference/guide.md`
|
||||
- ✗ **Bad**: `scripts\helper.py`, `reference\guide.md`
|
||||
|
||||
Unix-style paths work cross-platform.
|
||||
|
||||
## Iterative Development
|
||||
|
||||
### Build Evaluations First
|
||||
|
||||
Create test cases BEFORE extensive documentation:
|
||||
|
||||
1. **Identify gaps**: Run Claude on tasks without skill, document failures
|
||||
2. **Create evaluations**: Build 3-5 test scenarios
|
||||
3. **Establish baseline**: Measure Claude's performance without skill
|
||||
4. **Write minimal instructions**: Just enough to pass evaluations
|
||||
5. **Iterate**: Execute evaluations, refine
|
||||
|
||||
### Develop Iteratively with Claude
|
||||
|
||||
**Use Claude to help write skills:**
|
||||
|
||||
1. **Complete a task without skill**: Work through problem, note what context you provide
|
||||
2. **Identify reusable pattern**: What context is useful for similar tasks?
|
||||
3. **Ask Claude to create skill**: "Create a skill that captures this pattern"
|
||||
4. **Review for conciseness**: Remove unnecessary explanations
|
||||
5. **Test on similar tasks**: Use skill with fresh Claude instance
|
||||
6. **Iterate based on observation**: Where does Claude struggle?
|
||||
|
||||
Claude understands skill format natively - no special prompts needed.
|
||||
|
||||
## Checklist for Effective Skills
|
||||
|
||||
**Before publishing:**
|
||||
|
||||
### Core Quality
|
||||
- [ ] Description is specific and includes key terms
|
||||
- [ ] Description includes what skill does AND when to use it
|
||||
- [ ] SKILL.md body under 500 lines
|
||||
- [ ] Additional details in separate files (if needed)
|
||||
- [ ] No time-sensitive information
|
||||
- [ ] Consistent terminology throughout
|
||||
- [ ] Examples are concrete, not abstract
|
||||
- [ ] File references are one level deep
|
||||
- [ ] Progressive disclosure used appropriately
|
||||
- [ ] Workflows have clear steps
|
||||
|
||||
### Code and Scripts
|
||||
- [ ] Scripts solve problems, don't punt to Claude
|
||||
- [ ] Error handling is explicit and helpful
|
||||
- [ ] No "magic numbers" (all values justified)
|
||||
- [ ] Required packages listed and verified
|
||||
- [ ] Scripts have clear documentation
|
||||
- [ ] No Windows-style paths (all forward slashes)
|
||||
- [ ] Validation steps for critical operations
|
||||
- [ ] Feedback loops for quality-critical tasks
|
||||
|
||||
### Testing
|
||||
- [ ] At least 3 test cases created
|
||||
- [ ] Tested with Haiku (if that's the target)
|
||||
- [ ] Tested with real usage scenarios
|
||||
- [ ] Team feedback incorporated (if applicable)
|
||||
197
old2/skills/create-capability/SKILL.md
Normal file
197
old2/skills/create-capability/SKILL.md
Normal file
@@ -0,0 +1,197 @@
|
||||
---
|
||||
name: create-capability
|
||||
description: >
|
||||
Create a new capability (skill, agent, or a cohesive set) for the architecture
|
||||
repository. Use when creating new skills, agents, extending AI workflows, or when
|
||||
user says /create-capability.
|
||||
model: claude-haiku-4-5
|
||||
argument-hint: <description>
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Create Capability
|
||||
|
||||
@~/.claude/skills/capability-writing/SKILL.md
|
||||
|
||||
Create new capabilities following latest Anthropic best practices (progressive disclosure, script bundling, Haiku-first).
|
||||
|
||||
## Process
|
||||
|
||||
1. **Understand the capability**: Analyze "$1" to understand what the user wants to build
|
||||
- What domain or workflow does this cover?
|
||||
- What user need does it address?
|
||||
- What existing capabilities might overlap?
|
||||
|
||||
2. **Determine components needed**: Based on the description, recommend which components:
|
||||
|
||||
| Pattern | When to Use |
|
||||
|---------|-------------|
|
||||
| Skill only (background) | Knowledge to apply automatically (reused across other skills) |
|
||||
| Skill only (user-invocable) | User-invoked workflow |
|
||||
| Skill + Agent | Workflow with isolated worker for complex subtasks |
|
||||
| Full set | New domain expertise + workflow + isolated work |
|
||||
|
||||
Present recommendation with reasoning:
|
||||
```
|
||||
## Recommended Components for: $1
|
||||
|
||||
Based on your description, I recommend:
|
||||
- **Skill**: `name` - [why this knowledge is needed]
|
||||
- **Agent**: `name` - [why isolation/specialization is needed] (optional)
|
||||
|
||||
Reasoning: [explain why this combination fits the need]
|
||||
```
|
||||
|
||||
3. **Analyze complexity** (NEW): For each skill, determine structure needed:
|
||||
|
||||
**Ask these questions:**
|
||||
|
||||
a) **Expected size**: Will this skill be >300 lines?
|
||||
- If NO → Simple structure (just SKILL.md)
|
||||
- If YES → Suggest progressive disclosure
|
||||
|
||||
b) **Error-prone operations**: Are there complex bash operations?
|
||||
- Check for: PR creation, worktree management, complex git operations
|
||||
- If YES → Suggest bundling scripts
|
||||
|
||||
c) **Degree of freedom**: What instruction style is appropriate?
|
||||
- Multiple valid approaches → Text instructions (high freedom)
|
||||
- Preferred pattern with variation → Templates (medium freedom)
|
||||
- Fragile operations, exact sequence → Scripts (low freedom)
|
||||
|
||||
**Present structure recommendation:**
|
||||
```
|
||||
## Recommended Structure
|
||||
|
||||
Based on complexity analysis:
|
||||
- **Size**: [Simple | Progressive disclosure]
|
||||
- **Scripts**: [None | Bundle error-prone operations]
|
||||
- **Degrees of freedom**: [High | Medium | Low]
|
||||
|
||||
Structure:
|
||||
[Show folder structure diagram]
|
||||
```
|
||||
|
||||
4. **Gather information**: For each recommended component, ask:
|
||||
|
||||
**For all components:**
|
||||
- Name (kebab-case, descriptive)
|
||||
- Description (one-line summary including trigger conditions)
|
||||
|
||||
**For Skills:**
|
||||
- What domain/knowledge does this cover?
|
||||
- What are the key concepts to teach?
|
||||
- What patterns or templates should it include?
|
||||
- Is it user-invocable (workflow) or background (reference)?
|
||||
|
||||
**For Agents:**
|
||||
- What specialized role does this fill?
|
||||
- What skills does it need?
|
||||
- Should it be read-only (no Edit/Write)?
|
||||
|
||||
5. **Select appropriate models** (UPDATED):
|
||||
|
||||
**Default to Haiku, upgrade only if needed:**
|
||||
|
||||
| Model | Use For | Cost vs Haiku |
|
||||
|-------|---------|---------------|
|
||||
| `claude-haiku-4-5` | Most skills and agents (DEFAULT) | Baseline |
|
||||
| `claude-sonnet-4-5` | When Haiku would struggle (<80% success rate) | 12x more expensive |
|
||||
| `claude-opus-4-5` | Deep reasoning, architectural analysis | 60x more expensive |
|
||||
|
||||
**Ask for justification if not Haiku:**
|
||||
- "This looks like a simple workflow. Should we try Haiku first?"
|
||||
- "Does this require complex reasoning that Haiku can't handle?"
|
||||
|
||||
For each component, recommend Haiku unless there's clear reasoning for Sonnet/Opus.
|
||||
|
||||
6. **Generate files**: Create content using templates from capability-writing skill
|
||||
|
||||
**Structure options:**
|
||||
|
||||
a) **Simple skill** (most common):
|
||||
```
|
||||
skills/skill-name/
|
||||
└── SKILL.md
|
||||
```
|
||||
|
||||
b) **Progressive disclosure** (for large skills):
|
||||
```
|
||||
skills/skill-name/
|
||||
├── SKILL.md (~200-300 lines)
|
||||
├── reference/
|
||||
│ ├── detailed-guide.md
|
||||
│ └── api-reference.md
|
||||
└── examples/
|
||||
└── usage-examples.md
|
||||
```
|
||||
|
||||
c) **With bundled scripts** (for error-prone operations):
|
||||
```
|
||||
skills/skill-name/
|
||||
├── SKILL.md
|
||||
├── reference/
|
||||
│ └── error-handling.md
|
||||
└── scripts/
|
||||
├── validate.sh
|
||||
└── process.sh
|
||||
```
|
||||
|
||||
**Ensure proper inter-references:**
|
||||
- User-invocable skill references background skills via `@~/.claude/skills/name/SKILL.md`
|
||||
- Agent lists skills in `skills:` frontmatter (names only, not paths)
|
||||
- User-invocable skill spawns agent via Task tool if agent is part of the set
|
||||
- Scripts are called with `./scripts/script-name.sh` in SKILL.md
|
||||
|
||||
7. **Present for approval**: Show all generated files with their full content:
|
||||
```
|
||||
## Generated Files
|
||||
|
||||
### skills/name/SKILL.md
|
||||
[full content]
|
||||
|
||||
### skills/name/scripts/helper.sh (if applicable)
|
||||
[full content]
|
||||
|
||||
### agents/name/AGENT.md (if applicable)
|
||||
[full content]
|
||||
|
||||
Ready to create these files?
|
||||
```
|
||||
|
||||
8. **Create files** in correct locations after approval:
|
||||
- Create directories if needed
|
||||
- `skills/<name>/SKILL.md`
|
||||
- `skills/<name>/scripts/` (if scripts recommended)
|
||||
- `skills/<name>/reference/` (if progressive disclosure)
|
||||
- `agents/<name>/AGENT.md` (if agent recommended)
|
||||
|
||||
9. **Report success**:
|
||||
```
|
||||
## Capability Created: name
|
||||
|
||||
Files created:
|
||||
- skills/name/SKILL.md
|
||||
- skills/name/scripts/helper.sh (if applicable)
|
||||
- agents/name/AGENT.md (if applicable)
|
||||
|
||||
## Guidelines (UPDATED)
|
||||
|
||||
- Follow all conventions from capability-writing skill
|
||||
- **Default to Haiku** for all new skills/agents (12x cheaper, 2-5x faster)
|
||||
- **Bundle scripts** for error-prone bash operations
|
||||
- **Use progressive disclosure** for skills >500 lines
|
||||
- Reference existing skills rather than duplicating knowledge
|
||||
- Keep components focused - split if scope is too broad
|
||||
- User-invocable skills should have approval checkpoints
|
||||
- Skills should have descriptive `description` fields with trigger conditions
|
||||
- **Be concise** - assume Claude knows basics
|
||||
|
||||
## Output Style
|
||||
|
||||
Be concise and direct:
|
||||
- No preambles ("I'll help you...")
|
||||
- No sign-offs ("Let me know...")
|
||||
- Show structure diagrams clearly
|
||||
- Use tables for comparisons
|
||||
- One decision per section
|
||||
249
old2/skills/create-milestones/SKILL.md
Normal file
249
old2/skills/create-milestones/SKILL.md
Normal file
@@ -0,0 +1,249 @@
|
||||
---
|
||||
name: create-milestones
|
||||
description: >
|
||||
Analyze existing Gitea issues and group into value-based milestones. Creates
|
||||
milestones, assigns issues, applies value/risk labels. Use when organizing
|
||||
backlog by capability, or when user says /create-milestones.
|
||||
model: claude-haiku-4-5
|
||||
argument-hint:
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Create Milestones
|
||||
|
||||
@~/.claude/skills/milestone-planning/SKILL.md
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
|
||||
Analyze existing issues and organize into value-based milestones (shippable capabilities).
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Fetch Existing Issues
|
||||
|
||||
```bash
|
||||
tea issues --state open -o json
|
||||
```
|
||||
|
||||
Get all open issues from current repository.
|
||||
|
||||
Verify issues exist. If none:
|
||||
```
|
||||
No open issues found. Create issues first using /vision-to-backlog or /ddd-breakdown.
|
||||
```
|
||||
|
||||
### 2. Analyze Issues
|
||||
|
||||
Read issue details for each:
|
||||
```bash
|
||||
tea issues <number>
|
||||
```
|
||||
|
||||
**Look for:**
|
||||
- Issue titles and descriptions
|
||||
- Bounded context labels (if present)
|
||||
- Capability labels (if present)
|
||||
- User stories
|
||||
- Acceptance criteria
|
||||
- DDD guidance (aggregates, commands, events)
|
||||
|
||||
### 3. Spawn Milestone Planner
|
||||
|
||||
Use Task tool to spawn `milestone-planner` agent:
|
||||
|
||||
```
|
||||
Analyze these issues and group into value-based milestones.
|
||||
|
||||
Issues: [list of issue numbers with titles]
|
||||
|
||||
For each issue, you have access to:
|
||||
- Full issue description
|
||||
- Labels
|
||||
- DDD context
|
||||
|
||||
Group issues into milestones that represent shippable business capabilities.
|
||||
|
||||
Follow milestone-planning skill principles:
|
||||
- Milestone = capability user can demo
|
||||
- 5-25 issues per milestone
|
||||
- Cross-cutting (commands + events + reads + UI)
|
||||
- Vertical slice test
|
||||
|
||||
Output:
|
||||
- Milestone definitions
|
||||
- Issue assignments
|
||||
- Value/risk labels per issue
|
||||
|
||||
Follow milestone-planner agent instructions.
|
||||
```
|
||||
|
||||
Agent returns grouped milestones.
|
||||
|
||||
### 4. Review Grouped Milestones
|
||||
|
||||
Present agent output to user:
|
||||
|
||||
```
|
||||
## Proposed Milestones
|
||||
|
||||
### Milestone: Customer can register and authenticate
|
||||
**Description:** User registration, login, and session management
|
||||
**Issues:** 8
|
||||
**Value:** high
|
||||
**Issues:**
|
||||
- #42: Implement User aggregate
|
||||
- #43: Add RegisterUser command
|
||||
- #44: Publish UserRegistered event
|
||||
- #45: Add LoginUser command
|
||||
- #46: Create UserSession read model
|
||||
- #47: Build registration form
|
||||
- #48: Build login form
|
||||
- #49: Add session middleware
|
||||
|
||||
### Milestone: Order can be placed and paid
|
||||
**Description:** Complete order placement with payment processing
|
||||
**Issues:** 12
|
||||
**Value:** high
|
||||
**Issues:**
|
||||
- #50: Implement Order aggregate
|
||||
- #51: Add PlaceOrder command
|
||||
...
|
||||
|
||||
[... more milestones]
|
||||
```
|
||||
|
||||
**Ask user:**
|
||||
- Approve these milestones?
|
||||
- Modify any groupings?
|
||||
- Change value/risk labels?
|
||||
|
||||
### 5. Ensure Labels Exist
|
||||
|
||||
Before creating milestones, ensure labels exist in Gitea:
|
||||
|
||||
**Check for labels:**
|
||||
```bash
|
||||
tea labels list
|
||||
```
|
||||
|
||||
**Create missing labels:**
|
||||
```bash
|
||||
# Value labels
|
||||
tea labels create "value/high" --color "#d73a4a" --description "Highest business value"
|
||||
tea labels create "value/medium" --color "#fbca04" --description "Moderate business value"
|
||||
tea labels create "value/low" --color "#0075ca" --description "Nice to have"
|
||||
|
||||
# Risk label
|
||||
tea labels create "risk/high" --color "#e99695" --description "Technical risk or uncertainty"
|
||||
```
|
||||
|
||||
### 6. Create Milestones in Gitea
|
||||
|
||||
For each approved milestone:
|
||||
|
||||
```bash
|
||||
tea milestones create \
|
||||
--title "<milestone title>" \
|
||||
--description "<milestone description>"
|
||||
```
|
||||
|
||||
Capture milestone ID/title for issue assignment.
|
||||
|
||||
### 7. Assign Issues and Apply Labels
|
||||
|
||||
**For each milestone, process all its issues:**
|
||||
|
||||
```bash
|
||||
# For each milestone:
|
||||
for milestone in milestones:
|
||||
# For each issue in this milestone:
|
||||
for issue in milestone.issues:
|
||||
# Combine milestone assignment + labels in single command
|
||||
tea issues edit <issue-number> \
|
||||
--milestone "<milestone-title>" \
|
||||
--labels "<existing-labels>,<value-label>,<risk-label-if-applicable>"
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
# Issue #42 in "Customer can register and authenticate" milestone
|
||||
tea issues edit 42 \
|
||||
--milestone "Customer can register and authenticate" \
|
||||
--labels "bounded-context/auth,value/high"
|
||||
|
||||
# Issue #43 with risk
|
||||
tea issues edit 43 \
|
||||
--milestone "Customer can register and authenticate" \
|
||||
--labels "bounded-context/auth,value/high,risk/high"
|
||||
```
|
||||
|
||||
**Important:**
|
||||
- Process one milestone at a time, all issues in that milestone
|
||||
- Preserve existing labels (bounded-context, capability, etc.)
|
||||
- Add value label for all issues
|
||||
- Add risk/high only if issue has technical risk
|
||||
- Combine milestone + labels in single `tea issues edit` command (efficient)
|
||||
|
||||
### 8. Report Results
|
||||
|
||||
Show created milestones with links:
|
||||
|
||||
```
|
||||
## Milestones Created
|
||||
|
||||
### Customer can register and authenticate (8 issues)
|
||||
- Value: high
|
||||
- Issues: #42, #43, #44, #45, #46, #47, #48, #49
|
||||
- Link: [view milestone](https://git.flowmade.one/owner/repo/milestone/1)
|
||||
|
||||
### Order can be placed and paid (12 issues)
|
||||
- Value: high
|
||||
- Issues: #50-#61
|
||||
- Link: [view milestone](https://git.flowmade.one/owner/repo/milestone/2)
|
||||
|
||||
[... more milestones]
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Review milestones** in Gitea
|
||||
2. **Activate ONE milestone** (the current value focus)
|
||||
3. **Close milestone** when capability is demoable
|
||||
4. **Pick next milestone** to activate
|
||||
|
||||
Remember: Only one open/active milestone at a time!
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
|
||||
**Value slices:**
|
||||
- Each milestone is a shippable capability
|
||||
- Can be demoed independently
|
||||
- User sees observable value
|
||||
|
||||
**One active milestone:**
|
||||
- User manually activates ONE
|
||||
- This workflow doesn't activate automatically
|
||||
- Forces focus and completion
|
||||
|
||||
**Label strategy:**
|
||||
- Every issue gets value label
|
||||
- High-risk issues get risk/high label
|
||||
- Preserves existing labels (context, capability)
|
||||
|
||||
**Sizing:**
|
||||
- 5-25 issues per milestone
|
||||
- If larger, agent should split
|
||||
- If smaller, might not need milestone
|
||||
|
||||
**No dates:**
|
||||
- Milestones are capability-based
|
||||
- Not time-based
|
||||
- Ship when done, not by deadline
|
||||
|
||||
## Tips
|
||||
|
||||
- Run after creating issues from /vision-to-backlog
|
||||
- Re-run if backlog grows and needs reorganization
|
||||
- Agent groups by capability boundaries (aggregates, contexts)
|
||||
- Review groupings - agent might miss domain nuance
|
||||
- Adjust value/risk labels based on business context
|
||||
- Keep one milestone open at all times
|
||||
47
old2/skills/dashboard/SKILL.md
Normal file
47
old2/skills/dashboard/SKILL.md
Normal file
@@ -0,0 +1,47 @@
|
||||
---
|
||||
name: dashboard
|
||||
description: >
|
||||
Display milestones with unblocked issues at a glance.
|
||||
Use when you want to see project progress and which issues are ready to work on.
|
||||
Invoke with /dashboard [milestone-name-filter]
|
||||
model: claude-haiku-4-5
|
||||
user-invocable: true
|
||||
context: fork
|
||||
allowed-tools:
|
||||
- Bash(~/.claude/skills/dashboard/scripts/generate-dashboard.sh*)
|
||||
---
|
||||
|
||||
# Dashboard
|
||||
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
|
||||
Display all milestones and their unblocked issues. Issues are considered unblocked if they have no open blockers in their dependency list.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Run the dashboard script** with the milestone filter argument (if provided):
|
||||
```bash
|
||||
~/.claude/skills/dashboard/scripts/generate-dashboard.sh "$1"
|
||||
```
|
||||
|
||||
2. **Display the output** to the user
|
||||
|
||||
The script automatically:
|
||||
- Fetches all milestones from the repository
|
||||
- For each milestone, gets all open issues
|
||||
- For each issue, checks dependencies with `tea issues deps list`
|
||||
- Categorizes issues as unblocked (no open dependencies) or blocked (has open dependencies)
|
||||
- Displays results grouped by milestone in this format:
|
||||
|
||||
```
|
||||
## Milestone: Release 1.0
|
||||
|
||||
✓ Unblocked (3):
|
||||
#42 Implement feature X
|
||||
#43 Fix bug in Y
|
||||
#45 Add tests for Z
|
||||
|
||||
⊘ Blocked (2):
|
||||
#40 Feature A (blocked by #39)
|
||||
#41 Feature B (blocked by #38, #37)
|
||||
```
|
||||
83
old2/skills/dashboard/scripts/generate-dashboard.sh
Executable file
83
old2/skills/dashboard/scripts/generate-dashboard.sh
Executable file
@@ -0,0 +1,83 @@
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
|
||||
# Generate dashboard showing milestones with unblocked/blocked issues
|
||||
# Usage: ./generate-dashboard.sh [milestone-filter]
|
||||
|
||||
MILESTONE_FILTER="${1:-}"
|
||||
|
||||
# Get all milestones
|
||||
milestones_json=$(tea milestones -o json)
|
||||
|
||||
# Parse milestone names
|
||||
milestone_names=$(echo "$milestones_json" | jq -r '.[].title')
|
||||
|
||||
# Process each milestone
|
||||
while IFS= read -r milestone; do
|
||||
# Skip if filter provided and doesn't match
|
||||
if [[ -n "$MILESTONE_FILTER" && ! "$milestone" =~ $MILESTONE_FILTER ]]; then
|
||||
continue
|
||||
fi
|
||||
|
||||
echo "## Milestone: $milestone"
|
||||
echo ""
|
||||
|
||||
# Get open issues for this milestone
|
||||
issues_json=$(tea issues --milestones "$milestone" --state open -o json 2>/dev/null || echo "[]")
|
||||
|
||||
# Skip empty milestones or invalid JSON
|
||||
issue_count=$(echo "$issues_json" | jq -e 'length' 2>/dev/null || echo "0")
|
||||
if [[ "$issue_count" -eq 0 ]]; then
|
||||
echo "No open issues"
|
||||
echo ""
|
||||
continue
|
||||
fi
|
||||
|
||||
# Arrays for categorizing issues
|
||||
declare -a unblocked=()
|
||||
declare -a blocked=()
|
||||
|
||||
# Process each issue
|
||||
while IFS=$'\t' read -r number title; do
|
||||
# Check dependencies (tea returns plain text "Issue #N has no dependencies" when empty)
|
||||
deps_output=$(tea issues deps list "$number" -o json 2>/dev/null || echo "")
|
||||
|
||||
# If output contains "has no dependencies", treat as empty array
|
||||
if [[ "$deps_output" == *"has no dependencies"* ]]; then
|
||||
deps_json="[]"
|
||||
else
|
||||
deps_json="$deps_output"
|
||||
fi
|
||||
|
||||
# Count open dependencies
|
||||
open_deps=$(echo "$deps_json" | jq -r '[.[] | select(.state == "open")] | length' 2>/dev/null || echo "0")
|
||||
|
||||
if [[ "$open_deps" -eq 0 ]]; then
|
||||
# No open blockers - unblocked
|
||||
unblocked+=("#$number $title")
|
||||
else
|
||||
# Has open blockers - blocked
|
||||
blocker_list=$(echo "$deps_json" | jq -r '[.[] | select(.state == "open") | "#\(.index)"] | join(", ")')
|
||||
blocked+=("#$number $title (blocked by $blocker_list)")
|
||||
fi
|
||||
done < <(echo "$issues_json" | jq -r '.[] | [.index, .title] | @tsv')
|
||||
|
||||
# Display unblocked issues
|
||||
echo "✓ Unblocked (${#unblocked[@]}):"
|
||||
if [[ ${#unblocked[@]} -eq 0 ]]; then
|
||||
echo " (none)"
|
||||
else
|
||||
printf ' %s\n' "${unblocked[@]}"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Display blocked issues
|
||||
echo "⊘ Blocked (${#blocked[@]}):"
|
||||
if [[ ${#blocked[@]} -eq 0 ]]; then
|
||||
echo " (none)"
|
||||
else
|
||||
printf ' %s\n' "${blocked[@]}"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
done <<< "$milestone_names"
|
||||
272
old2/skills/ddd/SKILL.md
Normal file
272
old2/skills/ddd/SKILL.md
Normal file
@@ -0,0 +1,272 @@
|
||||
---
|
||||
name: ddd
|
||||
description: >
|
||||
Domain-Driven Design concepts: bounded contexts, aggregates, commands, events,
|
||||
and tactical patterns. Use when analyzing domain models, identifying bounded
|
||||
contexts, or mapping features to DDD patterns.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Domain-Driven Design (DDD)
|
||||
|
||||
Strategic and tactical patterns for modeling complex domains.
|
||||
|
||||
## Strategic DDD: Bounded Contexts
|
||||
|
||||
### What is a Bounded Context?
|
||||
|
||||
A **bounded context** is a boundary within which a domain model is consistent. Same terms can mean different things in different contexts.
|
||||
|
||||
**Example:** "Order" means different things in different contexts:
|
||||
- **Sales Context**: Order = customer purchase with payment and shipping
|
||||
- **Fulfillment Context**: Order = pick list for warehouse
|
||||
- **Accounting Context**: Order = revenue transaction
|
||||
|
||||
### Identifying Bounded Contexts
|
||||
|
||||
Look for:
|
||||
1. **Different language**: Same term means different things
|
||||
2. **Different models**: Same concept has different attributes/behavior
|
||||
3. **Different teams**: Natural organizational boundaries
|
||||
4. **Different lifecycles**: Entities created/destroyed at different times
|
||||
5. **Different rate of change**: Some areas evolve faster than others
|
||||
|
||||
**From vision/manifesto:**
|
||||
- Identify personas → each persona likely interacts with different contexts
|
||||
- Identify core domain concepts → group related concepts into contexts
|
||||
- Identify capabilities → capabilities often align with contexts
|
||||
|
||||
**From existing code:**
|
||||
- Look for packages/modules that cluster related concepts
|
||||
- Identify seams where code is loosely coupled
|
||||
- Look for translation layers between subsystems
|
||||
- Identify areas where same terms mean different things
|
||||
|
||||
### Context Boundaries
|
||||
|
||||
**Good boundaries:**
|
||||
- Clear interfaces between contexts
|
||||
- Each context owns its data
|
||||
- Contexts communicate via events or APIs
|
||||
- Minimal coupling between contexts
|
||||
|
||||
**Bad boundaries:**
|
||||
- Shared database tables across contexts
|
||||
- Direct object references across contexts
|
||||
- Mixed concerns within a context
|
||||
|
||||
### Common Context Patterns
|
||||
|
||||
| Pattern | Description | Example |
|
||||
|---------|-------------|---------|
|
||||
| **Core Domain** | Your unique competitive advantage | Custom business logic |
|
||||
| **Supporting Subdomain** | Necessary but not differentiating | User management |
|
||||
| **Generic Subdomain** | Common problems, use off-the-shelf | Email sending, file storage |
|
||||
|
||||
## Tactical DDD: Building Blocks
|
||||
|
||||
### Aggregates
|
||||
|
||||
An **aggregate** is a cluster of entities and value objects treated as a unit for data changes.
|
||||
|
||||
**Rules:**
|
||||
- One entity is the **aggregate root** (only entity referenced from outside)
|
||||
- All changes go through the root
|
||||
- Enforce business invariants within the aggregate
|
||||
- Keep aggregates small (2-3 entities max when possible)
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Order (root)
|
||||
├── OrderLine
|
||||
├── ShippingAddress
|
||||
└── Payment
|
||||
```
|
||||
|
||||
External code only references `Order`, never `OrderLine` directly.
|
||||
|
||||
**Identifying aggregates:**
|
||||
- What entities always change together?
|
||||
- What invariants must be enforced?
|
||||
- What is the transactional boundary?
|
||||
|
||||
### Commands
|
||||
|
||||
**Commands** represent intent to change state. Named with imperative verbs.
|
||||
|
||||
**Format:** `[Verb][AggregateRoot]` or `[AggregateRoot][Verb]`
|
||||
|
||||
**Examples:**
|
||||
- `PlaceOrder` or `OrderPlace`
|
||||
- `CancelSubscription` or `SubscriptionCancel`
|
||||
- `ApproveInvoice` or `InvoiceApprove`
|
||||
|
||||
**Commands:**
|
||||
- Are handled by the aggregate root
|
||||
- Either succeed completely or fail
|
||||
- Can be rejected (return error)
|
||||
- Represent user intent or system action
|
||||
|
||||
### Events
|
||||
|
||||
**Events** represent facts that happened in the past. Named in past tense.
|
||||
|
||||
**Format:** `[AggregateRoot][PastVerb]` or `[Something]Happened`
|
||||
|
||||
**Examples:**
|
||||
- `OrderPlaced`
|
||||
- `SubscriptionCancelled`
|
||||
- `InvoiceApproved`
|
||||
- `PaymentFailed`
|
||||
|
||||
**Events:**
|
||||
- Are immutable (already happened)
|
||||
- Can be published to other contexts
|
||||
- Enable eventual consistency
|
||||
- Create audit trail
|
||||
|
||||
### Value Objects
|
||||
|
||||
**Value Objects** are immutable objects defined by their attributes, not identity.
|
||||
|
||||
**Examples:**
|
||||
- `Money` (amount + currency)
|
||||
- `EmailAddress`
|
||||
- `DateRange`
|
||||
- `Address`
|
||||
|
||||
**Characteristics:**
|
||||
- No identity (two with same values are equal)
|
||||
- Immutable (cannot change, create new instance)
|
||||
- Can contain validation logic
|
||||
- Can contain behavior
|
||||
|
||||
**When to use:**
|
||||
- Concept has no lifecycle (no create/update/delete)
|
||||
- Equality is based on attributes, not identity
|
||||
- Can be shared/reused
|
||||
|
||||
### Entities
|
||||
|
||||
**Entities** have identity that persists over time, even if attributes change.
|
||||
|
||||
**Examples:**
|
||||
- `User` (ID remains same even if name/email changes)
|
||||
- `Order` (ID remains same through lifecycle)
|
||||
- `Product` (ID remains same even if price changes)
|
||||
|
||||
**Characteristics:**
|
||||
- Has unique identifier
|
||||
- Can change over time
|
||||
- Identity matters more than attributes
|
||||
|
||||
## Mapping Features to DDD Patterns
|
||||
|
||||
### Process
|
||||
|
||||
For each feature from vision:
|
||||
|
||||
1. **Identify the bounded context**: Which context does this belong to?
|
||||
|
||||
2. **Identify the aggregate(s)**: What entities/value objects are involved?
|
||||
|
||||
3. **Identify commands**: What actions can users/systems take?
|
||||
|
||||
4. **Identify events**: What facts should be recorded when commands succeed?
|
||||
|
||||
5. **Identify value objects**: What concepts are attribute-defined, not identity-defined?
|
||||
|
||||
### Example: "User can place an order"
|
||||
|
||||
**Bounded Context:** Sales
|
||||
|
||||
**Aggregate:** `Order` (root)
|
||||
- `OrderLine` (entity)
|
||||
- `ShippingAddress` (value object)
|
||||
- `Money` (value object)
|
||||
|
||||
**Commands:**
|
||||
- `PlaceOrder`
|
||||
- `AddOrderLine`
|
||||
- `RemoveOrderLine`
|
||||
- `UpdateShippingAddress`
|
||||
|
||||
**Events:**
|
||||
- `OrderPlaced`
|
||||
- `OrderLineAdded`
|
||||
- `OrderLineRemoved`
|
||||
- `ShippingAddressUpdated`
|
||||
|
||||
**Value Objects:**
|
||||
- `Money` (amount, currency)
|
||||
- `Address` (street, city, zip, country)
|
||||
- `Quantity`
|
||||
|
||||
## Refactoring to DDD
|
||||
|
||||
When existing code doesn't follow DDD patterns:
|
||||
|
||||
### Identify Misalignments
|
||||
|
||||
**Anemic domain model:**
|
||||
- Entities with only getters/setters
|
||||
- Business logic in services, not entities
|
||||
- **Fix:** Move behavior into aggregates
|
||||
|
||||
**God objects:**
|
||||
- One entity doing too much
|
||||
- **Fix:** Split into multiple aggregates or value objects
|
||||
|
||||
**Context leakage:**
|
||||
- Same model shared across contexts
|
||||
- **Fix:** Create context-specific models with translation layers
|
||||
|
||||
**Missing boundaries:**
|
||||
- Everything in one module/package
|
||||
- **Fix:** Identify bounded contexts, separate into modules
|
||||
|
||||
### Refactoring Strategies
|
||||
|
||||
**Extract bounded context:**
|
||||
```markdown
|
||||
As a developer, I want to extract [Context] into a separate module,
|
||||
so that it has clear boundaries and can evolve independently
|
||||
```
|
||||
|
||||
**Extract aggregate:**
|
||||
```markdown
|
||||
As a developer, I want to extract [Aggregate] from [GodObject],
|
||||
so that it enforces its own invariants
|
||||
```
|
||||
|
||||
**Introduce value object:**
|
||||
```markdown
|
||||
As a developer, I want to replace [primitive] with [ValueObject],
|
||||
so that validation is centralized and the domain model is clearer
|
||||
```
|
||||
|
||||
**Introduce event:**
|
||||
```markdown
|
||||
As a developer, I want to publish [Event] when [Command] succeeds,
|
||||
so that other contexts can react to state changes
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
**Avoid:**
|
||||
- Aggregates spanning multiple bounded contexts
|
||||
- Shared mutable state across contexts
|
||||
- Direct database access across contexts
|
||||
- Aggregates with dozens of entities (too large)
|
||||
- Value objects with identity
|
||||
- Commands without clear aggregate ownership
|
||||
- Events that imply future actions (use commands)
|
||||
|
||||
## Tips
|
||||
|
||||
- Start with strategic DDD (bounded contexts) before tactical patterns
|
||||
- Bounded contexts align with team/organizational boundaries
|
||||
- Keep aggregates small (single entity when possible)
|
||||
- Use events for cross-context communication
|
||||
- Value objects make impossible states impossible
|
||||
- Refactor incrementally - don't rewrite everything at once
|
||||
129
old2/skills/examples/progressive-disclosure.md
Normal file
129
old2/skills/examples/progressive-disclosure.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# Example: Progressive Disclosure Skill
|
||||
|
||||
A skill that uses reference files to keep the main SKILL.md concise.
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
skills/database-query/
|
||||
├── SKILL.md (~200 lines)
|
||||
├── reference/
|
||||
│ ├── schemas.md (table schemas)
|
||||
│ ├── common-queries.md (frequently used queries)
|
||||
│ └── optimization-tips.md (performance guidance)
|
||||
└── examples/
|
||||
├── simple-select.md
|
||||
└── complex-join.md
|
||||
```
|
||||
|
||||
## When to Use
|
||||
|
||||
- Skill content would be >500 lines
|
||||
- Multiple domains or topics
|
||||
- Reference documentation is large
|
||||
- Want to keep main workflow concise
|
||||
|
||||
## Example: database-query (main SKILL.md)
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: database-query
|
||||
description: >
|
||||
Help users query the PostgreSQL database with proper schemas and optimization.
|
||||
Use when user needs to write SQL queries or mentions database/tables.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Database Query Helper
|
||||
|
||||
Help write efficient, correct SQL queries for our PostgreSQL database.
|
||||
|
||||
## Quick Start
|
||||
|
||||
\`\`\`sql
|
||||
SELECT id, name, created_at
|
||||
FROM users
|
||||
WHERE status = 'active'
|
||||
LIMIT 10;
|
||||
\`\`\`
|
||||
|
||||
## Table Schemas
|
||||
|
||||
We have 3 main schemas:
|
||||
|
||||
- **Users & Auth**: See [reference/schemas.md#users](reference/schemas.md#users)
|
||||
- **Products**: See [reference/schemas.md#products](reference/schemas.md#products)
|
||||
- **Orders**: See [reference/schemas.md#orders](reference/schemas.md#orders)
|
||||
|
||||
## Common Queries
|
||||
|
||||
For frequently requested queries, see [reference/common-queries.md](reference/common-queries.md):
|
||||
- User activity reports
|
||||
- Sales summaries
|
||||
- Inventory status
|
||||
|
||||
## Writing Queries
|
||||
|
||||
1. **Identify tables**: Which schemas does this query need?
|
||||
2. **Check schema**: Load relevant schema from reference
|
||||
3. **Write query**: Use proper column names and types
|
||||
4. **Optimize**: See [reference/optimization-tips.md](reference/optimization-tips.md)
|
||||
|
||||
## Examples
|
||||
|
||||
- **Simple select**: See [examples/simple-select.md](examples/simple-select.md)
|
||||
- **Complex join**: See [examples/complex-join.md](examples/complex-join.md)
|
||||
```
|
||||
|
||||
## Example: reference/schemas.md
|
||||
|
||||
```markdown
|
||||
# Database Schemas
|
||||
|
||||
## Users
|
||||
|
||||
| Column | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| id | UUID | Primary key |
|
||||
| email | VARCHAR(255) | Unique email |
|
||||
| name | VARCHAR(100) | Display name |
|
||||
| status | ENUM('active','inactive','banned') | Account status |
|
||||
| created_at | TIMESTAMP | Account creation |
|
||||
| updated_at | TIMESTAMP | Last update |
|
||||
|
||||
## Products
|
||||
|
||||
| Column | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| id | UUID | Primary key |
|
||||
| name | VARCHAR(200) | Product name |
|
||||
| price | DECIMAL(10,2) | Price in USD |
|
||||
| inventory | INTEGER | Stock count |
|
||||
| category_id | UUID | FK to categories |
|
||||
|
||||
## Orders
|
||||
|
||||
[...more tables...]
|
||||
```
|
||||
|
||||
## Why This Works
|
||||
|
||||
- **Main file stays concise** (~200 lines)
|
||||
- **Details load on-demand**: schemas.md loads when user asks about specific table
|
||||
- **Fast for common cases**: Simple queries don't need reference files
|
||||
- **Scalable**: Can add more schemas without bloating main file
|
||||
|
||||
## Loading Pattern
|
||||
|
||||
1. User: "Show me all active users"
|
||||
2. Claude reads SKILL.md (sees Users schema reference)
|
||||
3. Claude: "I'll load the users schema to get column names"
|
||||
4. Claude reads reference/schemas.md#users
|
||||
5. Claude writes correct query
|
||||
|
||||
## What Makes It Haiku-Friendly
|
||||
|
||||
- ✓ Main workflow is simple ("identify → check schema → write query")
|
||||
- ✓ Reference files provide facts, not reasoning
|
||||
- ✓ Clear pointers to where details are
|
||||
- ✓ Examples show patterns
|
||||
71
old2/skills/examples/simple-workflow.md
Normal file
71
old2/skills/examples/simple-workflow.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# Example: Simple Workflow Skill
|
||||
|
||||
A basic skill with just a SKILL.md file - no scripts or reference files needed.
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
skills/list-open-prs/
|
||||
└── SKILL.md
|
||||
```
|
||||
|
||||
## When to Use
|
||||
|
||||
- Skill is simple (<300 lines)
|
||||
- No error-prone bash operations
|
||||
- No need for reference documentation
|
||||
- Straightforward workflow
|
||||
|
||||
## Example: list-open-prs
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: list-open-prs
|
||||
description: >
|
||||
List all open pull requests for the current repository.
|
||||
Use when user wants to see PRs or says /list-open-prs.
|
||||
model: haiku
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# List Open PRs
|
||||
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
|
||||
Show all open pull requests in the current repository.
|
||||
|
||||
## Process
|
||||
|
||||
1. **Get repository info**
|
||||
- `git remote get-url origin`
|
||||
- Parse owner/repo from URL
|
||||
|
||||
2. **Fetch open PRs**
|
||||
- `tea pulls list --state open --output simple`
|
||||
|
||||
3. **Format results** as table
|
||||
|
||||
| PR # | Title | Author | Created |
|
||||
|------|-------|--------|---------|
|
||||
| ... | ... | ... | ... |
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Show most recent PRs first
|
||||
- Include link to each PR
|
||||
- If no open PRs, say "No open pull requests"
|
||||
```
|
||||
|
||||
## Why This Works
|
||||
|
||||
- **Concise**: Entire skill fits in ~30 lines
|
||||
- **Simple commands**: Just git and tea CLI
|
||||
- **No error handling needed**: tea handles errors gracefully
|
||||
- **Structured output**: Table format is clear
|
||||
|
||||
## What Makes It Haiku-Friendly
|
||||
|
||||
- ✓ Simple sequential steps
|
||||
- ✓ Clear commands with no ambiguity
|
||||
- ✓ Structured output format
|
||||
- ✓ No complex decision-making
|
||||
210
old2/skills/examples/with-scripts.md
Normal file
210
old2/skills/examples/with-scripts.md
Normal file
@@ -0,0 +1,210 @@
|
||||
# Example: Skill with Bundled Scripts
|
||||
|
||||
A skill that bundles helper scripts for error-prone operations.
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
skills/deploy-to-staging/
|
||||
├── SKILL.md
|
||||
├── reference/
|
||||
│ └── rollback-procedure.md
|
||||
└── scripts/
|
||||
├── validate-build.sh
|
||||
├── deploy.sh
|
||||
└── health-check.sh
|
||||
```
|
||||
|
||||
## When to Use
|
||||
|
||||
- Operations have complex error handling
|
||||
- Need retry logic
|
||||
- Multiple validation steps
|
||||
- Fragile bash commands
|
||||
|
||||
## Example: deploy-to-staging (main SKILL.md)
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: deploy-to-staging
|
||||
description: >
|
||||
Deploy current branch to staging environment with validation and health checks.
|
||||
Use when deploying to staging or when user says /deploy-to-staging.
|
||||
model: haiku
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Deploy to Staging
|
||||
|
||||
Deploy current branch to staging with automated validation and rollback capability.
|
||||
|
||||
## Process
|
||||
|
||||
1. **Validate build**
|
||||
- `./scripts/validate-build.sh`
|
||||
- Checks tests pass, linter clean, no uncommitted changes
|
||||
|
||||
2. **Show deployment plan** for approval
|
||||
- Branch name
|
||||
- Latest commit
|
||||
- Services that will be updated
|
||||
|
||||
3. **If approved, deploy**
|
||||
- `./scripts/deploy.sh staging $branch`
|
||||
- Script handles Docker build, push, k8s apply
|
||||
|
||||
4. **Health check**
|
||||
- `./scripts/health-check.sh staging`
|
||||
- Verifies all services are healthy
|
||||
|
||||
5. **Report results**
|
||||
- Deployment URL
|
||||
- Status of each service
|
||||
- Rollback command if needed
|
||||
|
||||
## Rollback
|
||||
|
||||
If deployment fails, see [reference/rollback-procedure.md](reference/rollback-procedure.md)
|
||||
```
|
||||
|
||||
## Example: scripts/validate-build.sh
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# validate-build.sh - Pre-deployment validation
|
||||
#
|
||||
# Checks:
|
||||
# - Tests pass
|
||||
# - Linter clean
|
||||
# - No uncommitted changes
|
||||
# - Docker builds successfully
|
||||
|
||||
set -e
|
||||
|
||||
RED='\033[0;31m'
|
||||
GREEN='\033[0;32m'
|
||||
NC='\033[0m'
|
||||
|
||||
error() {
|
||||
echo -e "${RED}ERROR: $1${NC}" >&2
|
||||
exit 1
|
||||
}
|
||||
|
||||
success() {
|
||||
echo -e "${GREEN}✓ $1${NC}"
|
||||
}
|
||||
|
||||
# Check 1: No uncommitted changes
|
||||
if ! git diff-index --quiet HEAD --; then
|
||||
error "Uncommitted changes detected. Commit or stash first."
|
||||
fi
|
||||
success "No uncommitted changes"
|
||||
|
||||
# Check 2: Tests pass
|
||||
if ! npm test > /dev/null 2>&1; then
|
||||
error "Tests failing. Fix tests before deploying."
|
||||
fi
|
||||
success "Tests pass"
|
||||
|
||||
# Check 3: Linter clean
|
||||
if ! npm run lint > /dev/null 2>&1; then
|
||||
error "Linter errors. Run 'npm run lint' to see details."
|
||||
fi
|
||||
success "Linter clean"
|
||||
|
||||
# Check 4: Docker builds
|
||||
if ! docker build -t test-build . > /dev/null 2>&1; then
|
||||
error "Docker build failed"
|
||||
fi
|
||||
success "Docker build successful"
|
||||
|
||||
echo ""
|
||||
echo -e "${GREEN}✓ All validations passed${NC}"
|
||||
```
|
||||
|
||||
## Example: scripts/deploy.sh
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# deploy.sh - Deploy to environment
|
||||
#
|
||||
# Usage: deploy.sh <environment> <branch>
|
||||
# Example: deploy.sh staging feature-new-ui
|
||||
|
||||
set -e
|
||||
|
||||
ENVIRONMENT=$1
|
||||
BRANCH=$2
|
||||
|
||||
if [ -z "$ENVIRONMENT" ] || [ -z "$BRANCH" ]; then
|
||||
echo "Usage: $0 <environment> <branch>"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Deploying $BRANCH to $ENVIRONMENT..."
|
||||
|
||||
# Build Docker image
|
||||
docker build -t myapp:$BRANCH .
|
||||
|
||||
# Tag for registry
|
||||
docker tag myapp:$BRANCH registry.example.com/myapp:$BRANCH
|
||||
|
||||
# Push to registry with retry
|
||||
for i in {1..3}; do
|
||||
if docker push registry.example.com/myapp:$BRANCH; then
|
||||
break
|
||||
fi
|
||||
echo "Push failed, retrying ($i/3)..."
|
||||
sleep 5
|
||||
done
|
||||
|
||||
# Update Kubernetes deployment
|
||||
kubectl set image deployment/myapp \
|
||||
myapp=registry.example.com/myapp:$BRANCH \
|
||||
-n $ENVIRONMENT
|
||||
|
||||
# Wait for rollout
|
||||
kubectl rollout status deployment/myapp -n $ENVIRONMENT --timeout=5m
|
||||
|
||||
echo "Deployment complete!"
|
||||
echo "URL: https://$ENVIRONMENT.example.com"
|
||||
```
|
||||
|
||||
## Why This Works
|
||||
|
||||
**Script benefits:**
|
||||
- **Deterministic**: Same behavior every time
|
||||
- **Error handling**: Retries, clear messages
|
||||
- **Validation**: Pre-flight checks prevent bad deployments
|
||||
- **No token cost**: Scripts execute without loading code into context
|
||||
|
||||
**Skill stays simple:**
|
||||
- Main SKILL.md is ~30 lines
|
||||
- Just calls scripts in order
|
||||
- No complex bash logic inline
|
||||
- Easy to test scripts independently
|
||||
|
||||
## What Makes It Haiku-Friendly
|
||||
|
||||
- ✓ Skill has simple instructions ("run script X, then Y")
|
||||
- ✓ Scripts handle all complexity
|
||||
- ✓ Clear success/failure from script exit codes
|
||||
- ✓ Validation prevents ambiguous states
|
||||
- ✓ Structured output from scripts is easy to parse
|
||||
|
||||
## Testing Scripts
|
||||
|
||||
Scripts can be tested independently:
|
||||
|
||||
```bash
|
||||
# Test validation
|
||||
./scripts/validate-build.sh
|
||||
|
||||
# Test deployment (dry-run)
|
||||
./scripts/deploy.sh staging test-branch --dry-run
|
||||
|
||||
# Test health check
|
||||
./scripts/health-check.sh staging
|
||||
```
|
||||
|
||||
This makes the skill more reliable than inline bash.
|
||||
212
old2/skills/issue-writing/SKILL.md
Normal file
212
old2/skills/issue-writing/SKILL.md
Normal file
@@ -0,0 +1,212 @@
|
||||
---
|
||||
name: issue-writing
|
||||
description: >
|
||||
Write clear, actionable issues with user stories, vertical slices, 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 that deliver user value.
|
||||
|
||||
## Primary Format: User Story
|
||||
|
||||
Frame issues as user capabilities, not technical tasks:
|
||||
|
||||
```markdown
|
||||
Title: As a [persona], I want to [action], so that [benefit]
|
||||
|
||||
## User Story
|
||||
As a [persona], I want to [action], so that [benefit]
|
||||
|
||||
## 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.
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
Title: As a domain expert, I want to save my diagram, so that I can resume work later
|
||||
|
||||
## User Story
|
||||
As a domain expert, I want to save my diagram to the cloud, so that I can resume
|
||||
work later from any device.
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] User can click "Save" button in toolbar
|
||||
- [ ] Diagram persists to cloud storage
|
||||
- [ ] User sees confirmation message on successful save
|
||||
- [ ] Saved diagram appears in recent files list
|
||||
|
||||
## Context
|
||||
Users currently lose work when closing the browser. This is the #1 requested feature.
|
||||
```
|
||||
|
||||
## 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) |
|
||||
|-----------------|------------------|
|
||||
| "As a user, I want to save my diagram" | "Add persistence layer" |
|
||||
| "As a user, I want to see errors when login fails" | "Add error handling" |
|
||||
| "As a domain expert, I want to list orders" | "Add query syntax to ADL" |
|
||||
|
||||
The technical work is the same, but vertical slices make success criteria clear and deliver demonstrable value.
|
||||
|
||||
## Writing User Stories
|
||||
|
||||
### Format
|
||||
|
||||
```
|
||||
As a [persona], I want [capability], so that [benefit]
|
||||
```
|
||||
|
||||
**Persona:** From manifesto or product vision (e.g., domain expert, developer, product owner)
|
||||
|
||||
**Capability:** What the user can do (not how it's implemented)
|
||||
|
||||
**Benefit:** Why this matters to the user
|
||||
|
||||
### Examples
|
||||
|
||||
```markdown
|
||||
✓ As a developer, I want to run tests locally, so that I can verify changes before pushing
|
||||
✓ As a product owner, I want to view open issues, so that I can prioritize work
|
||||
✓ As a domain expert, I want to export my model as JSON, so that I can share it with my team
|
||||
|
||||
✗ As a developer, I want a test runner (missing benefit)
|
||||
✗ I want to add authentication (missing persona and benefit)
|
||||
✗ As a user, I want the system to be fast (not specific/testable)
|
||||
```
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
## Alternative Formats
|
||||
|
||||
### Bug Report
|
||||
|
||||
```markdown
|
||||
Title: Fix [specific problem] in [area]
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
### Technical Task
|
||||
|
||||
Use sparingly - prefer user stories when possible.
|
||||
|
||||
```markdown
|
||||
Title: [Action] [component/area]
|
||||
|
||||
## Summary
|
||||
What technical work needs to be done and why.
|
||||
|
||||
## Scope
|
||||
- Include: ...
|
||||
- Exclude: ...
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] Measurable technical outcome
|
||||
- [ ] Another measurable outcome
|
||||
```
|
||||
|
||||
## Issue Sizing
|
||||
|
||||
Issues should be **small enough to complete in 1-3 days**.
|
||||
|
||||
**Too large?** Split into smaller vertical slices:
|
||||
|
||||
```markdown
|
||||
# Too large
|
||||
As a user, I want full authentication, so that my data is secure
|
||||
|
||||
# Better: Split into slices
|
||||
1. As a user, I want to register with email/password, so that I can create an account
|
||||
2. As a user, I want to log in with my credentials, so that I can access my data
|
||||
3. As a user, I want to reset my password, so that I can regain access if I forget it
|
||||
```
|
||||
|
||||
## Labels
|
||||
|
||||
Use labels to categorize:
|
||||
- Type: `bug`, `feature`, `enhancement`, `refactor`
|
||||
- Priority: `priority/high`, `priority/medium`, `priority/low`
|
||||
- Component: Project-specific (e.g., `auth`, `api`, `ui`)
|
||||
- DDD: `bounded-context/[name]`, `aggregate`, `command`, `event` (when applicable)
|
||||
|
||||
## 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.
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
**Avoid:**
|
||||
- Generic titles: "Fix bugs", "Improve performance"
|
||||
- Technical jargon without context: "Refactor service layer"
|
||||
- Missing acceptance criteria
|
||||
- Horizontal slices: "Build API", "Add database tables"
|
||||
- Vague criteria: "Make it better", "Improve UX"
|
||||
- Issues too large to complete in a sprint
|
||||
192
old2/skills/milestone-planning/SKILL.md
Normal file
192
old2/skills/milestone-planning/SKILL.md
Normal file
@@ -0,0 +1,192 @@
|
||||
---
|
||||
name: milestone-planning
|
||||
description: >
|
||||
Value-based milestone planning: milestones as shippable capabilities, not phases.
|
||||
One active milestone, vertical slices, value/risk labels. Use when planning
|
||||
milestones or organizing backlog by capability.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Milestone Planning
|
||||
|
||||
Value-driven milestone framework: milestones represent shippable business capabilities, not time-based phases.
|
||||
|
||||
## Core Principle
|
||||
|
||||
**If you don't deliver by date, milestones must represent value slices, not time.**
|
||||
|
||||
**Milestone = A shippable business capability**
|
||||
|
||||
Not a phase. Not "MVP". Not "Auth".
|
||||
|
||||
## What Makes a Good Milestone
|
||||
|
||||
Each milestone should answer one business question:
|
||||
|
||||
**"What new capability exists for the user once this is done?"**
|
||||
|
||||
### Good Examples
|
||||
|
||||
✓ Customer can register and authenticate
|
||||
✓ Order can be placed and paid
|
||||
✓ Admin can manage products
|
||||
✓ Audit trail exists for all state changes
|
||||
|
||||
### Bad Examples
|
||||
|
||||
✗ MVP (what capability?)
|
||||
✗ Backend (technical layer, not user value)
|
||||
✗ Auth improvements (vague, no completion criteria)
|
||||
✗ Phase 1 (time-based, not value-based)
|
||||
|
||||
**Test:** If it can't be demoed independently, it's too vague.
|
||||
|
||||
## Mapping DDD Issues to Milestones
|
||||
|
||||
**DDD building blocks → issues**
|
||||
- Aggregates
|
||||
- Commands
|
||||
- Events
|
||||
- Read models
|
||||
- Policies
|
||||
|
||||
**End-to-end capability → milestone**
|
||||
- Spans multiple aggregates
|
||||
- Commands + invariants + events
|
||||
- Read models for visibility
|
||||
- Maybe UI/API glue
|
||||
|
||||
**Value is cross-cutting by nature.**
|
||||
|
||||
A milestone usually includes:
|
||||
- Multiple aggregates working together
|
||||
- Commands that achieve user goal
|
||||
- Events connecting aggregates
|
||||
- Read models for user feedback
|
||||
- UI/API to trigger capability
|
||||
|
||||
## One Active Milestone at a Time
|
||||
|
||||
**Rule:** Exactly one open milestone = current value focus
|
||||
|
||||
**Why:**
|
||||
- Preserves focus
|
||||
- Avoids parallel half-value
|
||||
- Forces completion
|
||||
- Makes priority explicit
|
||||
|
||||
**Practice:**
|
||||
- Everything else stays unassigned
|
||||
- When done → close it → pick next highest-value milestone
|
||||
- Multiple open milestones = accidental roadmap
|
||||
|
||||
## Priority Without Dates
|
||||
|
||||
Since Gitea milestones have no ordering, use labels:
|
||||
|
||||
**Minimal label set:**
|
||||
- `value/high` - Highest business value
|
||||
- `value/medium` - Moderate business value
|
||||
- `value/low` - Nice to have
|
||||
- `risk/high` - Technical risk or uncertainty
|
||||
|
||||
**Issues have:**
|
||||
- Always: value label
|
||||
- Sometimes: risk label
|
||||
|
||||
**You now have:**
|
||||
- **Milestone** → what capability
|
||||
- **Label** → why now
|
||||
|
||||
## Sizing Guidelines
|
||||
|
||||
A value milestone should:
|
||||
- Be completable in days to a few weeks
|
||||
- Deliver observable user value
|
||||
- Contain 5-25 issues
|
||||
|
||||
**If it keeps growing:**
|
||||
- You discovered multiple capabilities
|
||||
- Split into separate milestones
|
||||
|
||||
## Vertical Slice Test
|
||||
|
||||
Before creating a milestone, verify:
|
||||
|
||||
**Can this be demoed independently?**
|
||||
|
||||
Test questions:
|
||||
- Can a user interact with this capability end-to-end?
|
||||
- Does it produce observable results?
|
||||
- Is it useful on its own (not just foundation)?
|
||||
- Can we ship this and get feedback?
|
||||
|
||||
If NO to any → not a value slice yet.
|
||||
|
||||
## Label Strategy
|
||||
|
||||
**Value labels (always):**
|
||||
- Reflect business priority
|
||||
- Based on user impact, revenue, strategic alignment
|
||||
- Applied to every issue in milestone
|
||||
|
||||
**Risk labels (optional):**
|
||||
- Flag technical uncertainty
|
||||
- Flag new patterns/technologies
|
||||
- Flag complex integrations
|
||||
- Helps sequence work (derisk early)
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
**"We just deliver highest value first"**
|
||||
Only works if:
|
||||
- Value is explicit (labels)
|
||||
- Scope is bounded (milestones)
|
||||
- Work is finishable (vertical slices)
|
||||
|
||||
Without milestones, "value-first" quietly becomes "interesting-first".
|
||||
|
||||
**Multiple open milestones:**
|
||||
- Splits focus
|
||||
- Encourages context switching
|
||||
- Hides incomplete work
|
||||
- Prevents shipping
|
||||
|
||||
**Technical milestones:**
|
||||
- "Backend" is not a capability
|
||||
- "API layer" is not demoable
|
||||
- "Database migration" might be necessary but not a milestone
|
||||
|
||||
**Phase-based milestones:**
|
||||
- "MVP" → what can user do?
|
||||
- "Phase 1" → what capability?
|
||||
- "Q1 goals" → what ships?
|
||||
|
||||
## When NOT to Use Milestones
|
||||
|
||||
**Don't use milestones when:**
|
||||
- Single capability with <5 issues (just label it)
|
||||
- Exploratory work (use spike label instead)
|
||||
- Refactoring without user-visible change (use technical debt label)
|
||||
- Everything ships together (waterfall project)
|
||||
|
||||
**Milestones enforce discipline around value slices.**
|
||||
|
||||
## Workflow Summary
|
||||
|
||||
1. **Issues exist** (from DDD analysis or backlog)
|
||||
2. **Group by capability** (milestone-planner agent)
|
||||
3. **One milestone open** (current value slice)
|
||||
4. **Label for priority** (value/risk)
|
||||
5. **No dates** (capability-based, not time-based)
|
||||
6. **Close ruthlessly** (finish before starting next)
|
||||
|
||||
## Tips
|
||||
|
||||
- Start with 3-5 milestones defined, 1 active
|
||||
- Keep unassigned issues in backlog
|
||||
- Move issues between milestones if capability boundaries change
|
||||
- Split milestones that grow beyond 25 issues
|
||||
- Close milestone when capability is demoable
|
||||
- Review value/risk labels regularly
|
||||
- Active milestone = team's current focus
|
||||
210
old2/skills/product-strategy/SKILL.md
Normal file
210
old2/skills/product-strategy/SKILL.md
Normal file
@@ -0,0 +1,210 @@
|
||||
---
|
||||
name: product-strategy
|
||||
description: >
|
||||
Opinionated framework for translating manifesto into executable backlog through
|
||||
problem space analysis, domain modeling, and capability mapping. Use when planning
|
||||
product strategy or decomposing vision into work.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Product Strategy Framework
|
||||
|
||||
A disciplined chain from organizational values to executable work, preventing cargo-cult DDD and feature churn.
|
||||
|
||||
## The Chain
|
||||
|
||||
```
|
||||
Manifesto
|
||||
↓ (constraints + outcomes)
|
||||
Product Vision
|
||||
↓ (events + decisions)
|
||||
Problem Space
|
||||
↓ (boundaries)
|
||||
Bounded Contexts
|
||||
↓ (invariants)
|
||||
Domain Models
|
||||
↓ (system abilities)
|
||||
Capabilities
|
||||
↓ (user value)
|
||||
Features
|
||||
↓ (executable)
|
||||
Issues
|
||||
```
|
||||
|
||||
Each step has a clear artifact and decision gate.
|
||||
|
||||
## Step 1: Manifesto → Product Vision
|
||||
|
||||
**Purpose:** Decide what is worth building (and what not).
|
||||
|
||||
**Artifact:** 1-page Product Vision (per product)
|
||||
|
||||
**Method:**
|
||||
Translate values into constraints + outcomes, not features.
|
||||
|
||||
| Manifesto Element | Vision Element |
|
||||
|-------------------|----------------|
|
||||
| Value | Non-negotiable design rule |
|
||||
| Belief | Product promise |
|
||||
| Principle | Trade-off rule |
|
||||
|
||||
**Vision must answer (hard requirement):**
|
||||
- Who is this product for?
|
||||
- What pain is eliminated?
|
||||
- What job is now trivial?
|
||||
- What won't we do?
|
||||
|
||||
**Decision gate:** If this can't be answered crisply → stop.
|
||||
|
||||
## Step 2: Product Vision → Problem Space
|
||||
|
||||
**Purpose:** Understand reality before modeling software.
|
||||
|
||||
**Artifact:** Problem Map (language-first)
|
||||
|
||||
**Do NOT start with DDD yet.**
|
||||
|
||||
**First, explore:**
|
||||
- Core user journeys
|
||||
- Decisions users struggle with
|
||||
- Irreversible vs reversible actions
|
||||
- Where mistakes are expensive
|
||||
|
||||
**Techniques:**
|
||||
- Event Storming (Big Picture)
|
||||
- Jobs-To-Be-Done
|
||||
- Narrative walkthroughs ("a day in the life")
|
||||
|
||||
**Output:**
|
||||
A timeline of business events, not entities.
|
||||
|
||||
**Anti-pattern:** If you don't see events, you're still thinking in CRUD.
|
||||
|
||||
## Step 3: Problem Space → Domain Boundaries
|
||||
|
||||
**Purpose:** Decide where models must be pure and where they may rot.
|
||||
|
||||
**Artifact:** Bounded Context Map
|
||||
|
||||
**How to cut boundaries (rules):**
|
||||
- Different language → different context
|
||||
- Different lifecycle → different context
|
||||
- Different owners → different context
|
||||
- Different scaling needs → different context
|
||||
|
||||
**Anti-pattern:** "One big domain model" is not DDD; it's denial.
|
||||
|
||||
## Step 4: Bounded Context → Domain Model
|
||||
|
||||
**Purpose:** Capture business invariants, not data structures.
|
||||
|
||||
**Artifact (per context):**
|
||||
- Aggregates
|
||||
- Commands
|
||||
- Events
|
||||
- Policies
|
||||
- Read models
|
||||
|
||||
**Process:**
|
||||
1. Identify invariants (what must never break)
|
||||
2. Define aggregates only where invariants exist
|
||||
3. Everything else becomes a read model or policy
|
||||
|
||||
**Anti-pattern:** If an aggregate has no invariant, it shouldn't exist.
|
||||
|
||||
## Step 5: Domain Model → Product Capabilities
|
||||
|
||||
**Purpose:** Bridge domain thinking to roadmap thinking.
|
||||
|
||||
**Artifact:** Capability Map
|
||||
|
||||
**A capability is:**
|
||||
"The system's ability to cause a meaningful domain change"
|
||||
|
||||
**Examples:**
|
||||
- "Validate eligibility"
|
||||
- "Authorize execution"
|
||||
- "Resolve conflicts"
|
||||
- "Publish outcome"
|
||||
|
||||
**Key insight:** Capabilities ≠ features
|
||||
|
||||
Capabilities survive UI rewrites and tech changes.
|
||||
|
||||
## Step 6: Capabilities → Features
|
||||
|
||||
**Purpose:** Define user-visible value slices.
|
||||
|
||||
**Artifact:** Feature definitions
|
||||
|
||||
**Each feature:**
|
||||
- Enables or improves one capability
|
||||
- Has a clear success condition
|
||||
- Is demoable
|
||||
|
||||
**Rule:** If a feature doesn't move a capability, it's noise.
|
||||
|
||||
## Step 7: Features → Work Items
|
||||
|
||||
**Purpose:** Make work executable without losing intent.
|
||||
|
||||
**Artifact:** Issues / Stories / Tasks
|
||||
|
||||
**Decomposition order:**
|
||||
1. Command handling
|
||||
2. Domain rules
|
||||
3. Events
|
||||
4. Read models
|
||||
5. UI last
|
||||
|
||||
**Golden rule:**
|
||||
Issues should reference domain concepts, not screens.
|
||||
|
||||
**Bad:** "Create edit form"
|
||||
**Good:** "Allow policy to approve eligibility override"
|
||||
|
||||
## Common Failure Modes
|
||||
|
||||
| Failure | Result |
|
||||
|---------|--------|
|
||||
| Starting DDD before product vision | Elegant nonsense |
|
||||
| Treating aggregates as data models | Anemic domains |
|
||||
| Roadmaps built from features instead of capabilities | Churn |
|
||||
| Tickets written in UI language | Lost intent |
|
||||
|
||||
## Decision Gates
|
||||
|
||||
**After Vision:** Can you answer the 4 questions crisply? No → stop and clarify.
|
||||
|
||||
**After Problem Space:** Do you see events, not entities? No → go deeper.
|
||||
|
||||
**After Contexts:** Are boundaries clear? No → re-examine language/lifecycle/ownership.
|
||||
|
||||
**After Domain Models:** Does each aggregate enforce an invariant? No → simplify.
|
||||
|
||||
**After Capabilities:** Can each capability be demoed? No → clarify.
|
||||
|
||||
**After Features:** Does each feature move a capability? No → cut it.
|
||||
|
||||
## Brownfield (Existing Code)
|
||||
|
||||
At each step, compare intended state vs actual state:
|
||||
|
||||
**Context Mapping:**
|
||||
- Intended contexts vs actual modules
|
||||
- Identify leaky boundaries
|
||||
|
||||
**Domain Modeling:**
|
||||
- Intended aggregates vs actual models
|
||||
- Identify anemic domains
|
||||
|
||||
**Result:** Refactoring issues + new feature issues
|
||||
|
||||
## Tips
|
||||
|
||||
- Don't skip steps (especially problem space)
|
||||
- Each artifact is 1 page max
|
||||
- Decision gates prevent waste
|
||||
- DDD starts at step 3, not step 1
|
||||
- Capabilities are the pivot between domain and product
|
||||
- Issues reference domain language, not UI elements
|
||||
536
old2/skills/reference/anti-patterns.md
Normal file
536
old2/skills/reference/anti-patterns.md
Normal file
@@ -0,0 +1,536 @@
|
||||
# Anti-Patterns to Avoid
|
||||
|
||||
Common mistakes when creating skills and agents.
|
||||
|
||||
## Skill Design Anti-Patterns
|
||||
|
||||
### 1. Overly Broad Components
|
||||
|
||||
**Bad:** One skill that does everything
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: project-management
|
||||
description: Handles issues, PRs, releases, documentation, deployment, testing, CI/CD...
|
||||
---
|
||||
|
||||
# Project Management
|
||||
|
||||
This skill does:
|
||||
- Issue management
|
||||
- Pull request reviews
|
||||
- Release planning
|
||||
- Documentation
|
||||
- Deployment
|
||||
- Testing
|
||||
- CI/CD configuration
|
||||
...
|
||||
```
|
||||
|
||||
**Why it's bad:**
|
||||
- Huge context window usage
|
||||
- Hard to maintain
|
||||
- Unclear when to trigger
|
||||
- Tries to do too much
|
||||
|
||||
**Good:** Focused components
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: issue-writing
|
||||
description: How to write clear, actionable issues with acceptance criteria.
|
||||
---
|
||||
```
|
||||
|
||||
**Separate skills for:**
|
||||
- `issue-writing` - Issue quality
|
||||
- `review-pr` - PR reviews
|
||||
- `gitea` - CLI reference
|
||||
- Each does one thing well
|
||||
|
||||
---
|
||||
|
||||
### 2. Vague Instructions
|
||||
|
||||
**Bad:**
|
||||
|
||||
```markdown
|
||||
1. Handle the issue
|
||||
2. Do the work
|
||||
3. Finish up
|
||||
4. Let me know when done
|
||||
```
|
||||
|
||||
**Why it's bad:**
|
||||
- No clear actions
|
||||
- Claude has to guess
|
||||
- Inconsistent results
|
||||
- Hard to validate
|
||||
|
||||
**Good:**
|
||||
|
||||
```markdown
|
||||
1. **View issue**: `tea issues $1 --comments`
|
||||
2. **Create branch**: `git checkout -b issue-$1-<title>`
|
||||
3. **Plan work**: Use TodoWrite to break down steps
|
||||
4. **Implement**: Make necessary changes
|
||||
5. **Commit**: `git commit -m "feat: ..."`
|
||||
6. **Create PR**: `tea pulls create --title "..." --description "..."`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Missing Skill References
|
||||
|
||||
**Bad:**
|
||||
|
||||
```markdown
|
||||
Use the gitea skill to create an issue.
|
||||
```
|
||||
|
||||
**Why it's bad:**
|
||||
- Skills have ~20% auto-activation rate
|
||||
- Claude might not load the skill
|
||||
- Inconsistent results
|
||||
|
||||
**Good:**
|
||||
|
||||
```markdown
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
|
||||
Use `tea issues create --title "..." --description "..."`
|
||||
```
|
||||
|
||||
**The `@` reference guarantees the skill content is loaded.**
|
||||
|
||||
---
|
||||
|
||||
### 4. God Skills
|
||||
|
||||
**Bad:** Single 1500-line skill covering everything
|
||||
|
||||
```
|
||||
skills/database/SKILL.md (1500 lines)
|
||||
- PostgreSQL
|
||||
- MySQL
|
||||
- MongoDB
|
||||
- Redis
|
||||
- All queries
|
||||
- All optimization tips
|
||||
- All schemas
|
||||
```
|
||||
|
||||
**Why it's bad:**
|
||||
- Exceeds recommended 500 lines
|
||||
- Loads everything even if you need one thing
|
||||
- Hard to maintain
|
||||
- Wastes tokens
|
||||
|
||||
**Good:** Progressive disclosure
|
||||
|
||||
```
|
||||
skills/database/
|
||||
├── SKILL.md (200 lines - overview)
|
||||
├── reference/
|
||||
│ ├── postgres.md
|
||||
│ ├── mysql.md
|
||||
│ ├── mongodb.md
|
||||
│ └── redis.md
|
||||
└── schemas/
|
||||
├── users.md
|
||||
├── products.md
|
||||
└── orders.md
|
||||
```
|
||||
|
||||
Claude loads only what's needed.
|
||||
|
||||
---
|
||||
|
||||
### 5. Premature Agent Creation
|
||||
|
||||
**Bad:** Creating an agent for every task
|
||||
|
||||
```
|
||||
agents/
|
||||
├── issue-viewer/
|
||||
├── branch-creator/
|
||||
├── commit-maker/
|
||||
├── pr-creator/
|
||||
└── readme-updater/
|
||||
```
|
||||
|
||||
**Why it's bad:**
|
||||
- Overhead of spawning agents
|
||||
- Most tasks don't need isolation
|
||||
- Harder to follow workflow
|
||||
- Slower execution
|
||||
|
||||
**Good:** Use agents only when needed:
|
||||
- Context isolation (parallel work)
|
||||
- Skill composition (multiple skills together)
|
||||
- Specialist persona (architecture review)
|
||||
|
||||
**Simple tasks → Skills**
|
||||
**Complex isolated work → Agents**
|
||||
|
||||
---
|
||||
|
||||
### 6. Verbose Explanations
|
||||
|
||||
**Bad:**
|
||||
|
||||
```markdown
|
||||
Git is a distributed version control system that was created by Linus Torvalds in 2005. It allows multiple developers to work on the same codebase simultaneously while maintaining a complete history of all changes. When you want to save your changes, you use the git commit command, which creates a snapshot of your current working directory...
|
||||
```
|
||||
|
||||
**Why it's bad:**
|
||||
- Wastes tokens
|
||||
- Claude already knows git
|
||||
- Slows down loading
|
||||
- Adds no value
|
||||
|
||||
**Good:**
|
||||
|
||||
```markdown
|
||||
`git commit -m 'feat: add feature'`
|
||||
```
|
||||
|
||||
**Assume Claude is smart. Only add domain-specific context.**
|
||||
|
||||
---
|
||||
|
||||
## Instruction Anti-Patterns
|
||||
|
||||
### 7. Offering Too Many Options
|
||||
|
||||
**Bad:**
|
||||
|
||||
```markdown
|
||||
You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or camelot, or tabula, or...
|
||||
```
|
||||
|
||||
**Why it's bad:**
|
||||
- Decision paralysis
|
||||
- Inconsistent choices
|
||||
- No clear default
|
||||
|
||||
**Good:**
|
||||
|
||||
```markdown
|
||||
Use pdfplumber for text extraction:
|
||||
|
||||
\`\`\`python
|
||||
import pdfplumber
|
||||
with pdfplumber.open("file.pdf") as pdf:
|
||||
text = pdf.pages[0].extract_text()
|
||||
\`\`\`
|
||||
|
||||
For scanned PDFs requiring OCR, use pdf2image + pytesseract instead.
|
||||
```
|
||||
|
||||
**Provide default, mention alternative only when needed.**
|
||||
|
||||
---
|
||||
|
||||
### 8. Time-Sensitive Information
|
||||
|
||||
**Bad:**
|
||||
|
||||
```markdown
|
||||
If you're doing this before August 2025, use the old API.
|
||||
After August 2025, use the new API.
|
||||
```
|
||||
|
||||
**Why it's bad:**
|
||||
- Will become wrong
|
||||
- Requires maintenance
|
||||
- Confusing after the date
|
||||
|
||||
**Good:**
|
||||
|
||||
```markdown
|
||||
## Current Method
|
||||
Use v2 API: `api.example.com/v2/messages`
|
||||
|
||||
## Old Patterns
|
||||
<details>
|
||||
<summary>Legacy v1 API (deprecated 2025-08)</summary>
|
||||
The v1 API: `api.example.com/v1/messages`
|
||||
No longer supported.
|
||||
</details>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 9. Inconsistent Terminology
|
||||
|
||||
**Bad:** Mixing terms for the same thing
|
||||
|
||||
```markdown
|
||||
1. Get the API endpoint
|
||||
2. Call the URL
|
||||
3. Hit the API route
|
||||
4. Query the path
|
||||
```
|
||||
|
||||
**Why it's bad:**
|
||||
- Confusing
|
||||
- Looks like different things
|
||||
- Harder to search
|
||||
|
||||
**Good:** Pick one term and stick with it
|
||||
|
||||
```markdown
|
||||
1. Get the API endpoint
|
||||
2. Call the API endpoint
|
||||
3. Check the API endpoint response
|
||||
4. Retry the API endpoint if needed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 10. Windows-Style Paths
|
||||
|
||||
**Bad:**
|
||||
|
||||
```markdown
|
||||
Run: `scripts\helper.py`
|
||||
See: `reference\guide.md`
|
||||
```
|
||||
|
||||
**Why it's bad:**
|
||||
- Fails on Unix systems
|
||||
- Causes errors on Mac/Linux
|
||||
|
||||
**Good:**
|
||||
|
||||
```markdown
|
||||
Run: `scripts/helper.py`
|
||||
See: `reference/guide.md`
|
||||
```
|
||||
|
||||
**Always use forward slashes. They work everywhere.**
|
||||
|
||||
---
|
||||
|
||||
## Script Anti-Patterns
|
||||
|
||||
### 11. Punting to Claude
|
||||
|
||||
**Bad script:**
|
||||
|
||||
```python
|
||||
def process_file(path):
|
||||
return open(path).read() # Let Claude handle errors
|
||||
```
|
||||
|
||||
**Why it's bad:**
|
||||
- Script fails with no helpful message
|
||||
- Claude has to guess what happened
|
||||
- Inconsistent error handling
|
||||
|
||||
**Good script:**
|
||||
|
||||
```python
|
||||
def process_file(path):
|
||||
try:
|
||||
with open(path) as f:
|
||||
return f.read()
|
||||
except FileNotFoundError:
|
||||
print(f"ERROR: File {path} not found")
|
||||
print("Creating default file...")
|
||||
with open(path, 'w') as f:
|
||||
f.write('')
|
||||
return ''
|
||||
except PermissionError:
|
||||
print(f"ERROR: Cannot access {path}")
|
||||
print("Using default value")
|
||||
return ''
|
||||
```
|
||||
|
||||
**Scripts should solve problems, not punt to Claude.**
|
||||
|
||||
---
|
||||
|
||||
### 12. Magic Numbers
|
||||
|
||||
**Bad:**
|
||||
|
||||
```bash
|
||||
TIMEOUT=47 # Why 47?
|
||||
RETRIES=5 # Why 5?
|
||||
DELAY=3.7 # Why 3.7?
|
||||
```
|
||||
|
||||
**Why it's bad:**
|
||||
- No one knows why these values
|
||||
- Hard to adjust
|
||||
- "Voodoo constants"
|
||||
|
||||
**Good:**
|
||||
|
||||
```bash
|
||||
# HTTP requests typically complete in <30s
|
||||
# Extra buffer for slow connections
|
||||
TIMEOUT=30
|
||||
|
||||
# Three retries balances reliability vs speed
|
||||
# Most intermittent failures resolve by retry 2
|
||||
RETRIES=3
|
||||
|
||||
# Exponential backoff: 1s, 2s, 4s
|
||||
INITIAL_DELAY=1
|
||||
```
|
||||
|
||||
**Document why each value is what it is.**
|
||||
|
||||
---
|
||||
|
||||
## Model Selection Anti-Patterns
|
||||
|
||||
### 13. Always Using Sonnet/Opus
|
||||
|
||||
**Bad:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: dashboard
|
||||
model: opus # "Just to be safe"
|
||||
---
|
||||
```
|
||||
|
||||
**Why it's bad:**
|
||||
- 60x more expensive than Haiku
|
||||
- 5x slower
|
||||
- Wasted cost for simple task
|
||||
|
||||
**Good:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: dashboard
|
||||
model: haiku # Tested: 5/5 tests passed
|
||||
---
|
||||
```
|
||||
|
||||
**Test with Haiku first. Only upgrade if needed.**
|
||||
|
||||
---
|
||||
|
||||
### 14. Never Testing Haiku
|
||||
|
||||
**Bad:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: review-pr
|
||||
model: sonnet # Assumed it needs Sonnet, never tested Haiku
|
||||
---
|
||||
```
|
||||
|
||||
**Why it's bad:**
|
||||
- Might work fine with Haiku
|
||||
- Missing 12x cost savings
|
||||
- Missing 2.5x speed improvement
|
||||
|
||||
**Good:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: review-pr
|
||||
model: haiku # Tested: Haiku 4/5 (80%), good enough!
|
||||
---
|
||||
```
|
||||
|
||||
Or:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: review-pr
|
||||
model: sonnet # Tested: Haiku 2/5 (40%), Sonnet 4/5 (80%)
|
||||
---
|
||||
```
|
||||
|
||||
**Always test Haiku first, document results.**
|
||||
|
||||
---
|
||||
|
||||
## Progressive Disclosure Anti-Patterns
|
||||
|
||||
### 15. Deeply Nested References
|
||||
|
||||
**Bad:**
|
||||
|
||||
```
|
||||
SKILL.md → advanced.md → details.md → actual-info.md
|
||||
```
|
||||
|
||||
**Why it's bad:**
|
||||
- Claude may partially read nested files
|
||||
- Information might be incomplete
|
||||
- Hard to navigate
|
||||
|
||||
**Good:**
|
||||
|
||||
```
|
||||
SKILL.md → {advanced.md, reference.md, examples.md}
|
||||
```
|
||||
|
||||
**Keep references one level deep from SKILL.md.**
|
||||
|
||||
---
|
||||
|
||||
### 16. No Table of Contents for Long Files
|
||||
|
||||
**Bad:** 500-line reference file with no structure
|
||||
|
||||
```markdown
|
||||
# Reference
|
||||
|
||||
(500 lines of content with no navigation)
|
||||
```
|
||||
|
||||
**Why it's bad:**
|
||||
- Hard to preview
|
||||
- Claude might miss sections
|
||||
- User can't navigate
|
||||
|
||||
**Good:**
|
||||
|
||||
```markdown
|
||||
# Reference
|
||||
|
||||
## Contents
|
||||
- Authentication and setup
|
||||
- Core methods
|
||||
- Advanced features
|
||||
- Error handling
|
||||
- Examples
|
||||
|
||||
## Authentication and Setup
|
||||
...
|
||||
```
|
||||
|
||||
**Files >100 lines should have TOC.**
|
||||
|
||||
---
|
||||
|
||||
## Checklist to Avoid Anti-Patterns
|
||||
|
||||
Before publishing a skill:
|
||||
|
||||
- [ ] Not overly broad (does one thing well)
|
||||
- [ ] Instructions are specific (not vague)
|
||||
- [ ] Skill references use `@` syntax
|
||||
- [ ] Under 500 lines (or uses progressive disclosure)
|
||||
- [ ] Only creates agents when needed
|
||||
- [ ] Concise (assumes Claude knows basics)
|
||||
- [ ] Provides default, not 10 options
|
||||
- [ ] No time-sensitive information
|
||||
- [ ] Consistent terminology
|
||||
- [ ] Forward slashes for paths
|
||||
- [ ] Scripts handle errors, don't punt
|
||||
- [ ] No magic numbers in scripts
|
||||
- [ ] Tested with Haiku first
|
||||
- [ ] References are one level deep
|
||||
- [ ] Long files have table of contents
|
||||
278
old2/skills/reference/frontmatter-fields.md
Normal file
278
old2/skills/reference/frontmatter-fields.md
Normal file
@@ -0,0 +1,278 @@
|
||||
# Frontmatter Fields Reference
|
||||
|
||||
Complete documentation of all available frontmatter fields for skills and agents.
|
||||
|
||||
## Skill Frontmatter
|
||||
|
||||
### Required Fields
|
||||
|
||||
#### `name`
|
||||
- **Type:** string
|
||||
- **Required:** Yes
|
||||
- **Format:** Lowercase, hyphens only, no spaces
|
||||
- **Max length:** 64 characters
|
||||
- **Must match:** Directory name
|
||||
- **Cannot contain:** XML tags, reserved words ("anthropic", "claude")
|
||||
- **Example:** `work-issue`, `code-review`, `gitea`
|
||||
|
||||
#### `description`
|
||||
- **Type:** string (multiline supported with `>`)
|
||||
- **Required:** Yes
|
||||
- **Max length:** 1024 characters
|
||||
- **Cannot contain:** XML tags
|
||||
- **Should include:**
|
||||
- What the skill does
|
||||
- When to use it
|
||||
- Trigger conditions
|
||||
- **Example:**
|
||||
```yaml
|
||||
description: >
|
||||
View, create, and manage Gitea issues and pull requests.
|
||||
Use when working with issues, PRs, or when user mentions tea, gitea, issue numbers.
|
||||
```
|
||||
|
||||
#### `user-invocable`
|
||||
- **Type:** boolean
|
||||
- **Required:** Yes
|
||||
- **Values:** `true` or `false`
|
||||
- **Usage:**
|
||||
- `true`: User can trigger with `/skill-name`
|
||||
- `false`: Background skill, auto-loaded when needed
|
||||
|
||||
### Optional Fields
|
||||
|
||||
#### `model`
|
||||
- **Type:** string
|
||||
- **Required:** No
|
||||
- **Values:** `haiku`, `sonnet`, `opus`
|
||||
- **Default:** Inherits from parent (usually haiku)
|
||||
- **Guidance:** Default to `haiku`, only upgrade if needed
|
||||
- **Example:**
|
||||
```yaml
|
||||
model: haiku # 12x cheaper than sonnet
|
||||
```
|
||||
|
||||
#### `argument-hint`
|
||||
- **Type:** string
|
||||
- **Required:** No (only for user-invocable skills)
|
||||
- **Format:** `<required>` for required params, `[optional]` for optional
|
||||
- **Shows in UI:** Helps users know what arguments to provide
|
||||
- **Example:**
|
||||
```yaml
|
||||
argument-hint: <issue-number>
|
||||
argument-hint: <issue-number> [optional-title]
|
||||
```
|
||||
|
||||
#### `context`
|
||||
- **Type:** string
|
||||
- **Required:** No
|
||||
- **Values:** `fork`
|
||||
- **Usage:** Set to `fork` for skills needing isolated context
|
||||
- **When to use:** Heavy exploration tasks that would pollute main context
|
||||
- **Example:**
|
||||
```yaml
|
||||
context: fork # For arch-review-repo, deep exploration
|
||||
```
|
||||
|
||||
#### `allowed-tools`
|
||||
- **Type:** list of strings
|
||||
- **Required:** No
|
||||
- **Usage:** Restrict which tools the skill can use
|
||||
- **Example:**
|
||||
```yaml
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Bash
|
||||
- Grep
|
||||
```
|
||||
- **Note:** Rarely used, most skills have all tools
|
||||
|
||||
## Agent Frontmatter
|
||||
|
||||
### Required Fields
|
||||
|
||||
#### `name`
|
||||
- **Type:** string
|
||||
- **Required:** Yes
|
||||
- **Same rules as skill name**
|
||||
|
||||
#### `description`
|
||||
- **Type:** string
|
||||
- **Required:** Yes
|
||||
- **Should include:**
|
||||
- What the agent does
|
||||
- When to spawn it
|
||||
- **Example:**
|
||||
```yaml
|
||||
description: >
|
||||
Automated code review of pull requests for quality, bugs, security, and style.
|
||||
Spawn when reviewing PRs or checking code quality.
|
||||
```
|
||||
|
||||
### Optional Fields
|
||||
|
||||
#### `model`
|
||||
- **Type:** string
|
||||
- **Required:** No
|
||||
- **Values:** `haiku`, `sonnet`, `opus`, `inherit`
|
||||
- **Default:** `inherit` (uses parent's model)
|
||||
- **Guidance:**
|
||||
- Default to `haiku` for simple agents
|
||||
- Use `sonnet` for balanced performance
|
||||
- Reserve `opus` for deep reasoning
|
||||
- **Example:**
|
||||
```yaml
|
||||
model: haiku # Fast and cheap for code review checklist
|
||||
```
|
||||
|
||||
#### `skills`
|
||||
- **Type:** comma-separated list of skill names (not paths)
|
||||
- **Required:** No
|
||||
- **Usage:** Auto-load these skills when agent spawns
|
||||
- **Format:** Just skill names, not paths
|
||||
- **Example:**
|
||||
```yaml
|
||||
skills: gitea, issue-writing, code-review
|
||||
```
|
||||
- **Note:** Agent runtime loads skills automatically
|
||||
|
||||
#### `disallowedTools`
|
||||
- **Type:** list of tool names
|
||||
- **Required:** No
|
||||
- **Common use:** Make agents read-only
|
||||
- **Example:**
|
||||
```yaml
|
||||
disallowedTools:
|
||||
- Edit
|
||||
- Write
|
||||
```
|
||||
- **When to use:** Analysis agents that shouldn't modify code
|
||||
|
||||
#### `permissionMode`
|
||||
- **Type:** string
|
||||
- **Required:** No
|
||||
- **Values:** `default`, `bypassPermissions`
|
||||
- **Usage:** Rarely used, for agents that need to bypass permission prompts
|
||||
- **Example:**
|
||||
```yaml
|
||||
permissionMode: bypassPermissions
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Minimal User-Invocable Skill
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: dashboard
|
||||
description: Show open issues, PRs, and CI status.
|
||||
user-invocable: true
|
||||
---
|
||||
```
|
||||
|
||||
### Full-Featured Skill
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: work-issue
|
||||
description: >
|
||||
Implement a Gitea issue with full workflow: branch, plan, code, PR, review.
|
||||
Use when implementing issues or when user says /work-issue.
|
||||
model: haiku
|
||||
argument-hint: <issue-number>
|
||||
user-invocable: true
|
||||
---
|
||||
```
|
||||
|
||||
### Background Skill
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: gitea
|
||||
description: >
|
||||
View, create, and manage Gitea issues and PRs using tea CLI.
|
||||
Use when working with issues, PRs, viewing issue details, or when user mentions tea, gitea, issue numbers.
|
||||
user-invocable: false
|
||||
---
|
||||
```
|
||||
|
||||
### Read-Only Agent
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: code-reviewer
|
||||
description: >
|
||||
Automated code review of pull requests for quality, bugs, security, style, and test coverage.
|
||||
model: sonnet
|
||||
skills: gitea, code-review
|
||||
disallowedTools:
|
||||
- Edit
|
||||
- Write
|
||||
---
|
||||
```
|
||||
|
||||
### Implementation Agent
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: issue-worker
|
||||
description: >
|
||||
Autonomously implements a single issue in an isolated git worktree.
|
||||
model: haiku
|
||||
skills: gitea, issue-writing, software-architecture
|
||||
---
|
||||
```
|
||||
|
||||
## Validation Rules
|
||||
|
||||
### Name Validation
|
||||
- Must be lowercase
|
||||
- Must use hyphens (not underscores or spaces)
|
||||
- Cannot contain: `anthropic`, `claude`
|
||||
- Cannot contain XML tags `<`, `>`
|
||||
- Max 64 characters
|
||||
- Must match directory name exactly
|
||||
|
||||
### Description Validation
|
||||
- Cannot be empty
|
||||
- Max 1024 characters
|
||||
- Cannot contain XML tags
|
||||
- Should end with period
|
||||
|
||||
### Model Validation
|
||||
- Must be one of: `haiku`, `sonnet`, `opus`, `inherit`
|
||||
- Case-sensitive (must be lowercase)
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
**Bad: Using paths in skills field**
|
||||
```yaml
|
||||
skills: ~/.claude/skills/gitea/SKILL.md # Wrong!
|
||||
```
|
||||
|
||||
**Good: Just skill names**
|
||||
```yaml
|
||||
skills: gitea, issue-writing
|
||||
```
|
||||
|
||||
**Bad: Reserved word in name**
|
||||
```yaml
|
||||
name: claude-helper # Contains "claude"
|
||||
```
|
||||
|
||||
**Good: Descriptive name**
|
||||
```yaml
|
||||
name: code-helper
|
||||
```
|
||||
|
||||
**Bad: Vague description**
|
||||
```yaml
|
||||
description: Helps with stuff
|
||||
```
|
||||
|
||||
**Good: Specific description**
|
||||
```yaml
|
||||
description: >
|
||||
Analyze Excel spreadsheets, create pivot tables, generate charts.
|
||||
Use when analyzing Excel files, spreadsheets, or .xlsx files.
|
||||
```
|
||||
336
old2/skills/reference/model-selection.md
Normal file
336
old2/skills/reference/model-selection.md
Normal file
@@ -0,0 +1,336 @@
|
||||
# Model Selection Guide
|
||||
|
||||
Detailed guidance on choosing the right model for skills and agents.
|
||||
|
||||
## Cost Comparison
|
||||
|
||||
| Model | Input (per MTok) | Output (per MTok) | vs Haiku |
|
||||
|-------|------------------|-------------------|----------|
|
||||
| **Haiku** | $0.25 | $1.25 | Baseline |
|
||||
| **Sonnet** | $3.00 | $15.00 | 12x more expensive |
|
||||
| **Opus** | $15.00 | $75.00 | 60x more expensive |
|
||||
|
||||
**Example cost for typical skill call (2K input, 1K output):**
|
||||
- Haiku: $0.00175
|
||||
- Sonnet: $0.021 (12x more)
|
||||
- Opus: $0.105 (60x more)
|
||||
|
||||
## Speed Comparison
|
||||
|
||||
| Model | Tokens/Second | vs Haiku |
|
||||
|-------|---------------|----------|
|
||||
| **Haiku** | ~100 | Baseline |
|
||||
| **Sonnet** | ~40 | 2.5x slower |
|
||||
| **Opus** | ~20 | 5x slower |
|
||||
|
||||
## Decision Framework
|
||||
|
||||
```
|
||||
Start with Haiku by default
|
||||
|
|
||||
v
|
||||
Test on 3-5 representative tasks
|
||||
|
|
||||
+-- Success rate ≥80%? ---------> ✓ Use Haiku
|
||||
| (12x cheaper, 2-5x faster)
|
||||
|
|
||||
+-- Success rate <80%? --------> Try Sonnet
|
||||
| |
|
||||
| v
|
||||
| Test on same tasks
|
||||
| |
|
||||
| +-- Success ≥80%? --> Use Sonnet
|
||||
| |
|
||||
| +-- Still failing? --> Opus or redesign
|
||||
|
|
||||
v
|
||||
Document why you chose the model
|
||||
```
|
||||
|
||||
## When Haiku Works Well
|
||||
|
||||
### ✓ Ideal for Haiku
|
||||
|
||||
**Simple sequential workflows:**
|
||||
- `/dashboard` - Fetch and display
|
||||
- `/roadmap` - List and format
|
||||
- `/commit` - Generate message from diff
|
||||
|
||||
**Workflows with scripts:**
|
||||
- Error-prone operations in scripts
|
||||
- Skills just orchestrate script calls
|
||||
- Validation is deterministic
|
||||
|
||||
**Structured outputs:**
|
||||
- Tasks with clear templates
|
||||
- Format is defined upfront
|
||||
- No ambiguous formatting
|
||||
|
||||
**Reference/knowledge skills:**
|
||||
- `gitea` - CLI reference
|
||||
- `issue-writing` - Patterns and templates
|
||||
- `software-architecture` - Best practices
|
||||
|
||||
### Examples of Haiku Success
|
||||
|
||||
**work-issue skill:**
|
||||
- Sequential steps (view → branch → plan → implement → PR)
|
||||
- Each step has clear validation
|
||||
- Scripts handle error-prone operations
|
||||
- Success rate: ~90%
|
||||
|
||||
**dashboard skill:**
|
||||
- Fetch data (tea commands)
|
||||
- Format as table
|
||||
- Clear, structured output
|
||||
- Success rate: ~95%
|
||||
|
||||
## When to Use Sonnet
|
||||
|
||||
### Use Sonnet When
|
||||
|
||||
**Haiku fails 20%+ of the time**
|
||||
- Test with Haiku first
|
||||
- If success rate <80%, upgrade to Sonnet
|
||||
|
||||
**Complex judgment required:**
|
||||
- Code review (quality assessment)
|
||||
- Issue grooming (clarity evaluation)
|
||||
- Architecture decisions
|
||||
|
||||
**Nuanced reasoning:**
|
||||
- Understanding implicit requirements
|
||||
- Making trade-off decisions
|
||||
- Applying context-dependent rules
|
||||
|
||||
### Examples of Sonnet Success
|
||||
|
||||
**review-pr skill:**
|
||||
- Requires code understanding
|
||||
- Judgment about quality/bugs
|
||||
- Context-dependent feedback
|
||||
- Originally tried Haiku: 65% success → Sonnet: 85%
|
||||
|
||||
**issue-worker agent:**
|
||||
- Autonomous implementation
|
||||
- Pattern matching
|
||||
- Architectural decisions
|
||||
- Originally tried Haiku: 70% success → Sonnet: 82%
|
||||
|
||||
## When to Use Opus
|
||||
|
||||
### Reserve Opus For
|
||||
|
||||
**Deep architectural reasoning:**
|
||||
- `software-architect` agent
|
||||
- Pattern recognition across large codebases
|
||||
- Identifying subtle anti-patterns
|
||||
- Trade-off analysis
|
||||
|
||||
**High-stakes decisions:**
|
||||
- Breaking changes analysis
|
||||
- System-wide refactoring plans
|
||||
- Security architecture review
|
||||
|
||||
**Complex pattern recognition:**
|
||||
- Requires sophisticated understanding
|
||||
- Multiple layers of abstraction
|
||||
- Long-term implications
|
||||
|
||||
### Examples of Opus Success
|
||||
|
||||
**software-architect agent:**
|
||||
- Analyzes entire codebase
|
||||
- Identifies 8 different anti-patterns
|
||||
- Provides prioritized recommendations
|
||||
- Sonnet: 68% success → Opus: 88%
|
||||
|
||||
**arch-review-repo skill:**
|
||||
- Comprehensive architecture audit
|
||||
- Cross-cutting concerns
|
||||
- System-wide patterns
|
||||
- Opus justified for depth
|
||||
|
||||
## Making Haiku More Effective
|
||||
|
||||
If Haiku is struggling, try these improvements **before** upgrading to Sonnet:
|
||||
|
||||
### 1. Add Validation Steps
|
||||
|
||||
**Instead of:**
|
||||
```markdown
|
||||
3. Implement changes and create PR
|
||||
```
|
||||
|
||||
**Try:**
|
||||
```markdown
|
||||
3. Implement changes
|
||||
4. Validate: Run `./scripts/validate.sh` (tests pass, linter clean)
|
||||
5. Create PR: `./scripts/create-pr.sh`
|
||||
```
|
||||
|
||||
### 2. Bundle Error-Prone Operations in Scripts
|
||||
|
||||
**Instead of:**
|
||||
```markdown
|
||||
5. Create PR: `tea pulls create --title "..." --description "..."`
|
||||
```
|
||||
|
||||
**Try:**
|
||||
```markdown
|
||||
5. Create PR: `./scripts/create-pr.sh $issue "$title"`
|
||||
```
|
||||
|
||||
### 3. Add Structured Output Templates
|
||||
|
||||
**Instead of:**
|
||||
```markdown
|
||||
Show the results
|
||||
```
|
||||
|
||||
**Try:**
|
||||
```markdown
|
||||
Format results as:
|
||||
|
||||
| Issue | Status | Link |
|
||||
|-------|--------|------|
|
||||
| ... | ... | ... |
|
||||
```
|
||||
|
||||
### 4. Add Explicit Checklists
|
||||
|
||||
**Instead of:**
|
||||
```markdown
|
||||
Review the code for quality
|
||||
```
|
||||
|
||||
**Try:**
|
||||
```markdown
|
||||
Check:
|
||||
- [ ] Code quality (readability, naming)
|
||||
- [ ] Bugs (edge cases, null checks)
|
||||
- [ ] Tests (coverage, assertions)
|
||||
```
|
||||
|
||||
### 5. Make Instructions More Concise
|
||||
|
||||
**Instead of:**
|
||||
```markdown
|
||||
Git is a version control system. When you want to commit changes, you use the git commit command which saves your changes to the repository...
|
||||
```
|
||||
|
||||
**Try:**
|
||||
```markdown
|
||||
`git commit -m 'feat: add feature'`
|
||||
```
|
||||
|
||||
## Testing Methodology
|
||||
|
||||
### Create Test Suite
|
||||
|
||||
For each skill, create 3-5 test cases:
|
||||
|
||||
**Example: work-issue skill tests**
|
||||
1. Simple bug fix issue
|
||||
2. New feature with acceptance criteria
|
||||
3. Issue missing acceptance criteria
|
||||
4. Issue with tests that fail
|
||||
5. Complex refactoring task
|
||||
|
||||
### Test with Haiku
|
||||
|
||||
```bash
|
||||
# Set skill to Haiku
|
||||
model: haiku
|
||||
|
||||
# Run all 5 tests
|
||||
# Document success/failure for each
|
||||
```
|
||||
|
||||
### Measure Success Rate
|
||||
|
||||
```
|
||||
Success rate = (Successful tests / Total tests) × 100
|
||||
```
|
||||
|
||||
**Decision:**
|
||||
- ≥80% → Keep Haiku
|
||||
- <80% → Try Sonnet
|
||||
- <50% → Likely need Opus or redesign
|
||||
|
||||
### Test with Sonnet (if needed)
|
||||
|
||||
```bash
|
||||
# Upgrade to Sonnet
|
||||
model: sonnet
|
||||
|
||||
# Run same 5 tests
|
||||
# Compare results
|
||||
```
|
||||
|
||||
### Document Decision
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: work-issue
|
||||
model: haiku # Tested: 4/5 tests passed with Haiku (80%)
|
||||
---
|
||||
```
|
||||
|
||||
Or:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: review-pr
|
||||
model: sonnet # Tested: Haiku 3/5 (60%), Sonnet 4/5 (80%)
|
||||
---
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Pattern: Start Haiku, Upgrade if Needed
|
||||
|
||||
**Issue-worker agent evolution:**
|
||||
1. **V1 (Haiku):** 70% success - struggled with pattern matching
|
||||
2. **Analysis:** Added more examples, still 72%
|
||||
3. **V2 (Sonnet):** 82% success - better code understanding
|
||||
4. **Decision:** Keep Sonnet, document why
|
||||
|
||||
### Pattern: Haiku for Most, Sonnet for Complex
|
||||
|
||||
**Review-pr skill:**
|
||||
- Static analysis steps: Haiku could handle
|
||||
- Manual code review: Needs Sonnet judgment
|
||||
- **Decision:** Use Sonnet for whole skill (simplicity)
|
||||
|
||||
### Pattern: Split Complex Skills
|
||||
|
||||
**Instead of:** One complex skill using Opus
|
||||
|
||||
**Try:** Split into:
|
||||
- Haiku skill for orchestration
|
||||
- Sonnet agent for complex subtask
|
||||
- Saves cost (most work in Haiku)
|
||||
|
||||
## Model Selection Checklist
|
||||
|
||||
Before choosing a model:
|
||||
|
||||
- [ ] Tested with Haiku first
|
||||
- [ ] Measured success rate on 3-5 test cases
|
||||
- [ ] Tried improvements (scripts, validation, checklists)
|
||||
- [ ] Documented why this model is needed
|
||||
- [ ] Considered cost implications (12x/60x)
|
||||
- [ ] Considered speed implications (2.5x/5x slower)
|
||||
- [ ] Will re-test if Claude models improve
|
||||
|
||||
## Future-Proofing
|
||||
|
||||
**Models improve over time.**
|
||||
|
||||
Periodically re-test Sonnet/Opus skills with Haiku:
|
||||
- Haiku v2 might handle what Haiku v1 couldn't
|
||||
- Cost savings compound over time
|
||||
- Speed improvements are valuable
|
||||
|
||||
**Set a reminder:** Test Haiku again in 3-6 months.
|
||||
49
old2/skills/setup.md
Normal file
49
old2/skills/setup.md
Normal file
@@ -0,0 +1,49 @@
|
||||
# Gitea CLI Setup
|
||||
|
||||
One-time installation and authentication setup for `tea` CLI.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
brew install tea
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
The `tea` CLI authenticates via `tea logins add`. Credentials are stored locally by tea.
|
||||
|
||||
```bash
|
||||
tea logins add # Interactive login
|
||||
tea logins add --url <url> --token <token> --name <name> # Non-interactive
|
||||
tea logins list # Show configured logins
|
||||
tea logins default <name> # Set default login
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Config is stored at `~/Library/Application Support/tea/config.yml` (macOS).
|
||||
|
||||
To avoid needing `--login` on every command, set defaults:
|
||||
|
||||
```yaml
|
||||
preferences:
|
||||
editor: false
|
||||
flag_defaults:
|
||||
remote: origin
|
||||
login: git.flowmade.one
|
||||
```
|
||||
|
||||
## Example: Flowmade One Setup
|
||||
|
||||
```bash
|
||||
# Install
|
||||
brew install tea
|
||||
|
||||
# Add login (get token from https://git.flowmade.one/user/settings/applications)
|
||||
tea logins add --name flowmade --url https://git.flowmade.one --token <your-token>
|
||||
|
||||
# Set as default
|
||||
tea logins default flowmade
|
||||
```
|
||||
|
||||
Now `tea` commands will automatically use the flowmade login when run in a repository with a git.flowmade.one remote.
|
||||
291
old2/skills/spawn-issues/SKILL.md
Normal file
291
old2/skills/spawn-issues/SKILL.md
Normal file
@@ -0,0 +1,291 @@
|
||||
---
|
||||
name: spawn-issues
|
||||
description: >
|
||||
Orchestrate parallel issue implementation with automated review cycles. Use when
|
||||
implementing multiple issues concurrently, or when user says /spawn-issues.
|
||||
model: claude-haiku-4-5
|
||||
argument-hint: <issue-number> [<issue-number>...]
|
||||
allowed-tools: Bash, Task, Read, TaskOutput
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Spawn Issues
|
||||
|
||||
@~/.claude/skills/worktrees/SKILL.md
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
|
||||
Orchestrate parallel implementation of multiple issues with automated PR review and fixes.
|
||||
|
||||
## Arguments
|
||||
|
||||
One or more issue numbers: `$ARGUMENTS`
|
||||
|
||||
Example: `/spawn-issues 42 43 44`
|
||||
|
||||
## Workflow
|
||||
|
||||
```
|
||||
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 ──► ✓
|
||||
|
||||
Event-driven: As each task completes, immediately start next step.
|
||||
```
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Parse and Validate
|
||||
|
||||
Parse `$ARGUMENTS` into issue numbers. If empty:
|
||||
```
|
||||
Usage: /spawn-issues <issue-number> [<issue-number>...]
|
||||
Example: /spawn-issues 42 43 44
|
||||
```
|
||||
|
||||
### 2. Setup Repository Context
|
||||
|
||||
```bash
|
||||
REPO_PATH=$(pwd)
|
||||
REPO_NAME=$(basename "$REPO_PATH")
|
||||
WORKTREES_DIR="${REPO_PATH}/../worktrees"
|
||||
```
|
||||
|
||||
Verify in git repository:
|
||||
```bash
|
||||
git rev-parse --git-dir >/dev/null 2>&1 || exit 1
|
||||
```
|
||||
|
||||
### 3. Create All Worktrees Upfront
|
||||
|
||||
For each issue, create worktree using script:
|
||||
```bash
|
||||
cd "$REPO_PATH"
|
||||
worktree_path=$(~/.claude/skills/worktrees/scripts/create-worktree.sh issue <ISSUE_NUMBER>)
|
||||
```
|
||||
|
||||
Track worktree paths:
|
||||
```javascript
|
||||
issues = {
|
||||
42: {
|
||||
worktree: "/path/to/worktrees/repo-issue-42",
|
||||
stage: "ready",
|
||||
task_id: null,
|
||||
pr: null,
|
||||
branch: null,
|
||||
review_iterations: 0
|
||||
},
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Print initial status:
|
||||
```
|
||||
Created worktrees for 3 issues:
|
||||
[#42] ready
|
||||
[#43] ready
|
||||
[#44] ready
|
||||
```
|
||||
|
||||
### 4. Spawn All Issue Workers
|
||||
|
||||
For each issue, spawn issue-worker agent in background:
|
||||
|
||||
```
|
||||
Task tool with:
|
||||
- subagent_type: "issue-worker"
|
||||
- run_in_background: true
|
||||
- prompt: "Implement issue #<NUMBER>
|
||||
|
||||
Repository: <REPO_PATH>
|
||||
Repository name: <REPO_NAME>
|
||||
Issue number: <NUMBER>
|
||||
Worktree: <WORKTREE_PATH>
|
||||
|
||||
Follow the issue-worker agent instructions to implement, commit, push, and create PR.
|
||||
Output the result in ISSUE_WORKER_RESULT format."
|
||||
```
|
||||
|
||||
Track task_id for each issue and update stage to "implementing".
|
||||
|
||||
Print status:
|
||||
```
|
||||
[#42] implementing...
|
||||
[#43] implementing...
|
||||
[#44] implementing...
|
||||
```
|
||||
|
||||
### 5. Event-Driven Pipeline
|
||||
|
||||
**Wait for `<task-notification>` messages** that arrive automatically when background tasks complete.
|
||||
|
||||
When notification arrives:
|
||||
|
||||
1. **Identify which issue/task completed:**
|
||||
- Extract task_id from notification
|
||||
- Look up which issue this belongs to
|
||||
|
||||
2. **Read task output:**
|
||||
```
|
||||
TaskOutput tool with task_id
|
||||
```
|
||||
|
||||
3. **Parse result and update state:**
|
||||
- If issue-worker: extract PR number, branch, status
|
||||
- If code-reviewer: extract verdict (approved/needs-work)
|
||||
- If pr-fixer: extract status
|
||||
|
||||
4. **Print status update:**
|
||||
```
|
||||
[#42] Worker completed → PR #55 created, starting review
|
||||
[#43] Review: approved ✓
|
||||
[#42] Review: needs work → spawning fixer
|
||||
```
|
||||
|
||||
5. **Spawn next agent if needed:**
|
||||
- Worker done → spawn code-reviewer
|
||||
- Reviewer says "needs-work" → spawn pr-fixer
|
||||
- Fixer done → spawn code-reviewer again
|
||||
- Reviewer says "approved" → mark complete
|
||||
|
||||
6. **Check if all done:**
|
||||
- If all issues in terminal state → proceed to cleanup
|
||||
|
||||
### 6. State Transitions
|
||||
|
||||
```
|
||||
ready → implementing → reviewing → done
|
||||
→ needs-work → fixing → reviewing...
|
||||
→ (3 iterations) → needs-manual-review
|
||||
→ failed → done
|
||||
```
|
||||
|
||||
**Terminal states:** done, failed, needs-manual-review
|
||||
|
||||
### 7. Spawning Code Reviewer
|
||||
|
||||
When worker completes successfully:
|
||||
|
||||
**Get PR branch name from worker result:**
|
||||
```javascript
|
||||
branch_name = worker_result.branch
|
||||
```
|
||||
|
||||
**Create review worktree:**
|
||||
```bash
|
||||
cd "$REPO_PATH"
|
||||
review_worktree=$(~/.claude/skills/worktrees/scripts/create-worktree.sh review <PR_NUMBER> <BRANCH_NAME>)
|
||||
```
|
||||
|
||||
**Spawn code-reviewer agent:**
|
||||
```
|
||||
Task tool with:
|
||||
- subagent_type: "code-reviewer"
|
||||
- run_in_background: true
|
||||
- prompt: "Review PR #<PR_NUMBER>
|
||||
|
||||
Repository: <REPO_PATH>
|
||||
PR number: <PR_NUMBER>
|
||||
Worktree: <REVIEW_WORKTREE>
|
||||
|
||||
Follow the code-reviewer agent instructions to review the PR.
|
||||
Output the result in REVIEW_RESULT format."
|
||||
```
|
||||
|
||||
Update state: stage = "reviewing"
|
||||
|
||||
### 8. Spawning PR Fixer
|
||||
|
||||
When reviewer says "needs-work":
|
||||
|
||||
**Check iteration count:**
|
||||
- If review_iterations >= 3: mark as "needs-manual-review", skip fixer
|
||||
- Otherwise: increment review_iterations and spawn fixer
|
||||
|
||||
**Use existing issue worktree** (don't create new one):
|
||||
```javascript
|
||||
worktree_path = issues[issue_number].worktree
|
||||
```
|
||||
|
||||
**Spawn pr-fixer agent:**
|
||||
```
|
||||
Task tool with:
|
||||
- subagent_type: "pr-fixer"
|
||||
- run_in_background: true
|
||||
- prompt: "Fix review feedback for PR #<PR_NUMBER>
|
||||
|
||||
Repository: <REPO_PATH>
|
||||
PR number: <PR_NUMBER>
|
||||
Worktree: <WORKTREE_PATH>
|
||||
|
||||
Follow the pr-fixer agent instructions to address feedback.
|
||||
Output the result in PR_FIXER_RESULT format."
|
||||
```
|
||||
|
||||
Update state: stage = "fixing"
|
||||
|
||||
### 9. Cleanup Worktrees
|
||||
|
||||
After all issues reach terminal state:
|
||||
|
||||
```bash
|
||||
cd "$REPO_PATH"
|
||||
~/.claude/skills/worktrees/scripts/cleanup-worktrees.sh "$WORKTREES_DIR"
|
||||
```
|
||||
|
||||
This removes all issue and review worktrees created during this run.
|
||||
|
||||
### 10. Final Report
|
||||
|
||||
Print summary table:
|
||||
|
||||
```
|
||||
All done!
|
||||
|
||||
| Issue | PR | Status |
|
||||
|-------|-----|---------------------|
|
||||
| #42 | #55 | approved |
|
||||
| #43 | #56 | approved |
|
||||
| #44 | #57 | needs-manual-review |
|
||||
|
||||
2 approved, 1 needs manual review
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
|
||||
**Event-driven execution:**
|
||||
- Wait for task-notification messages
|
||||
- Don't poll or check task status manually
|
||||
- Process notifications as they arrive
|
||||
- Pipeline each issue independently
|
||||
|
||||
**Worktree management:**
|
||||
- Create all issue worktrees at start
|
||||
- Create review worktrees on demand
|
||||
- Reuse issue worktrees for pr-fixer
|
||||
- Clean up all worktrees at end
|
||||
|
||||
**State tracking:**
|
||||
- Track stage, task_id, PR, branch for each issue
|
||||
- Update state when notifications arrive
|
||||
- Print status after each transition
|
||||
|
||||
**Error handling:**
|
||||
- If worker fails: mark as "failed", continue with others
|
||||
- If reviewer fails: mark as "review-failed", continue
|
||||
- If 3 review iterations: mark as "needs-manual-review"
|
||||
- Always cleanup worktrees, even on error
|
||||
|
||||
**Review iteration limit:**
|
||||
- Maximum 3 review/fix cycles per issue
|
||||
- After 3 iterations: requires manual intervention
|
||||
- Prevents infinite review loops
|
||||
|
||||
## Tips
|
||||
|
||||
- Use `cd "$REPO_PATH"` before git/worktree operations
|
||||
- Scripts are in `~/.claude/skills/worktrees/scripts/`
|
||||
- Agents output structured results for parsing
|
||||
- Event notifications include task_id
|
||||
- Print status frequently to show progress
|
||||
259
old2/skills/spawn-pr-fixers/SKILL.md
Normal file
259
old2/skills/spawn-pr-fixers/SKILL.md
Normal file
@@ -0,0 +1,259 @@
|
||||
---
|
||||
name: spawn-pr-fixers
|
||||
description: >
|
||||
Fix one or more PRs based on review feedback using pr-fixer agents. Creates
|
||||
isolated worktrees, addresses review comments, commits and pushes fixes. Use
|
||||
when PRs need work, or when user says /spawn-pr-fixers.
|
||||
model: claude-haiku-4-5
|
||||
argument-hint: <pr-number> [<pr-number>...]
|
||||
allowed-tools: Bash, Task, Read, TaskOutput
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Spawn PR Fixers
|
||||
|
||||
@~/.claude/skills/worktrees/SKILL.md
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
|
||||
Fix one or more pull requests that have review feedback using pr-fixer agents.
|
||||
|
||||
## Arguments
|
||||
|
||||
One or more PR numbers: `$ARGUMENTS`
|
||||
|
||||
Example: `/spawn-pr-fixers 55 56 57`
|
||||
|
||||
## Workflow
|
||||
|
||||
```
|
||||
Concurrent Fixes - each PR fixed independently:
|
||||
|
||||
PR #55 ──► fetch branch ──► create worktree ──► read feedback ──► fix ──► commit ──► push ✓
|
||||
PR #56 ──► fetch branch ──► create worktree ──► read feedback ──► fix ──► commit ──► push ✓
|
||||
PR #57 ──► fetch branch ──► create worktree ──► read feedback ──► fix ──► commit ──► push ✓
|
||||
|
||||
Event-driven: As each fix completes, show results immediately.
|
||||
```
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Parse and Validate
|
||||
|
||||
Parse `$ARGUMENTS` into PR numbers. If empty:
|
||||
```
|
||||
Usage: /spawn-pr-fixers <pr-number> [<pr-number>...]
|
||||
Example: /spawn-pr-fixers 55 56
|
||||
```
|
||||
|
||||
### 2. Setup Repository Context
|
||||
|
||||
```bash
|
||||
REPO_PATH=$(pwd)
|
||||
REPO_NAME=$(basename "$REPO_PATH")
|
||||
WORKTREES_DIR="${REPO_PATH}/../worktrees"
|
||||
```
|
||||
|
||||
Verify in git repository:
|
||||
```bash
|
||||
git rev-parse --git-dir >/dev/null 2>&1 || exit 1
|
||||
```
|
||||
|
||||
### 3. Fetch PR Details and Create Worktrees
|
||||
|
||||
For each PR number:
|
||||
|
||||
**Get PR details:**
|
||||
```bash
|
||||
tea pulls <PR_NUMBER>
|
||||
```
|
||||
|
||||
Extract:
|
||||
- Branch name (e.g., "issue-42-feature-name")
|
||||
- PR title
|
||||
- PR state (verify it's open)
|
||||
|
||||
**Check for review comments:**
|
||||
```bash
|
||||
tea pulls <PR_NUMBER> --comments
|
||||
```
|
||||
|
||||
Verify there are review comments. If no comments:
|
||||
```
|
||||
[PR #<NUMBER>] No review comments found - skipping
|
||||
```
|
||||
|
||||
**Create fix worktree:**
|
||||
```bash
|
||||
cd "$REPO_PATH"
|
||||
git fetch origin
|
||||
fix_worktree=$(~/.claude/skills/worktrees/scripts/create-worktree.sh review <PR_NUMBER> <BRANCH_NAME>)
|
||||
```
|
||||
|
||||
Track PR state:
|
||||
```javascript
|
||||
prs = {
|
||||
55: {
|
||||
worktree: "/path/to/worktrees/repo-review-55",
|
||||
branch: "issue-42-feature",
|
||||
title: "Add user authentication",
|
||||
stage: "ready",
|
||||
task_id: null
|
||||
},
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Print initial status:
|
||||
```
|
||||
Created fix worktrees for 3 PRs:
|
||||
[PR #55] ready - Add user authentication
|
||||
[PR #56] ready - Fix validation bug
|
||||
[PR #57] ready - Update documentation
|
||||
```
|
||||
|
||||
### 4. Spawn PR Fixers
|
||||
|
||||
For each PR, spawn pr-fixer agent in background:
|
||||
|
||||
```
|
||||
Task tool with:
|
||||
- subagent_type: "pr-fixer"
|
||||
- run_in_background: true
|
||||
- prompt: "Fix PR #<PR_NUMBER> based on review feedback
|
||||
|
||||
Repository: <REPO_PATH>
|
||||
PR number: <PR_NUMBER>
|
||||
Worktree: <WORKTREE_PATH>
|
||||
|
||||
Follow the pr-fixer agent instructions to address review feedback.
|
||||
Output the result in PR_FIXER_RESULT format."
|
||||
```
|
||||
|
||||
Track task_id for each PR and update stage to "fixing".
|
||||
|
||||
Print status:
|
||||
```
|
||||
[PR #55] fixing...
|
||||
[PR #56] fixing...
|
||||
[PR #57] fixing...
|
||||
```
|
||||
|
||||
### 5. Event-Driven Results
|
||||
|
||||
**Wait for `<task-notification>` messages** that arrive automatically when background tasks complete.
|
||||
|
||||
When notification arrives:
|
||||
|
||||
1. **Identify which PR completed:**
|
||||
- Extract task_id from notification
|
||||
- Look up which PR this belongs to
|
||||
|
||||
2. **Read task output:**
|
||||
```
|
||||
TaskOutput tool with task_id
|
||||
```
|
||||
|
||||
3. **Parse result:**
|
||||
- Extract status (fixed/partial/failed)
|
||||
- Extract changes summary
|
||||
|
||||
4. **Print status update:**
|
||||
```
|
||||
[PR #55] Fix complete: fixed ✓
|
||||
[PR #56] Fix complete: partial (some issues unclear)
|
||||
[PR #57] Fix complete: fixed ✓
|
||||
```
|
||||
|
||||
5. **Check if all done:**
|
||||
- If all PRs fixed → proceed to cleanup and summary
|
||||
|
||||
### 6. Cleanup Worktrees
|
||||
|
||||
After all fixes complete:
|
||||
|
||||
```bash
|
||||
cd "$REPO_PATH"
|
||||
~/.claude/skills/worktrees/scripts/cleanup-worktrees.sh "$WORKTREES_DIR"
|
||||
```
|
||||
|
||||
This removes all fix worktrees created during this run.
|
||||
|
||||
### 7. Final Summary
|
||||
|
||||
Print summary table with links:
|
||||
|
||||
```
|
||||
All fixes complete!
|
||||
|
||||
| PR | Title | Status | Changes |
|
||||
|-----|---------------------------|-------------|--------------------------------------|
|
||||
| #55 | Add user authentication | fixed ✓ | Fixed error handling, added tests |
|
||||
| #56 | Fix validation bug | partial | Fixed main issue, one unclear |
|
||||
| #57 | Update documentation | fixed ✓ | Fixed typos, improved examples |
|
||||
|
||||
2 fully fixed, 1 partial
|
||||
|
||||
PRs updated:
|
||||
- PR #55: https://git.flowmade.one/owner/repo/pulls/55
|
||||
- PR #56: https://git.flowmade.one/owner/repo/pulls/56
|
||||
- PR #57: https://git.flowmade.one/owner/repo/pulls/57
|
||||
|
||||
Next: Re-run reviews with /spawn-pr-reviews to verify fixes
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
|
||||
**Event-driven execution:**
|
||||
- Wait for task-notification messages
|
||||
- Don't poll or check task status manually
|
||||
- Process notifications as they arrive
|
||||
- Fix each PR independently
|
||||
|
||||
**Worktree management:**
|
||||
- Create fix worktrees upfront
|
||||
- One worktree per PR
|
||||
- Clean up all worktrees at end
|
||||
- Always cleanup, even on error
|
||||
|
||||
**State tracking:**
|
||||
- Track stage and task_id for each PR
|
||||
- Update state when notifications arrive
|
||||
- Print status after each transition
|
||||
|
||||
**Error handling:**
|
||||
- If PR not found: skip it, continue with others
|
||||
- If PR is closed: skip it, note in summary
|
||||
- If no review comments: skip it, note why
|
||||
- If branch not found: skip it, note error
|
||||
- If fixer fails: mark as "failed"
|
||||
- Always cleanup worktrees
|
||||
|
||||
**Review iteration:**
|
||||
- This is one fix pass
|
||||
- After fixes, use /spawn-pr-reviews to re-review
|
||||
- Can repeat fix → review cycles manually
|
||||
- For automated cycles, use /spawn-issues instead
|
||||
|
||||
## Use Cases
|
||||
|
||||
**When to use spawn-pr-fixers:**
|
||||
- PRs have review feedback that needs addressing
|
||||
- Manual PRs from team members need fixes
|
||||
- spawn-issues hit review iteration limit (3 cycles)
|
||||
- You want to re-apply fixes after manual changes
|
||||
- Quick fixes to existing PRs
|
||||
|
||||
**When NOT to use spawn-pr-fixers:**
|
||||
- Implementing new issues (use /spawn-issues)
|
||||
- Just reviewing PRs (use /spawn-pr-reviews)
|
||||
- Need automated review loops (use /spawn-issues)
|
||||
- PRs have no review comments yet
|
||||
|
||||
## Tips
|
||||
|
||||
- Run after /spawn-pr-reviews identifies issues
|
||||
- Can fix multiple PRs at once for efficiency
|
||||
- Fixes are autonomous (agents make judgment calls)
|
||||
- Review the fixes after completion
|
||||
- Use /spawn-pr-reviews again to verify fixes
|
||||
- For full automation, use /spawn-issues instead
|
||||
230
old2/skills/spawn-pr-reviews/SKILL.md
Normal file
230
old2/skills/spawn-pr-reviews/SKILL.md
Normal file
@@ -0,0 +1,230 @@
|
||||
---
|
||||
name: spawn-pr-reviews
|
||||
description: >
|
||||
Review one or more pull requests using code-reviewer agent. Creates isolated
|
||||
review worktrees, spawns reviewers, posts feedback. Use when reviewing PRs,
|
||||
or when user says /spawn-pr-reviews.
|
||||
model: claude-haiku-4-5
|
||||
argument-hint: <pr-number> [<pr-number>...]
|
||||
allowed-tools: Bash, Task, Read, TaskOutput
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Spawn PR Reviews
|
||||
|
||||
@~/.claude/skills/worktrees/SKILL.md
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
|
||||
Review one or more pull requests in parallel using code-reviewer agents.
|
||||
|
||||
## Arguments
|
||||
|
||||
One or more PR numbers: `$ARGUMENTS`
|
||||
|
||||
Example: `/spawn-pr-reviews 55 56 57`
|
||||
|
||||
## Workflow
|
||||
|
||||
```
|
||||
Concurrent Reviews - each PR reviewed independently:
|
||||
|
||||
PR #55 ──► fetch branch ──► create worktree ──► review ──► post comment ✓
|
||||
PR #56 ──► fetch branch ──► create worktree ──► review ──► post comment ✓
|
||||
PR #57 ──► fetch branch ──► create worktree ──► review ──► post comment ✓
|
||||
|
||||
Event-driven: As each review completes, show results immediately.
|
||||
```
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Parse and Validate
|
||||
|
||||
Parse `$ARGUMENTS` into PR numbers. If empty:
|
||||
```
|
||||
Usage: /spawn-pr-reviews <pr-number> [<pr-number>...]
|
||||
Example: /spawn-pr-reviews 55 56
|
||||
```
|
||||
|
||||
### 2. Setup Repository Context
|
||||
|
||||
```bash
|
||||
REPO_PATH=$(pwd)
|
||||
REPO_NAME=$(basename "$REPO_PATH")
|
||||
WORKTREES_DIR="${REPO_PATH}/../worktrees"
|
||||
```
|
||||
|
||||
Verify in git repository:
|
||||
```bash
|
||||
git rev-parse --git-dir >/dev/null 2>&1 || exit 1
|
||||
```
|
||||
|
||||
### 3. Fetch PR Details and Create Worktrees
|
||||
|
||||
For each PR number:
|
||||
|
||||
**Get PR details:**
|
||||
```bash
|
||||
tea pulls <PR_NUMBER>
|
||||
```
|
||||
|
||||
Extract:
|
||||
- Branch name (e.g., "issue-42-feature-name")
|
||||
- PR title
|
||||
- PR state (verify it's open)
|
||||
|
||||
**Create review worktree:**
|
||||
```bash
|
||||
cd "$REPO_PATH"
|
||||
git fetch origin
|
||||
review_worktree=$(~/.claude/skills/worktrees/scripts/create-worktree.sh review <PR_NUMBER> <BRANCH_NAME>)
|
||||
```
|
||||
|
||||
Track PR state:
|
||||
```javascript
|
||||
prs = {
|
||||
55: {
|
||||
worktree: "/path/to/worktrees/repo-review-55",
|
||||
branch: "issue-42-feature",
|
||||
title: "Add user authentication",
|
||||
stage: "ready",
|
||||
task_id: null
|
||||
},
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Print initial status:
|
||||
```
|
||||
Created review worktrees for 3 PRs:
|
||||
[PR #55] ready - Add user authentication
|
||||
[PR #56] ready - Fix validation bug
|
||||
[PR #57] ready - Update documentation
|
||||
```
|
||||
|
||||
### 4. Spawn Code Reviewers
|
||||
|
||||
For each PR, spawn code-reviewer agent in background:
|
||||
|
||||
```
|
||||
Task tool with:
|
||||
- subagent_type: "code-reviewer"
|
||||
- run_in_background: true
|
||||
- prompt: "Review PR #<PR_NUMBER>
|
||||
|
||||
Repository: <REPO_PATH>
|
||||
PR number: <PR_NUMBER>
|
||||
Worktree: <WORKTREE_PATH>
|
||||
|
||||
Follow the code-reviewer agent instructions to review the PR.
|
||||
Output the result in REVIEW_RESULT format."
|
||||
```
|
||||
|
||||
Track task_id for each PR and update stage to "reviewing".
|
||||
|
||||
Print status:
|
||||
```
|
||||
[PR #55] reviewing...
|
||||
[PR #56] reviewing...
|
||||
[PR #57] reviewing...
|
||||
```
|
||||
|
||||
### 5. Event-Driven Results
|
||||
|
||||
**Wait for `<task-notification>` messages** that arrive automatically when background tasks complete.
|
||||
|
||||
When notification arrives:
|
||||
|
||||
1. **Identify which PR completed:**
|
||||
- Extract task_id from notification
|
||||
- Look up which PR this belongs to
|
||||
|
||||
2. **Read task output:**
|
||||
```
|
||||
TaskOutput tool with task_id
|
||||
```
|
||||
|
||||
3. **Parse result:**
|
||||
- Extract verdict (approved/needs-work)
|
||||
- Extract summary
|
||||
|
||||
4. **Print status update:**
|
||||
```
|
||||
[PR #55] Review complete: approved ✓
|
||||
[PR #56] Review complete: needs-work
|
||||
[PR #57] Review complete: approved ✓
|
||||
```
|
||||
|
||||
5. **Check if all done:**
|
||||
- If all PRs reviewed → proceed to cleanup and summary
|
||||
|
||||
### 6. Cleanup Worktrees
|
||||
|
||||
After all reviews complete:
|
||||
|
||||
```bash
|
||||
cd "$REPO_PATH"
|
||||
~/.claude/skills/worktrees/scripts/cleanup-worktrees.sh "$WORKTREES_DIR"
|
||||
```
|
||||
|
||||
This removes all review worktrees created during this run.
|
||||
|
||||
### 7. Final Summary
|
||||
|
||||
Print summary table with links:
|
||||
|
||||
```
|
||||
All reviews complete!
|
||||
|
||||
| PR | Title | Verdict |
|
||||
|-----|---------------------------|-------------|
|
||||
| #55 | Add user authentication | approved ✓ |
|
||||
| #56 | Fix validation bug | needs-work |
|
||||
| #57 | Update documentation | approved ✓ |
|
||||
|
||||
2 approved, 1 needs changes
|
||||
|
||||
View reviews:
|
||||
- PR #55: https://git.flowmade.one/owner/repo/pulls/55
|
||||
- PR #56: https://git.flowmade.one/owner/repo/pulls/56
|
||||
- PR #57: https://git.flowmade.one/owner/repo/pulls/57
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
|
||||
**Event-driven execution:**
|
||||
- Wait for task-notification messages
|
||||
- Don't poll or check task status manually
|
||||
- Process notifications as they arrive
|
||||
- Review each PR independently
|
||||
|
||||
**Worktree management:**
|
||||
- Create review worktrees upfront
|
||||
- One worktree per PR
|
||||
- Clean up all worktrees at end
|
||||
- Always cleanup, even on error
|
||||
|
||||
**State tracking:**
|
||||
- Track stage and task_id for each PR
|
||||
- Update state when notifications arrive
|
||||
- Print status after each transition
|
||||
|
||||
**Error handling:**
|
||||
- If PR not found: skip it, continue with others
|
||||
- If PR is closed: skip it, note in summary
|
||||
- If branch not found: skip it, note error
|
||||
- If reviewer fails: mark as "review-failed"
|
||||
- Always cleanup worktrees
|
||||
|
||||
**Read-only operation:**
|
||||
- Reviews are read-only (no fixes applied)
|
||||
- Comments posted to PRs
|
||||
- No merging or state changes
|
||||
- User decides on next actions
|
||||
|
||||
## Tips
|
||||
|
||||
- Run after PRs are created
|
||||
- Can review multiple PRs at once for efficiency
|
||||
- Review comments include specific actionable feedback
|
||||
- Use spawn-issues if you want automatic fix loops
|
||||
- Check PR state before spawning (open vs closed)
|
||||
67
old2/skills/templates/agent.md
Normal file
67
old2/skills/templates/agent.md
Normal file
@@ -0,0 +1,67 @@
|
||||
---
|
||||
name: agent-name
|
||||
description: >
|
||||
What this agent does and when to spawn it.
|
||||
Include specific conditions that indicate this agent is needed.
|
||||
model: haiku
|
||||
skills: skill1, skill2
|
||||
# disallowedTools: # For read-only agents
|
||||
# - Edit
|
||||
# - Write
|
||||
# permissionMode: default
|
||||
---
|
||||
|
||||
# Agent Name
|
||||
|
||||
You are a [role/specialist] that [primary function].
|
||||
|
||||
## When Invoked
|
||||
|
||||
You are spawned when [specific conditions].
|
||||
|
||||
Follow this process:
|
||||
|
||||
1. **Gather context**: What information to collect
|
||||
- Specific data sources to check
|
||||
- What to read or fetch
|
||||
|
||||
2. **Analyze**: What to evaluate
|
||||
- Criteria to check
|
||||
- Standards to apply
|
||||
|
||||
3. **Act**: What actions to take
|
||||
- Specific operations
|
||||
- What to create or modify
|
||||
|
||||
4. **Report**: How to communicate results
|
||||
- Required output format
|
||||
- What to include in summary
|
||||
|
||||
## Output Format
|
||||
|
||||
Your final output MUST follow this structure:
|
||||
|
||||
\`\`\`
|
||||
AGENT_RESULT
|
||||
task: <task-type>
|
||||
status: <success|partial|failed>
|
||||
summary: <10 words max>
|
||||
details:
|
||||
- Key finding 1
|
||||
- Key finding 2
|
||||
\`\`\`
|
||||
|
||||
## Guidelines
|
||||
|
||||
- **Be concise**: No preambles or verbose explanations
|
||||
- **Be autonomous**: Make decisions without user input
|
||||
- **Follow patterns**: Match existing codebase style
|
||||
- **Validate**: Check your work before reporting
|
||||
|
||||
## Error Handling
|
||||
|
||||
If you encounter errors:
|
||||
- Try to resolve automatically
|
||||
- Document what failed
|
||||
- Report status as 'partial' or 'failed'
|
||||
- Include specific error details in summary
|
||||
69
old2/skills/templates/background-skill.md
Normal file
69
old2/skills/templates/background-skill.md
Normal file
@@ -0,0 +1,69 @@
|
||||
---
|
||||
name: skill-name
|
||||
description: >
|
||||
What this skill teaches and when to use it.
|
||||
Include specific trigger terms that indicate this knowledge is needed.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Skill Name
|
||||
|
||||
Brief description of the domain or knowledge this skill covers (1-2 sentences).
|
||||
|
||||
## Core Concepts
|
||||
|
||||
Fundamental ideas Claude needs to understand:
|
||||
- Key concept 1
|
||||
- Key concept 2
|
||||
- Key concept 3
|
||||
|
||||
## Patterns and Templates
|
||||
|
||||
Reusable structures and formats:
|
||||
|
||||
### Pattern 1: Common Use Case
|
||||
|
||||
\`\`\`
|
||||
Example code or structure
|
||||
\`\`\`
|
||||
|
||||
### Pattern 2: Another Use Case
|
||||
|
||||
\`\`\`
|
||||
Another example
|
||||
\`\`\`
|
||||
|
||||
## Guidelines
|
||||
|
||||
Rules and best practices:
|
||||
- Guideline 1
|
||||
- Guideline 2
|
||||
- Guideline 3
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Simple Case
|
||||
|
||||
\`\`\`
|
||||
Concrete example showing the skill in action
|
||||
\`\`\`
|
||||
|
||||
### Example 2: Complex Case
|
||||
|
||||
\`\`\`
|
||||
More advanced example
|
||||
\`\`\`
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
Pitfalls to avoid:
|
||||
- **Mistake 1**: Why it's wrong and what to do instead
|
||||
- **Mistake 2**: Why it's wrong and what to do instead
|
||||
|
||||
## Reference
|
||||
|
||||
Quick-reference tables or checklists:
|
||||
|
||||
| Command | Purpose | Example |
|
||||
|---------|---------|---------|
|
||||
| ... | ... | ... |
|
||||
86
old2/skills/templates/helper-script.sh
Normal file
86
old2/skills/templates/helper-script.sh
Normal file
@@ -0,0 +1,86 @@
|
||||
#!/bin/bash
|
||||
# script-name.sh - Brief description of what this script does
|
||||
#
|
||||
# Usage: script-name.sh <param1> <param2> [optional-param]
|
||||
#
|
||||
# Example:
|
||||
# script-name.sh value1 value2
|
||||
# script-name.sh value1 value2 optional-value
|
||||
#
|
||||
# Exit codes:
|
||||
# 0 - Success
|
||||
# 1 - Invalid arguments or general error
|
||||
# 2 - Specific error condition (document what)
|
||||
|
||||
set -e # Exit immediately on error
|
||||
# set -x # Uncomment for debugging
|
||||
|
||||
# Color output for better visibility
|
||||
RED='\033[0;31m'
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[1;33m'
|
||||
NC='\033[0m' # No Color
|
||||
|
||||
# Helper functions
|
||||
error() {
|
||||
echo -e "${RED}ERROR: $1${NC}" >&2
|
||||
exit 1
|
||||
}
|
||||
|
||||
success() {
|
||||
echo -e "${GREEN}SUCCESS: $1${NC}"
|
||||
}
|
||||
|
||||
warn() {
|
||||
echo -e "${YELLOW}WARNING: $1${NC}"
|
||||
}
|
||||
|
||||
# Input validation
|
||||
if [ $# -lt 2 ]; then
|
||||
echo "Usage: $0 <param1> <param2> [optional-param]"
|
||||
echo ""
|
||||
echo "Description: Brief description of what this does"
|
||||
echo ""
|
||||
echo "Arguments:"
|
||||
echo " param1 Description of param1"
|
||||
echo " param2 Description of param2"
|
||||
echo " optional-param Description of optional param (default: value)"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Parse arguments
|
||||
PARAM1=$1
|
||||
PARAM2=$2
|
||||
OPTIONAL_PARAM=${3:-"default-value"}
|
||||
|
||||
# Validate inputs
|
||||
if [ -z "$PARAM1" ]; then
|
||||
error "param1 cannot be empty"
|
||||
fi
|
||||
|
||||
# Main logic
|
||||
main() {
|
||||
echo "Processing with param1=$PARAM1, param2=$PARAM2..."
|
||||
|
||||
# Step 1: Describe what this step does
|
||||
if ! some_command "$PARAM1"; then
|
||||
error "Failed to process param1"
|
||||
fi
|
||||
|
||||
# Step 2: Another operation with error handling
|
||||
result=$(another_command "$PARAM2" 2>&1)
|
||||
if [ $? -ne 0 ]; then
|
||||
error "Failed to process param2: $result"
|
||||
fi
|
||||
|
||||
# Step 3: Validation
|
||||
if [ ! -f "$result" ]; then
|
||||
error "Expected file not found: $result"
|
||||
fi
|
||||
|
||||
success "Operation completed successfully"
|
||||
echo "$result" # Output for caller to parse
|
||||
}
|
||||
|
||||
# Execute main function
|
||||
main
|
||||
65
old2/skills/templates/user-invocable-skill.md
Normal file
65
old2/skills/templates/user-invocable-skill.md
Normal file
@@ -0,0 +1,65 @@
|
||||
---
|
||||
name: skill-name
|
||||
description: >
|
||||
Clear description of what this skill does and when to use it.
|
||||
Use when [specific trigger conditions] or when user says /skill-name.
|
||||
model: haiku
|
||||
argument-hint: <required-param> [optional-param]
|
||||
user-invocable: true
|
||||
# context: fork # Use for skills needing isolated context
|
||||
# allowed-tools: # Restrict tools if needed
|
||||
# - Read
|
||||
# - Bash
|
||||
---
|
||||
|
||||
# Skill Title
|
||||
|
||||
@~/.claude/skills/relevant-background-skill/SKILL.md
|
||||
|
||||
Brief intro explaining the skill's purpose (1-2 sentences max).
|
||||
|
||||
## Process
|
||||
|
||||
1. **First step**: Clear action with specific command or instruction
|
||||
- `command or tool to use`
|
||||
- What to look for or validate
|
||||
|
||||
2. **Second step**: Next action
|
||||
- Specific details
|
||||
- Expected output
|
||||
|
||||
3. **Ask for approval** before significant actions
|
||||
- Show what will be created/modified
|
||||
- Wait for user confirmation
|
||||
|
||||
4. **Execute** the approved actions
|
||||
- Run commands/create files
|
||||
- Handle errors gracefully
|
||||
|
||||
5. **Present results** with links and summary
|
||||
- Structured output (table or list)
|
||||
- Links to created resources
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Keep responses concise
|
||||
- Use structured output (tables, lists)
|
||||
- No preambles or sign-offs
|
||||
- Validate inputs before acting
|
||||
|
||||
## Output Format
|
||||
|
||||
Use this structure for responses:
|
||||
|
||||
\`\`\`
|
||||
## Summary
|
||||
[1-2 sentences]
|
||||
|
||||
## Results
|
||||
| Item | Status | Link |
|
||||
|------|--------|------|
|
||||
| ... | ... | ... |
|
||||
|
||||
## Next Steps
|
||||
- ...
|
||||
\`\`\`
|
||||
349
old2/skills/vision-to-backlog/SKILL.md
Normal file
349
old2/skills/vision-to-backlog/SKILL.md
Normal file
@@ -0,0 +1,349 @@
|
||||
---
|
||||
name: vision-to-backlog
|
||||
description: >
|
||||
Orchestrate the full product strategy chain from manifesto to executable backlog.
|
||||
Use when breaking down product vision into work, or when user says /vision-to-backlog.
|
||||
model: claude-haiku-4-5
|
||||
argument-hint: [vision-file]
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Vision to Backlog
|
||||
|
||||
@~/.claude/skills/product-strategy/SKILL.md
|
||||
@~/.claude/skills/gitea/SKILL.md
|
||||
|
||||
Orchestrate the disciplined chain: Manifesto → Vision → Problem Space → Contexts → Domain → Capabilities → Features → Issues.
|
||||
|
||||
## Arguments
|
||||
|
||||
Optional: path to vision.md file (defaults to `./vision.md`)
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Locate Manifesto and Vision
|
||||
|
||||
**Manifesto** (organization-level):
|
||||
```bash
|
||||
cat ~/.claude/manifesto.md
|
||||
# Or if in architecture repo:
|
||||
cat ./manifesto.md
|
||||
```
|
||||
|
||||
**Vision** (product-level):
|
||||
```bash
|
||||
# If argument provided: use that file
|
||||
# Otherwise: look for vision.md in current repo
|
||||
cat ./vision.md
|
||||
```
|
||||
|
||||
Verify both files exist. If vision doesn't exist, help user create it following product-strategy framework.
|
||||
|
||||
### 2. Create Artifacts Directory
|
||||
|
||||
Create directory for strategy artifacts:
|
||||
```bash
|
||||
mkdir -p .product-strategy
|
||||
```
|
||||
|
||||
All artifacts will be saved here to keep root clean.
|
||||
|
||||
### 3. Vision Decision Gate
|
||||
|
||||
Show vision to user and ask:
|
||||
|
||||
**Can you answer these crisply:**
|
||||
- Who is this product for?
|
||||
- What pain is eliminated?
|
||||
- What job is now trivial?
|
||||
- What won't we do?
|
||||
|
||||
If NO → help refine vision first, don't proceed.
|
||||
If YES → continue to problem space.
|
||||
|
||||
### 4. Spawn Problem Space Analyst
|
||||
|
||||
Use Task tool to spawn `problem-space-analyst` agent:
|
||||
|
||||
```
|
||||
Analyze the product vision to identify the problem space.
|
||||
|
||||
Manifesto: [path]
|
||||
Vision: [path]
|
||||
Codebase: [current directory]
|
||||
|
||||
Output:
|
||||
- Event timeline (business events, not entities)
|
||||
- User journeys
|
||||
- Decision points
|
||||
- Irreversible vs reversible actions
|
||||
- Where mistakes are expensive
|
||||
|
||||
Save artifact to: .product-strategy/problem-map.md
|
||||
|
||||
Follow problem-space-analyst agent instructions.
|
||||
```
|
||||
|
||||
Agent returns Problem Map artifact saved to `.product-strategy/problem-map.md`.
|
||||
|
||||
### 5. Problem Space Decision Gate
|
||||
|
||||
Show Problem Map to user and ask:
|
||||
|
||||
**Do you see events, not entities?**
|
||||
- If NO → problem space needs more work
|
||||
- If YES → continue to context mapping
|
||||
|
||||
### 6. Spawn Context Mapper
|
||||
|
||||
Use Task tool to spawn `context-mapper` agent:
|
||||
|
||||
```
|
||||
Identify bounded contexts from the problem space.
|
||||
|
||||
Problem Map: .product-strategy/problem-map.md
|
||||
Codebase: [current directory]
|
||||
|
||||
Analyze:
|
||||
- Intended contexts (from problem space)
|
||||
- Actual contexts (from codebase structure)
|
||||
- Misalignments
|
||||
|
||||
Output:
|
||||
- Bounded Context Map
|
||||
- Boundary rules
|
||||
- Refactoring needs (if brownfield)
|
||||
|
||||
Save artifact to: .product-strategy/context-map.md
|
||||
|
||||
Follow context-mapper agent instructions.
|
||||
```
|
||||
|
||||
Agent returns Bounded Context Map saved to `.product-strategy/context-map.md`.
|
||||
|
||||
### 7. Context Decision Gate
|
||||
|
||||
Show Bounded Context Map to user and ask:
|
||||
|
||||
**Are boundaries clear?**
|
||||
- Different language per context?
|
||||
- Different lifecycles per context?
|
||||
|
||||
If NO → revise contexts
|
||||
If YES → continue to domain modeling
|
||||
|
||||
### 8. Spawn Domain Modeler (Per Context)
|
||||
|
||||
For each bounded context, spawn `domain-modeler` agent:
|
||||
|
||||
```
|
||||
Model the domain for bounded context: [CONTEXT_NAME]
|
||||
|
||||
Context: [context details from .product-strategy/context-map.md]
|
||||
Codebase: [current directory]
|
||||
|
||||
Identify:
|
||||
- Aggregates (only where invariants exist)
|
||||
- Commands
|
||||
- Events
|
||||
- Policies
|
||||
- Read models
|
||||
|
||||
Compare with existing code if present.
|
||||
|
||||
Save artifact to: .product-strategy/domain-[context-name].md
|
||||
|
||||
Follow domain-modeler agent instructions.
|
||||
```
|
||||
|
||||
Agent returns Domain Model saved to `.product-strategy/domain-[context-name].md`.
|
||||
|
||||
### 9. Domain Model Decision Gate
|
||||
|
||||
For each context, verify:
|
||||
|
||||
**Does each aggregate enforce an invariant?**
|
||||
- If NO → simplify (might be read model or policy)
|
||||
- If YES → continue
|
||||
|
||||
### 10. Spawn Capability Extractor
|
||||
|
||||
Use Task tool to spawn `capability-extractor` agent:
|
||||
|
||||
```
|
||||
Extract product capabilities from domain models.
|
||||
|
||||
Domain Models: .product-strategy/domain-*.md
|
||||
|
||||
Output:
|
||||
- Capability Map
|
||||
- System abilities that cause meaningful domain changes
|
||||
|
||||
Save artifact to: .product-strategy/capabilities.md
|
||||
|
||||
Follow capability-extractor agent instructions.
|
||||
```
|
||||
|
||||
Agent returns Capability Map saved to `.product-strategy/capabilities.md`.
|
||||
|
||||
### 11. Capability Decision Gate
|
||||
|
||||
Show Capability Map to user and ask:
|
||||
|
||||
**Which capabilities do you want to build?**
|
||||
- Show all capabilities with descriptions
|
||||
- Let user select subset
|
||||
- Prioritize if needed
|
||||
|
||||
### 12. Spawn Backlog Builder
|
||||
|
||||
Use Task tool to spawn `backlog-builder` agent:
|
||||
|
||||
```
|
||||
Generate features and issues from selected capabilities.
|
||||
|
||||
Selected Capabilities: [user selection from .product-strategy/capabilities.md]
|
||||
Domain Models: .product-strategy/domain-*.md
|
||||
Codebase: [current directory]
|
||||
|
||||
For each capability:
|
||||
1. Define features (user-visible value)
|
||||
2. Decompose into issues (domain-order: commands, rules, events, reads, UI)
|
||||
3. Identify refactoring issues (if misaligned with domain)
|
||||
|
||||
Follow issue-writing skill format.
|
||||
|
||||
Save artifact to: .product-strategy/backlog.md
|
||||
|
||||
Follow backlog-builder agent instructions.
|
||||
```
|
||||
|
||||
Agent returns Features + Issues saved to `.product-strategy/backlog.md`.
|
||||
|
||||
### 13. Feature Decision Gate
|
||||
|
||||
Show generated features and ask:
|
||||
|
||||
**Does each feature move a capability?**
|
||||
**Is each feature demoable?**
|
||||
|
||||
If NO → refine features
|
||||
If YES → continue to issue creation
|
||||
|
||||
### 14. Issue Review
|
||||
|
||||
Present all generated issues from `.product-strategy/backlog.md` to user:
|
||||
|
||||
```
|
||||
## Generated Backlog
|
||||
|
||||
### Context: [Context Name]
|
||||
**Refactoring:**
|
||||
- #issue: [title]
|
||||
- #issue: [title]
|
||||
|
||||
**Features:**
|
||||
- Feature: [name]
|
||||
- #issue: [title] (command)
|
||||
- #issue: [title] (domain rule)
|
||||
- #issue: [title] (event)
|
||||
- #issue: [title] (read model)
|
||||
- #issue: [title] (UI)
|
||||
```
|
||||
|
||||
Ask user:
|
||||
**Ready to create these issues in Gitea?**
|
||||
- If YES → automatically proceed to create all issues (step 14)
|
||||
- If NO → ask what to modify, regenerate, ask again
|
||||
|
||||
### 15. Create Issues in Gitea (automatic after approval)
|
||||
|
||||
**After user approves in step 13, automatically create all issues.**
|
||||
|
||||
For each issue:
|
||||
```bash
|
||||
tea issues create \
|
||||
--title "[issue title]" \
|
||||
--description "[full issue with acceptance criteria]"
|
||||
```
|
||||
|
||||
Apply labels:
|
||||
- `feature` or `refactor`
|
||||
- `bounded-context/[context-name]`
|
||||
- `capability/[capability-name]`
|
||||
|
||||
### 16. Link Dependencies
|
||||
|
||||
For issues with dependencies:
|
||||
```bash
|
||||
tea issues deps add <dependent-issue> <blocker-issue>
|
||||
```
|
||||
|
||||
### 17. Final Report
|
||||
|
||||
Show created issues with links:
|
||||
|
||||
```
|
||||
## Backlog Created
|
||||
|
||||
### Context: Authentication
|
||||
- #42: Implement User aggregate
|
||||
- #43: Add RegisterUser command
|
||||
- #44: Publish UserRegistered event
|
||||
|
||||
### Context: Orders
|
||||
- #45: Refactor Order model to enforce invariants
|
||||
- #46: Add PlaceOrder command
|
||||
- #47: Publish OrderPlaced event
|
||||
|
||||
Total: 6 issues created across 2 contexts
|
||||
View backlog: [gitea issues link]
|
||||
|
||||
All artifacts saved in .product-strategy/:
|
||||
- problem-map.md
|
||||
- context-map.md
|
||||
- domain-*.md (one per context)
|
||||
- capabilities.md
|
||||
- backlog.md
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
|
||||
**Follow the chain:**
|
||||
- Don't skip steps
|
||||
- Each step has decision gate
|
||||
- User approves before proceeding to next step
|
||||
|
||||
**Automatic execution after approval:**
|
||||
- After user approves at decision gate, automatically proceed
|
||||
- Don't wait for another prompt
|
||||
- Execute the next step immediately
|
||||
- Example: "Ready to create issues?" → YES → create all issues automatically
|
||||
|
||||
**Let agents work:**
|
||||
- Agents do analysis autonomously
|
||||
- Orchestrator just dispatches and gates
|
||||
|
||||
**Decision gates prevent waste:**
|
||||
- Stop early if vision unclear
|
||||
- Verify events before contexts
|
||||
- Verify invariants before building
|
||||
- But once approved, automatically continue
|
||||
|
||||
**Brownfield handling:**
|
||||
- Agents analyze existing code at each step
|
||||
- Generate refactoring issues for misalignments
|
||||
- Generate feature issues for new capabilities
|
||||
|
||||
**Issue quality:**
|
||||
- Reference domain concepts, not UI
|
||||
- Follow domain decomposition order
|
||||
- Link dependencies properly
|
||||
|
||||
## Tips
|
||||
|
||||
- Run when starting new product or major feature area
|
||||
- Each artifact is presented for review
|
||||
- User can iterate at any decision gate
|
||||
- Issues are DDD-informed and executable
|
||||
- Works for greenfield and brownfield
|
||||
229
old2/skills/worktrees/SKILL.md
Normal file
229
old2/skills/worktrees/SKILL.md
Normal file
@@ -0,0 +1,229 @@
|
||||
---
|
||||
name: worktrees
|
||||
description: >
|
||||
Git worktree patterns for parallel development workflows. Use when managing
|
||||
multiple concurrent branches, implementing issues in parallel, or isolating
|
||||
work contexts.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Git Worktrees
|
||||
|
||||
Patterns and scripts for managing git worktrees in parallel development workflows.
|
||||
|
||||
## What are Worktrees?
|
||||
|
||||
Git worktrees allow multiple working directories from a single repository. Each worktree can have a different branch checked out, enabling true parallel development.
|
||||
|
||||
**Use cases:**
|
||||
- Implementing multiple issues simultaneously
|
||||
- Isolated review environments for PRs
|
||||
- Switching contexts without stashing
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
**Directory structure:**
|
||||
```
|
||||
project/
|
||||
├── .git/ # Main repo
|
||||
├── src/ # Main working tree
|
||||
└── ../worktrees/ # Sibling worktrees directory
|
||||
├── project-issue-42/ # Issue implementation
|
||||
├── project-issue-43/ # Another issue
|
||||
└── project-review-55/ # PR review
|
||||
```
|
||||
|
||||
**Naming patterns:**
|
||||
- Issue work: `${REPO_NAME}-issue-${ISSUE_NUMBER}`
|
||||
- PR review: `${REPO_NAME}-review-${PR_NUMBER}`
|
||||
- Feature work: `${REPO_NAME}-feature-${FEATURE_NAME}`
|
||||
|
||||
**Why sibling directory:**
|
||||
- Keeps main repo clean
|
||||
- Easy to identify worktrees
|
||||
- Simple bulk operations
|
||||
- Works with tooling that scans parent directories
|
||||
|
||||
## Creating Worktrees
|
||||
|
||||
### For Issue Implementation
|
||||
|
||||
```bash
|
||||
REPO_PATH=$(pwd)
|
||||
REPO_NAME=$(basename "$REPO_PATH")
|
||||
WORKTREES_DIR="${REPO_PATH}/../worktrees"
|
||||
ISSUE_NUMBER=42
|
||||
|
||||
# Create worktrees directory
|
||||
mkdir -p "$WORKTREES_DIR"
|
||||
|
||||
# Fetch latest
|
||||
git fetch origin
|
||||
|
||||
# Get issue title for branch name
|
||||
ISSUE_TITLE=$(tea issues $ISSUE_NUMBER | grep -i "title" | head -1 | cut -d: -f2- | xargs)
|
||||
BRANCH_NAME="issue-${ISSUE_NUMBER}-$(echo "$ISSUE_TITLE" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd '[:alnum:]-' | cut -c1-50)"
|
||||
|
||||
# Create worktree with new branch from main
|
||||
git worktree add "${WORKTREES_DIR}/${REPO_NAME}-issue-${ISSUE_NUMBER}" \
|
||||
-b "$BRANCH_NAME" origin/main
|
||||
```
|
||||
|
||||
### For PR Review
|
||||
|
||||
```bash
|
||||
# For reviewing existing PR branch
|
||||
PR_NUMBER=55
|
||||
BRANCH_NAME="issue-42-feature-name" # Get from PR details
|
||||
|
||||
git fetch origin
|
||||
git worktree add "${WORKTREES_DIR}/${REPO_NAME}-review-${PR_NUMBER}" \
|
||||
"origin/${BRANCH_NAME}"
|
||||
```
|
||||
|
||||
## Bundled Scripts
|
||||
|
||||
Use bundled scripts for error-prone operations. Scripts are located in `~/.claude/skills/worktrees/scripts/`:
|
||||
|
||||
### Create Worktree
|
||||
|
||||
```bash
|
||||
# Usage: ~/.claude/skills/worktrees/scripts/create-worktree.sh issue <issue-number>
|
||||
# Usage: ~/.claude/skills/worktrees/scripts/create-worktree.sh review <pr-number> <branch-name>
|
||||
|
||||
~/.claude/skills/worktrees/scripts/create-worktree.sh issue 42
|
||||
~/.claude/skills/worktrees/scripts/create-worktree.sh review 55 issue-42-feature-name
|
||||
```
|
||||
|
||||
Returns worktree path on success.
|
||||
|
||||
### List Worktrees
|
||||
|
||||
```bash
|
||||
~/.claude/skills/worktrees/scripts/list-worktrees.sh
|
||||
```
|
||||
|
||||
Shows all active worktrees with their branches.
|
||||
|
||||
### Cleanup Worktrees
|
||||
|
||||
```bash
|
||||
# Remove specific worktree
|
||||
~/.claude/skills/worktrees/scripts/cleanup-worktrees.sh "${WORKTREES_DIR}/${REPO_NAME}-issue-42"
|
||||
|
||||
# Remove all worktrees in directory
|
||||
~/.claude/skills/worktrees/scripts/cleanup-worktrees.sh "${WORKTREES_DIR}"
|
||||
|
||||
# Force remove even if dirty
|
||||
~/.claude/skills/worktrees/scripts/cleanup-worktrees.sh --force "${WORKTREES_DIR}"
|
||||
```
|
||||
|
||||
## Patterns
|
||||
|
||||
### Pattern: Parallel Issue Implementation
|
||||
|
||||
**Orchestrator creates all worktrees upfront:**
|
||||
```bash
|
||||
for issue in 42 43 44; do
|
||||
worktree_path=$(~/.claude/skills/worktrees/scripts/create-worktree.sh issue $issue)
|
||||
# Spawn worker with worktree_path
|
||||
done
|
||||
```
|
||||
|
||||
**Worker uses provided worktree:**
|
||||
```bash
|
||||
cd "$WORKTREE_PATH" # Provided by orchestrator
|
||||
# Do work
|
||||
git add -A && git commit -m "..."
|
||||
git push -u origin $(git branch --show-current)
|
||||
```
|
||||
|
||||
**Orchestrator cleans up after all complete:**
|
||||
```bash
|
||||
~/.claude/skills/worktrees/scripts/cleanup-worktrees.sh "${WORKTREES_DIR}"
|
||||
```
|
||||
|
||||
### Pattern: Review in Isolation
|
||||
|
||||
**Create review worktree:**
|
||||
```bash
|
||||
worktree_path=$(~/.claude/skills/worktrees/scripts/create-worktree.sh review $PR_NUMBER $BRANCH_NAME)
|
||||
cd "$worktree_path"
|
||||
git diff origin/main...HEAD # Review changes
|
||||
```
|
||||
|
||||
### Pattern: Error Recovery
|
||||
|
||||
**List stale worktrees:**
|
||||
```bash
|
||||
~/.claude/skills/worktrees/scripts/list-worktrees.sh
|
||||
```
|
||||
|
||||
**Force cleanup:**
|
||||
```bash
|
||||
~/.claude/skills/worktrees/scripts/cleanup-worktrees.sh --force "${WORKTREES_DIR}"
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
**Always provide worktree paths to agents:**
|
||||
- Orchestrator creates worktrees
|
||||
- Agents receive path as parameter
|
||||
- Agents work in provided path
|
||||
- Orchestrator handles cleanup
|
||||
|
||||
**Never nest cleanup:**
|
||||
- Only orchestrator cleans up
|
||||
- Agents never remove their own worktree
|
||||
- Cleanup happens after all work complete
|
||||
|
||||
**Track worktree paths:**
|
||||
```bash
|
||||
# In orchestrator
|
||||
declare -A worktrees
|
||||
worktrees[42]=$(~/.claude/skills/worktrees/scripts/create-worktree.sh issue 42)
|
||||
worktrees[43]=$(~/.claude/skills/worktrees/scripts/create-worktree.sh issue 43)
|
||||
|
||||
# Pass to agents
|
||||
spawn_agent --worktree="${worktrees[42]}"
|
||||
```
|
||||
|
||||
**Handle errors gracefully:**
|
||||
- Use scripts (they handle errors)
|
||||
- Always cleanup, even on failure
|
||||
- Force-remove if necessary
|
||||
|
||||
## Common Issues
|
||||
|
||||
**Worktree already exists:**
|
||||
```bash
|
||||
# Remove old worktree first
|
||||
~/.claude/skills/worktrees/scripts/cleanup-worktrees.sh "${WORKTREES_DIR}/${REPO_NAME}-issue-42"
|
||||
|
||||
# Then create new one
|
||||
~/.claude/skills/worktrees/scripts/create-worktree.sh issue 42
|
||||
```
|
||||
|
||||
**Branch already exists:**
|
||||
```bash
|
||||
# Delete branch if safe
|
||||
git branch -d issue-42-old-name
|
||||
|
||||
# Or force delete
|
||||
git branch -D issue-42-old-name
|
||||
```
|
||||
|
||||
**Stale worktrees after crash:**
|
||||
```bash
|
||||
# List and force remove
|
||||
~/.claude/skills/worktrees/scripts/list-worktrees.sh
|
||||
~/.claude/skills/worktrees/scripts/cleanup-worktrees.sh --force "${WORKTREES_DIR}"
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
- Keep worktrees short-lived (hours, not days)
|
||||
- Clean up regularly to avoid clutter
|
||||
- Use scripts for reliability
|
||||
- Let orchestrator manage lifecycle
|
||||
- Check `git worktree list` if unsure about state
|
||||
56
old2/skills/worktrees/scripts/cleanup-worktrees.sh
Executable file
56
old2/skills/worktrees/scripts/cleanup-worktrees.sh
Executable file
@@ -0,0 +1,56 @@
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
|
||||
# Clean up git worktrees
|
||||
#
|
||||
# Usage:
|
||||
# ./cleanup-worktrees.sh <path> # Remove specific worktree
|
||||
# ./cleanup-worktrees.sh <directory> # Remove all worktrees in directory
|
||||
# ./cleanup-worktrees.sh --force <path> # Force remove even if dirty
|
||||
|
||||
FORCE=false
|
||||
if [ "$1" = "--force" ]; then
|
||||
FORCE=true
|
||||
shift
|
||||
fi
|
||||
|
||||
TARGET="$1"
|
||||
REPO_PATH=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
|
||||
|
||||
cd "$REPO_PATH"
|
||||
|
||||
remove_worktree() {
|
||||
local worktree_path="$1"
|
||||
|
||||
if [ ! -d "$worktree_path" ]; then
|
||||
return 0
|
||||
fi
|
||||
|
||||
if [ "$FORCE" = true ]; then
|
||||
git worktree remove "$worktree_path" --force 2>/dev/null || true
|
||||
else
|
||||
git worktree remove "$worktree_path" 2>/dev/null || true
|
||||
fi
|
||||
}
|
||||
|
||||
# Check if target is a directory containing multiple worktrees
|
||||
if [ -d "$TARGET" ]; then
|
||||
# Check if it's a worktree itself or a directory of worktrees
|
||||
if git worktree list | grep -q "$TARGET\$"; then
|
||||
# It's a single worktree
|
||||
remove_worktree "$TARGET"
|
||||
else
|
||||
# It's a directory, remove all worktrees inside
|
||||
for worktree in "$TARGET"/*; do
|
||||
if [ -d "$worktree" ]; then
|
||||
remove_worktree "$worktree"
|
||||
fi
|
||||
done
|
||||
|
||||
# Try to remove the directory if empty
|
||||
rmdir "$TARGET" 2>/dev/null || true
|
||||
fi
|
||||
else
|
||||
echo "Error: Path does not exist: $TARGET" >&2
|
||||
exit 1
|
||||
fi
|
||||
74
old2/skills/worktrees/scripts/create-worktree.sh
Executable file
74
old2/skills/worktrees/scripts/create-worktree.sh
Executable file
@@ -0,0 +1,74 @@
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
|
||||
# Create a git worktree for issue work or PR review
|
||||
#
|
||||
# Usage:
|
||||
# ./create-worktree.sh issue <issue-number>
|
||||
# ./create-worktree.sh review <pr-number> <branch-name>
|
||||
#
|
||||
# Returns: Absolute path to created worktree (stdout)
|
||||
|
||||
MODE="$1"
|
||||
REPO_PATH=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
|
||||
REPO_NAME=$(basename "$REPO_PATH")
|
||||
WORKTREES_DIR="${REPO_PATH}/../worktrees"
|
||||
|
||||
# Ensure worktrees directory exists
|
||||
mkdir -p "$WORKTREES_DIR"
|
||||
|
||||
# Fetch latest from origin
|
||||
cd "$REPO_PATH"
|
||||
git fetch origin >/dev/null 2>&1
|
||||
|
||||
case "$MODE" in
|
||||
issue)
|
||||
ISSUE_NUMBER="$2"
|
||||
WORKTREE_NAME="${REPO_NAME}-issue-${ISSUE_NUMBER}"
|
||||
WORKTREE_PATH="${WORKTREES_DIR}/${WORKTREE_NAME}"
|
||||
|
||||
# Get issue title for branch name (tea issues output has title on line 2: " # #1 Title here")
|
||||
ISSUE_TITLE=$(tea issues "$ISSUE_NUMBER" 2>/dev/null | sed -n '2p' | sed 's/.*#[0-9]* //' | xargs || echo "untitled")
|
||||
|
||||
# Create safe branch name
|
||||
BRANCH_NAME="issue-${ISSUE_NUMBER}-$(echo "$ISSUE_TITLE" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd '[:alnum:]-' | cut -c1-50)"
|
||||
|
||||
# Remove worktree if it already exists
|
||||
if [ -d "$WORKTREE_PATH" ]; then
|
||||
git worktree remove "$WORKTREE_PATH" --force 2>/dev/null || true
|
||||
fi
|
||||
|
||||
# Delete branch if it exists
|
||||
git branch -D "$BRANCH_NAME" 2>/dev/null || true
|
||||
|
||||
# Create worktree with new branch from main
|
||||
git worktree add "$WORKTREE_PATH" -b "$BRANCH_NAME" origin/main >/dev/null 2>&1
|
||||
|
||||
echo "$WORKTREE_PATH"
|
||||
;;
|
||||
|
||||
review)
|
||||
PR_NUMBER="$2"
|
||||
BRANCH_NAME="$3"
|
||||
WORKTREE_NAME="${REPO_NAME}-review-${PR_NUMBER}"
|
||||
WORKTREE_PATH="${WORKTREES_DIR}/${WORKTREE_NAME}"
|
||||
|
||||
# Remove worktree if it already exists
|
||||
if [ -d "$WORKTREE_PATH" ]; then
|
||||
git worktree remove "$WORKTREE_PATH" --force 2>/dev/null || true
|
||||
fi
|
||||
|
||||
# Create worktree from existing branch
|
||||
git worktree add "$WORKTREE_PATH" "origin/${BRANCH_NAME}" >/dev/null 2>&1
|
||||
|
||||
echo "$WORKTREE_PATH"
|
||||
;;
|
||||
|
||||
*)
|
||||
echo "Error: Invalid mode '$MODE'. Use 'issue' or 'review'" >&2
|
||||
echo "Usage:" >&2
|
||||
echo " $0 issue <issue-number>" >&2
|
||||
echo " $0 review <pr-number> <branch-name>" >&2
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
13
old2/skills/worktrees/scripts/list-worktrees.sh
Executable file
13
old2/skills/worktrees/scripts/list-worktrees.sh
Executable file
@@ -0,0 +1,13 @@
|
||||
#!/bin/bash
|
||||
set -euo pipefail
|
||||
|
||||
# List all active git worktrees
|
||||
#
|
||||
# Usage:
|
||||
# ./list-worktrees.sh
|
||||
|
||||
REPO_PATH=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
|
||||
cd "$REPO_PATH"
|
||||
|
||||
echo "Active worktrees:"
|
||||
git worktree list
|
||||
Reference in New Issue
Block a user