@cluesmith/codev 2.0.2 → 2.0.6

package/skeleton/resources/commands/agent-farm.md

@@ -148,7 +148,7 @@ af spawn [options]
 ```
 
 **Options:**
-- `-p, --project <id>` - Spawn builder for a spec (e.g., `0042`)
+- `-p, --project <id>` - Spawn builder for a spec (e.g., `42`)
 - `--task <text>` - Spawn builder with a task description
 - `--protocol <name>` - Spawn builder to run a protocol
 - `--shell` - Spawn a bare Claude session
@@ -166,8 +166,8 @@ Creates a new builder in an isolated git worktree. The builder gets:
 **Examples:**
 
 ```bash
-# Spawn builder for spec 0042
-af spawn -p 0042
+# Spawn builder for spec 42
+af spawn -p 42
 
 # Spawn with task description
 af spawn --task "Fix login bug in auth module"
@@ -176,7 +176,7 @@ af spawn --task "Fix login bug in auth module"
 af spawn --shell
 
 # Spawn with context files
-af spawn -p 0042 --files "src/auth.ts,tests/auth.test.ts"
+af spawn -p 42 --files "src/auth.ts,tests/auth.test.ts"
 ```
 
 ---
@@ -198,8 +198,8 @@ Displays the current state of all builders and the architect:
 │ ID     │ Name         │ Status      │ Branch  │
 ├────────┼──────────────┼─────────────┼─────────┤
 │ arch   │ Architect    │ running     │ main    │
-│ 0042   │ auth-feature │ implementing│ builder/0042-auth │
-│ 0043   │ api-refactor │ pr-ready    │ builder/0043-api  │
+│ 42   │ auth-feature │ implementing│ builder/42-auth │
+│ 43   │ api-refactor │ pr-ready    │ builder/43-api  │
 └────────┴──────────────┴─────────────┴─────────┘
 ```
 
@@ -232,10 +232,10 @@ Removes a builder's worktree and associated resources. By default, refuses to de
 
 ```bash
 # Clean up completed builder
-af cleanup -p 0042
+af cleanup -p 42
 
 # Force cleanup (may lose work)
-af cleanup -p 0042 --force
+af cleanup -p 42 --force
 ```
 
 ---
@@ -249,7 +249,7 @@ af send [builder] [message] [options]
 ```
 
 **Arguments:**
-- `builder` - Builder ID (e.g., `0042`)
+- `builder` - Builder ID (e.g., `42`)
 - `message` - Message to send
 
 **Options:**
@@ -270,16 +270,16 @@ Sends text to a builder's terminal. Useful for:
 
 ```bash
 # Send message to builder
-af send 0042 "Focus on the auth module first"
+af send 42 "Focus on the auth module first"
 
 # Interrupt and send new instructions
-af send 0042 --interrupt "Stop that. Try a different approach."
+af send 42 --interrupt "Stop that. Try a different approach."
 
 # Send to all builders
 af send --all "Time to wrap up, create PRs"
 
 # Include file content
-af send 0042 --file src/api.ts "Review this implementation"
+af send 42 --file src/api.ts "Review this implementation"
 ```
 
 ---
@@ -352,7 +352,7 @@ af rename <id> <name>
 **Example:**
 
 ```bash
-af rename 0042 "auth-rework"
+af rename 42 "auth-rework"
 ```
 
 ---
@@ -528,7 +528,7 @@ Or override via CLI flags:
 
 ```bash
 af start --architect-cmd "claude --model opus"
-af spawn -p 0042 --builder-cmd "claude --model haiku"
+af spawn -p 42 --builder-cmd "claude --model haiku"
 ```
 
 ---

package/skeleton/resources/commands/codev.md

@@ -30,7 +30,6 @@ Creates a minimal codev project structure:
 - `codev/specs/` - Specification files
 - `codev/plans/` - Implementation plans
 - `codev/reviews/` - Review documents
-- `codev/projectlist.md` - Project tracking
 - `CLAUDE.md` / `AGENTS.md` - AI agent instructions
 - `.gitignore` - Standard ignores
 

package/skeleton/resources/commands/consult.md

@@ -77,7 +77,7 @@ consult -m <model> spec <number>
 ```
 
 **Arguments:**
-- `number` - Spec number to review (e.g., `42` for `codev/specs/0042-*.md`)
+- `number` - Spec number to review (e.g., `42` for `codev/specs/42-*.md`)
 
 **Description:**
 
