@cluesmith/codev 3.0.0-rc.1 → 3.0.0-rc.11

package/skeleton/.claude/skills/af/SKILL.md

@@ -1,146 +0,0 @@
----
-name: af
-description: Agent Farm CLI — the tool for spawning builders, managing Tower, workspaces, and cron tasks. ALWAYS consult this skill BEFORE running any `af` command to get the exact syntax. This prevents wasting time guessing flags that don't exist. Use this whenever you need to spawn a builder, check status, send messages, clean up worktrees, manage Tower, or run cron tasks. If you're about to type `af` followed by anything, check here first.
----
-
-# Agent Farm CLI
-
-## af spawn
-
-Spawns a new builder in an isolated git worktree.
-
-```
-af spawn [number] [options]
-```
-
-**The ONLY flags that exist:**
-
-| Flag | Description |
-|------|-------------|
-| `--protocol <name>` | Protocol: spir, aspir, air, bugfix, tick, maintain, experiment. **Required for numbered spawns.** |
-| `--task <text>` | Ad-hoc task (no issue number needed) |
-| `--shell` | Bare Claude session |
-| `--worktree` | Bare worktree session |
-| `--amends <number>` | Original spec number (TICK only) |
-| `--files <files>` | Context files, comma-separated. **Requires `--task`.** |
-| `--no-comment` | Skip commenting on the GitHub issue |
-| `--force` | Skip dirty-worktree and collision checks |
-| `--soft` | Soft mode (AI follows protocol, you verify) |
-| `--strict` | Strict mode (porch orchestrates) — this is the default |
-| `--resume` | Resume builder in existing worktree |
-| `--no-role` | Skip loading role prompt |
-
-**There is NO `-t`, `--title`, `--name`, or `--branch` flag.** The branch name is auto-generated from the issue title.
-
-**Examples:**
-```bash
-af spawn 42 --protocol spir           # SPIR builder for issue #42
-af spawn 42 --protocol aspir          # ASPIR (autonomous, no human gates)
-af spawn 42 --protocol air            # AIR (small features)
-af spawn 42 --protocol bugfix         # Bugfix
-af spawn 42 --protocol tick --amends 30  # TICK amendment to spec 30
-af spawn 42 --protocol spir --soft    # Soft mode
-af spawn 42 --resume                  # Resume existing builder
-af spawn --task "fix the flaky test"  # Ad-hoc task (no issue)
-af spawn 42 --protocol spir --force   # Skip dirty-worktree check
-```
-
-**Pre-spawn checklist:**
-1. `git status` — worktree must be clean (or use `--force`)
-2. Commit specs/plans first — builders branch from HEAD and can't see uncommitted files
-3. `--protocol` is required for numbered spawns
-
-## af send
-
-Sends a message to a running builder.
-
-```
-af send [builder] [message]
-```
-
-| Flag | Description |
-|------|-------------|
-| `--all` | Send to all builders |
-| `--file <path>` | Include file content |
-| `--interrupt` | Send Ctrl+C first |
-| `--raw` | Skip structured formatting |
-| `--no-enter` | Don't press Enter after message |
-
-```bash
-af send 0042 "PR approved, please merge"
-af send 0585 "check the test output" --file /tmp/test-results.txt
-```
-
-## af cleanup
-
-Removes a builder's worktree and branch after work is done.
-
-```
-af cleanup [options]
-```
-
-| Flag | Description |
-|------|-------------|
-| `-p, --project <id>` | Builder project ID (no leading zeros: `585` not `0585`) |
-| `-i, --issue <number>` | Cleanup bugfix builder by issue number |
-| `-t, --task <id>` | Cleanup task builder (e.g., `task-bEPd`) |
-| `-f, --force` | Force cleanup even if branch not merged |
-
-```bash
-af cleanup -p 585              # Clean up project 585
-af cleanup -p 585 -f           # Force (unmerged branch)
-```
-
-**Note:** `af cleanup` uses plain numbers (`585`), not zero-padded (`0585`). But `af send` uses zero-padded IDs (`0585`).
-
-## af status
-
-```bash
-af status                      # Show all builders and workspace status
-```
-
-No flags needed. Shows Tower status, workspace, and all active builders.
-
-## af tower
-
-```bash
-af tower start                 # Start Tower on port 4100
-af tower stop                  # Stop Tower
-af tower log                   # Tail Tower logs
-af tower status                # Check daemon and cloud connection status
-af tower connect               # Connect to Codev Cloud
-af tower disconnect            # Disconnect from Codev Cloud
-```
-
-There is NO `af tower restart` — use `af tower stop && af tower start`.
-
-## af workspace
-
-```bash
-af workspace start             # Start workspace for current project
-af workspace stop              # Stop workspace processes
-```
-
-`af dash` is a deprecated alias — use `af workspace` instead.
-
-## af cron
-
-```bash
-af cron list                   # List all cron tasks
-af cron status <name>          # Check task status
-af cron run <name>             # Run immediately
-af cron enable <name>          # Enable
-af cron disable <name>         # Disable
-```
-
-There is NO `af cron add` — create YAML files in `.af-cron/` directly.
-
-## Other commands
-
-```bash
-af open <file>                 # Open file in annotation viewer (NOT system open)
-af shell                       # Spawn utility shell
-af attach                      # Attach to running builder terminal
-af rename <name>               # Rename current shell session
-af architect                   # Start architect session in current terminal
-```

