ai-fob 1.11.1 → 1.11.2

package/assets/pi/prompts/build-feature-interagent.md

@@ -0,0 +1,394 @@
+---
+description: Orchestrate a full multi-phase feature build by launching Claude Code teammates through inter-agent-team
+argument-hint: "<path to HL plan spec> [start phase] [end phase]"
+---
+
+# Build Feature — Inter-Agent Team Claude Code Runner
+
+Orchestrate a full multi-phase feature build by launching one Claude Code teammate per phase through the `inter_agent_team` tool.
+
+This workflow exists to avoid headless Claude Code execution (`claude -p`) while still automating phase sequencing. Each phase runs in a live Claude Code session launched with the existing Claude Code command:
+
+```txt
+/build-phase-V2 <HL_PLAN_PATH> <PHASE_NUMBER>
+```
+
+The Pi agent is the supervisor/orchestrator. Claude Code performs the phase build. Pi watches durable filesystem artifacts (`phase_completion_report.md` and `specs/STATE.md`) to decide when a phase has completed and whether to continue.
+
+## Required skills/tools
+
+Before reading or interpreting `specs/STATE.md`, load and follow the `FOB-state-context` skill.
+
+Use the `inter_agent_team` tool to create, show, attach only if explicitly requested, and close Claude Code teammates.
+
+Do not use headless Claude Code (`claude -p`) in this workflow.
+
+## Arguments
+
+Raw arguments: `$ARGUMENTS`
+
+Parse into:
+
+- `HL_PLAN_PATH`: first argument, required
+- `START_PHASE`: second argument, optional, default: first incomplete phase or `1`
+- `END_PHASE`: third argument, optional, default: total phases from plan frontmatter
+
+If `HL_PLAN_PATH` is missing, stop with:
+
+```txt
+Usage: /build-feature-interagent <path to HL plan spec> [start phase] [end phase]
+```
+
+## Derived variables
+
+Compute in Step 0:
+
+- `PROJECT_ROOT`: nearest ancestor containing `.pi/` or `.claude/`, preferably git root when available
+- `HL_PLAN_PATH_ABS`: absolute path to high-level plan markdown file
+- `HL_PLAN_PATH_REL`: project-root-relative path to high-level plan markdown file
+- `SPEC_DIR`: parent directory of `HL_PLAN_PATH_ABS`
+- `SPEC_DIR_REL`: project-root-relative path to `SPEC_DIR`
+- `TASK_NAME`: `task:` from HL plan YAML frontmatter
+- `TOTAL_PHASES`: `phases:` from HL plan YAML frontmatter
+- `FEATURE_SLUG`: basename of `SPEC_DIR`
+- `TEAM_NAME`: `build-feature-{FEATURE_SLUG}`
+- `WORKFLOW_STATE_DIR`: `{PROJECT_ROOT}/.pi/inter-agent-team/workflows/build-feature`
+- `WORKFLOW_STATE_FILE`: `{WORKFLOW_STATE_DIR}/{FEATURE_SLUG}.json`
+- `STATE_MD`: nearest `specs/STATE.md` according to `FOB-state-context`; usually `{PROJECT_ROOT}/specs/STATE.md`
+- `LEARNINGS_FILE`: `{SPEC_DIR}/build-feature-interagent-learnings.md`
+
+## Workflow state file
+
+Maintain a resumable orchestration state file at `WORKFLOW_STATE_FILE`.
+
+Shape:
+
+```json
+{
+  "workflow": "build-feature-interagent",
+  "status": "running",
+  "planPath": "specs/example/example_V1.md",
+  "featureSlug": "example",
+  "teamName": "build-feature-example",
+  "createdAt": "ISO timestamp",
+  "updatedAt": "ISO timestamp",
+  "startPhase": 1,
+  "endPhase": 3,
+  "currentPhase": 1,
+  "phases": [
+    {
+      "phase": 1,
+      "status": "completed | running | blocked | failed | interrupted | skipped",
+      "agentName": "phase-1-builder",
+      "launchPrompt": "/build-phase-V2 specs/example/example_V1.md 1",
+      "startedAt": "ISO timestamp",
+      "completedAt": "ISO timestamp",
+      "completionReport": "specs/example/phase1_name/phase_completion_report.md",
+      "result": "complete | blocked | failed | unknown",
+      "validationResult": "pass | pass-with-followups | blocked | fail | unknown",
+      "stateHashBefore": "sha256",
+      "stateHashAfter": "sha256"
+    }
+  ]
+}
+```
+
+Read and update this file using safe read-modify-write behavior. Create parent directories if needed.
+
+## Completion signals
+
+A phase is complete when the build-phase-V2 Claude teammate has produced durable completion evidence.
+
+Use layered detection:
+
+1. Primary signal: a matching phase completion report exists and was created or modified after the phase launch:
+
+   ```txt
+   {SPEC_DIR}/phase{N}_*/phase_completion_report.md
+   ```
+
+2. Secondary signal: `STATE_MD` changed after launch, or the matching phase in `STATE_MD` is marked complete.
+
+3. Classification signal: the phase report YAML frontmatter contains:
+
+   ```yaml
+   type: phase-report
+   status: complete | blocked | failed
+   validation-result: pass | pass-with-followups | blocked | fail
+   ```
+
+Proceed automatically only when:
+
+```txt
+status: complete
+```
+
+Treat `validation-result: pass-with-followups` as complete and continue, while recording follow-ups in the learnings file.
+
+Stop automatically when:
+
+```txt
+status: blocked
+status: failed
+validation-result: blocked
+validation-result: fail
+```
+
+If report parsing is ambiguous, stop and summarize the uncertainty. Do not launch the next phase on ambiguous evidence.
+
+## Polling defaults
+
+Default poll interval:
+
+```txt
+60 seconds
+```
+
+Maximum no-evidence wait before surfacing a stall warning:
+
+```txt
+30 minutes
+```
+
+Do not kill a running Claude Code teammate solely because polling has not observed progress. Surface the stall and continue polling unless the user instructs otherwise.
+
+## Step 0: Parse, validate, and resume-detect
+
+1. Parse arguments.
+2. Resolve `PROJECT_ROOT`:
+   - prefer `git rev-parse --show-toplevel`
+   - otherwise walk upward from `HL_PLAN_PATH` until finding `.pi/` or `.claude/`
+3. Resolve `HL_PLAN_PATH_ABS` and `HL_PLAN_PATH_REL`.
+4. Verify `HL_PLAN_PATH_ABS` exists and is a Markdown file.
+5. Read the HL plan.
+6. Parse YAML frontmatter:
+   - `task:` → `TASK_NAME`; required
+   - `phases:` → `TOTAL_PHASES`; required positive integer
+7. Validate `START_PHASE` and `END_PHASE` if provided.
+8. Load `FOB-state-context` before reading `STATE_MD`.
+9. Locate/read `STATE_MD`.
+10. Create/read `WORKFLOW_STATE_FILE`.
+11. Reconcile prior state with filesystem:
+    - For each phase `1..TOTAL_PHASES`, look for `phase{N}_*/phase_completion_report.md`.
+    - If valid report exists with `status: complete`, mark phase completed in workflow state.
+    - If report exists with `status: blocked` or `status: failed`, mark phase blocked/failed and stop unless user explicitly asks to resume past it.
+    - If workflow state says `running` but there is no live teammate/session visible through `inter_agent_team list`, mark it `interrupted`.
+12. Determine the next phase:
+    - If `START_PHASE` was provided, use it.
+    - Otherwise use the first phase in the requested range that is not completed.
+13. If all phases in range are already complete, write final summary and stop.
+
+## Step 1: Initialize learnings and pre-flight log
+
+Create or append to `LEARNINGS_FILE`.
+
+Initial section:
+
+```markdown
+# Build Feature Inter-Agent Learnings: {TASK_NAME}
+
+Spec: {HL_PLAN_PATH_REL}
+Project Root: {PROJECT_ROOT}
+Total Phases: {TOTAL_PHASES}
+Requested Range: {START_PHASE}-{END_PHASE}
+Started/Resumed: {ISO timestamp}
+Workflow State: {WORKFLOW_STATE_FILE}
+
+---
+```
+
+Append a pre-flight section:
+
+```markdown
+## Pre-Flight Checks
+Timestamp: {ISO timestamp}
+
+- Git status: {clean | N uncommitted changes | unavailable}
+- STATE.md: {STATE_MD path, task found/not found, completed phases if detected}
+- Existing workflow state: {new | resumed}
+- Existing reports: {phase report summary}
+- Team strategy: one team per feature, one Claude Code teammate per phase
+- Claude launch mode: claude --dangerously-skip-permissions "{launch prompt}"
+```
+
+## Step 2: Ensure feature team exists
+
+Use a single active team for the feature:
+
+```txt
+TEAM_NAME = build-feature-{FEATURE_SLUG}
+```
+
+Before creating a new team:
+
+1. Call `inter_agent_team list`.
+2. If an active team with `TEAM_NAME` exists, reuse it.
+3. Otherwise create the team when launching the first phase.
+
+Important: the current `inter_agent_team create` action creates team and teammates together. If no active team exists, create the feature team with the first phase teammate. If a team exists and adding new teammates is not supported yet, create a new phase-specific team named:
+
+```txt
+build-feature-{FEATURE_SLUG}-phase-{N}
+```
+
+Record the actual team name/id in `WORKFLOW_STATE_FILE`.
+
+## Step 3: Launch and supervise phases sequentially
+
+For each phase `N` from current phase through `END_PHASE`:
+
+### 3.1 Baseline before launch
+
+Record:
+
+- current timestamp `PHASE_STARTED_AT`
+- `STATE_MD` hash before launch, if file exists
+- any existing matching `phase{N}_*/phase_completion_report.md` path and hash/mtime
+- current workflow state
+
+If a valid completion report already exists and phase is marked complete, skip to the next phase.
+
+### 3.2 Launch Claude Code teammate
+
+Construct:
+
+```txt
+AGENT_NAME = phase-{N}-builder
+LAUNCH_PROMPT = /build-phase-V2 {HL_PLAN_PATH_REL} {N}
+```
+
+Call `inter_agent_team create` with a Claude Code teammate:
+
+```ts
+inter_agent_team({
+  action: "create",
+  name: "build-feature-{FEATURE_SLUG}-phase-{N}",
+  task: "Run Claude Code build phase {N} for {HL_PLAN_PATH_REL} and write the standard phase completion report.",
+  agents: [{
+    name: "phase-{N}-builder",
+    role: "Claude Code build-phase-V2 runner for phase {N}",
+    runtime: "claude-code",
+    runtimeArgs: ["--dangerously-skip-permissions"],
+    launchPrompt: "/build-phase-V2 {HL_PLAN_PATH_REL} {N}"
+  }]
+})
+```
+
+Record team id/name, agent id/name, launch prompt, state hash before launch, and timestamp in `WORKFLOW_STATE_FILE`.
+
+Do not attach unless the user explicitly asks.
+
+### 3.3 Poll for completion
+
+Loop:
+
+1. Sleep 60 seconds:
+
+   ```bash
+   sleep 60
+   ```
+
+2. Search for phase report:
+
+   ```bash
+   find "{SPEC_DIR}" -maxdepth 2 -type f -path "*/phase{N}_*/phase_completion_report.md" -print 2>/dev/null
+   find "{SPEC_DIR}" -maxdepth 2 -type f -path "*/phase_completion_report.md" -print 2>/dev/null | grep "/phase{N}_" || true
+   ```
+
+3. Check report mtime/hash against baseline. Prefer reports modified after `PHASE_STARTED_AT`.
+4. Read candidate report if found.
+5. Parse YAML frontmatter from the report.
+6. Check `STATE_MD` hash and phase marker.
+7. Optionally call `inter_agent_team show` for passive inspection if no file progress is observed for multiple polls. Do not attach automatically.
+8. Update `WORKFLOW_STATE_FILE` with last poll timestamp and observed evidence.
+
+### 3.4 Completion decision
+
+If report frontmatter is valid:
+
+- `status: complete`:
+  1. Mark phase completed in workflow state.
+  2. Record `completionReport`, `validationResult`, and `stateHashAfter`.
+  3. Append phase summary to `LEARNINGS_FILE`.
+  4. Close the phase teammate/team with `inter_agent_team close_team` for the phase team.
+  5. Continue to phase `N+1`.
+
+- `status: blocked`:
+  1. Mark phase blocked in workflow state.
+  2. Append blocked summary to `LEARNINGS_FILE`.
+  3. Close or leave teammate based on user preference; default close after report exists.
+  4. Stop the workflow. Do not launch next phase.
+
+- `status: failed` or `status: fail`:
+  1. Mark phase failed in workflow state.
+  2. Append failure summary to `LEARNINGS_FILE`.
+  3. Close or leave teammate based on user preference; default close after report exists.
+  4. Stop the workflow. Do not launch next phase.
+
+If report exists but frontmatter is invalid or missing required fields, stop and surface the issue.
+
+If `STATE_MD` changed but no report exists, keep polling. `STATE.md` alone is not enough to proceed.
+
+### 3.5 Stall warning
+
+If no report and no `STATE_MD` hash change have been observed for 30 minutes:
+
+1. Call `inter_agent_team show` for passive output inspection.
+2. Append a stall warning to `LEARNINGS_FILE`.
+3. Present options to the user:
+   - continue polling
+   - attach to teammate
+   - stop and leave teammate running
+   - close teammate and mark phase interrupted
+
+Default if no instruction is available: continue polling.
+
+## Step 4: Resume behavior after interruption
+
+When this prompt is run again for the same plan:
+
+1. Load `WORKFLOW_STATE_FILE`.
+2. Call `inter_agent_team list` to see live/active teams.
+3. Reconcile state with filesystem reports.
+4. For any phase marked `running`:
+   - If its completion report now exists and is valid, mark it complete/blocked/failed according to report.
+   - If there is no live teammate and no report, mark it `interrupted`.
+   - If there is a live teammate, continue polling that phase instead of launching a duplicate.
+5. Continue from the first incomplete/interrupted phase in range.
+6. If relaunching an interrupted phase, rely on `/build-phase-V2`'s own resume detection from `STATE.md` and phase artifacts.
+
+Do not duplicate-run a phase if a live teammate for that phase is already active.
+
+## Step 5: Final report
+
+When all requested phases complete, close/archive any phase teams created by this workflow that are still active and write:
+
+```markdown
+## Final Feature Summary
+Completed: {ISO timestamp}
+Status: completed | partial | blocked | failed | interrupted
+Phases requested: {START_PHASE}-{END_PHASE}
+Phases completed: {list}
+Phases stopped: {list or none}
+Reports:
+- Phase N: {report path} ({status}, validation-result: {validationResult})
+```
+
+Also print a concise final response to the user with:
+
+- overall status
+- completed phases
+- stopped/blocked phase if any
+- key report paths
+- workflow state file path
+- learnings file path
+
+## Safety and constraints
+
+- Do not run `claude -p`.
+- Do not launch phases in parallel unless the user explicitly requests parallel phase execution.
+- Do not attach automatically.
+- Do not proceed past blocked/failed/ambiguous reports without explicit user instruction.
+- Close phase teams after a report is produced and classified, unless the user asks to keep them open.
+- Treat `pass-with-followups` as complete but record follow-ups.
+- Preserve `/build-phase-V2` as the source of truth for actual phase implementation, validation, reporting, and `STATE.md` updates.

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.11.1",
+  "version": "1.11.2",
   "presets": {
     "coding": {
       "description": "Research-driven coding workflow",
@@ -101,7 +101,8 @@
       "prompts": [
         "explore-codebase",
         "build-phase",
-        "build-feature"
+        "build-feature",
+        "build-feature-interagent"
       ],
       "extensions": [
         "pinned-response",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-fob",
-  "version": "1.11.1",
+  "version": "1.11.2",
   "description": "Deploy research-driven AI coding assistant assets (skills, agents, commands) into your projects",
   "bin": {
     "ai-fob": "bin/install.js"