cadence-skill-installer 0.2.37 → 0.2.39

package/README.md

@@ -12,6 +12,7 @@ The installer shows a multi-select prompt (comma-separated choices) so you can i
 If a selected tool already has Cadence installed, the installer prints an update notice and warns that files will be overwritten.
 In TTY terminals, selection is a real interactive TUI: use arrow keys (or `j`/`k`) to move, `space` to toggle, `a` to toggle all, and `enter` to confirm.
 The TUI includes color highlighting and a large ASCII `CADANCE` header.
+Before copying skill files, the installer checks for `python3`; if missing, it warns and offers to install Python 3 using a detected system package manager.
 
 ## Non-interactive examples
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cadence-skill-installer",
-  "version": "0.2.37",
+  "version": "0.2.39",
   "description": "Install the Cadence skill into supported AI tool skill directories.",
   "repository": "https://github.com/snowdamiz/cadence",
   "private": false,

package/scripts/install-cadence-skill.mjs

@@ -4,6 +4,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import readline from "node:readline/promises";
+import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { stdin as input, stdout as output } from "node:process";
 
@@ -106,7 +107,11 @@ function printHelp(binName, installerVersion) {
       "  --all                  Install to all supported tools.",
       "  --yes                  Skip confirmation prompt.",
       "  --home <path>          Override home directory for destination paths.",
-      "  --help                 Show this message."
+      "  --help                 Show this message.",
+      "",
+      "Prerequisite:",
+      "  python3 is required for Cadence workflow scripts. Installer preflight checks",
+      "  python3 and can offer installation guidance in interactive runs."
     ].join("\n") + "\n"
   );
 }
@@ -154,6 +159,150 @@ function parseArgs(argv) {
   return parsed;
 }
 