package/skeleton/porch/prompts/understand.md

@@ -1,61 +0,0 @@
-# Understand Phase Prompt (TICK)
-
-You are working in a TICK protocol - fast autonomous implementation for amendments.
-
-## Your Mission
-
-Understand the existing spec and what amendment is being requested. TICK is for small changes to existing, integrated features.
-
-## Input Context
-
-Read these files:
-1. `codev/specs/{project-id}-*.md` - The existing spec (being amended)
-2. `codev/plans/{project-id}-*.md` - The existing plan
-3. `codev/status/{project-id}-*.md` - Current state and amendment description
-
-## Workflow
-
-### 1. Identify the Amendment
-
-From the status file, understand:
-- What change is being requested?
-- What's the scope? (Should be < 300 LOC)
-- What existing code will be affected?
-
-### 2. Verify TICK is Appropriate
-
-TICK is appropriate when:
-- [ ] Feature already has an integrated spec
-- [ ] Change is small (< 300 LOC)
-- [ ] Requirements are clear
-- [ ] No architectural changes needed
-
-If NOT appropriate, signal: `<signal>NEEDS_SPIR</signal>`
-
-### 3. Document Understanding
-
-Update status file with:
-```markdown
-## Amendment Understanding
-
-**Existing Spec**: {spec-id}
-**Amendment Request**: {description}
-**Scope**: {estimated LOC}
-**Files to Change**:
-- file1.ts
-- file2.ts
-
-**Approach**: {brief description of how to implement}
-```
-
-### 4. Signal Completion
-
-When understanding is complete:
-1. Update status file
-2. Output: `<signal>UNDERSTOOD</signal>`
-
-## Constraints
-
-- DO NOT start implementing
-- DO NOT create new spec files (amend existing)
-- Keep scope small - if > 300 LOC, recommend SPIR instead

package/skeleton/porch/prompts/verify.md

@@ -1,58 +0,0 @@
-# Verify Phase Prompt (TICK)
-
-You are in the Verify phase of TICK protocol.
-
-## Your Mission
-
-Verify that the amendment implementation is complete and correct. Run tests and build to ensure nothing is broken.
-
-## Input Context
-
-Read these files:
-1. `codev/specs/{project-id}-*.md` - Spec with amendment
-2. `codev/status/{project-id}-*.md` - Implementation notes
-
-## Workflow
-
-### 1. Run Build
-
-```bash
-npm run build
-```
-
-If build fails:
-- Output: `<signal>VERIFICATION_FAILED</signal>`
-- Include error details in output
-
-### 2. Run Tests
-
-```bash
-npm test
-```
-
-If tests fail:
-- Output: `<signal>VERIFICATION_FAILED</signal>`
-- Include which tests failed
-
-### 3. Quick Manual Check
-
-Verify:
-- [ ] Amendment matches the request
-- [ ] No unintended side effects
-- [ ] Code follows project conventions
-
-### 4. Signal Completion
-
-When all checks pass:
-1. Update status file with verification results
-2. Output: `<signal>VERIFIED</signal>`
-
-## Backpressure
-
-Both build AND tests must pass before VERIFIED can be signaled. This is non-negotiable.
-
-## Constraints
-
-- DO NOT add new features
-- DO NOT refactor unrelated code
-- Keep verification focused on the amendment

package/skeleton/protocols/maintain/prompts/audit.md

@@ -1,111 +0,0 @@
-# AUDIT Phase Prompt
-
-You are executing the **AUDIT** phase of the MAINTAIN protocol.
-
-## Your Goal
-
-Analyze the codebase to identify dead code, unused dependencies, and stale documentation.
-
-## Context
-
-- **Current State**: {{current_state}}
-
-## Process
-
-### 1. Determine Base Commit
-
-Find the last maintenance run:
-```bash
-ls codev/maintain/
-```
-
-If previous runs exist, note the base commit to focus on changes since then.
-
-### 2. Scan for Dead Code
-
-Run static analysis tools:
-
-```bash
-# TypeScript/JavaScript
-npx ts-prune 2>/dev/null || echo "ts-prune not available"
-npx depcheck 2>/dev/null || echo "depcheck not available"
-
-# Check for unused exports
-grep -r "export " --include="*.ts" --include="*.tsx" | head -50
-```
-
-### 3. Scan for Unused Dependencies
-
-Check package.json for unused dependencies:
-```bash
-cat package.json | grep -A100 '"dependencies"' | head -50
-```
-
-Cross-reference with actual imports in the codebase.
-
-### 4. Scan for Stale Documentation
-
-Check for references to deleted files/functions:
-```bash
-# Recent changes
-git log --oneline -20
-
-# Check if arch.md references exist
-grep -E "src/|packages/" codev/resources/arch.md | head -20
-```
-
-### 5. Create Audit Report
-
-Create a maintenance run file: `codev/maintain/NNN.md`
-
-Document:
-- Dead code identified (with file paths)
-- Unused dependencies
-- Stale documentation references
-- Recommended actions
-
-Use the template structure:
-```markdown
-# Maintenance Run NNN
-
-**Date**: YYYY-MM-DD
-**Base Commit**: <commit-hash>
-
-## Dead Code Identified
-
-| File | Item | Reason |
-|------|------|--------|
-| path/to/file.ts | unusedFunction() | Not imported anywhere |
-
-## Unused Dependencies
-
-| Package | Reason |
-|---------|--------|
-| some-pkg | Not imported |
-
-## Stale Documentation
-
-| Document | Issue |
-|----------|-------|
-| arch.md | References deleted module |
-
-## Recommended Actions
-
-1. Remove X
-2. Update Y
-3. ...
-```
-
-## Signals
-
-When audit report is complete:
-
-```
-<signal>PHASE_COMPLETE</signal>
-```
-
-If blocked:
-
-```
-<signal>BLOCKED:reason</signal>
-```

package/skeleton/protocols/maintain/prompts/clean.md

@@ -1,91 +0,0 @@
-# CLEAN Phase Prompt
-
-You are executing the **CLEAN** phase of the MAINTAIN protocol.
-
-## Your Goal
-
-Remove the dead code and unused dependencies identified in the audit phase.
-
-## Context
-
-- **Current State**: {{current_state}}
-
-## Prerequisites
-
-Read the audit report from the previous phase:
-```bash
-ls -la codev/maintain/
-cat codev/maintain/*.md | tail -100
-```
-
-## Process
-
-### 1. Remove Dead Code
-
-For each item identified in the audit:
-
-1. Verify it's truly unused (double-check with grep)
-2. Use `git rm` for tracked files
-3. For untracked files, move to `.trash/` before deleting
-
-**CRITICAL**: Use soft deletion first:
-```bash
-mkdir -p codev/maintain/.trash/$(date +%Y-%m-%d)
-mv path/to/file codev/maintain/.trash/$(date +%Y-%m-%d)/
-```
-
-### 2. Remove Unused Dependencies
-
-```bash
-# Remove from package.json
-npm uninstall <package-name>
-```
-
-### 3. Verify Build After Each Removal
-
-After each significant removal:
-```bash
-npm run build
-npm test -- --exclude='**/e2e/**'
-```
-
-If build fails, revert the change and investigate.
-
-### 4. Commit Changes
-
-Make atomic commits for each logical change:
-```bash
-git add <specific-files>
-git commit -m "[Maintain] Remove unused X"
-```
-
-**NEVER use `git add -A` or `git add .`**
-
-## Important Rules
-
-1. **One removal at a time** - Don't batch unrelated changes
-2. **Verify after each removal** - Build must pass
-3. **Document what was removed** - Update the maintenance run file
-4. **Soft delete first** - Move to .trash/ before permanent deletion
-5. **Check for side effects** - Grep for references before removing
-
-## Output
-
-Update the maintenance run file with:
-- What was removed
-- Build/test status after removal
-- Any issues encountered
-
-## Signals
-
-When all dead code is removed and build passes:
-
-```
-<signal>PHASE_COMPLETE</signal>
-```
-
-If blocked:
-
-```
-<signal>BLOCKED:reason</signal>
-```

package/skeleton/protocols/maintain/prompts/sync.md

