feed-the-machine 1.3.0 → 1.3.1

package/ftm-retro/SKILL.md

@@ -51,19 +51,73 @@ Never ask the user to provide data you can find yourself. Read the files.
 
 ---
 
-## Scoring Flow
+## Scoring Dimensions
 
-Score execution across 5 dimensions. Read `references/protocols/SCORING-RUBRICS.md` for the full rubric for each dimension (scale breakpoints, evidence requirements, formula for Dimension 4).
+Score each dimension 0–10 with a citation to specific data. Do not estimate without evidence — if data is missing, note it and score conservatively.
 
-**The 5 dimensions:**
+### 1. Wave Parallelism Efficiency (0–10)
 
-1. **Wave Parallelism Efficiency** — were independent tasks actually dispatched in parallel?
-2. **Audit Pass Rate** — what percentage of tasks passed ftm-audit on the first attempt?
-3. **Codex Gate Pass Rate** — what percentage of waves passed the ftm-codex-gate on the first attempt?
-4. **Retry and Fix Count** — how many total review-fix cycles were needed? Lower is better.
-5. **Execution Smoothness** — evidence-grounded assessment of blockers, ambiguities, and manual interventions.
+Were independent tasks actually dispatched in parallel? Could more tasks have been parallelized?
 
-Every score requires a citation to specific data. If data for a dimension is unavailable, note the gap and score conservatively.
+- **10**: Every task that could run in parallel did. No serial bottlenecks where parallelism was possible.
+- **7–9**: Minor serial steps that could have been parallel (e.g., final post-processing tasks run sequentially).
+- **4–6**: Significant parallelism opportunities missed. Tasks that had no dependencies ran serially.
+- **1–3**: Nearly all tasks ran serially despite having no dependencies on each other.
+- **0**: Everything was serial regardless of dependency structure.
+
+Evidence to cite: wave structure from PROGRESS.md, task dependency graph, agent dispatch timestamps.
+
+### 2. Audit Pass Rate (0–10)
+
+What percentage of tasks passed ftm-audit on the first attempt?
+
+- **10**: 100% first-pass. No task needed a fix cycle.
+- **8**: 90%+ first-pass. One or two tasks needed minor fixes.
+- **6**: 75–89% first-pass.
+- **4**: 50–74% first-pass. Roughly half the tasks needed audit remediation.
+- **2**: Below 50% first-pass.
+- **0**: Every single task failed audit on the first attempt.
+
+Evidence to cite: per-task audit results (pass/fail counts, auto-fix counts, manual-fix counts).
+
+### 3. Codex Gate Pass Rate (0–10)
+
+What percentage of waves passed the ftm-codex-gate on the first attempt?
+
+- **10**: All waves passed on first gate run.
+- **7–9**: One wave needed a fix-and-retry.
+- **4–6**: Multiple waves needed retries.
+- **1–3**: Most waves failed the gate at least once.
+- **0**: Every wave failed the gate.
+
+Evidence to cite: codex gate results per wave (pass/fail, failure types).
+
+### 4. Retry and Fix Count (0–10)
+
+How many total review-fix cycles were needed across all tasks and waves? Lower is better.
+
+Formula: score = max(0, 10 - (total_retries / task_count) * 5)
+
+- **10**: Zero retries.
+- **8**: Fewer than 0.5 retries per task on average.
+- **6**: 0.5–1.0 retries per task.
+- **4**: 1–2 retries per task.
+- **2**: 2–3 retries per task.
+- **0**: More than 3 retries per task on average.
+
+Evidence to cite: total retries, broken down by type (audit fix, codex gate retry, manual intervention).
+
+### 5. Execution Smoothness (0–10)
+
+Subjective but evidence-grounded assessment. Were there blockers, ambiguous plan steps, confusing errors, or required manual interventions?
+
+- **10**: Fully autonomous from start to finish. No blockers, no ambiguity, no manual steps.
+- **7–9**: Minor friction — one clarification needed, one unexpected error handled gracefully.
+- **4–6**: Moderate friction — multiple ambiguities, one blocker that paused execution, one manual intervention.
+- **1–3**: Significant friction — repeated blockers, unclear plan steps that caused wrong-direction work, multiple manual interventions.
+- **0**: Execution could not proceed without constant human steering.
+
+Evidence to cite: error log entries, any manual interventions recorded in PROGRESS.md, plan ambiguities encountered.
 
 ---
 
