feat: expand agents (10), skills (20), and hooks (11) with profile system
Agents: - Add YAML frontmatter (model, tools) to all 7 existing agents - New agents: planner (opus), build-error-resolver (sonnet), loop-operator (sonnet) Skills: - search-first: research before building (Adopt/Extend/Compose/Build) - verification-loop: full quality gate pipeline (Build→TypeCheck→Lint→Test→Security→Diff) - strategic-compact: when and how to run /compact effectively - autonomous-loops: 6 patterns for autonomous agent workflows - continuous-learning: extract session learnings into instincts Hooks: - Profile system (minimal/standard/strict) via run-with-profile.sh - config-protection: block linter/formatter config edits (standard) - suggest-compact: remind about /compact every ~50 tool calls (standard) - auto-tmux-dev: suggest tmux for dev servers (standard) - session-save/session-load: persist and restore session context (Stop/SessionStart) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
olekhondera
49
.claude/hooks/auto-tmux-dev.sh
Executable file
49
.claude/hooks/auto-tmux-dev.sh
Executable file
@@ -0,0 +1,49 @@
|
||||
#!/bin/bash
|
||||
# Auto-start dev server in tmux session when build/dev commands are detected
|
||||
# Event: PreToolUse | Matcher: Bash
|
||||
# Profile: standard
|
||||
# Non-blocking (exit 0)
|
||||
|
||||
INPUT=$(cat)
|
||||
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
|
||||
|
||||
if [ -z "$COMMAND" ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Detect dev server commands
|
||||
DEV_PATTERNS=(
|
||||
'npm\s+run\s+dev'
|
||||
'pnpm\s+(run\s+)?dev'
|
||||
'yarn\s+dev'
|
||||
'next\s+dev'
|
||||
'vite\s*$'
|
||||
'vite\s+dev'
|
||||
)
|
||||
|
||||
IS_DEV_COMMAND=false
|
||||
for pattern in "${DEV_PATTERNS[@]}"; do
|
||||
if echo "$COMMAND" | grep -qE "$pattern"; then
|
||||
IS_DEV_COMMAND=true
|
||||
break
|
||||
fi
|
||||
done
|
||||
|
||||
if [ "$IS_DEV_COMMAND" = false ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Check if tmux is available
|
||||
if ! command -v tmux &>/dev/null; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Check if dev server is already running in a tmux session
|
||||
SESSION_NAME="claude-dev"
|
||||
if tmux has-session -t "$SESSION_NAME" 2>/dev/null; then
|
||||
echo "Dev server already running in tmux session '$SESSION_NAME'. Use 'tmux attach -t $SESSION_NAME' to view." >&2
|
||||
exit 0
|
||||
fi
|
||||
|
||||
echo "Tip: Long-running dev servers work better in tmux. Run: tmux new -d -s $SESSION_NAME '$COMMAND'" >&2
|
||||
exit 0
|
||||
43
.claude/hooks/config-protection.sh
Executable file
43
.claude/hooks/config-protection.sh
Executable file
@@ -0,0 +1,43 @@
|
||||
#!/bin/bash
|
||||
# Block modifications to linter/formatter configuration files
|
||||
# Event: PreToolUse | Matcher: Edit|Write
|
||||
# Profile: standard
|
||||
# Exit 2 = block, Exit 0 = allow
|
||||
|
||||
INPUT=$(cat)
|
||||
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
|
||||
|
||||
if [ -z "$FILE_PATH" ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Protected config files (linters, formatters, build configs)
|
||||
PROTECTED_CONFIGS=(
|
||||
".eslintrc"
|
||||
".eslintrc.js"
|
||||
".eslintrc.json"
|
||||
".eslintrc.yml"
|
||||
"eslint.config.js"
|
||||
"eslint.config.mjs"
|
||||
".prettierrc"
|
||||
".prettierrc.js"
|
||||
".prettierrc.json"
|
||||
"prettier.config.js"
|
||||
"biome.json"
|
||||
"biome.jsonc"
|
||||
".editorconfig"
|
||||
"tsconfig.json"
|
||||
"tsconfig.base.json"
|
||||
)
|
||||
|
||||
FILENAME=$(basename "$FILE_PATH")
|
||||
|
||||
for config in "${PROTECTED_CONFIGS[@]}"; do
|
||||
if [ "$FILENAME" = "$config" ]; then
|
||||
echo "Blocked: modifying config file '$FILENAME'. These files affect the entire project." >&2
|
||||
echo "If this change is intentional, disable this hook: CLAUDE_DISABLED_HOOKS=config-protection.sh" >&2
|
||||
exit 2
|
||||
fi
|
||||
done
|
||||
|
||||
exit 0
|
||||
46
.claude/hooks/run-with-profile.sh
Executable file
46
.claude/hooks/run-with-profile.sh
Executable file
@@ -0,0 +1,46 @@
|
||||
#!/bin/bash
|
||||
# Hook profile gate — wraps hooks to enable/disable by profile
|
||||
# Profiles: minimal (safety only), standard (safety + quality), strict (everything)
|
||||
#
|
||||
# Usage in settings.json:
|
||||
# "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/run-with-profile.sh standard $CLAUDE_PROJECT_DIR/.claude/hooks/some-hook.sh"
|
||||
#
|
||||
# Environment variables:
|
||||
# CLAUDE_HOOK_PROFILE — Override profile (minimal|standard|strict). Default: standard
|
||||
# CLAUDE_DISABLED_HOOKS — Comma-separated list of hook filenames to skip. E.g.: "suggest-compact.sh,auto-tmux-dev.sh"
|
||||
|
||||
REQUIRED_PROFILE="${1:?Usage: run-with-profile.sh <profile> <hook-script>}"
|
||||
HOOK_SCRIPT="${2:?Usage: run-with-profile.sh <profile> <hook-script>}"
|
||||
shift 2
|
||||
|
||||
# Current profile (default: standard)
|
||||
CURRENT_PROFILE="${CLAUDE_HOOK_PROFILE:-standard}"
|
||||
|
||||
# Profile hierarchy: minimal < standard < strict
|
||||
profile_level() {
|
||||
case "$1" in
|
||||
minimal) echo 1 ;;
|
||||
standard) echo 2 ;;
|
||||
strict) echo 3 ;;
|
||||
*) echo 2 ;; # default to standard
|
||||
esac
|
||||
}
|
||||
|
||||
CURRENT_LEVEL=$(profile_level "$CURRENT_PROFILE")
|
||||
REQUIRED_LEVEL=$(profile_level "$REQUIRED_PROFILE")
|
||||
|
||||
# Skip if current profile is lower than required
|
||||
if [ "$CURRENT_LEVEL" -lt "$REQUIRED_LEVEL" ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Check if hook is explicitly disabled
|
||||
HOOK_NAME=$(basename "$HOOK_SCRIPT")
|
||||
if [ -n "$CLAUDE_DISABLED_HOOKS" ]; then
|
||||
if echo ",$CLAUDE_DISABLED_HOOKS," | grep -q ",$HOOK_NAME,"; then
|
||||
exit 0
|
||||
fi
|
||||
fi
|
||||
|
||||
# Execute the hook, passing stdin through
|
||||
exec "$HOOK_SCRIPT" "$@"
|
||||
31
.claude/hooks/session-load.sh
Executable file
31
.claude/hooks/session-load.sh
Executable file
@@ -0,0 +1,31 @@
|
||||
#!/bin/bash
|
||||
# Restore session context from previous session
|
||||
# Event: SessionStart
|
||||
# Reads .claude/sessions/latest.json and outputs a context summary
|
||||
|
||||
SESSION_FILE="${CLAUDE_PROJECT_DIR:-.}/.claude/sessions/latest.json"
|
||||
|
||||
if [ ! -f "$SESSION_FILE" ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Read session data
|
||||
TIMESTAMP=$(jq -r '.timestamp // "unknown"' "$SESSION_FILE" 2>/dev/null)
|
||||
BRANCH=$(jq -r '.branch // "unknown"' "$SESSION_FILE" 2>/dev/null)
|
||||
PHASE=$(jq -r '.phase // "unknown"' "$SESSION_FILE" 2>/dev/null)
|
||||
MODIFIED=$(jq -r '.modified_files // [] | length' "$SESSION_FILE" 2>/dev/null)
|
||||
STAGED=$(jq -r '.staged_files // [] | length' "$SESSION_FILE" 2>/dev/null)
|
||||
COMMITS=$(jq -r '.recent_commits // [] | join("\n ")' "$SESSION_FILE" 2>/dev/null)
|
||||
|
||||
echo "Previous session ($TIMESTAMP):"
|
||||
echo " Branch: $BRANCH"
|
||||
echo " Phase: $PHASE"
|
||||
echo " Modified files: $MODIFIED, Staged: $STAGED"
|
||||
if [ -n "$COMMITS" ] && [ "$COMMITS" != "" ]; then
|
||||
echo " Recent commits:"
|
||||
echo " $COMMITS"
|
||||
fi
|
||||
echo ""
|
||||
echo "Reminder: check RULES.md and RECOMMENDATIONS.md for project conventions."
|
||||
|
||||
exit 0
|
||||
31
.claude/hooks/session-save.sh
Executable file
31
.claude/hooks/session-save.sh
Executable file
@@ -0,0 +1,31 @@
|
||||
#!/bin/bash
|
||||
# Save session context on stop for restoration in next session
|
||||
# Event: Stop
|
||||
# Saves: branch, modified files, recent commits, phase
|
||||
|
||||
SESSION_DIR="${CLAUDE_PROJECT_DIR:-.}/.claude/sessions"
|
||||
mkdir -p "$SESSION_DIR"
|
||||
|
||||
SESSION_FILE="$SESSION_DIR/latest.json"
|
||||
|
||||
# Gather session state
|
||||
BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
|
||||
MODIFIED=$(git diff --name-only 2>/dev/null | head -20 | jq -R -s 'split("\n") | map(select(. != ""))')
|
||||
STAGED=$(git diff --cached --name-only 2>/dev/null | head -20 | jq -R -s 'split("\n") | map(select(. != ""))')
|
||||
RECENT_COMMITS=$(git log --oneline -5 2>/dev/null | jq -R -s 'split("\n") | map(select(. != ""))')
|
||||
PHASE=$(grep -m1 'Current Phase' "${CLAUDE_PROJECT_DIR:-.}/docs/phases-plan.md" 2>/dev/null || echo "unknown")
|
||||
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
|
||||
|
||||
# Write session file
|
||||
cat > "$SESSION_FILE" << ENDJSON
|
||||
{
|
||||
"timestamp": "$TIMESTAMP",
|
||||
"branch": "$BRANCH",
|
||||
"phase": "$PHASE",
|
||||
"modified_files": $MODIFIED,
|
||||
"staged_files": $STAGED,
|
||||
"recent_commits": $RECENT_COMMITS
|
||||
}
|
||||
ENDJSON
|
||||
|
||||
exit 0
|
||||
24
.claude/hooks/suggest-compact.sh
Executable file
24
.claude/hooks/suggest-compact.sh
Executable file
@@ -0,0 +1,24 @@
|
||||
#!/bin/bash
|
||||
# Suggest /compact after ~50 tool calls
|
||||
# Event: PreToolUse | Matcher: Edit|Write
|
||||
# Profile: standard
|
||||
# Non-blocking reminder (exit 0)
|
||||
|
||||
COUNTER_FILE="${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/.tool-counter"
|
||||
|
||||
# Initialize counter if it doesn't exist
|
||||
if [ ! -f "$COUNTER_FILE" ]; then
|
||||
echo "0" > "$COUNTER_FILE"
|
||||
fi
|
||||
|
||||
# Increment counter
|
||||
COUNT=$(cat "$COUNTER_FILE" 2>/dev/null || echo "0")
|
||||
COUNT=$((COUNT + 1))
|
||||
echo "$COUNT" > "$COUNTER_FILE"
|
||||
|
||||
# Suggest compact every 50 calls
|
||||
if [ $((COUNT % 50)) -eq 0 ]; then
|
||||
echo "Context optimization: $COUNT tool calls in this session. Consider running /strategic-compact if context feels bloated." >&2
|
||||
fi
|
||||
|
||||
exit 0
|
||||
@@ -7,6 +7,14 @@
|
||||
{
|
||||
"type": "command",
|
||||
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
|
||||
},
|
||||
{
|
||||
"type": "command",
|
||||
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-with-profile.sh standard \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/config-protection.sh"
|
||||
},
|
||||
{
|
||||
"type": "command",
|
||||
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-with-profile.sh standard \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/suggest-compact.sh"
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -20,6 +28,10 @@
|
||||
{
|
||||
"type": "command",
|
||||
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/commit-docs-reminder.sh"
|
||||
},
|
||||
{
|
||||
"type": "command",
|
||||
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-with-profile.sh standard \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/auto-tmux-dev.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -30,7 +42,7 @@
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/post-edit-format.sh"
|
||||
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-with-profile.sh strict \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/post-edit-format.sh"
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -57,11 +69,22 @@
|
||||
],
|
||||
"SessionStart": [
|
||||
{
|
||||
"matcher": "compact",
|
||||
"matcher": "",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "echo \"Reminder: check RULES.md and RECOMMENDATIONS.md for project conventions. Current phase: $(grep -m1 'Current Phase' \"$CLAUDE_PROJECT_DIR/docs/phases-plan.md\" 2>/dev/null || echo 'unknown')\""
|
||||
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/session-load.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"Stop": [
|
||||
{
|
||||
"matcher": "",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/session-save.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
204
.claude/skills/autonomous-loops/SKILL.md
Normal file
204
.claude/skills/autonomous-loops/SKILL.md
Normal file
@@ -0,0 +1,204 @@
|
||||
---
|
||||
name: autonomous-loops
|
||||
description: Patterns for running autonomous agent workflows — from simple pipelines to complex multi-agent DAGs. Reference for setting up build-fix loops, continuous PRs, and de-sloppify passes.
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Autonomous Loop Patterns
|
||||
|
||||
Reference guide for autonomous agent workflows, ranked by complexity.
|
||||
|
||||
## Pattern 1: Sequential Pipeline
|
||||
|
||||
**Complexity**: Low
|
||||
**Use when**: Simple one-shot tasks chained together
|
||||
|
||||
```bash
|
||||
# Run a sequence of claude commands
|
||||
claude -p "Implement feature X" --output-format json | \
|
||||
claude -p "Write tests for the implementation" --output-format json | \
|
||||
claude -p "Review the code for issues"
|
||||
```
|
||||
|
||||
**Pros**: Simple, predictable, easy to debug
|
||||
**Cons**: No error recovery, no parallelism
|
||||
|
||||
## Pattern 2: Build-Fix Loop
|
||||
|
||||
**Complexity**: Medium
|
||||
**Use when**: Making the build green after changes
|
||||
|
||||
```bash
|
||||
MAX_CYCLES=5
|
||||
CYCLE=0
|
||||
|
||||
while [ $CYCLE -lt $MAX_CYCLES ]; do
|
||||
CYCLE=$((CYCLE + 1))
|
||||
echo "=== Cycle $CYCLE ==="
|
||||
|
||||
# Run build/tests
|
||||
BUILD_OUTPUT=$(npm run build 2>&1)
|
||||
if [ $? -eq 0 ]; then
|
||||
echo "Build passed on cycle $CYCLE"
|
||||
break
|
||||
fi
|
||||
|
||||
# Fix errors
|
||||
claude -p "Fix these build errors. Make minimal changes only:
|
||||
$BUILD_OUTPUT"
|
||||
|
||||
if [ $CYCLE -eq $MAX_CYCLES ]; then
|
||||
echo "STALLED after $MAX_CYCLES cycles — escalating"
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
**Key rules**:
|
||||
- Set a MAX_CYCLES limit (3-5 is reasonable)
|
||||
- Detect stalls (same error repeating)
|
||||
- Use the `loop-operator` agent for monitoring
|
||||
|
||||
## Pattern 3: Test-Driven Fix Loop
|
||||
|
||||
**Complexity**: Medium
|
||||
**Use when**: Fixing failing tests one at a time
|
||||
|
||||
```bash
|
||||
# Get failing tests
|
||||
FAILURES=$(npm test 2>&1 | grep "FAIL")
|
||||
|
||||
for test_file in $FAILURES; do
|
||||
claude -p "Fix this failing test. Read the test to understand intent,
|
||||
then fix the implementation (not the test):
|
||||
File: $test_file"
|
||||
done
|
||||
|
||||
# Verify all tests pass
|
||||
npm test
|
||||
```
|
||||
|
||||
**Key rules**:
|
||||
- Fix implementation, not tests (unless test is wrong)
|
||||
- Run full suite after fixes to catch regressions
|
||||
- Stop if fix count exceeds threshold
|
||||
|
||||
## Pattern 4: Continuous PR Loop
|
||||
|
||||
**Complexity**: High
|
||||
**Use when**: Processing a backlog of tasks as PRs
|
||||
|
||||
```bash
|
||||
# Process tasks from a list
|
||||
while IFS= read -r task; do
|
||||
BRANCH="auto/$(echo "$task" | tr ' ' '-' | head -c 40)"
|
||||
git checkout -b "$BRANCH" main
|
||||
|
||||
claude -p "Implement: $task
|
||||
Requirements:
|
||||
- Create a single focused PR
|
||||
- Include tests
|
||||
- Follow RULES.md conventions"
|
||||
|
||||
# Run verification
|
||||
claude -p "/verification-loop"
|
||||
|
||||
# Create PR if verification passes
|
||||
if [ $? -eq 0 ]; then
|
||||
git push -u origin "$BRANCH"
|
||||
gh pr create --title "$task" --body "Automated implementation"
|
||||
fi
|
||||
|
||||
git checkout main
|
||||
done < tasks.txt
|
||||
```
|
||||
|
||||
**Key rules**:
|
||||
- One task = one branch = one PR
|
||||
- Run verification before creating PR
|
||||
- Set cost/time limits per task
|
||||
- Skip tasks that fail after N attempts
|
||||
|
||||
## Pattern 5: De-Sloppify Pass
|
||||
|
||||
**Complexity**: Medium
|
||||
**Use when**: Cleaning up after a fast implementation pass
|
||||
|
||||
The insight: **Two focused agents outperform one constrained agent**. First implement fast, then clean up.
|
||||
|
||||
```bash
|
||||
# Phase 1: Fast implementation (allow some sloppiness)
|
||||
claude -p "Implement feature X quickly. Focus on correctness, not polish."
|
||||
|
||||
# Phase 2: Cleanup pass
|
||||
claude -p "Review and clean up the recent changes:
|
||||
1. Remove console.log/debug statements
|
||||
2. Add missing error handling
|
||||
3. Fix type safety issues (no 'any')
|
||||
4. Ensure consistent naming
|
||||
5. Add missing JSDoc for public APIs
|
||||
|
||||
Do NOT change behavior or add features. Only clean up."
|
||||
```
|
||||
|
||||
**Key rules**:
|
||||
- Cleanup agent must not change behavior
|
||||
- Use git diff to scope the cleanup
|
||||
- Run tests after cleanup to verify no regressions
|
||||
|
||||
## Pattern 6: Multi-Agent DAG
|
||||
|
||||
**Complexity**: Very High
|
||||
**Use when**: Large features requiring coordinated parallel work
|
||||
|
||||
```
|
||||
┌─────────┐
|
||||
│ Planner │
|
||||
└────┬────┘
|
||||
│
|
||||
┌─────┼─────┐
|
||||
▼ ▼ ▼
|
||||
[API] [UI] [DB] ← Parallel agents in worktrees
|
||||
│ │ │
|
||||
└─────┼─────┘
|
||||
▼
|
||||
┌───────────┐
|
||||
│ Integrator│ ← Merges and resolves conflicts
|
||||
└─────┬─────┘
|
||||
▼
|
||||
┌───────────┐
|
||||
│ Reviewer │ ← Final quality check
|
||||
└───────────┘
|
||||
```
|
||||
|
||||
**Implementation**:
|
||||
|
||||
1. **Planner** decomposes the spec into independent tasks with dependencies
|
||||
2. Independent tasks run in **parallel worktrees** (isolated git branches)
|
||||
3. **Integrator** merges worktrees, resolves conflicts
|
||||
4. **Reviewer** does final quality check
|
||||
|
||||
**Key rules**:
|
||||
- Use git worktrees for isolation
|
||||
- Each agent gets a focused, self-contained task
|
||||
- Integrator handles merge conflicts
|
||||
- Full verification after integration
|
||||
|
||||
## Choosing a Pattern
|
||||
|
||||
| Situation | Pattern |
|
||||
|-----------|---------|
|
||||
| Single task, no iteration needed | 1 (Sequential) |
|
||||
| Build is broken, need to fix | 2 (Build-Fix) |
|
||||
| Tests are failing | 3 (Test-Driven Fix) |
|
||||
| Backlog of independent tasks | 4 (Continuous PR) |
|
||||
| Fast implementation needs polish | 5 (De-Sloppify) |
|
||||
| Large feature, multiple concerns | 6 (Multi-Agent DAG) |
|
||||
|
||||
## Safety Rules (All Patterns)
|
||||
|
||||
1. **Always set limits** — Max cycles, max time, max cost
|
||||
2. **Always verify** — Run tests/build after each change
|
||||
3. **Always detect stalls** — Same error 3x = stop
|
||||
4. **Always preserve work** — Commit before risky operations
|
||||
5. **Always escalate** — When stuck, stop and ask for human input
|
||||
116
.claude/skills/continuous-learning/SKILL.md
Normal file
116
.claude/skills/continuous-learning/SKILL.md
Normal file
@@ -0,0 +1,116 @@
|
||||
---
|
||||
name: continuous-learning
|
||||
description: Extract patterns and instincts from the current session — what worked, what didn't, what should be remembered. Produces actionable learnings that improve future sessions.
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Continuous Learning
|
||||
|
||||
Extract learnings from the current session to improve future work.
|
||||
|
||||
## Context
|
||||
|
||||
Recent git history:
|
||||
!`git log --oneline -10 2>/dev/null || echo "No git history"`
|
||||
|
||||
Project rules:
|
||||
!`head -30 RULES.md 2>/dev/null || echo "No RULES.md"`
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Review the session
|
||||
|
||||
Analyze what happened in this session:
|
||||
|
||||
- **Tasks completed**: What was accomplished?
|
||||
- **Approaches tried**: What methods were used?
|
||||
- **Errors encountered**: What went wrong and how was it fixed?
|
||||
- **User corrections**: Where did the user redirect or correct the approach?
|
||||
- **Surprises**: What was unexpected about the codebase or requirements?
|
||||
|
||||
### 2. Extract instincts
|
||||
|
||||
An **instinct** is a pattern that should influence future behavior. Categories:
|
||||
|
||||
#### Project-specific instincts
|
||||
|
||||
Patterns unique to this codebase:
|
||||
- Code conventions not captured in RULES.md
|
||||
- Hidden dependencies between modules
|
||||
- "Gotchas" that aren't obvious from reading the code
|
||||
- User preferences for how work should be done
|
||||
|
||||
#### Approach instincts
|
||||
|
||||
What worked or didn't work:
|
||||
- Tools/agents that were effective for specific tasks
|
||||
- Sequences of actions that solved problems efficiently
|
||||
- Dead ends that should be avoided next time
|
||||
|
||||
#### Communication instincts
|
||||
|
||||
How the user prefers to interact:
|
||||
- Level of detail they want in explanations
|
||||
- Whether they prefer to be asked or just shown solutions
|
||||
- How they respond to different types of suggestions
|
||||
|
||||
### 3. Classify each instinct
|
||||
|
||||
For each instinct, determine:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| **Pattern** | What was observed (specific, not vague) |
|
||||
| **Context** | When this applies (file types, tasks, situations) |
|
||||
| **Action** | What to do differently next time |
|
||||
| **Confidence** | How certain (low/medium/high) based on how many times observed |
|
||||
| **Scope** | Project-only or applicable to all projects |
|
||||
|
||||
### 4. Decide where to store
|
||||
|
||||
Based on scope and type:
|
||||
|
||||
| Learning Type | Store In |
|
||||
|---------------|----------|
|
||||
| User preference | Memory (type: feedback) |
|
||||
| Project convention | `RULES.md` or `RECOMMENDATIONS.md` |
|
||||
| Codebase gotcha | Code comment or `RECOMMENDATIONS.md` |
|
||||
| Tool/agent effectiveness | Memory (type: feedback) |
|
||||
| Communication preference | Memory (type: user or feedback) |
|
||||
| Temporary state | Don't store — it's ephemeral |
|
||||
|
||||
### 5. Output
|
||||
|
||||
```markdown
|
||||
# Session Learnings
|
||||
|
||||
## Summary
|
||||
[1-2 sentences: what was accomplished, overall assessment]
|
||||
|
||||
## Instincts Extracted
|
||||
|
||||
### 1. [Pattern name]
|
||||
- **Observed**: [what happened]
|
||||
- **Context**: [when this applies]
|
||||
- **Action**: [what to do next time]
|
||||
- **Confidence**: [low/medium/high]
|
||||
- **Store in**: [memory type / RULES.md / RECOMMENDATIONS.md / skip]
|
||||
|
||||
### 2. ...
|
||||
|
||||
## Recommendations
|
||||
- [Changes to RULES.md if any patterns should become rules]
|
||||
- [Changes to RECOMMENDATIONS.md if decisions should be recorded]
|
||||
- [New memory entries to create]
|
||||
|
||||
## Anti-Learnings
|
||||
[Things that seemed like patterns but were actually one-off situations — don't generalize these]
|
||||
```
|
||||
|
||||
### 6. Anti-patterns
|
||||
|
||||
- **Over-generalizing** — Don't turn a one-time fix into a permanent rule
|
||||
- **Storing ephemera** — Don't save things like "currently debugging X"
|
||||
- **Ignoring negative results** — Failed approaches are as valuable as successful ones
|
||||
- **Redundant storage** — Don't save what's already in RULES.md or git history
|
||||
- **Low-confidence instincts** — If you've only seen it once, note it but don't enforce it
|
||||
110
.claude/skills/search-first/SKILL.md
Normal file
110
.claude/skills/search-first/SKILL.md
Normal file
@@ -0,0 +1,110 @@
|
||||
---
|
||||
name: search-first
|
||||
description: Research existing solutions before writing custom code. Checks npm/PyPI/MCP/GitHub for packages, then decides between Adopt, Extend, Compose, or Build.
|
||||
disable-model-invocation: true
|
||||
argument-hint: "[feature or problem to research]"
|
||||
---
|
||||
|
||||
# Search Before Building
|
||||
|
||||
Research existing solutions for: `$ARGUMENTS`
|
||||
|
||||
## Context
|
||||
|
||||
Project dependencies:
|
||||
!`cat package.json 2>/dev/null | jq '.dependencies // {} | keys' 2>/dev/null || echo "No package.json"`
|
||||
|
||||
Project tech stack:
|
||||
!`cat RECOMMENDATIONS.md 2>/dev/null | head -30 || echo "No RECOMMENDATIONS.md"`
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Define the need
|
||||
|
||||
Clarify what exactly is needed:
|
||||
- **Problem statement**: What problem does this solve?
|
||||
- **Requirements**: Must-haves vs nice-to-haves
|
||||
- **Constraints**: License, bundle size, browser support, security
|
||||
|
||||
### 2. Search for existing solutions
|
||||
|
||||
Search in order of preference:
|
||||
|
||||
1. **Already in project** — Check if a dependency already solves this:
|
||||
- Read `package.json` / `requirements.txt` / `go.mod`
|
||||
- Search codebase for similar implementations
|
||||
2. **Package registries** — Search npm, PyPI, crates.io, pkg.go.dev
|
||||
3. **MCP servers** — Check if an MCP server provides this capability
|
||||
4. **GitHub** — Search for well-maintained repos with the needed functionality
|
||||
5. **Framework built-ins** — Check if the framework already provides this (e.g., Next.js Image, React Server Actions)
|
||||
|
||||
For each candidate, evaluate:
|
||||
|
||||
| Criterion | Check |
|
||||
|-----------|-------|
|
||||
| Maintenance | Last commit < 6 months, active issues |
|
||||
| Popularity | Downloads/stars relative to category |
|
||||
| Bundle size | Check via bundlephobia or equivalent |
|
||||
| License | Compatible with project license |
|
||||
| Security | No known CVEs, dependency tree reasonable |
|
||||
| Types | TypeScript types included or available |
|
||||
| API quality | Clean API, good docs, follows conventions |
|
||||
|
||||
### 3. Decision matrix
|
||||
|
||||
Apply this decision framework:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Does an existing solution meet ≥80% of requirements? │
|
||||
└─────────────────────────┬───────────────────────────┘
|
||||
│
|
||||
YES ────────┼──────── NO
|
||||
│ │ │
|
||||
▼ │ ▼
|
||||
Is it well-maintained? Can you compose
|
||||
Is the API acceptable? 2-3 packages to
|
||||
│ cover 100%?
|
||||
YES │ NO │
|
||||
│ │ │ YES │ NO
|
||||
▼ │ ▼ │ │ │
|
||||
ADOPT │ EXTEND ▼ │ ▼
|
||||
│ (fork/wrap) COMPOSE BUILD
|
||||
│ (custom)
|
||||
```
|
||||
|
||||
| Strategy | When | Risk Level |
|
||||
|----------|------|------------|
|
||||
| **Adopt** | Solution fits ≥80%, well-maintained, good API | Low |
|
||||
| **Extend** | Good base but needs customization (wrapper/plugin) | Medium |
|
||||
| **Compose** | No single solution, but 2-3 packages combine well | Medium |
|
||||
| **Build** | No viable existing solution, or critical security/performance need | High |
|
||||
|
||||
### 4. Report
|
||||
|
||||
```markdown
|
||||
## Research: [Feature]
|
||||
|
||||
### Candidates Found
|
||||
| Package | Downloads | Size | License | Last Updated | Fit |
|
||||
|---------|-----------|------|---------|-------------|-----|
|
||||
| ... | ... | ... | ... | ... | ... |
|
||||
|
||||
### Recommendation: [ADOPT / EXTEND / COMPOSE / BUILD]
|
||||
|
||||
**Selected**: [package name or "custom implementation"]
|
||||
**Reason**: [why this is the best choice]
|
||||
**Trade-offs**: [what you give up]
|
||||
|
||||
### Implementation Notes
|
||||
- [How to integrate]
|
||||
- [Estimated effort]
|
||||
```
|
||||
|
||||
### 5. Anti-patterns to avoid
|
||||
|
||||
- **NIH syndrome** — Building custom when a mature solution exists
|
||||
- **Dependency hoarding** — Adding a package for a 5-line function
|
||||
- **Popularity bias** — Choosing the most popular, not the best fit
|
||||
- **Stale research** — Not checking if a previously rejected package has improved
|
||||
- **Ignoring composition** — Not considering that 2 small libraries > 1 bloated one
|
||||
93
.claude/skills/strategic-compact/SKILL.md
Normal file
93
.claude/skills/strategic-compact/SKILL.md
Normal file
@@ -0,0 +1,93 @@
|
||||
---
|
||||
name: strategic-compact
|
||||
description: Guide for when and how to run /compact effectively — preserving critical context while freeing token budget. Use at phase transitions, before large implementations, or when context is bloated.
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Strategic Compact
|
||||
|
||||
Evaluate whether `/compact` should be run now, and if so, prepare for it.
|
||||
|
||||
## Context
|
||||
|
||||
Current conversation state:
|
||||
!`echo "Working directory: $(pwd)" && echo "Git branch: $(git branch --show-current 2>/dev/null)" && echo "Modified files: $(git diff --name-only 2>/dev/null | wc -l | tr -d ' ')" && echo "Staged files: $(git diff --cached --name-only 2>/dev/null | wc -l | tr -d ' ')"`
|
||||
|
||||
## When to Compact
|
||||
|
||||
Use this decision table:
|
||||
|
||||
| Trigger | Should Compact? | Priority |
|
||||
|---------|----------------|----------|
|
||||
| Phase transition (planning → implementation) | Yes | High |
|
||||
| Starting a new major feature | Yes | High |
|
||||
| After completing a large task (before next) | Yes | Medium |
|
||||
| Context feels sluggish or repetitive | Yes | Medium |
|
||||
| Mid-implementation (code partially written) | **No** — finish first | - |
|
||||
| Debugging an active issue | **No** — need full context | - |
|
||||
| Waiting for user input | Maybe — depends on context size | Low |
|
||||
|
||||
### Do NOT compact when:
|
||||
|
||||
- You're in the middle of writing code (partial state will be lost)
|
||||
- You're debugging and need the full error trail
|
||||
- You have uncommitted understanding of complex relationships
|
||||
- The user just gave important instructions that aren't saved to files
|
||||
|
||||
## Pre-Compact Checklist
|
||||
|
||||
Before running `/compact`, ensure critical context survives:
|
||||
|
||||
### 1. Save state to files
|
||||
|
||||
Information that exists only in conversation will be lost. Save to appropriate places:
|
||||
|
||||
- **Implementation plan** → Update or create a task list
|
||||
- **Decisions made** → Record in `RECOMMENDATIONS.md` or ADR
|
||||
- **Current phase/status** → Verify `docs/phases-plan.md` is current
|
||||
- **Known issues** → Document in code comments or issues
|
||||
|
||||
### 2. Commit work in progress
|
||||
|
||||
```bash
|
||||
# Check for uncommitted changes
|
||||
git status
|
||||
# If meaningful changes exist, commit them
|
||||
git add -A && git commit -m "wip: [what was in progress]"
|
||||
```
|
||||
|
||||
### 3. Verify anchors
|
||||
|
||||
Ensure these files are up-to-date (they'll be re-read after compact):
|
||||
- `RULES.md` — project conventions
|
||||
- `RECOMMENDATIONS.md` — current decisions and constraints
|
||||
- `docs/phases-plan.md` — phase status
|
||||
|
||||
### 4. Write a compact summary
|
||||
|
||||
Create a brief note of what survives compaction vs. what's re-derivable:
|
||||
|
||||
**Survives** (in files):
|
||||
- Project rules and recommendations
|
||||
- Code changes (committed)
|
||||
- Documentation updates
|
||||
|
||||
**Lost** (conversation-only):
|
||||
- Reasoning chains and trade-off discussions
|
||||
- Rejected approaches and why
|
||||
- Nuanced context from user messages
|
||||
|
||||
## After Compact
|
||||
|
||||
After `/compact` runs:
|
||||
1. Re-read `RULES.md` and `RECOMMENDATIONS.md`
|
||||
2. Check task list for current progress
|
||||
3. Review `git log --oneline -5` for recent context
|
||||
4. Resume work from the task list
|
||||
|
||||
## Token Optimization Tips
|
||||
|
||||
- **Before compact**: Write meaningful commit messages — they're your post-compact memory
|
||||
- **File references**: Use `file:line` references instead of pasting code blocks
|
||||
- **Avoid re-reading**: Once you've read a file, note the key facts — don't re-read it
|
||||
- **Trim conversation**: If the user asks a tangential question, answer it concisely without pulling in the full project context
|
||||
114
.claude/skills/verification-loop/SKILL.md
Normal file
114
.claude/skills/verification-loop/SKILL.md
Normal file
@@ -0,0 +1,114 @@
|
||||
---
|
||||
name: verification-loop
|
||||
description: Run a full verification pipeline — Build, TypeCheck, Lint, Test, Security scan, and Diff review — producing a READY or NOT READY verdict.
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Verification Loop
|
||||
|
||||
Run a complete quality gate pipeline on the current codebase changes.
|
||||
|
||||
## Context
|
||||
|
||||
Changed files:
|
||||
!`git diff --name-only HEAD 2>/dev/null || echo "No git changes"`
|
||||
|
||||
Package manager:
|
||||
!`[ -f pnpm-lock.yaml ] && echo "pnpm" || ([ -f yarn.lock ] && echo "yarn" || echo "npm")`
|
||||
|
||||
Available scripts:
|
||||
!`cat package.json 2>/dev/null | jq '.scripts // {}' 2>/dev/null || echo "No package.json"`
|
||||
|
||||
## Pipeline
|
||||
|
||||
Run each phase in order. Stop on CRITICAL failure. Track results for final verdict.
|
||||
|
||||
### Phase 1: Build
|
||||
|
||||
```bash
|
||||
# Detect and run build command
|
||||
pnpm build || npm run build || yarn build
|
||||
```
|
||||
|
||||
**Pass criteria**: Exit code 0, no errors in output
|
||||
**On failure**: CRITICAL — stop pipeline, report errors
|
||||
|
||||
### Phase 2: Type Check
|
||||
|
||||
```bash
|
||||
# TypeScript type checking
|
||||
npx tsc --noEmit 2>&1
|
||||
```
|
||||
|
||||
**Pass criteria**: Exit code 0, zero type errors
|
||||
**On failure**: Report all type errors with file:line locations
|
||||
|
||||
### Phase 3: Lint
|
||||
|
||||
```bash
|
||||
# Run linter (detect which one is configured)
|
||||
npx biome check . 2>&1 || npx eslint . 2>&1
|
||||
```
|
||||
|
||||
**Pass criteria**: Zero errors (warnings acceptable)
|
||||
**On failure**: Report errors grouped by rule
|
||||
|
||||
### Phase 4: Test
|
||||
|
||||
```bash
|
||||
# Run test suite
|
||||
pnpm test || npm test || yarn test
|
||||
```
|
||||
|
||||
**Pass criteria**: All tests pass, coverage meets threshold
|
||||
**On failure**: Report failing tests with error messages
|
||||
|
||||
### Phase 5: Security Scan
|
||||
|
||||
```bash
|
||||
# Check for known vulnerabilities
|
||||
npm audit --audit-level=high 2>&1 || pnpm audit 2>&1
|
||||
```
|
||||
|
||||
**Pass criteria**: No high/critical vulnerabilities
|
||||
**On failure**: Report vulnerable packages with fix suggestions
|
||||
|
||||
### Phase 6: Diff Review
|
||||
|
||||
Review the actual changes for common issues:
|
||||
- Secrets or credentials in diff
|
||||
- TODO/FIXME/HACK markers without ticket references
|
||||
- Console.log/print statements (non-test files)
|
||||
- Large files (>500 lines changed)
|
||||
|
||||
## Verdict
|
||||
|
||||
After all phases complete, produce the final report:
|
||||
|
||||
```markdown
|
||||
# Verification Report
|
||||
|
||||
**Verdict**: ✅ READY / ❌ NOT READY
|
||||
|
||||
| Phase | Status | Issues |
|
||||
|-------|--------|--------|
|
||||
| Build | ✅/❌ | [count or "clean"] |
|
||||
| TypeCheck | ✅/❌ | [count or "clean"] |
|
||||
| Lint | ✅/❌/⚠️ | [errors/warnings] |
|
||||
| Test | ✅/❌ | [pass/fail/skip counts] |
|
||||
| Security | ✅/❌ | [vuln count] |
|
||||
| Diff Review | ✅/⚠️ | [findings] |
|
||||
|
||||
## Blocking Issues
|
||||
[List of issues that must be fixed before merge]
|
||||
|
||||
## Warnings
|
||||
[Non-blocking issues worth addressing]
|
||||
|
||||
## Recommendations
|
||||
[Suggested improvements, prioritized]
|
||||
```
|
||||
|
||||
**READY** requires: Build ✅, TypeCheck ✅, Lint ✅ (no errors), Test ✅, Security ✅ (no high/critical)
|
||||
|
||||
**NOT READY** if any of the above fail. List what needs to be fixed.
|
||||
Reference in New Issue
Block a user