@@ -111,7 +111,7 @@ consult -m <model> plan <number>
 ```
 
 **Arguments:**
-- `number` - Plan number to review (e.g., `42` for `codev/plans/0042-*.md`)
+- `number` - Plan number to review (e.g., `42` for `codev/plans/42-*.md`)
 
 **Description:**
 
@@ -310,7 +310,7 @@ cp $(npm root -g)/@cluesmith/codev/skeleton/roles/consultant.md codev/roles/
 All consultations are logged to `.consult/history.log`:
 
 ```
-2024-01-15T10:30:00.000Z model=gemini duration=142.3s query=Review spec 0042...
+2024-01-15T10:30:00.000Z model=gemini duration=142.3s query=Review spec 42...
 ```
 
 ---

package/skeleton/resources/spikes.md

@@ -43,7 +43,7 @@ Store spikes in `codev/spikes/{spec-number}/`:
 
 ```
 codev/spikes/
-└── 0062/
+└── 62/
     ├── spike-api-behavior.ts
     ├── spike-event-handoff.ts
     └── spike-storage-roundtrip.ts
@@ -63,7 +63,7 @@ Each spike file should:
  * 2. [Another test case]
  * 3. [Edge case]
  *
- * Run with: npx tsx codev/spikes/0062/spike-name.ts
+ * Run with: npx tsx codev/spikes/62/spike-name.ts
  */
 
 // Self-contained, runnable code that validates the assumption
@@ -115,4 +115,4 @@ Why:
 - Keeps build fast and focused on production code
 - Prevents spike code from accidentally shipping
 
-Run spikes directly: `npx tsx codev/spikes/0062/spike-name.ts`
+Run spikes directly: `npx tsx codev/spikes/62/spike-name.ts`

package/skeleton/resources/workflow-reference.md

@@ -10,7 +10,7 @@ Quick reference for the 7-stage project workflow. For protocol details, see `cod
 │                                                                                     │
 │  → 1. CONCEIVED                                                                     │
 │         User describes project concept                                              │
-│         Architect adds to projectlist, writes spec                                  │
+│         Architect creates GitHub Issue, writes spec                                 │
 │         Architect does 3-way spec review                                            │
 │         ⏸️  HUMAN GATE: Approve spec                                                │
 │                                                                                     │
@@ -80,19 +80,19 @@ AI agents must stop and wait for human action at these gates.
 af dash start
 
 # Spawn a builder for a project
-af spawn -p 0044
+af spawn -p 44
 
 # Check all builder statuses
 af status
 
 # Send message to builder
-af send 0044 "Check PR comments and address feedback"
+af send 44 "Check PR comments and address feedback"
 
 # Open a file for review
-af open codev/specs/0044-name.md
+af open codev/specs/44-name.md
 
 # Clean up after merge
-af cleanup -p 0044
+af cleanup -p 44
 
 # Stop everything
 af dash stop
@@ -128,16 +128,16 @@ codev import github:owner/repo --dry-run
 
 ```bash
 # Spec review (during Stage 1)
-consult --model gemini --type spec-review spec 0044
-consult --model codex --type spec-review spec 0044
+consult --model gemini --type spec-review spec 44
+consult --model codex --type spec-review spec 44
 
 # Plan review (during Stage 2)
-consult --model gemini --type plan-review plan 0044
-consult --model codex --type plan-review plan 0044
+consult --model gemini --type plan-review plan 44
+consult --model codex --type plan-review plan 44
 
 # Implementation review (during Stage 4, after each phase)
-consult --model gemini --type impl-review spec 0044
-consult --model codex --type impl-review spec 0044
+consult --model gemini --type impl-review spec 44
+consult --model codex --type impl-review spec 44
 
 # PR ready review (during Stage 5)
 consult --model gemini --type pr-ready pr 88
@@ -148,9 +148,9 @@ consult --model gemini --type integration-review pr 88
 consult --model codex --type integration-review pr 88
 
 # Parallel 3-way reviews (run all three concurrently)
-consult --model gemini --type spec-review spec 0044 &
-consult --model codex --type spec-review spec 0044 &
-consult --model claude --type spec-review spec 0044 &
+consult --model gemini --type spec-review spec 44 &
+consult --model codex --type spec-review spec 44 &
+consult --model claude --type spec-review spec 44 &
 wait
 ```
 

package/skeleton/roles/architect.md

@@ -28,16 +28,16 @@ Builders work autonomously in isolated git worktrees. The Architect:
 ### Agent Farm CLI (`af`)
 
 ```bash