@@ -1,113 +0,0 @@
-# SYNC Phase Prompt
-
-You are executing the **SYNC** phase of the MAINTAIN protocol.
-
-## Your Goal
-
-Update documentation to match the current state of the codebase.
-
-## Context
-
-- **Current State**: {{current_state}}
-
-## Process
-
-### 1. Update arch.md
-
-Read the current architecture doc and compare with actual codebase:
-
-```bash
-cat codev/resources/arch.md
-ls -la packages/ src/ 2>/dev/null
-```
-
-Update:
-- Directory structure (if changed)
-- Component descriptions
-- Key files and their purposes
-- Remove references to deleted code
-- Add new utilities/components
-
-**arch.md must explain HOW things work, not just WHAT they are.**
-
-### 2. Generate/Update lessons-learned.md
-
-Scan review documents for lessons:
-
-```bash
-ls codev/reviews/
-```
-
-Extract actionable lessons:
-- Testing practices
-- Architecture decisions
-- Process improvements
-- Patterns to follow/avoid
-
-Format:
-```markdown
-## [Topic]
-- [From NNN] Lesson description
-```
-
-### 3. Sync CLAUDE.md with AGENTS.md
-
-Compare the two files:
-```bash
-diff CLAUDE.md AGENTS.md | head -50
-```
-
-They must be identical. Update the stale one to match.
-
-### 4. Prune Documentation
-
-Check document sizes:
-```bash
-wc -l CLAUDE.md AGENTS.md README.md
-```
-
-Target ~400 lines for CLAUDE.md/README.md (guideline, not mandate).
-
-For any content removed, document:
-- WHAT was removed
-- WHY it was removed (OBSOLETE, DUPLICATIVE, MOVED, VERBOSE)
-- WHERE it moved (if applicable)
-
-### 5. Commit Documentation Changes
-
-```bash
-git add codev/resources/arch.md codev/resources/lessons-learned.md
-git commit -m "[Maintain] Update arch.md and lessons-learned.md"
-
-git add CLAUDE.md AGENTS.md
-git commit -m "[Maintain] Sync CLAUDE.md with AGENTS.md"
-```
-
-## Important Rules
-
-1. **Never invent structure** - Only document what exists
-2. **Verify file paths** - Check that referenced files exist
-3. **Keep it current** - Remove obsolete references
-4. **Preserve important content** - Don't delete patterns/best practices
-5. **Document deletions** - Every removal needs justification
-
-## Output
-
-Update the maintenance run file with:
-- Documents updated
-- What was added/removed/changed
-- Any issues encountered
-
-## Signals
-
-When documentation is synchronized:
-
-```
-<signal>PHASE_COMPLETE</signal>
-```
-
-If blocked:
-
-```
-<signal>BLOCKED:reason</signal>
-```

package/skeleton/protocols/maintain/prompts/verify.md

@@ -1,110 +0,0 @@
-# VERIFY Phase Prompt
-
-You are executing the **VERIFY** phase of the MAINTAIN protocol.
-
-## Your Goal
-
-Run final validation and prepare for PR creation.
-
-## Context
-
-- **Current State**: {{current_state}}
-
-## Process
-
-### 1. Run Full Test Suite
-
-```bash
-npm run build
-npm test
-```
-
-Both must pass. If either fails, go back and fix the issue.
-
-### 2. Run Linting
-
-```bash
-npm run lint 2>/dev/null || echo "No lint script"
-```
-
-Fix any linting errors.
-
-### 3. Verify Documentation Links
-
-Check that documentation references resolve:
-```bash
-# Check arch.md file references
-grep -oE 'src/[^ ]+|packages/[^ ]+' codev/resources/arch.md | while read f; do
-  [ -e "$f" ] || echo "Missing: $f"
-done
-```
-
-### 4. Update Maintenance Run Summary
-
-Finalize the maintenance run file with:
-
-```markdown
-## Summary
-
-- **Dead code removed**: X files, Y functions
-- **Dependencies removed**: Z packages
-- **Documentation updated**: arch.md, lessons-learned.md
-- **All tests passing**: Yes/No
-- **Build status**: Success/Failure
-
-## Next Maintenance
-
-Recommended focus areas for next run:
-- ...
-```
-
-### 5. Create PR
-
-```bash
-git push origin HEAD
-
-gh pr create --title "[Maintain] Codebase maintenance run NNN" --body "$(cat <<'EOF'
-## Summary
-
-- Dead code removal
-- Documentation sync
-- Dependency cleanup
-
-## Changes
-
-[List key changes]
-
-## Verification
-
-- [x] Build passes
-- [x] Tests pass
-- [x] Documentation updated
-EOF
-)"
-```
-
-## Validation Checklist
-
-Before signaling complete:
-
-- [ ] All tests pass
-- [ ] Build succeeds
-- [ ] No import/module errors
-- [ ] Documentation links resolve
-- [ ] Linter passes (if configured)
-- [ ] Maintenance run file is complete
-- [ ] PR is created
-
-## Signals
-
-When validation passes and PR is ready:
-
-```
-<signal>PHASE_COMPLETE</signal>
-```
-
-If blocked:
-
-```
-<signal>BLOCKED:reason</signal>
-```