@@ -75,28 +129,122 @@ Every score requires a citation to specific data. If data for a dimension is una
 mkdir -p ~/.claude/ftm-retros/
 ```
 
-### Step 2: Check for past retros
+### Step 2: Generate plan slug
 
-Before writing anything, check whether any `.md` files exist in `~/.claude/ftm-retros/`. If they do, read them all. You will use them for the Pattern Analysis section.
+Take the plan title, lowercase it, replace spaces with hyphens, strip all non-alphanumeric characters except hyphens.
 
-### Step 3: Write the report
+Examples:
+- "FTM Ecosystem Expansion" → `ftm-ecosystem-expansion`
+- "Fix Auth Bug + Rate Limiting" → `fix-auth-bug-rate-limiting`
+- "v2.0 API Refactor" → `v20-api-refactor`
+
+### Step 3: Check for past retros
+
+Before writing anything, check whether any `.md` files exist in `~/.claude/ftm-retros/`. If they do, read them all. You will use them for the Pattern Analysis section.
 
-Read `references/templates/REPORT-FORMAT.md` for the exact output template, slug generation rules, and section format.
+### Step 4: Write the report
 
 Save to: `~/.claude/ftm-retros/{plan-slug}-{YYYY-MM-DD}.md`
 
+Use this exact format:
+
+```markdown
+# Retro: {Plan Title}
+
+**Date:** {YYYY-MM-DD}
+**Plan:** {absolute path to plan file}
+**Duration:** {total execution time, e.g. "47 minutes"}
+
+## Scores
+
+| Dimension | Score | Notes |
+|-----------|-------|-------|
+| Wave Parallelism | X/10 | {1-sentence justification with data} |
+| Audit Pass Rate | X/10 | {N}/{total} tasks first-pass |
+| Codex Gate Pass Rate | X/10 | {N}/{total} waves first-pass |
+| Retry/Fix Count | X/10 | {total retries} across {N} tasks |
+| Execution Smoothness | X/10 | {1-sentence justification} |
+
+**Overall: {sum}/50**
+
+## Raw Data
+
+- Tasks: {N}
+- Waves: {N}
+- Agents spawned: {N}
+- Audit findings: {N} total ({N} auto-fixed, {N} manual)
+- Codex gate results: Wave 1: pass | Wave 2: fail → pass | Wave 3: pass
+- Errors/blockers: {list any, or "none"}
+
+## What Went Well
+
+{2–4 specific observations, each grounded in a data point or task number.}
+
+Example format:
+- **Task 3 (auth middleware)** completed in a single commit with zero audit findings. The agent prompt had clear acceptance criteria and a scoped file list — the agent never wandered.
+- **Wave 2 parallelism** was fully utilized: all 4 tasks dispatched simultaneously, cutting estimated serial time from ~32 minutes to ~9 minutes.
+
+## What Was Slow
+
+{2–4 specific bottlenecks with timing data or retry counts where available.}
+
+Example format:
+- **ftm-audit Phase 1 (knip)** repeated full project analysis for each task in wave 3, even though tasks only touched 2–3 files each. Added ~40s × 5 tasks = ~3.5 minutes of unnecessary scanning.
+- **Task 7 needed 3 audit fix cycles** due to an import path that kept regenerating incorrectly. The agent prompt did not specify the alias configuration in tsconfig.paths.
+
+## Proposed Improvements
+
+{3–5 specific, actionable suggestions. Each must identify: which skill to change, what to change exactly, and why it would help.}
+
+Format each as:
+**N. {Short title}** — {Skill to change} — {Specific change} — {Expected impact}
+
+Examples:
+1. **Cache knip results within a wave** — ftm-audit — In Phase 1, check whether knip results are already cached for the current wave (via a temp file at `/tmp/ftm-knip-cache-{wave-id}.json`). Only re-run knip if the cache is missing or if the files changed by this task differ from cached scope. Expected: 3× speedup for ftm-audit on large projects with many tasks per wave.
+2. **Dispatch Instrumentor and Researcher in parallel** — ftm-debug — These two agents have no shared state and currently run sequentially. Dispatch them simultaneously. Expected: ~40% reduction in ftm-debug total runtime.
+3. **Add tsconfig.paths to agent context for TypeScript projects** — ftm-executor — When generating agent prompts for TypeScript tasks, include the relevant `paths` aliases from `tsconfig.json`. Expected: eliminates the import-alias regeneration loop that caused 3 retries on Task 7.
+
+## Pattern Analysis
+
+{Only include this section if past retros exist in ~/.claude/ftm-retros/}
+
+### Recurring Issues
+
+{List problems that appeared in 2 or more retros. Format: "Issue description — appeared in: retro-slug-1, retro-slug-2"}
+
+### Score Trends
+
+{Compare overall scores across retros. Are they improving, declining, or stable? Cite actual numbers.}
+
+Example: Overall scores: 32/50 → 38/50 → 41/50 across the last 3 retros. Parallelism and smoothness improving; audit pass rate stuck at 6/10 for all three runs.
+
+### Unaddressed Suggestions
+
+{List proposed improvements from past retros that have not yet been implemented. These get escalated — flag them explicitly.}
+
+Format: "**[ESCALATED]** {suggestion} — first proposed in {retro-slug-date}, appeared {N} times"
+```
+
 ---
 
 ## Key Behaviors
 
+### Evidence-first scoring
+
+Every score needs a citation. "Tasks passed audit" is not a citation. "12/14 tasks passed audit on first attempt; Tasks 3 and 9 each needed one auto-fix cycle" is a citation. If the data to score a dimension is genuinely unavailable, note the gap explicitly and score conservatively (assume worst case for that dimension).
+
 ### Improvement specificity
 
-"Improve parallelism" is not an improvement proposal. "Add a dependency pre-check step to ftm-executor Phase 2 that flags tasks with no declared dependencies as parallelizable, and warn when they are dispatched serially" is an improvement proposal. Every proposed improvement must be concrete enough that a future session could implement it from the description alone.
+"Improve parallelism" is not an improvement proposal. "Add a dependency pre-check step to ftm-executor Phase 2 that flags tasks with no declared dependencies as parallelizable, and warn when they are dispatched serially" is an improvement proposal. Every proposed improvement must be concrete enough that a future session could implement it from the description alone without asking clarifying questions.
 
 ### Pattern escalation
 
 Recurring issues that have appeared in 3+ retros without being addressed should be flagged with `[ESCALATED - 3+ occurrences]` and moved to the top of the Proposed Improvements list. These are systemic problems, not one-off noise.
 
+### No vibes
+
+Do not write "the execution felt smooth" or "agents seemed efficient." Write "0 manual interventions were required and all errors were caught and auto-resolved by ftm-audit Phase 2." The report is read by future executions that need to calibrate behavior, not by humans looking for encouragement.
+
 ---
 
 ## Output
@@ -111,7 +259,7 @@ Top issue: {single most impactful bottleneck in one sentence}
 Top suggestion: {single highest-value proposed improvement in one sentence}
 ```
 