-af spawn -p 0001                          # Strict mode (default) - porch-driven
-af spawn -p 0001 -t "feature"             # Strict mode with title (no spec yet)
-af spawn -p 0001 --resume                 # Resume existing porch state
-af spawn --soft -p 0001                   # Soft mode - protocol-guided
+af spawn -p 1                          # Strict mode (default) - porch-driven
+af spawn -p 1 -t "feature"             # Strict mode with title (no spec yet)
+af spawn -p 1 --resume                 # Resume existing porch state
+af spawn --soft -p 1                   # Soft mode - protocol-guided
 af spawn --task "fix the bug"             # Ad-hoc task builder (soft mode)
 af spawn --worktree                       # Worktree with no initial prompt
 af status                                 # Check all builders
-af cleanup -p 0001                        # Remove completed builder
+af cleanup -p 1                        # Remove completed builder
 af dash start/stop                        # Dashboard management
-af send 0001 "message"                    # Short message to builder
+af send 1 "message"                    # Short message to builder
 ```
 
 **Note:** `af`, `consult`, `porch`, and `codev` are global commands. They work from any directory.
@@ -45,8 +45,8 @@ af send 0001 "message"                    # Short message to builder
 ### Porch CLI (for strict mode)
 
 ```bash
-porch status 0001                           # Check project state
-porch approve 0001 spec-approval            # Approve a gate
+porch status 1                           # Check project state
+porch approve 1 spec-approval            # Approve a gate
 porch pending                               # List pending gates
 ```
 
@@ -63,7 +63,7 @@ wait
 ## Responsibilities
 
 1. **Decide what to build** - Identify features, prioritize work
-2. **Maintain project list** - Track all projects in `codev/projectlist.md`
+2. **Track projects** - Use GitHub Issues as the project registry
 3. **Spawn builders** - Choose soft or strict mode based on needs
 4. **Approve gates** - (Strict mode) Review specs and plans, approve to continue
 5. **Monitor progress** - Track builder status, unblock when stuck
@@ -75,17 +75,17 @@ wait
 ### 1. Starting a New Feature
 
 ```bash
-# 1. Reserve project number in projectlist.md
+# 1. Create a GitHub Issue for the feature
 # 2. Spawn the builder
 
 # Default: Strict mode (porch-driven with gates)
-af spawn -p 0042
+af spawn -p 42
 
 # With project title (if no spec exists yet)
-af spawn -p 0042 -t "user-authentication"
+af spawn -p 42 -t "user-authentication"
 
 # Or: Soft mode (builder follows protocol independently)
-af spawn --soft -p 0042
+af spawn --soft -p 42
 ```
 
 ### 2. Approving Gates (Strict Mode Only)
@@ -95,26 +95,26 @@ The builder stops at gates requiring approval:
 **spec-approval** - After builder writes the spec
 ```bash
 # Review the spec in the builder's worktree
-cat worktrees/spir_0042_user-authentication/codev/specs/0042-user-authentication.md
+cat worktrees/spir_42_user-authentication/codev/specs/42-user-authentication.md
 
 # Approve if satisfactory
-porch approve 0042 spec-approval
+porch approve 42 spec-approval
 ```
 
 **plan-approval** - After builder writes the plan
 ```bash
 # Review the plan
-cat worktrees/spir_0042_user-authentication/codev/plans/0042-user-authentication.md
+cat worktrees/spir_42_user-authentication/codev/plans/42-user-authentication.md
 
 # Approve if satisfactory
-porch approve 0042 plan-approval
+porch approve 42 plan-approval
 ```
 
 ### 3. Monitoring Progress
 
 ```bash
 af status              # Overview of all builders
-porch status 0042      # Detailed state for one project (strict mode)
+porch status 42      # Detailed state for one project (strict mode)
 ```
 
 ### 4. Integration Review
@@ -139,7 +139,7 @@ Integration looks good. No conflicts with existing modules.
 Architect integration review"
 
 # Notify builder
-af send 0042 "PR approved, please merge"
+af send 42 "PR approved, please merge"
 ```
 
 ### 5. Cleanup
@@ -147,7 +147,7 @@ af send 0042 "PR approved, please merge"
 After builder merges and work is integrated:
 
 ```bash
-af cleanup -p 0042
+af cleanup -p 42
 ```
 
 ## Critical Rules
@@ -158,21 +158,21 @@ af cleanup -p 0042
 3. **DO NOT use `af send` for long messages** - Use GitHub PR comments instead
 
 ### ALWAYS Do These:
-1. **Reserve project numbers first** - Update projectlist.md before spawning
+1. **Create GitHub Issues first** - Track projects as issues before spawning
 2. **Review artifacts before approving gates** - (Strict mode) Read the spec/plan carefully
 3. **Use PR comments for feedback** - Not terminal send-keys
 4. **Let builders own their work** - Guide, don't take over
 
 ## Project Tracking
 
-**`codev/projectlist.md` is the canonical source of truth.**
+**GitHub Issues are the canonical source of truth for project tracking.**
 
 ```bash
 # See what needs work
-cat codev/projectlist.md
+gh issue list --label "priority:high"
 
-# Find high-priority items
-grep -A5 "priority: high" codev/projectlist.md
+# View a specific project
+gh issue view 42
 ```
 
 Update status as projects progress:

package/skeleton/roles/builder.md

@@ -164,7 +164,7 @@ If you encounter issues you can't resolve:
 
 Example:
 ```
-## BLOCKED: Spec 0077
+## BLOCKED: Spec 77
 Can't find the auth helper mentioned in spec. Options:
 1. Create a new auth helper
 2. Use a third-party library

package/skeleton/roles/consultant.md

@@ -25,3 +25,9 @@ You are a consultant providing a second perspective to support decision-making.
 | Consultant | Provides perspective, supports decisions |
 
 You think alongside the other agents, helping them see blind spots. You have filesystem access — use it to verify your claims against the actual codebase.
+
+## File Access Rules
+
+- **ALWAYS read files directly from disk** when reviewing specs, plans, or code. File paths are provided in the query — open and read them.
+- **NEVER rely on `git diff` or `git log -p` as your primary review source.** Diffs are lossy, get truncated, and miss uncommitted work. Read the actual files instead.
+- If you need to understand what changed, read the full file first, then optionally use `git diff` as a secondary reference.

package/skeleton/templates/AGENTS.md

@@ -30,9 +30,9 @@ This project uses **Codev** for AI-assisted development.
 ## File Naming Convention
 
 Use sequential numbering with descriptive names:
-- Specification: `codev/specs/0001-feature-name.md`
-- Plan: `codev/plans/0001-feature-name.md`
-- Review: `codev/reviews/0001-feature-name.md`
+- Specification: `codev/specs/1-feature-name.md`
+- Plan: `codev/plans/1-feature-name.md`
+- Review: `codev/reviews/1-feature-name.md`
 
 ## Git Workflow
 
@@ -40,8 +40,8 @@ Use sequential numbering with descriptive names:
 
 Commit messages format:
 ```
-[Spec 0001] Description of change
-[Spec 0001][Phase: implement] feat: Add feature
+[Spec 1] Description of change
+[Spec 1][Phase: implement] feat: Add feature
 ```
 
 ## CLI Commands

package/skeleton/templates/CLAUDE.md

@@ -28,9 +28,9 @@ This project uses **Codev** for AI-assisted development.
 ## File Naming Convention
 
 Use sequential numbering with descriptive names:
-- Specification: `codev/specs/0001-feature-name.md`
-- Plan: `codev/plans/0001-feature-name.md`
-- Review: `codev/reviews/0001-feature-name.md`
+- Specification: `codev/specs/1-feature-name.md`
+- Plan: `codev/plans/1-feature-name.md`
+- Review: `codev/reviews/1-feature-name.md`
 
 ## Git Workflow
 
@@ -38,8 +38,8 @@ Use sequential numbering with descriptive names:
 
 Commit messages format:
 ```
