@cluesmith/codev 2.0.0-rc.72 → 2.0.0-rc.74

package/skeleton/protocols/maintain/protocol.md

@@ -186,8 +186,8 @@ Scan the actual codebase and update `codev/resources/arch.md`:
 - **Location**: path/to/component
 - **How It Works**:
   - Step-by-step explanation of the mechanism
-  - Key technologies used (e.g., "uses shepherd processes for terminal persistence")
-  - Runtime behavior (e.g., "spawns a shepherd process per builder terminal")
+  - Key technologies used (e.g., "uses shellper processes for terminal persistence")
+  - Runtime behavior (e.g., "spawns a shellper process per builder terminal")
   - State management (e.g., "state stored in SQLite at .agent-farm/state.db")
 - **Key Files**:
   - `file.ts` - does X
@@ -222,7 +222,7 @@ For each major component, arch.md MUST explain the implementation mechanism, not
 
 | Bad (just WHAT) | Good (includes HOW) |
 |-----------------|---------------------|
-| "Agent Farm manages builders" | "Agent Farm spawns builders in isolated git worktrees. Each builder runs in a shepherd-backed terminal session. The Tower dashboard exposes terminals via WebSocket. State is persisted in SQLite." |
+| "Agent Farm manages builders" | "Agent Farm spawns builders in isolated git worktrees. Each builder runs in a shellper-backed terminal session. The Tower dashboard exposes terminals via WebSocket. State is persisted in SQLite." |
 | "Consult tool queries AI models" | "Consult shells out to external CLIs (gemini-cli, codex, claude). It writes the consultant role to a temp file, sets environment variables, and streams stdout/stderr back to the user." |
 
 This level of detail enables rapid onboarding and debugging.

package/skeleton/protocols/spir/builder-prompt.md

@@ -53,6 +53,13 @@ Follow the implementation plan at: `{{plan.path}}`
 {{task_text}}
 {{/if}}
 
+## Notifications
+Always use `af send architect "..."` to notify the architect at key moments:
+- **Gate reached**: `af send architect "Project {{project_id}}: <gate-name> ready for approval"`
+- **PR ready**: `af send architect "PR #N ready for review (project {{project_id}})"`
+- **PR merged**: `af send architect "Project {{project_id}} complete. PR merged. Ready for cleanup."`
+- **Blocked**: `af send architect "Blocked on project {{project_id}}: [reason]"`
+
 ## Getting Started
 1. Read the protocol document thoroughly
 2. Review the spec and plan (if available)

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

@@ -43,7 +43,7 @@ af dash start [options]
 Starts the agent-farm dashboard with:
 - Architect terminal (Claude session with architect role)
 - Web-based UI for monitoring builders
-- Terminal session management (shepherd processes)
+- Terminal session management (shellper processes)
 
 The dashboard is accessible via browser at `http://localhost:<port>`.
 
@@ -132,7 +132,7 @@ af dash stop
 **Description:**
 
 Stops all running agent-farm processes including:
-- Terminal sessions (shepherd processes)
+- Terminal sessions (shellper processes)
 - Dashboard servers
 
 Does NOT clean up worktrees - use `af cleanup` for that.

package/skeleton/roles/builder.md

@@ -140,12 +140,26 @@ porch status      # (strict mode) Your project status
 af status         # All builders
 ```
 
+## Notifications
+
+**ALWAYS notify the architect** via `af send` at these key moments:
+
+| When | What to send |
+|------|-------------|
+| **Gate reached** | `af send architect "Project XXXX: <gate-name> ready for approval"` |
+| **PR ready** | `af send architect "PR #N ready for review"` |
+| **PR merged** | `af send architect "Project XXXX complete. PR merged. Ready for cleanup."` |
+| **Blocked/stuck** | `af send architect "Blocked on X — need guidance"` |
+| **Escalation needed** | `af send architect "Issue too complex — recommend escalating to SPIR/TICK"` |
+
+The architect may be working on other tasks and won't know you need attention unless you send a message. **Don't assume they're watching** — always notify explicitly.
+
 ## When You're Blocked
 
 If you encounter issues you can't resolve:
 
 1. **Output a clear blocker message** describing the problem and options
-2. **Use `af send architect "..."` ** to notify the Architect
+2. **Use `af send architect "..."` to notify the Architect**
 3. **Wait for guidance** before proceeding
 
 Example: