ai-fob 1.9.7 → 1.9.8

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

@@ -0,0 +1,597 @@
+---
+description: Orchestrate a full multi-phase feature build with Pi build-phase runner monitoring
+argument-hint: "<path to HL plan spec>"
+---
+
+# Build Feature
+
+Orchestrate a full multi-phase feature build by launching the Pi build-phase runner once and monitoring it from a distance.
+
+The key architecture: **the build-feature agent is an observer/monitor/doctor, not the direct phase controller**. The deterministic phase loop runs in `.pi/scripts/build-phase-runner.sh`; this prompt launches that script in the background, polls durable files on disk, diagnoses stalls, applies bounded interventions when a known recovery playbook matches, audits high-level success criteria, writes a durable learnings file, and presents a final feature-level report.
+
+Use careful, evidence-grounded reasoning for diagnosis and intervention decisions. Do not rewrite phase artifacts on behalf of phase agents.
+
+## Required skill
+
+Before reading or interpreting `STATE.md`, load and follow the `FOB-state-context` skill.
+
+## Arguments
+
+Raw arguments: `$ARGUMENTS`
+
+Parse into:
+
+- `HL_PLAN_PATH`: first argument
+
+If missing, stop with:
+
+```txt
+Usage: /build-feature <path to HL plan spec>
+```
+
+## Variables
+
+Derived in Step 0:
+
+- `HL_PLAN_PATH`: absolute path to high-level plan markdown file
+- `SPEC_DIR`: parent directory of `HL_PLAN_PATH`
+- `PROJECT_ROOT`: nearest ancestor containing `.pi/prompts/build-phase.md`
+- `TASK_NAME`: `task:` from HL plan YAML frontmatter
+- `TOTAL_PHASES`: `phases:` from HL plan YAML frontmatter
+- `LEARNINGS_FILE`: `{SPEC_DIR}/build-feature-learnings.md`
+- `RUNNER_SCRIPT`: `{PROJECT_ROOT}/.pi/scripts/build-phase-runner.sh`
+- `HL_CRITERIA`: map of phase number to original HL success criteria strings
+
+Monitoring state:
+
+- `BUILD_PID`: PID of backgrounded runner process
+- `BUILD_START_TIME`: epoch seconds when launched
+- `CURRENT_PHASE`: phase currently active from `STATE.md`
+- `CURRENT_STEP`: step currently active from `STATE.md`
+- `LAST_POLL_PHASE`: phase from previous poll
+- `LAST_POLL_STEP`: step from previous poll
+- `STALL_SUSPECTED`: false until one no-progress poll, true until confirmed/resolved
+- `INTERVENTION_COUNTS`: per-phase intervention counter, max 2
+- `VERIFIED_PHASES`: phases whose success criteria have already been audited
+- `POLL_NUMBER`: incremented each poll
+
+## Status vocabulary
+
+Use Claude-compatible feature-level status names in the final report:
+
+```txt
+completed -> all required phases reached status: complete and criteria audit is acceptable
+partial -> at least one phase completed, but the run stopped on blocked/failed/incomplete phase
+aborted -> monitor aborted due to unrecoverable stall, process failure, invalid setup, or manual stop
+```
+
+Use Pi phase-level statuses exactly as reported in `phase_completion_report.md`:
+
+```txt
+complete -> phase succeeded; runner may continue
+blocked -> external/environment/human-action blocker; stop by default unless explicitly accepted
+failed/fail -> validation/build failure after internal recovery loops; stop
+missing/invalid report -> orchestration/artifact failure; stop
+```
+
+Blocked is not failed, but blocked must not be silently ignored.
+
+## Workflow
+
+### Step 0: Parse and validate inputs
+
+1. Parse `HL_PLAN_PATH` from `$ARGUMENTS`. Trim whitespace.
+2. Resolve it to an absolute path.
+3. Verify it exists and ends in `.md`.
+4. Read the HL plan.
+5. Parse YAML frontmatter between the first pair of `---` delimiters:
+   - `task:` -> `TASK_NAME`; if missing/empty, abort.
+   - `phases:` -> `TOTAL_PHASES`; if missing/not positive integer, abort.
+6. Set `SPEC_DIR` to the parent directory of `HL_PLAN_PATH`.
+7. Derive `PROJECT_ROOT` by walking upward from `SPEC_DIR` until finding `.pi/prompts/build-phase.md`. If not found, abort.
+8. Set `RUNNER_SCRIPT` to `{PROJECT_ROOT}/.pi/scripts/build-phase-runner.sh`; verify it exists and is executable.
+9. Set `LEARNINGS_FILE` to `{SPEC_DIR}/build-feature-learnings.md`.
+10. Load `FOB-state-context` before reading `STATE.md`.
+11. Extract original high-level success criteria per phase:
+    - Find phase sections such as `### Phase N: ...`.
+    - Within each phase section, find `**Success Criteria**:` or equivalent success criteria block.
+    - Extract checkbox items beginning `- [ ]` or `- [x]`.
+    - Store exact criterion text in `HL_CRITERIA[N]`.
+    - If no criteria are found for a phase, store an empty list and log a warning.
+
+### Step 1: Initialize durable learnings file
+
+If `LEARNINGS_FILE` does not exist, write:
+
+```markdown
+# Build Feature Learnings: {TASK_NAME}
+
+Spec: {HL_PLAN_PATH}
+Project Root: {PROJECT_ROOT}
+Total Phases: {TOTAL_PHASES}
+Started: {ISO-8601 timestamp}
+
+---
+```
+
+If it exists, append a restart section:
+
+```markdown
+
+---
+
+# Build Feature Restart: {TASK_NAME}
+
+Restarted: {ISO-8601 timestamp}
+Spec: {HL_PLAN_PATH}
+Project Root: {PROJECT_ROOT}
+Total Phases: {TOTAL_PHASES}
+
+---
+```
+
+Always read the current file first, append in memory, then write the full updated content.
+
+### Step 2: Pre-flight checks
+
+Run and log these checks before launch. Accumulate results and append one `## Pre-Flight Checks` section to `LEARNINGS_FILE`.
+
+#### 2.1 Lock file check
+
+Lock file:
+
+```txt
+{SPEC_DIR}/.build-phase.lock
+```
+
+If it exists:
+
+1. Read PID.
+2. If PID is running, abort with a clear message: another build is active.
+3. If PID is dead, remove the stale lock and log it.
+
+#### 2.2 Port check
+
+Check port 3000 for existing processes:
+
+```bash
+lsof -ti:3000 2>/dev/null
+```
+
+If occupied, kill those PIDs before launch and log the action. This matches current test-project behavior. Future versions may read the configured dev port from `testing-and-validation`.
+
+#### 2.3 Git status check
+
+Run from `PROJECT_ROOT`:
+
+```bash
+git status --porcelain 2>/dev/null || echo GIT_UNAVAILABLE
+```
+
+Log clean/dirty/unavailable. Do not abort on dirty state.
+
+#### 2.4 STATE.md check
+
+Read `{SPEC_DIR}/../STATE.md` if present, or the nearest `specs/STATE.md` according to `FOB-state-context` conventions.
+
+Log whether `TASK_NAME` exists and which phases are already marked `[x]`.
+
+#### 2.5 Runner sanity check
+
+Run:
+
+```bash
+bash -n "{RUNNER_SCRIPT}"
+```
+
+Abort if syntax check fails.
+
+#### 2.6 Write pre-flight section
+
+Append:
+
+```markdown
+## Pre-Flight Checks
+Timestamp: {ISO-8601 timestamp}
+
+- Lock file: {clean | stale lock removed PID | active lock abort}
+- Port 3000: {clean | killed PIDs}
+- Git status: {clean | N uncommitted changes | unavailable}
+- STATE.md: {task found, completed phases ... | task not found}
+- Runner syntax: {pass | fail}
+```
+
+### Step 3: Launch runner once
+
+1. Append to `LEARNINGS_FILE`:
+
+```markdown
+## Build Launch
+Started: {ISO-8601 timestamp}
+Phase spec: all ({TOTAL_PHASES} total phases)
+Runner: {RUNNER_SCRIPT}
+```
+
+2. Initialize monitoring state:
+   - `INTERVENTION_COUNTS = {}`
+   - `VERIFIED_PHASES = {}`
+   - `LAST_POLL_PHASE = null`
+   - `LAST_POLL_STEP = null`
+   - `STALL_SUSPECTED = false`
+   - `POLL_NUMBER = 0`
+
+3. Launch the runner using shell-level backgrounding in one Bash call:
+
+```bash
+cd "{PROJECT_ROOT}" && "{RUNNER_SCRIPT}" "{HL_PLAN_PATH}" all > /tmp/build-feature.log 2>&1 &
+echo $!
+```
+
+Important: use shell `&`. Do not attempt to keep the build loop inside the agent. Capture stdout PID as `BUILD_PID`.
+
+4. Append `Build PID: {BUILD_PID}` to `LEARNINGS_FILE`.
+5. Set `BUILD_START_TIME` using `date +%s`.
+6. Create freshness marker:
+
+```bash
+touch /tmp/build-feature-lastpoll
+```
+
+### Step 4: Monitoring loop
+
+Poll until the runner exits or the monitor aborts.
+
+Default polling interval: 15 minutes, matching Claude Code vocabulary. During initial testing, a user may ask for a shorter interval, but the prompt default is 15 minutes.
+
+Each poll:
+
+1. Sleep:
+
+```bash
+sleep 900
+```
+
+2. Increment `POLL_NUMBER`.
+3. Check runner process:
+
+```bash
+kill -0 {BUILD_PID} 2>/dev/null && echo ALIVE || echo EXITED
+```
+
+If exited, proceed to Step 7 Completion Assessment.
+
+4. Read `STATE.md` and determine:
+   - active phase with any step `[~]`
+   - active step number/name
+   - completed phases whose Step 1-6 are `[x]`
+   - between-phase state, if no `[~]` but next phase not started
+
+5. Detect phase transition:
+   - If `CURRENT_PHASE` differs from `LAST_POLL_PHASE` and `LAST_POLL_PHASE` is not null, log transition.
+   - Audit the just-completed phase using Step 6.
+   - Run between-phase cleanup (Step 5).
+   - Reset `STALL_SUSPECTED=false`.
+
+6. Check for new artifacts since last poll:
+
+```bash
+NEW_FILES=""
+for dir in $(find "{SPEC_DIR}" -maxdepth 1 -type d -name "phase*_*" 2>/dev/null); do
+  FILES=$(find "$dir" -newer /tmp/build-feature-lastpoll -type f 2>/dev/null | head -5)
+  if [ -n "$FILES" ]; then
+    NEW_FILES="${NEW_FILES}${FILES}\n"
+  fi
+done
+if [ -n "$NEW_FILES" ]; then
+  echo "NEW_ARTIFACTS:"
+  echo -e "$NEW_FILES"
+else
+  echo "NO_NEW_ARTIFACTS"
+fi
+touch /tmp/build-feature-lastpoll
+```
+
+7. Tail runner log for context:
+
+```bash
+tail -80 /tmp/build-feature.log 2>/dev/null || true
+```
+
+8. Stall detection:
+   - Phase changed -> progress.
+   - Step changed -> progress.
+   - Same step but new artifacts -> progress.
+   - Same step and no new artifacts for one poll -> set `STALL_SUSPECTED=true`, log warning.
+   - Same step and no new artifacts for two consecutive polls -> confirmed stall; proceed to Step 8 Diagnosis and Intervention.
+
+9. Append poll section to `LEARNINGS_FILE`:
+
+```markdown
+### Poll {POLL_NUMBER} ({elapsed_minutes}m)
+- Process alive: yes
+- Current phase: Phase {CURRENT_PHASE}
+- Current step: Step {CURRENT_STEP} - {step_name}
+- Phases completed: {list}
+- New artifacts since last poll: {list or none}
+- Runner log tail: summarized / see /tmp/build-feature.log
+- Progress status: {progress | possible stall | confirmed stall}
+```
+
+10. Continue polling.
+
+### Step 5: Between-phase cleanup
+
+On phase transition only, while runner is still alive:
+
+1. Clear port 3000:
+
+```bash
+lsof -ti:3000 | xargs kill -9 2>/dev/null; echo "Port cleanup done"
+```
+
+2. Append:
+
+```markdown
+### Between-Phase Cleanup (Phase {LAST_POLL_PHASE} -> Phase {CURRENT_PHASE})
+- Port 3000: cleared
+```
+
+Do not remove `.build-phase.lock` during normal between-phase cleanup; the runner owns it.
+
+### Step 6: Success criteria verification for a phase
+
+Run this when a phase transition is observed and again during final completion assessment for any phases not already verified.
+
+For phase `N`:
+
+1. Resolve phase directory:
+
+```bash
+find "{SPEC_DIR}" -maxdepth 1 -type d -name "phase{N}_*" 2>/dev/null | head -1
+```
+
+2. Read `{PHASE_DIR}/phase_completion_report.md`.
+3. Parse YAML frontmatter:
+   - `status:`
+   - `validation-result:`
+   - `checks-passed:`
+   - `checks-blocked:`
+   - `fix-cycles:`
+4. Find the report's `## HL Success Criteria Results` or `## HL Plan Success Criteria Results` section.
+5. Parse table rows into:
+   - criterion text
+   - result: `PASS`, `FAIL`, `BLOCKED`
+   - evidence
+6. Cross-reference against `HL_CRITERIA[N]` from the original HL plan:
+   - matching row with `PASS` -> `complete`
+   - matching row with `FAIL` -> `incomplete`
+   - matching row with `BLOCKED` -> `blocked`
+   - no matching row -> `dropped`
+7. Flag extra report rows not present in original HL criteria as `extra`.
+8. Append:
+
+```markdown
+### Success Criteria Verification: Phase {N}
+Timestamp: {ISO-8601 timestamp}
+Source: phase_completion_report.md vs HL plan
+Phase status: {status}
+Validation result: {validation-result}
+
+| # | Criterion | Status | Evidence |
+|---|-----------|--------|----------|
+| 1 | {criterion text} | {complete/incomplete/blocked/dropped} | {evidence} |
+
+Summary: {complete}/{total} criteria complete; {blocked} blocked; {dropped} dropped; {extra} extra.
+```
+
+This verification is observational. Do not modify phase reports.
+
+### Step 7: Completion assessment
+
+When the runner exits:
+
+1. Try to collect exit code:
+
+```bash
+wait {BUILD_PID} 2>/dev/null; echo $?
+```
+
+If unavailable because process was already reaped, record `unknown`.
+
+2. Read final `STATE.md`.
+3. For each phase `1..TOTAL_PHASES`:
+   - resolve phase directory,
+   - read `phase_completion_report.md`,
+   - parse frontmatter status,
+   - count completed Step 1-6 markers,
+   - compute per-phase result.
+4. Audit success criteria for any phase not in `VERIFIED_PHASES` using Step 6.
+5. Compute:
+   - total phases attempted,
+   - total phases complete,
+   - blocked phases,
+   - failed phases,
+   - incomplete/missing-report phases,
+   - total criteria,
+   - criteria complete,
+   - criteria incomplete,
+   - criteria blocked,
+   - criteria dropped,
+   - total interventions,
+   - total duration.
+6. Determine feature status:
+
+```txt
+all phases complete and no monitor abort -> completed
+some phases complete but blocked/failed/incomplete exist -> partial
+monitor aborted or unrecoverable stall/process issue -> aborted
+```
+
+7. Append to `LEARNINGS_FILE`:
+
+```markdown
+## Build Process Exited
+Timestamp: {ISO-8601 timestamp}
+Exit code: {code}
+Duration: {minutes}m
+
+### Per-Phase Results
+| Phase | Steps Completed | Status | Validation | Interventions |
+|-------|-----------------|--------|------------|---------------|
+| 1 | {count}/6 | {status} | {validation-result} | {count} |
+
+## Success Criteria Audit: Full Build
+Timestamp: {ISO-8601 timestamp}
+
+| Phase | Total Criteria | Complete | Incomplete | Blocked | Dropped |
+|-------|----------------|----------|------------|---------|---------|
+| 1 | {total} | {complete} | {incomplete} | {blocked} | {dropped} |
+| TOTAL | {total} | {complete} | {incomplete} | {blocked} | {dropped} |
+```
+
+Proceed to Step 9 Final Report.
+
+### Step 8: Diagnosis and intervention
+
+Run only after confirmed stall: two consecutive polls with same phase/step and no new artifacts.
+
+#### 8.1 Diagnosis
+
+Collect:
+
+```bash
+echo "=== Main process ==="
+ps -o pid,ppid,stat,%cpu,command -p {BUILD_PID} 2>/dev/null || true
+
+echo "=== Child processes ==="
+pgrep -P {BUILD_PID} 2>/dev/null | xargs ps -o pid,ppid,stat,%cpu,command -p 2>/dev/null || true
+
+echo "=== Grandchild processes ==="
+for child in $(pgrep -P {BUILD_PID} 2>/dev/null); do
+  pgrep -P "$child" 2>/dev/null | xargs ps -o pid,ppid,stat,%cpu,command -p 2>/dev/null
+done 2>/dev/null || true
+
+echo "=== Dev server processes ==="
+pgrep -f 'dev\.sh|bun.*dev|next dev|vite' 2>/dev/null | while read pid; do
+  ps -o pid,%cpu,command -p "$pid" 2>/dev/null
+done
+
+echo "=== Port 3000 ==="
+lsof -ti:3000 2>/dev/null || echo PORT_FREE
+
+echo "=== Runner log tail ==="
+tail -120 /tmp/build-feature.log 2>/dev/null || true
+```
+
+Append full diagnosis to `LEARNINGS_FILE`.
+
+#### 8.2 Known Error Playbook: Dev Server Foreground Hang
+
+Match if all are true:
+
+1. `STUCK_STEP` is Step 5 Validate Build.
+2. Dev server processes exist, port 3000 is occupied, or Step 5 has had no artifacts for 30+ minutes.
+3. `INTERVENTION_COUNTS[STUCK_PHASE] < 2`.
+
+Fix:
+
+1. Kill port 3000 processes.
+2. Kill `dev.sh`, `bun dev`, `next dev`, and `vite` processes.
+3. Kill runner process tree: grandchildren, children, then main PID.
+4. Sleep 5.
+5. Remove stale lock: `{SPEC_DIR}/.build-phase.lock`.
+6. Increment `INTERVENTION_COUNTS[STUCK_PHASE]`.
+7. Append an `### Intervention` entry to `LEARNINGS_FILE`.
+8. Relaunch the runner with `all`:
+
+```bash
+cd "{PROJECT_ROOT}" && "{RUNNER_SCRIPT}" "{HL_PLAN_PATH}" all > /tmp/build-feature.log 2>&1 &
+echo $!
+```
+
+9. Update `BUILD_PID`, reset `STALL_SUSPECTED=false`, touch `/tmp/build-feature-lastpoll`, and return to Step 4.
+
+Why `all`: the runner iterates all phases, and `build-phase` resumes/skips completed work from `STATE.md` and artifacts.
+
+#### 8.3 Unknown stall
+
+If no playbook matches:
+
+1. Append `### Unrecognized Stall` to `LEARNINGS_FILE`.
+2. Kill runner process tree and port 3000 to avoid orphans.
+3. Mark feature status `aborted`.
+4. Proceed to Step 9 Final Report.
+
+### Step 9: Final Build Feature Report
+
+Present the final results using this exact vocabulary and structure.
+
+```markdown
+## Build Feature Report
+
+**Feature:** {TASK_NAME}
+**Spec:** {HL_PLAN_PATH}
+**Status:** {completed | partial | aborted}
+**Duration:** {total minutes}m
+**Phases:** {completed_count}/{TOTAL_PHASES}
+**Criteria:** {complete_count}/{total_criteria_count} verified complete
+
+### Phase Results
+| Phase | Name | Status | Duration | Interventions | Criteria |
+|-------|------|--------|----------|---------------|----------|
+| 1 | {phase_name} | {status} | {duration}m | {count} | {complete}/{total} |
+
+### Criteria Issues
+| Phase | Criterion | Status | Detail |
+|-------|-----------|--------|--------|
+| {N} | {criterion text} | {incomplete/blocked/dropped} | {evidence or reason} |
+```
+
+Omit `### Criteria Issues` only if there are no incomplete, blocked, or dropped criteria.
+
+Continue:
+
+```markdown
+### Interventions
+{total_count} total interventions applied.
+
+{If total_count > 0: list each intervention with phase number, step, error type, and outcome.}
+{If total_count == 0: No interventions were needed. All phases completed without monitor intervention.}
+
+### Learnings File
+Full build log saved to: {LEARNINGS_FILE}
+Runner log: /tmp/build-feature.log
+
+### Next Steps
+- {If completed and all criteria complete: All phases built successfully and all success criteria verified. Review STATE.md and phase completion reports for details.}
+- {If completed but criteria issues exist: All phases completed, but {count} success criteria were not fully met. Review Criteria Issues and the learnings file.}
+- {If partial: Phases {list} completed. Phase {N} stopped with status {status}. Review the learnings file and phase completion report. To retry: /build-feature {HL_PLAN_PATH}}
+- {If aborted: Build aborted due to {reason}. See learnings file for diagnosis. After resolving the issue, retry with: /build-feature {HL_PLAN_PATH}}
+```
+
+### Step 10: Cleanup
+
+After final report, clean temporary monitor files unless the user asks to preserve them:
+
+```bash
+rm -f /tmp/build-feature-lastpoll
+```
+
+Do not delete `LEARNINGS_FILE`.
+
+Do not delete phase artifacts.
+
+If the build is still running because of an abort/intervention failure, kill the runner process tree and clear port 3000 before exiting.
+
+## Edge cases
+
+1. **Already-completed phases**: runner invokes `build-phase` for each selected phase; `build-phase` resume logic should detect complete artifacts/state and exit quickly.
+2. **Partial phases**: `build-phase` resumes from incomplete step according to `STATE.md` and artifact validity.
+3. **Blocked phase**: runner stops by default; monitor reports `partial` unless an explicit accepted-blocker policy is later added.
+4. **Accepted blockers**: future version may support explicit blocker override via prompt argument, HL metadata, or sidecar config. Do not silently continue through blocked phases in v1.
+5. **Max interventions**: max 2 per phase. After that, abort.
+6. **Concurrent runs**: active `.build-phase.lock` aborts preflight.
+7. **Context compaction**: `build-feature-learnings.md` is the durable source of truth.
+8. **Build continues independently**: monitor is observer, not controller. The runner process owns the phase loop.
+9. **Restart uses `all`**: this is intentional because `build-phase` resume logic handles skipped/completed work.
+10. **No macOS `open`**: browser validation remains owned by `build-phase` and must use `agent-browser` through existing skills.

package/manifest.json

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

package/package.json

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