-[Spec 0001] Description of change
-[Spec 0001][Phase: implement] feat: Add feature
+[Spec 1] Description of change
+[Spec 1][Phase: implement] feat: Add feature
 ```
 
 ## CLI Commands

package/skeleton/templates/lifecycle.md

@@ -18,7 +18,7 @@ conceived → specified → planned → implementing → implemented → committ
 
 **What happens next:** The Architect (AI) writes a specification. The human reviews and approves it.
 
-**Artifact:** Draft specification in `codev/specs/NNNN-name.md`
+**Artifact:** Draft specification in `codev/specs/NNN-name.md`
 
 ---
 
@@ -30,7 +30,7 @@ conceived → specified → planned → implementing → implemented → committ
 
 **What happens next:** The Architect creates an implementation plan.
 
-**Artifact:** Approved specification in `codev/specs/NNNN-name.md`
+**Artifact:** Approved specification in `codev/specs/NNN-name.md`
 
 ---
 
@@ -42,7 +42,7 @@ conceived → specified → planned → implementing → implemented → committ
 
 **What happens next:** A Builder is spawned to implement the plan.
 
-**Artifact:** Implementation plan in `codev/plans/NNNN-name.md`
+**Artifact:** Implementation plan in `codev/plans/NNN-name.md`
 
 ---
 
@@ -90,7 +90,7 @@ conceived → specified → planned → implementing → implemented → committ
 
 **What happens next:** Nothing - the project is complete! A review document captures lessons learned.
 
-**Artifact:** Review document in `codev/reviews/NNNN-name.md`
+**Artifact:** Review document in `codev/reviews/NNN-name.md`
 
 ---
 
@@ -100,7 +100,7 @@ Projects can also end up in terminal states if they won't be completed:
 
 ### Abandoned
 
-The project was canceled or rejected. It will not be implemented. The notes field in `projectlist.md` should explain why.
+The project was canceled or rejected. It will not be implemented. Close the GitHub Issue with a comment explaining why.
 
 ### On-Hold
 
@@ -125,12 +125,12 @@ conceived → [HUMAN APPROVES] → specified → planned → implementing → im
 
 ## Managing Projects
 
-All project tracking happens in `codev/projectlist.md`. To manage projects:
+Project tracking uses **GitHub Issues**. To manage projects:
 
-- **Add a project:** Tell the Architect what you want to build
-- **Update status:** Ask the Architect to update the project status
+- **Add a project:** Create a GitHub Issue describing what you want to build
+- **Update status:** Update issue labels and comments as work progresses
 - **Approve stages:** Review the spec/plan and tell the Architect to mark it approved
-- **View progress:** Check the Projects tab in the dashboard or read `projectlist.md`
+- **View progress:** Check the Work tab in the dashboard or `gh issue list`
 
 ---
 

package/templates/open.html

@@ -3,12 +3,12 @@
 <head>
   <meta charset="UTF-8">
   <title>Annotate: {{FILE}}</title>
-  <link href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism-tomorrow.min.css" rel="stylesheet">
+  <link href="vendor/prism-tomorrow.min.css" rel="stylesheet">
   <!-- Markdown preview dependencies (loaded only for .md files) -->
   <script>
     if ({{IS_MARKDOWN}}) {
-      document.write('<script src="https://cdn.jsdelivr.net/npm/marked@12/marked.min.js"><\/script>');
-      document.write('<script src="https://cdn.jsdelivr.net/npm/dompurify@3/dist/purify.min.js"><\/script>');
+      document.write('<script src="vendor/marked.min.js"><\/script>');
+      document.write('<script src="vendor/purify.min.js"><\/script>');
     }
   </script>
   <style>
@@ -547,16 +547,16 @@
     <div id="annotationsList"></div>
   </div>
 
-  <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/prism.min.js"></script>
-  <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-javascript.min.js"></script>
-  <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-typescript.min.js"></script>
-  <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-python.min.js"></script>
-  <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-bash.min.js"></script>
-  <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-markdown.min.js"></script>
-  <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-json.min.js"></script>
-  <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-yaml.min.js"></script>
-  <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-css.min.js"></script>
-  <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-markup.min.js"></script>
+  <script src="vendor/prism.min.js"></script>
+  <script src="vendor/prism-javascript.min.js"></script>
+  <script src="vendor/prism-typescript.min.js"></script>
+  <script src="vendor/prism-python.min.js"></script>
+  <script src="vendor/prism-bash.min.js"></script>
+  <script src="vendor/prism-markdown.min.js"></script>
+  <script src="vendor/prism-json.min.js"></script>
+  <script src="vendor/prism-yaml.min.js"></script>
+  <script src="vendor/prism-css.min.js"></script>
+  <script src="vendor/prism-markup.min.js"></script>
 
   <script>
     // State
@@ -988,17 +988,20 @@
       // Position dialog next to click
       const dialog = document.querySelector('.dialog');
       const rect = event.target.getBoundingClientRect();
-      const dialogWidth = 700;
+      // Use actual rendered width (CSS max-width: 90vw constrains on mobile)
+      const dialogWidth = Math.min(700, window.innerWidth * 0.9);
       const dialogHeight = 350;
+      const margin = 10;
 
       // Position to the right of the line number, with some padding
       let left = rect.right + 10;
       let top = rect.top;
 
       // Keep dialog in viewport
-      if (left + dialogWidth > window.innerWidth) {
-        left = window.innerWidth - dialogWidth - 20;
+      if (left + dialogWidth > window.innerWidth - margin) {
+        left = (window.innerWidth - dialogWidth) / 2;
       }
+      if (left < margin) left = margin;
       if (top + dialogHeight > window.innerHeight) {
         top = window.innerHeight - dialogHeight - 20;
       }