+function isCommandAvailable(command) {
+  if (process.platform === "win32") {
+    const result = spawnSync("where", [command], { stdio: "ignore" });
+    return result.status === 0;
+  }
+
+  const result = spawnSync("sh", ["-lc", `command -v ${command}`], { stdio: "ignore" });
+  return result.status === 0;
+}
+
+function withOptionalSudo(command, args) {
+  const display = `${command} ${args.join(" ")}`.trim();
+  if (process.platform === "win32") {
+    return { command, args, display };
+  }
+
+  const isRoot = typeof process.getuid === "function" && process.getuid() === 0;
+  if (isRoot || !isCommandAvailable("sudo")) {
+    return { command, args, display };
+  }
+
+  return {
+    command: "sudo",
+    args: [command, ...args],
+    display: `sudo ${display}`
+  };
+}
+
+function detectPythonInstallCommand() {
+  if (process.platform === "darwin") {
+    if (isCommandAvailable("brew")) {
+      return {
+        command: "brew",
+        args: ["install", "python"],
+        display: "brew install python"
+      };
+    }
+    return null;
+  }
+
+  if (process.platform === "linux") {
+    if (isCommandAvailable("apt-get")) {
+      return withOptionalSudo("apt-get", ["install", "-y", "python3"]);
+    }
+    if (isCommandAvailable("dnf")) {
+      return withOptionalSudo("dnf", ["install", "-y", "python3"]);
+    }
+    if (isCommandAvailable("yum")) {
+      return withOptionalSudo("yum", ["install", "-y", "python3"]);
+    }
+    if (isCommandAvailable("pacman")) {
+      return withOptionalSudo("pacman", ["-Sy", "--noconfirm", "python"]);
+    }
+    return null;
+  }
+
+  if (process.platform === "win32") {
+    if (isCommandAvailable("winget")) {
+      return {
+        command: "winget",
+        args: ["install", "-e", "--id", "Python.Python.3.12"],
+        display: "winget install -e --id Python.Python.3.12"
+      };
+    }
+    if (isCommandAvailable("choco")) {
+      return {
+        command: "choco",
+        args: ["install", "-y", "python"],
+        display: "choco install -y python"
+      };
+    }
+    return null;
+  }
+
+  return null;
+}
+
+async function confirmPythonInstall(commandDisplay) {
+  const rl = readline.createInterface({ input, output });
+  try {
+    const answer = await rl.question(
+      style(
+        `Python 3 is required and not detected. Install now using "${commandDisplay}"? [y/N]: `,
+        ANSI.bold,
+        ANSI.white
+      )
+    );
+    const normalized = answer.trim().toLowerCase();
+    return normalized === "y" || normalized === "yes";
+  } finally {
+    rl.close();
+  }
+}
+
+async function ensurePythonInstalled(parsed) {
+  if (isCommandAvailable("python3")) {
+    return;
+  }
+
+  output.write(
+    style(
+      "\nWarning: python3 is missing. Cadence workflow scripts require Python 3.\n",
+      ANSI.bold,
+      ANSI.brightYellow
+    )
+  );
+
+  const installCommand = detectPythonInstallCommand();
+  if (!installCommand) {
+    throw new Error(
+      "python3 is missing and no supported automatic installer was detected. Install Python 3 manually, then rerun cadence-skill-installer."
+    );
+  }
+
+  const canPrompt = input.isTTY && output.isTTY && !parsed.yes;
+  if (!canPrompt) {
+    throw new Error(
+      `python3 is missing. Re-run installer interactively to allow automatic installation with: ${installCommand.display}`
+    );
+  }
+
+  const installApproved = await confirmPythonInstall(installCommand.display);
+  if (!installApproved) {
+    throw new Error("python3 is required. Install Python 3 and rerun cadence-skill-installer.");
+  }
+
+  output.write(style(`\nInstalling Python 3 via: ${installCommand.display}\n`, ANSI.bold, ANSI.brightCyan));
+  const installResult = spawnSync(installCommand.command, installCommand.args, {
+    stdio: "inherit"
+  });
+
+  if (installResult.error) {
+    throw new Error(`Failed to run Python installer command: ${installResult.error.message}`);
+  }
+  if (installResult.status !== 0) {
+    throw new Error("Python installation command failed.");
+  }
+  if (!isCommandAvailable("python3")) {
+    throw new Error("Python installation completed, but python3 is still not detected on PATH.");
+  }
+
+  output.write(style("Python 3 detected. Continuing installation.\n", ANSI.bold, ANSI.brightGreen));
+}
+
 async function readInstallerVersion() {
   try {
     const raw = await fs.readFile(PACKAGE_JSON_PATH, "utf8");
@@ -583,6 +732,8 @@ async function main() {
     return;
   }
 
+  await ensurePythonInstalled(parsed);
+
   const homeDir = parsed.home || os.homedir();
   const sourceDir = resolveSourceDir();
   await ensureSourceDir(sourceDir);

package/skill/scripts/run-prerequisite-gate.py

@@ -3,7 +3,6 @@
 
 import argparse
 import json
-import shutil
 import subprocess
 import sys
 from pathlib import Path
@@ -14,6 +13,13 @@ from project_root import resolve_project_root, write_project_root_hint
 SCRIPT_DIR = Path(__file__).resolve().parent
 RESOLVE_SCRIPT = SCRIPT_DIR / "resolve-project-scripts-dir.py"
 ROUTE_GUARD_SCRIPT = SCRIPT_DIR / "assert-workflow-route.py"
+REQUIRED_RUNTIME_ASSETS = (
+    "handle-prerequisite-state.py",
+    "read-workflow-state.py",
+    "set-workflow-item-status.py",
+    "finalize-skill-checkpoint.py",
+    "workflow_state.py",
+)
 
 
 def run_command(command):
@@ -76,6 +82,21 @@ def resolve_scripts_dir(project_root: Path):
     return scripts_dir
 
 
+def assert_runtime_assets(scripts_dir: str):
+    scripts_path = Path(scripts_dir)
+    missing: list[str] = []
+    for asset in REQUIRED_RUNTIME_ASSETS:
+        if not (scripts_path / asset).is_file():
+            missing.append(asset)
+
+    if missing:
+        print(
+            "MISSING_CADENCE_RUNTIME_ASSET:" + ",".join(sorted(missing)),
+            file=sys.stderr,
+        )
+        raise SystemExit(1)
+
+
 def read_prerequisite_state(scripts_dir, project_root: Path):
     script_path = Path(scripts_dir) / "handle-prerequisite-state.py"
     result = run_command(
@@ -139,18 +160,33 @@ def main():
         scripts_dir = str(scripts_path)
     else:
         scripts_dir = resolve_scripts_dir(project_root)
+    assert_runtime_assets(scripts_dir)
     state = read_prerequisite_state(scripts_dir, project_root)
 
     if state == "true":
-        print(json.dumps({"status": "ok", "prerequisites_pass": True, "source": "cache"}))
+        print(
+            json.dumps(
+                {
+                    "status": "ok",
+                    "prerequisites_pass": True,
+                    "source": "cache",
+                    "runtime_assets": "ok",
+                }
+            )
+        )
         return
 
-    if shutil.which("python3") is None:
-        print("MISSING_PYTHON3", file=sys.stderr)
-        raise SystemExit(1)
-
     write_prerequisite_state(scripts_dir, "1", project_root)
-    print(json.dumps({"status": "ok", "prerequisites_pass": True, "source": "fresh-check"}))
+    print(
+        json.dumps(
+            {
+                "status": "ok",
+                "prerequisites_pass": True,
+                "source": "fresh-check",
+                "runtime_assets": "ok",
+            }
+        )
+    )
 
 
 if __name__ == "__main__":

package/skill/skills/brownfield-documenter/SKILL.md

@@ -60,3 +60,28 @@ description: Perform deep evidence-based analysis of an existing codebase and pe
 15. If `finalize-skill-checkpoint.py` returns `status=no_changes`, continue without failure.
 16. If `finalize-skill-checkpoint.py` reports an error, stop and surface it verbatim.
 17. In normal user-facing updates, report brownfield findings and persisted ideation outcomes without raw command traces or internal routing details unless explicitly requested.
+
+## Strict Response Format
+
+- If clarification is required before persistence, respond exactly:
+
+  ```text
+  Brownfield documentation in progress:
+
+  - Missing detail: <single highest-leverage gap>
+  - Question: <one focused question>
+  ```
+
+- On successful persistence, respond exactly in this shape:
+
+  ```text
+  Brownfield documentation captured:
+  
+  - Objective: <objective summary>
+  - Core outcome: <core outcome summary>
+  - Research agenda: blocks=<block_count>, topics=<topic_count>, entities=<entity_count>
+  - Payload repairs: <none|count + short description>
+  - Checkpoint: brownfield-documenter/documentation-captured (<ok|no_changes>)
+
+  Start a new chat with a new agent and say "cadence, research my project".
+  ```

package/skill/skills/brownfield-documenter/agents/openai.yaml

@@ -6,6 +6,7 @@ interface:
     Run scripts/run-skill-entry-gate.py --require-cadence, then use its JSON output for PROJECT_ROOT
     (project_root), CADENCE_SCRIPTS_DIR (cadence_scripts_dir), and push/local-only mode (repo_enabled).
     Never edit .cadence/cadence.json manually.
+    Enforce the strict user-facing response templates from skills/brownfield-documenter/SKILL.md.
     Run scripts/run-brownfield-documentation.py --project-root "$PROJECT_ROOT" discover, perform evidence-based
     analysis, then persist with scripts/run-brownfield-documentation.py --project-root "$PROJECT_ROOT" complete --stdin.
     Require a research_agenda with at least one topic, verify with scripts/get-ideation.py, and mention

package/skill/skills/brownfield-intake/SKILL.md

@@ -27,3 +27,33 @@ description: Classify project mode (greenfield vs brownfield) and capture a dete
 11. If `finalize-skill-checkpoint.py` returns `status=no_changes`, continue without failure.
 12. If `finalize-skill-checkpoint.py` reports an error, stop and surface it verbatim.
 13. In normal user-facing updates, report mode decision and baseline outcome without raw command traces or internal routing details unless explicitly requested.
+
+## Strict Response Format
+
+- If resulting mode is `brownfield`, respond exactly in this shape:
+
+  ```text
+  Brownfield intake result:
+
+  - Mode: brownfield (source: <mode_source>; detected: <detected_mode>)
+  - Repository scale: files=<file_count>, directories=<directory_count>
+  - Tooling manifests: <count>
+  - CI workflows: <count>
+  - Monorepo signal: <yes|no>
+  - Checkpoint: brownfield-intake/baseline-captured (<ok|no_changes>)
+
+  Start a new chat and say "cadence, document my existing project".
+  ```
+
+- If resulting mode is `greenfield`, respond exactly in this shape:
+
+  ```text
+  Brownfield intake result:
+  
+  - Mode: greenfield (source: <mode_source>; detected: <detected_mode>)
+  - Baseline capture: skipped (clean repository)
+  - Checkpoint: brownfield-intake/baseline-captured (<ok|no_changes>)
+  - Next step: Continue with ideation.
+
+   Start a new chat and say "cadence, help define my project".
+  ```

package/skill/skills/brownfield-intake/agents/openai.yaml

@@ -6,6 +6,7 @@ interface:
     Run scripts/run-skill-entry-gate.py --require-cadence, then use its JSON output for PROJECT_ROOT
     (project_root), CADENCE_SCRIPTS_DIR (cadence_scripts_dir), and push/local-only mode (repo_enabled).
     Never edit .cadence/cadence.json manually.
+    Enforce the strict user-facing response templates from skills/brownfield-intake/SKILL.md.
     Run scripts/run-brownfield-intake.py --project-root "$PROJECT_ROOT" --project-mode auto.
     Do not ask the user to choose mode up front; clean repositories should resolve to greenfield automatically.
     If the user explicitly asks to force a mode, rerun with --project-mode <greenfield|brownfield>.

package/skill/skills/ideation-updater/SKILL.md

@@ -65,3 +65,43 @@ description: Discuss, audit, and update existing project ideation in .cadence/ca
 18. If `finalize-skill-checkpoint.py` returns `status=no_changes`, continue without failure.
 19. If `finalize-skill-checkpoint.py` reports an error, stop and surface it verbatim.
 20. Ask whether to continue refining another aspect or stop.
+
+## Strict Response Format
+
+- In discussion-only mode (no persistence), respond exactly in this shape:
+
+  ```text
+  Ideation discussion update:
+
+  - Focus area: <current focus>
+  - Tradeoff summary: <short recommendation or options>
+
+  Next question: <exactly one question>
+  ```
+
+- Before persistence, respond exactly in this shape:
+
+  ```text
+  Proposed ideation update:
+
+  - Add: <fields>
+  - Update: <fields>
+  - Remove: <fields>
+  - Unchanged: <fields>
+  - Research impact: blocks=<count>, topics=<count>, entities=<count>
+  
+  Confirmation needed: Persist these ideation updates? (yes/no)
+  ```
+
+- After successful persistence, respond exactly in this shape:
+
+  ```text
+  Ideation update captured:
+
+  - Updated fields: <summary>
+  - Research agenda: blocks=<block_count>, topics=<topic_count>, entities=<entity_count>
+  - Research execution: reset for replanning
+  - Checkpoint: ideation-updater/ideation-updated (<ok|no_changes>)
+
+  Next action: Continue refining another aspect? (yes/no)
+  ```

package/skill/skills/ideation-updater/agents/openai.yaml

@@ -6,6 +6,7 @@ interface:
     Run scripts/run-skill-entry-gate.py --require-cadence, then use its JSON output for PROJECT_ROOT
     (project_root), CADENCE_SCRIPTS_DIR (cadence_scripts_dir), and push/local-only mode (repo_enabled).
     Never edit .cadence/cadence.json manually.
+    Enforce the strict user-facing response templates from skills/ideation-updater/SKILL.md.
     Review current ideation, discuss updates, rebuild the full ideation object with synchronized research_agenda,
     then run scripts/prepare-ideation-research.py and scripts/inject-ideation.py from PROJECT_ROOT.
     If the user is starting from scratch, hand off with:

package/skill/skills/ideator/SKILL.md

@@ -86,3 +86,42 @@ description: Guide users from a rough concept to a fully defined project idea th
 22. If `finalize-skill-checkpoint.py` returns `status=no_changes`, continue without failure.
 23. If `finalize-skill-checkpoint.py` reports an error, stop and surface it verbatim.
 24. If the user requests revisions later, regenerate the payload, rerun `prepare-ideation-research.py`, and rerun `inject-ideation.py` from `PROJECT_ROOT`.
+
+## Strict Response Format
+
+- During discovery turns (before final confirmation), respond exactly in this shape:
+
+  ```text
+  Ideation progress:
+
+  - Understanding update: <one sentence>
+
+  Next question: <exactly one question>
+  ```
+
+- When presenting final pre-persistence confirmation, respond exactly in this shape:
+
+  ```text
+  Proposed ideation package:
+
+  - Objective: <summary>
+  - Core outcome: <summary>
+  - Audience: <summary>
+  - Scope: in=<count>, out=<count>
+  - Research agenda: blocks=<block_count>, topics=<topic_count>, entities=<entity_count>
+  
+  Confirmation needed: Persist this ideation package? (yes/no)
+  ```
+
+- On successful persistence, respond exactly in this shape:
+
+  ```text
+  Ideation captured:
+
+  - Objective: <summary>
+  - Core outcome: <summary>
+  - Research agenda: blocks=<block_count>, topics=<topic_count>, entities=<entity_count>
+  - Checkpoint: ideator/ideation-completed (<ok|no_changes>)
+
+  Start a new chat with a new agent and say "cadence, research my project".
+  ```

package/skill/skills/ideator/agents/openai.yaml

@@ -7,6 +7,7 @@ interface:
     output for PROJECT_ROOT (project_root), CADENCE_SCRIPTS_DIR (cadence_scripts_dir), and push/local-only mode
     (repo_enabled).
     Never edit .cadence/cadence.json manually.
+    Enforce the strict user-facing response templates from skills/ideator/SKILL.md.
     Ask one question at a time, build an execution-ready ideation object and complete research_agenda,
     then from PROJECT_ROOT rerun route assertion, run scripts/prepare-ideation-research.py,
     and persist with scripts/inject-ideation.py.

package/skill/skills/planner/SKILL.md

@@ -27,3 +27,31 @@ description: Create a greenfield project roadmap from cadence ideation and resea
 9. If `finalize-skill-checkpoint.py` returns `status=no_changes`, continue without failure.
 10. If `finalize-skill-checkpoint.py` reports an error, stop and surface it verbatim.
 11. In normal user-facing updates, report roadmap outcomes without raw command traces or internal routing details unless explicitly requested.
+
+## Strict Response Format
+
+- Before persistence confirmation, respond exactly in this shape:
+
+  ```text
+  Proposed roadmap:
+
+  - Milestones: <milestone_count>
+  - Phases: <phase_count>
+  - Detail level: milestone_phase_v1
+  - Key assumptions: <count or "none">
+  
+  Confirmation needed: Persist this roadmap? (yes/no)
+  ```
+
+- After successful persistence, respond exactly in this shape:
+
+  ```text
+  Roadmap captured:
+
+  - Milestones: <milestone_count>
+  - Phases: <phase_count>
+  - Detail level: milestone_phase_v1
+  - Checkpoint: planner/plan-created (<ok|no_changes>)
+  
+  Next route: <skill_name or "workflow complete">
+  ```

package/skill/skills/planner/agents/openai.yaml

@@ -7,6 +7,7 @@ interface:
     for PROJECT_ROOT (project_root), CADENCE_SCRIPTS_DIR (cadence_scripts_dir), and push/local-only mode
     (repo_enabled).
     Never edit .cadence/cadence.json manually.
+    Enforce the strict user-facing response templates from skills/planner/SKILL.md.
     Gather context with scripts/run-planner.py --project-root "$PROJECT_ROOT" discover, then draft and confirm a
     roadmap containing milestones and phases only (no waves/tasks) using detail_level milestone_phase_v1.
     Persist with scripts/run-planner.py --project-root "$PROJECT_ROOT" complete --stdin.

package/skill/skills/prerequisite-gate/SKILL.md

@@ -1,21 +1,47 @@
 ---
 name: prerequisite-gate
-description: Run and persist Cadence prerequisite checks for Python availability. Use when Cadence starts work after scaffolding and must confirm prerequisites before lifecycle or delivery commands.
+description: Run and persist Cadence runtime prerequisite checks. Use when Cadence starts work after scaffolding and must confirm required Cadence runtime assets before lifecycle or delivery commands.
 ---
 
 # Prerequisite Gate
 
 1. Run this only after scaffold routing from `skills/scaffold/SKILL.md`.
    - Never manually edit `.cadence/cadence.json`; all Cadence state writes must go through Cadence scripts.
+   - Do not run Python interpreter availability checks in this workflow gate; installer-time preflight owns that check.
 2. Run shared skill entry gates once at conversation start:
    - `python3 ../../scripts/run-skill-entry-gate.py --require-cadence`
    - Parse JSON and store `PROJECT_ROOT` from `project_root`, `CADENCE_SCRIPTS_DIR` from `cadence_scripts_dir`, and push mode from `repo_enabled` (`false` means local-only commits).
 3. Run `python3 "$CADENCE_SCRIPTS_DIR/run-prerequisite-gate.py" --project-root "$PROJECT_ROOT" --scripts-dir "$CADENCE_SCRIPTS_DIR"`.
 4. `run-prerequisite-gate.py` performs workflow route assertion internally; if assertion fails, stop and surface the exact error.
-5. If the script reports `MISSING_PYTHON3`, stop and ask the user for confirmation to install prerequisites.
-6. Do not continue Cadence lifecycle or delivery execution while prerequisites are missing.
+5. If the script reports `MISSING_CADENCE_RUNTIME_ASSET:<files>`, stop and ask the user to repair/reinstall Cadence runtime files before continuing.
+6. Do not continue Cadence lifecycle or delivery execution while required runtime assets are missing.
 7. At end of this successful skill conversation, run `cd "$PROJECT_ROOT" && python3 "$CADENCE_SCRIPTS_DIR/finalize-skill-checkpoint.py" --scope prerequisite-gate --checkpoint prerequisites-passed --paths .`.
 8. If `finalize-skill-checkpoint.py` returns `status=no_changes`, continue without failure.
 9. If `finalize-skill-checkpoint.py` reports an error, stop and surface it verbatim.
 10. Surface script failures verbatim instead of adding custom fallback logic.
 11. In normal user-facing updates, share the prerequisite outcome without raw command traces or internal routing details unless explicitly requested.
+
+## Strict Response Format
+
+- If `MISSING_CADENCE_RUNTIME_ASSET:<files>` is returned, respond exactly:
+
+  ```text
+  Prerequisite status:
+
+  - Cadence runtime assets: missing
+  - Cadence prerequisite gate: not passed
+  
+  Action required: repair or reinstall Cadence skill files, then rerun the prerequisite gate.
+  ```
+
+- On successful prerequisite completion, respond exactly:
+
+  ```text
+  Prerequisite gate complete:
+
+  - Cadence runtime assets: available
+  - Cadence prerequisite gate: passed
+  - Checkpoint: prerequisite-gate/prerequisites-passed (<ok|no_changes>)
+  
+  Next step: Run project mode and baseline intake.
+  ```

package/skill/skills/prerequisite-gate/agents/openai.yaml

@@ -1,11 +1,12 @@
 interface:
   display_name: "Prerequisite Gate"
-  short_description: "Run and persist Cadence prerequisite checks for Python availability"
+  short_description: "Run and persist Cadence runtime prerequisite checks"
   default_prompt: >-
     Follow skills/prerequisite-gate/SKILL.md for exact gate behavior.
     Run scripts/run-skill-entry-gate.py --require-cadence, then use its JSON output for PROJECT_ROOT
     (project_root), CADENCE_SCRIPTS_DIR (cadence_scripts_dir), and push/local-only mode (repo_enabled).
     Never edit .cadence/cadence.json manually.
+    Enforce the strict user-facing response templates from skills/prerequisite-gate/SKILL.md.
     Run scripts/run-prerequisite-gate.py --project-root "$PROJECT_ROOT" --scripts-dir "$CADENCE_SCRIPTS_DIR".
     Finalize from PROJECT_ROOT with scripts/finalize-skill-checkpoint.py --scope prerequisite-gate
     --checkpoint prerequisites-passed --paths . (allow status=no_changes; treat failures as blocking).

package/skill/skills/project-progress/SKILL.md

@@ -9,10 +9,19 @@ description: Read and route project lifecycle progress from .cadence/cadence.jso
    - `python3 ../../scripts/run-skill-entry-gate.py --require-cadence --include-workflow-state`
    - Parse JSON and store `PROJECT_ROOT` from `project_root`, `CADENCE_SCRIPTS_DIR` from `cadence_scripts_dir`, push mode from `repo_enabled` (`false` means local-only commits), and workflow payload from `workflow_state`.
    - Never manually edit `.cadence/cadence.json`; all Cadence state writes must go through Cadence scripts.
-2. Always report current progress first:
+2. Always report current progress first with route-aware formatting:
    - current phase title
-   - completion summary (completed vs total actionable items, percent)
    - what comes next
+   - If `workflow_state.route.skill_name` is `researcher` (or `workflow_state.next_item.id` is `task-research`):
+     - Run `python3 "$CADENCE_SCRIPTS_DIR/run-research-pass.py" --project-root "$PROJECT_ROOT" status`.
+     - Report research progress only from that output:
+       - topics complete vs total
+       - topics needing follow-up
+       - topics pending
+       - completed passes vs pending passes
+       - next pass id (if present)
+     - Do not show global workflow completion counts/percent in this mode unless the user explicitly asks for full workflow metrics.
+   - Otherwise, report completion summary (completed vs total actionable items, percent).
 3. Interpret user intent:
    - If the user only asks status, answer with progress and stop.
    - If the user asks to continue or resume, answer with progress and then route using `workflow_state.route.skill_path` from the entry gate payload.
@@ -21,8 +30,54 @@ description: Read and route project lifecycle progress from .cadence/cadence.jso
    - If `route.skill_path` is present, invoke that skill.
    - If route skill is `researcher`, keep execution to one pass per conversation and follow researcher handoff behavior between passes.
    - If no route is present for a non-complete item, ask the user what action they want for that item.
-5. If `run-skill-entry-gate.py` errors (including workflow read failures), surface the script error verbatim and stop.
-6. At end of this successful skill conversation, run `cd "$PROJECT_ROOT" && python3 "$CADENCE_SCRIPTS_DIR/finalize-skill-checkpoint.py" --scope project-progress --checkpoint progress-checked --paths .`.
-7. If `finalize-skill-checkpoint.py` returns `status=no_changes`, continue without failure.
-8. If `finalize-skill-checkpoint.py` reports an error, stop and surface it verbatim.
-9. Do not expose raw workflow IDs, route paths, or execution traces in user-facing replies unless the user explicitly asks for internals.
+5. If `workflow_state.route.skill_name` is `researcher` and `run-research-pass.py status` fails, surface the script error verbatim and stop.
+6. If `run-skill-entry-gate.py` errors (including workflow read failures), surface the script error verbatim and stop.
+7. At end of this successful skill conversation, run `cd "$PROJECT_ROOT" && python3 "$CADENCE_SCRIPTS_DIR/finalize-skill-checkpoint.py" --scope project-progress --checkpoint progress-checked --paths .`.
+8. If `finalize-skill-checkpoint.py` returns `status=no_changes`, continue without failure.
+9. If `finalize-skill-checkpoint.py` reports an error, stop and surface it verbatim.
+10. Do not expose raw workflow IDs, route paths, or execution traces in user-facing replies unless the user explicitly asks for internals.
+
+## Strict Response Format
+
+- If routing is `researcher`, respond exactly in this shape:
+
+  ```text
+  Research progress:
+  
+  - Current phase: <phase_title>
+  - Topics complete: <topic_complete>/<topic_total>
+  - Topics needing follow-up: <topic_needs_followup>
+  - Topics pending: <topic_pending>
+  - Passes complete: <pass_complete>
+  - Passes pending: <pass_pending>
+  - Next pass: <next_pass_id or "none">
+  - Next route: researcher
+
+  Start a new chat and say "cadence, plan my project".
+  ```
+
+  - If the user asked to continue/resume and more passes remain, append this exact line:
+    - `Start a new chat and say "continue research".`
+
+- If routing is not `researcher`, respond exactly in this shape:
+
+  ```text
+  Workflow progress:
+
+  - Current phase: <phase_title>
+  - Completion: <completed_actionable_items>/<total_actionable_items> (<completion_percent>%)
+  - Next item: <next_item_title>
+  - Next route: <route_skill_name or "none">
+
+  Start a new chat and say "cadence, research my project".
+  ```
+
+- If workflow is complete, respond exactly:
+
+  ```text
+  Workflow progress:
+
+  - Current phase: Workflow Complete
+  - Completion: 100%
+  - Status: All currently tracked workflow items are complete.
+  ```

package/skill/skills/project-progress/agents/openai.yaml

@@ -7,7 +7,11 @@ interface:
     PROJECT_ROOT (project_root), CADENCE_SCRIPTS_DIR (cadence_scripts_dir), push/local-only mode (repo_enabled),
     and workflow payload (workflow_state).
     Never edit .cadence/cadence.json manually.
+    Enforce the strict user-facing response templates from skills/project-progress/SKILL.md.
     Summarize progress in user-facing terms and for continue/resume requests route via workflow_state.route.
+    When workflow_state.route.skill_name is researcher (or next_item.id is task-research), run
+    scripts/run-research-pass.py --project-root "$PROJECT_ROOT" status and report only research progress;
+    omit global workflow completion counts/percent unless the user explicitly asks for full workflow metrics.
     If routed to researcher and more passes remain, use:
     Start a new chat and say "continue research".
     Finalize from PROJECT_ROOT with scripts/finalize-skill-checkpoint.py --scope project-progress

package/skill/skills/researcher/SKILL.md

@@ -34,7 +34,86 @@ description: Execute ideation research agenda topics through dynamic multi-pass
    - Run `python3 "$CADENCE_SCRIPTS_DIR/read-workflow-state.py" --project-root "$PROJECT_ROOT"` and inspect `route.skill_name`.
    - If `route.skill_name` is `planner`, end with this exact handoff line: `Start a new chat and say "plan my project".`
    - If workflow is complete, report that research and currently tracked workflow items are complete.
-10. At end of this successful skill conversation, run `cd "$PROJECT_ROOT" && python3 "$CADENCE_SCRIPTS_DIR/finalize-skill-checkpoint.py" --scope researcher --checkpoint research-pass-recorded --paths .`.
-11. If `finalize-skill-checkpoint.py` returns `status=no_changes`, continue without failure.
-12. If `finalize-skill-checkpoint.py` reports an error, stop and surface it verbatim.
-13. Surface script failures verbatim and do not expose internal command traces unless explicitly requested.
+10. Strict user-facing return format is required for all successful runs. Use the exact section order below and fill values from script output (and the just-submitted pass payload where applicable):
+   - If `complete` returns `handoff_required=true`, respond exactly in this structure, then stop:
+
+     ```text
+     Pass recorded:
+
+     - Pass ID: <pass_id>
+     - Pass summary: <pass_summary>
+
+     Topic outcomes:
+
+     - <topic_id>: <status>; confidence=<confidence>; unresolved_questions=<count>
+     - <topic_id>: <status>; confidence=<confidence>; unresolved_questions=<count>
+
+     Research progress:
+
+     - Topics complete: <topic_complete>/<topic_total>
+     - Topics needing follow-up: <topic_needs_followup>
+     - Topics pending: <topic_pending>
+     - Passes complete: <pass_complete>
+     - Passes pending: <pass_pending>
+     - Next pass: <next_pass_id or "none">
+
+     Start a new chat and say "cadence, continue research".
+     ```
+
+   - If `complete` returns `research_complete=true` and route advances to planner, respond exactly:
+
+     ```text
+     Pass recorded:
+
+     - Pass ID: <pass_id>
+     - Pass summary: <pass_summary>
+
+     Research progress:
+
+     - Topics complete: <topic_complete>/<topic_total>
+     - Topics needing follow-up: <topic_needs_followup>
+     - Topics pending: <topic_pending>
+     - Passes complete: <pass_complete>
+     - Passes pending: <pass_pending>
+
+     Start a new chat and say "cadence, plan my project".
+     ```
+
+   - If `complete` returns `research_complete=true` and workflow is complete, respond exactly:
+
+     ```text
+     Pass recorded:
+
+     - Pass ID: <pass_id>
+     - Pass summary: <pass_summary>
+
+     Research progress:
+
+     - Topics complete: <topic_complete>/<topic_total>
+     - Topics needing follow-up: <topic_needs_followup>
+     - Topics pending: <topic_pending>
+     - Passes complete: <pass_complete>
+     - Passes pending: <pass_pending>
+
+     Research and currently tracked workflow items are complete.
+     ```
+
+   - If `start` returns `research_complete=true`, do not run a pass; respond exactly:
+
+     ```text
+     Research progress:
+     
+     - Topics complete: <topic_complete>/<topic_total>
+     - Topics needing follow-up: <topic_needs_followup>
+     - Topics pending: <topic_pending>
+     - Passes complete: <pass_complete>
+     - Passes pending: <pass_pending>
+
+     Research is already complete.
+     ```
+
+11. At end of this successful skill conversation, run `cd "$PROJECT_ROOT" && python3 "$CADENCE_SCRIPTS_DIR/finalize-skill-checkpoint.py" --scope researcher --checkpoint research-pass-recorded --paths .`.
+12. If `finalize-skill-checkpoint.py` returns `status=no_changes`, continue without failure.
+13. If `finalize-skill-checkpoint.py` reports an error, stop and surface it verbatim.
+14. Surface script failures verbatim and do not expose internal command traces unless explicitly requested.
+15. For successful runs, do not add extra prose before or after the strict templates in this file.

package/skill/skills/researcher/agents/openai.yaml

@@ -9,7 +9,10 @@ interface:
     Never edit .cadence/cadence.json manually.
     Run exactly one pass per chat: scripts/run-research-pass.py start, research only that pass's topics,
     then persist with scripts/run-research-pass.py complete. Do not run a second pass in the same chat.
-    If more work remains, end with: Start a new chat and say "continue research".
+    Enforce the strict user-facing return templates defined in skills/researcher/SKILL.md for every successful run,
+    and do not add extra prose outside those templates.
+    If more work remains, include the full required response sections and end with:
+    Start a new chat and say "continue research".
     If research is complete and route advances to planner, end with:
     Start a new chat and say "plan my project".
     Finalize from PROJECT_ROOT with scripts/finalize-skill-checkpoint.py --scope researcher

package/skill/skills/scaffold/SKILL.md

@@ -37,3 +37,30 @@ description: Initialize Cadence project scaffolding for first-time setup. Use wh
 13. If `finalize-skill-checkpoint.py` reports an error, stop and surface it verbatim.
 14. Execute scaffold actions serially. Do not run this flow in parallel with other setup gates.
 15. In user-facing replies, summarize only the result. Do not expose internal command lines, skill chains, or execution traces unless explicitly requested.
+
+## Strict Response Format
+
+- For decision-required turns, respond exactly in this shape:
+
+  ```text
+  Scaffold status:
+
+  - Project root: <PROJECT_ROOT>
+  - Cadence initialized: <yes|no>
+  - Repo mode: <remote-enabled|local-only|pending>
+
+  Decision needed: <one required decision>
+  ```
+
+- For successful completion, respond exactly in this shape:
+
+  ```text
+  Scaffold complete:
+
+  - Project root: <PROJECT_ROOT>
+  - Cadence state: initialized
+  - Repo mode: <remote-enabled|local-only>
+  - .cadence git policy: <tracked|ignored>
+  - Checkpoint: scaffold/<cadence-tracked|cadence-ignored> (<ok|no_changes>)
+  - Next step: Run prerequisite gate.
+  ```

package/skill/skills/scaffold/agents/openai.yaml

@@ -10,6 +10,7 @@ interface:
     For .cadence policy updates, run scripts/configure-cadence-gitignore.py with --mode and
     --gitignore-path "$PROJECT_ROOT/.gitignore" only (do not pass --project-root).
     Never edit .cadence/cadence.json manually.
+    Enforce the strict user-facing response templates from skills/scaffold/SKILL.md.
     Only rerun repo-status after remote setup to confirm repo_enabled=true; do not run an extra write pass
     just to persist false in local-only mode.
     Finalize with scripts/finalize-skill-checkpoint.py --paths . --project-root "$PROJECT_ROOT" and the scope/checkpoint

package/skill/tests/test_run_prerequisite_gate.py

@@ -0,0 +1,89 @@
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+SCRIPTS_DIR = Path(__file__).resolve().parents[1] / "scripts"
+if str(SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIR))
+
+from workflow_state import default_data, set_workflow_item_status
+
+RUN_SCRIPT = SCRIPTS_DIR / "run-prerequisite-gate.py"
+
+
+def build_prerequisite_ready_state() -> dict:
+    data = default_data()
+    data, found = set_workflow_item_status(
+        data,
+        item_id="task-scaffold",
+        status="complete",
+        cadence_dir_exists=True,
+    )
+    if not found:
+        raise RuntimeError("Missing task-scaffold in workflow fixture")
+    return data
+
+
+class RunPrerequisiteGateTests(unittest.TestCase):
+    @staticmethod
+    def write_cadence_state(project_root: Path) -> None:
+        (project_root / ".cadence").mkdir(parents=True, exist_ok=True)
+        (project_root / ".cadence" / "cadence.json").write_text(
+            json.dumps(build_prerequisite_ready_state(), indent=4) + "\n",
+            encoding="utf-8",
+        )
+
+    def test_passes_and_reports_runtime_assets(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            project_root = Path(tmp_dir)
+            self.write_cadence_state(project_root)
+
+            result = subprocess.run(
+                [
+                    sys.executable,
+                    str(RUN_SCRIPT),
+                    "--project-root",
+                    str(project_root),
+                    "--scripts-dir",
+                    str(SCRIPTS_DIR),
+                ],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+
+            self.assertEqual(result.returncode, 0, msg=result.stderr or result.stdout)
+            payload = json.loads(result.stdout)
+            self.assertEqual(payload["status"], "ok")
+            self.assertTrue(payload["prerequisites_pass"])
+            self.assertEqual(payload["runtime_assets"], "ok")
+            self.assertIn(payload["source"], {"fresh-check", "cache"})
+
+    def test_fails_when_runtime_assets_are_missing(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp_dir, tempfile.TemporaryDirectory() as scripts_dir:
+            project_root = Path(tmp_dir)
+            self.write_cadence_state(project_root)
+
+            result = subprocess.run(
+                [
+                    sys.executable,
+                    str(RUN_SCRIPT),
+                    "--project-root",
+                    str(project_root),
+                    "--scripts-dir",
+                    scripts_dir,
+                ],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+
+            self.assertNotEqual(result.returncode, 0)
+            self.assertIn("MISSING_CADENCE_RUNTIME_ASSET", result.stderr)
+
+
+if __name__ == "__main__":
+    unittest.main()