-Do not print the full report to the terminal — it lives in the file.
+Do not print the full report to the terminal — it lives in the file. The summary above is sufficient for the user to know the run completed and where to find details.
 
 ---
 
@@ -137,7 +285,7 @@ Confidence: [low/medium/high]"
 
 ### Experience Entry Creation
 
-Write a structured experience entry to `~/.claude/ftm-state/blackboard/experiences/YYYY-MM-DD_task-slug.json`.
+Write a structured experience entry to `~/.claude/ftm-state/blackboard/experiences/YYYY-MM-DD_task-slug.json` following the schema in blackboard-schema.md.
 
 Key fields:
 - `task_type`: derived from the task
@@ -177,17 +325,6 @@ During the first ~10 interactions (when `experiences/index.json` has `total_coun
 - Set `confidence: "low"` on all entries
 - Prioritize breadth of recording over depth of analysis
 
-## Blackboard Write
-
-After completing, update:
-1. `~/.claude/ftm-state/blackboard/context.json`:
-   - Set current_task status to "complete"
-   - Append decision summary to recent_decisions (cap at 10)
-   - Update session_metadata.skills_invoked and last_updated
-2. Write experience file to `~/.claude/ftm-state/blackboard/experiences/YYYY-MM-DD_task-slug.json`
-3. Update `experiences/index.json` with the new entry
-4. Emit `task_completed`
-
 ## Requirements
 
 - reference: `PROGRESS.md` | optional | executor progress log for auto-triggered mode

package/ftm-upgrade/SKILL.md

@@ -13,7 +13,7 @@ description: Self-upgrade mechanism for ftm skills ecosystem. Checks GitHub Rele
 
 # ftm-upgrade
 
-Self-upgrade mechanism for the ftm skills ecosystem. Fetches the latest release from `kkudumu/ftm-brain` on GitHub, compares it to the locally installed version, and copies updated skill files in place.
+Self-upgrade mechanism for the ftm skills ecosystem. Fetches the latest release from `kkudumu/ftm-skills` on GitHub, compares it to the locally installed version, and copies updated skill files in place.
 
 ---
 
@@ -135,7 +135,7 @@ Map `CHECK_FAILED <reason>` codes to user-facing messages:
 |---|---|
 | `gh_not_installed` | GitHub CLI is not installed. Install it with: `brew install gh` (macOS) or see https://cli.github.com |
 | `no_internet` | Cannot reach GitHub. Check your internet connection and try again. |
-| `repo_not_found` | Repository `kkudumu/ftm-brain` not found. Verify you have access to the repository. |
+| `repo_not_found` | Repository `kkudumu/ftm-skills` not found. Verify you have access to the repository. |
 | `no_releases_found` | No releases found in the repository yet. Check back later. |
 | any other reason | Version check failed: `<reason>`. Try running manually: `bash ~/.claude/skills/ftm-upgrade/scripts/check-version.sh` |
 
@@ -148,9 +148,9 @@ Map `CHECK_FAILED <reason>` codes to user-facing messages:
 | `~/.claude/skills/ftm-upgrade/scripts/check-version.sh` | Query GitHub for latest release, cache result 60 min |
 | `~/.claude/skills/ftm-upgrade/scripts/upgrade.sh` | Download and install latest release |
 
-**Cache location**: `~/.cache/ftm-brain/version-check`
+**Cache location**: `~/.cache/ftm-skills/version-check`
 **Version file**: `~/.claude/skills/ftm-version.txt`
-**Repo**: `kkudumu/ftm-brain`
+**Repo**: `kkudumu/ftm-skills`
 
 ## Requirements
 

package/hooks/ftm-blackboard-enforcer.sh

@@ -14,6 +14,7 @@
 
 set -euo pipefail
 
+# shellcheck disable=SC2034
 INPUT=$(cat)
 
 STATE_DIR="$HOME/.claude/ftm-state"

package/install.sh

@@ -117,7 +117,12 @@ for dir in "$REPO_DIR"/ftm*/; do
   echo "  LINK $name/"
 done
 
-SKILL_COUNT=$(ls "$REPO_DIR"/ftm*.yml 2>/dev/null | grep -v '.default.' | wc -l | tr -d ' ')
+SKILL_COUNT=0
+for _f in "$REPO_DIR"/ftm*.yml; do
+  [ -e "$_f" ] || continue
+  case "$_f" in *.default.*) continue ;; esac
+  SKILL_COUNT=$((SKILL_COUNT + 1))
+done
 echo ""
 echo "  $SKILL_COUNT skills linked."
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feed-the-machine",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "A unified intelligence layer for Claude Code — 22 skills with OODA-based reasoning, persistent memory, multi-model deliberation, and optional operator cockpit inbox",
   "license": "MIT",
   "author": "kkudumu",