cadence-skill-installer 0.2.6 → 0.2.7

package/package.json

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

package/skill/SKILL.md

@@ -45,6 +45,11 @@ description: Structured project operating system for end-to-end greenfield or br
 1. Invoke `skills/project-progress/SKILL.md` when the user asks to continue/resume or requests progress status (for example: "continue the project", "how far along are we?", "where did we leave off?").
 2. Use that skill's state-based routing result to continue from the correct next phase.
 
+## Manual Subskill Safety Gate
+1. If the user manually requests a Cadence subskill, run `python3 scripts/assert-workflow-route.py --skill-name <subskill>` before executing it.
+2. If route assertion fails, stop and surface the exact script error.
+3. Do not execute state-changing subskill steps when assertion fails.
+
 ## Ideation Flow
 1. Do not switch to `skills/ideator/SKILL.md` inside this conversation.
 2. After scaffold and prerequisite gates pass for a net-new project, hand off to a fresh chat so context resets cleanly.

package/skill/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Cadence"
   short_description: "Lifecycle + delivery system for structured project execution"
-  default_prompt: "Use Cadence to guide this project from lifecycle setup through phased execution, traceability, audit, and milestone completion. Always read and apply the active SOUL persona from .cadence/SOUL.json (fallback: SOUL.json). Keep user-facing responses concise and outcome-focused, and never expose internal skill-routing or command-execution traces unless the user explicitly asks. If user intent indicates resuming/continuing work or asking progress, invoke skills/project-progress/SKILL.md first, report current phase, then route to the next step. For net-new project starts, after scaffold and prerequisite gates pass, do not switch skills in-thread; tell the user: Start a new chat and either say \"help me define my project\" or share your project brief."
+  default_prompt: "Use Cadence to guide this project from lifecycle setup through phased execution, traceability, audit, and milestone completion. Always read and apply the active SOUL persona from .cadence/SOUL.json (fallback: SOUL.json). Keep user-facing responses concise and outcome-focused, and never expose internal skill-routing or command-execution traces unless the user explicitly asks. If user intent indicates resuming/continuing work or asking progress, invoke skills/project-progress/SKILL.md first, report current phase, then route to the next step. If the user manually requests a Cadence subskill, run scripts/assert-workflow-route.py with that skill name first and block state-changing execution on mismatch. For net-new project starts, after scaffold and prerequisite gates pass, do not switch skills in-thread; tell the user: Start a new chat and either say \"help me define my project\" or share your project brief."

package/skill/scripts/assert-workflow-route.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""Assert that a requested skill matches the current workflow route."""
+
+from __future__ import annotations
+
+import copy
+import json
+import sys
+from pathlib import Path
+
+from workflow_state import default_data, reconcile_workflow_state
+
+
+CADENCE_DIR = Path(".cadence")
+CADENCE_JSON_PATH = CADENCE_DIR / "cadence.json"
+
+
+def load_state() -> dict:
+    cadence_exists = CADENCE_DIR.exists()
+
+    if not CADENCE_JSON_PATH.exists():
+        data = default_data()
+        return reconcile_workflow_state(data, cadence_dir_exists=cadence_exists)
+
+    try:
+        with CADENCE_JSON_PATH.open("r", encoding="utf-8") as file:
+            original_data = json.load(file)
+    except json.JSONDecodeError as exc:
+        print(f"INVALID_CADENCE_JSON: {exc}", file=sys.stderr)
+        raise SystemExit(1)
+
+    return reconcile_workflow_state(copy.deepcopy(original_data), cadence_dir_exists=cadence_exists)
+
+
+def parse_args(argv: list[str]) -> tuple[str, bool]:
+    if not argv or len(argv) > 3:
+        print("Usage: assert-workflow-route.py --skill-name <name> [--allow-complete]", file=sys.stderr)
+        raise SystemExit(2)
+
+    skill_name = ""
+    allow_complete = False
+    idx = 0
+    while idx < len(argv):
+        token = argv[idx]
+        if token == "--skill-name":
+            if idx + 1 >= len(argv):
+                print("MISSING_SKILL_NAME", file=sys.stderr)
+                raise SystemExit(2)
+            skill_name = str(argv[idx + 1]).strip()
+            idx += 2
+            continue
+        if token == "--allow-complete":
+            allow_complete = True
+            idx += 1
+            continue
+
+        print(f"UNKNOWN_ARGUMENT: {token}", file=sys.stderr)
+        raise SystemExit(2)
+
+    if not skill_name:
+        print("MISSING_SKILL_NAME", file=sys.stderr)
+        raise SystemExit(2)
+
+    return skill_name, allow_complete
+
+
+def main() -> int:
+    requested_skill, allow_complete = parse_args(sys.argv[1:])
+    data = load_state()
+
+    workflow = data.get("workflow", {})
+    next_item = workflow.get("next_item", {})
+    next_route = workflow.get("next_route", {})
+
+    next_item_id = str(next_item.get("id", "complete")).strip() or "complete"
+    next_item_title = str(next_item.get("title", next_item_id)).strip() or next_item_id
+    expected_skill = str(next_route.get("skill_name", "")).strip()
+
+    if next_item_id == "complete" and not allow_complete:
+        print("WORKFLOW_ALREADY_COMPLETE", file=sys.stderr)
+        return 2
+
+    if next_item_id != "complete" and expected_skill != requested_skill:
+        expected = expected_skill or "none"
+        print(
+            (
+                "WORKFLOW_ROUTE_MISMATCH: "
+                f"expected={expected} "
+                f"requested={requested_skill} "
+                f"next_item={next_item_id}"
+            ),
+            file=sys.stderr,
+        )
+        return 2
+
+    print(
+        json.dumps(
+            {
+                "status": "ok",
+                "requested_skill": requested_skill,
+                "expected_skill": expected_skill,
+                "next_item_id": next_item_id,
+                "next_item_title": next_item_title,
+                "workflow_complete": next_item_id == "complete",
+            }
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skill/scripts/inject-ideation.py

@@ -3,6 +3,7 @@
 
 import argparse
 import json
+import subprocess
 import sys
 from pathlib import Path
 
@@ -10,6 +11,19 @@ from workflow_state import default_data, reconcile_workflow_state
 
 
 CADENCE_JSON_PATH = Path(".cadence") / "cadence.json"
+SCRIPT_DIR = Path(__file__).resolve().parent
+ROUTE_GUARD_SCRIPT = SCRIPT_DIR / "assert-workflow-route.py"
+
+
+def run_command(command):
+    return subprocess.run(command, capture_output=True, text=True, check=False)
+
+
+def assert_ideator_route():
+    result = run_command([sys.executable, str(ROUTE_GUARD_SCRIPT), "--skill-name", "ideator"])
+    if result.returncode != 0:
+        stderr = result.stderr.strip() or result.stdout.strip() or "WORKFLOW_ROUTE_CHECK_FAILED"
+        raise ValueError(stderr)
 
 
 def load_cadence():
@@ -99,6 +113,8 @@ def main():
     args = parse_args()
 
     try:
+        if args.completion_state == "complete":
+            assert_ideator_route()
         data = load_cadence()
         payload, payload_file_path = parse_payload(args)
     except ValueError as exc:

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

@@ -10,12 +10,21 @@ from pathlib import Path
 
 SCRIPT_DIR = Path(__file__).resolve().parent
 RESOLVE_SCRIPT = SCRIPT_DIR / "resolve-project-scripts-dir.py"
+ROUTE_GUARD_SCRIPT = SCRIPT_DIR / "assert-workflow-route.py"
 
 
 def run_command(command):
     return subprocess.run(command, capture_output=True, text=True, check=False)
 
 
+def assert_expected_route():
+    result = run_command([sys.executable, str(ROUTE_GUARD_SCRIPT), "--skill-name", "prerequisite-gate"])
+    if result.returncode != 0:
+        stderr = result.stderr.strip() or result.stdout.strip() or "WORKFLOW_ROUTE_CHECK_FAILED"
+        print(stderr, file=sys.stderr)
+        raise SystemExit(result.returncode)
+
+
 def resolve_scripts_dir():
     result = run_command([sys.executable, str(RESOLVE_SCRIPT)])
     if result.returncode != 0:
@@ -51,6 +60,7 @@ def write_prerequisite_state(scripts_dir, pass_state):
 
 
 def main():
+    assert_expected_route()
     scripts_dir = resolve_scripts_dir()
     state = read_prerequisite_state(scripts_dir)
 

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

@@ -11,12 +11,21 @@ CADENCE_JSON_PATH = Path(".cadence") / "cadence.json"
 SCRIPT_DIR = Path(__file__).resolve().parent
 SCAFFOLD_SCRIPT = SCRIPT_DIR / "scaffold-project.sh"
 INIT_SCRIPT = SCRIPT_DIR / "init-cadence-scripts-dir.py"
+ROUTE_GUARD_SCRIPT = SCRIPT_DIR / "assert-workflow-route.py"
 
 
 def run_command(command):
     return subprocess.run(command, capture_output=True, text=True, check=False)
 
 
+def assert_expected_route():
+    result = run_command([sys.executable, str(ROUTE_GUARD_SCRIPT), "--skill-name", "scaffold"])
+    if result.returncode != 0:
+        stderr = result.stderr.strip() or result.stdout.strip() or "WORKFLOW_ROUTE_CHECK_FAILED"
+        print(stderr, file=sys.stderr)
+        raise SystemExit(result.returncode)
+
+
 def run_scaffold():
     result = run_command(["bash", str(SCAFFOLD_SCRIPT)])
     if result.returncode != 0:
@@ -60,6 +69,7 @@ def verify_expected_state():
 
 
 def main():
+    assert_expected_route()
     scaffold_status = run_scaffold()
     initialize_scripts_dir()
     scripts_dir = verify_expected_state()

package/skill/skills/ideator/SKILL.md

@@ -6,39 +6,41 @@ description: Guide users from a rough concept to a fully defined project idea th
 # Ideator
 
 1. Keep user-facing responses focused on ideation content. Do not expose internal skill-routing, command output, or execution traces unless the user explicitly asks.
-2. Start from the user's input and briefly restate your understanding.
-3. Accept two input modes:
+2. Run `python3 ../../scripts/assert-workflow-route.py --skill-name ideator` and parse the JSON response.
+3. If route assertion fails, stop and surface the exact error to the user.
+4. Start from the user's input and briefly restate your understanding.
+5. Accept two input modes:
    - Conversational discovery from a rough idea.
    - Project brief or project document provided up front.
-4. If the user provides a project brief or document:
+6. If the user provides a project brief or document:
    - Extract the explicit requirements into a working ideation object.
    - Judge whether the brief is execution-ready across the relevant dimensions below.
    - If information is sufficient, present the final ideation summary and ask for confirmation.
    - If information is missing or ambiguous, ask exactly one highest-leverage follow-up question.
-5. Ask exactly one question at a time. Never ask a batch of questions in a single turn.
-6. After each user answer:
+7. Ask exactly one question at a time. Never ask a batch of questions in a single turn.
+8. After each user answer:
    - Summarize what changed in one short sentence.
    - Decide the next highest-leverage unknown.
    - Ask one natural follow-up question.
-7. Keep discovery domain-agnostic and adaptive:
+9. Keep discovery domain-agnostic and adaptive:
    - Derive the question path from the user's domain, any provided document, and prior answers.
    - Do not force fixed templates or hard-coded checklists during discovery.
    - Drill deep where ambiguity remains; move on when the topic is clear.
-8. Build understanding until the idea is execution-ready. Cover the relevant dimensions for the domain, including:
+10. Build understanding until the idea is execution-ready. Cover the relevant dimensions for the domain, including:
    - objective and core outcome
    - target audience or user
    - core experience or structure (for example mechanics, flow, chapters, systems)
    - scope boundaries (in-scope vs out-of-scope)
    - implementation approach (for example tools, tech stack, process, platforms)
    - delivery shape (milestones, sequencing, constraints, risks, success signals)
-9. Do not hard-code assumptions. If you infer something, label it explicitly and ask for confirmation.
-10. When coverage is deep enough, present a final ideation summary and ask for confirmation.
-11. Resolve helper scripts dir by running `python3 ../../scripts/resolve-project-scripts-dir.py` and store stdout in `CADENCE_SCRIPTS_DIR`.
-12. After confirmation, persist ideation programmatically:
+11. Do not hard-code assumptions. If you infer something, label it explicitly and ask for confirmation.
+12. When coverage is deep enough, present a final ideation summary and ask for confirmation.
+13. Resolve helper scripts dir by running `python3 ../../scripts/resolve-project-scripts-dir.py` and store stdout in `CADENCE_SCRIPTS_DIR`.
+14. After confirmation, persist ideation programmatically:
    - Create a JSON payload file at `.cadence/ideation_payload.json`.
    - Write the full finalized ideation object to that file.
    - Run `python3 "$CADENCE_SCRIPTS_DIR/inject-ideation.py" --file .cadence/ideation_payload.json --completion-state complete` (this injects ideation and deletes `.cadence/ideation_payload.json` on success).
-13. Verify persistence by running `python3 "$CADENCE_SCRIPTS_DIR/get-ideation.py"`.
-14. At end of this successful skill conversation, run `python3 "$CADENCE_SCRIPTS_DIR/finalize-skill-checkpoint.py" --scope ideator --checkpoint ideation-completed --paths .`.
-15. If `finalize-skill-checkpoint.py` returns `status=no_changes`, continue without failure.
-16. If the user requests revisions later, regenerate the payload and rerun `inject-ideation.py`.
+15. Verify persistence by running `python3 "$CADENCE_SCRIPTS_DIR/get-ideation.py"`.
+16. At end of this successful skill conversation, run `python3 "$CADENCE_SCRIPTS_DIR/finalize-skill-checkpoint.py" --scope ideator --checkpoint ideation-completed --paths .`.
+17. If `finalize-skill-checkpoint.py` returns `status=no_changes`, continue without failure.
+18. If the user requests revisions later, regenerate the payload and rerun `inject-ideation.py`.

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

@@ -1,4 +1,4 @@
 interface:
   display_name: "Ideator"
   short_description: "Step-by-step domain-agnostic ideation"
-  default_prompt: "Guide the user from a rough concept or provided project brief to a fully defined idea. If a project brief is provided, decide whether it is sufficient, then ask one follow-up question at a time only for missing critical details before persisting the final ideation payload. Keep user-facing responses focused on ideation outcomes and do not expose internal skill-routing or command traces unless explicitly requested."
+  default_prompt: "Guide the user from a rough concept or provided project brief to a fully defined idea. Before ideation steps, assert the workflow route with scripts/assert-workflow-route.py --skill-name ideator and stop on mismatch. If a project brief is provided, decide whether it is sufficient, then ask one follow-up question at a time only for missing critical details before persisting the final ideation payload. Keep user-facing responses focused on ideation outcomes and do not expose internal skill-routing or command traces unless explicitly requested."

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

@@ -6,10 +6,12 @@ description: Run and persist Cadence prerequisite checks for Python availability
 # Prerequisite Gate
 
 1. Run this only after scaffold routing from `skills/scaffold/SKILL.md`.
-2. Run `python3 ../../scripts/run-prerequisite-gate.py` (resolve this relative path from this sub-skill directory).
-3. If the script reports `MISSING_PYTHON3`, stop and ask the user for confirmation to install prerequisites.
-4. Do not continue Cadence lifecycle or delivery execution while prerequisites are missing.
-5. At end of this successful skill conversation, run `python3 ../../scripts/finalize-skill-checkpoint.py --scope prerequisite-gate --checkpoint prerequisites-passed --paths .`.
-6. If `finalize-skill-checkpoint.py` returns `status=no_changes`, continue without failure.
-7. Surface script failures verbatim instead of adding custom fallback logic.
-8. In normal user-facing updates, share the prerequisite outcome without raw command traces or internal routing details unless explicitly requested.
+2. Run `python3 ../../scripts/assert-workflow-route.py --skill-name prerequisite-gate` and parse the JSON response.
+3. If route assertion fails, stop and surface the exact error to the user.
+4. Run `python3 ../../scripts/run-prerequisite-gate.py` (resolve this relative path from this sub-skill directory).
+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.
+7. At end of this successful skill conversation, run `python3 ../../scripts/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. Surface script failures verbatim instead of adding custom fallback logic.
+10. In normal user-facing updates, share the prerequisite outcome without raw command traces or internal routing details unless explicitly requested.

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

@@ -1,4 +1,4 @@
 interface:
   display_name: "Prerequisite Gate"
   short_description: "Run and persist Cadence prerequisite checks for Python availability"
-  default_prompt: "Run Cadence prerequisite checks, verify Python availability, and persist pass state before lifecycle or delivery execution. Keep user-facing messages focused on prerequisite outcomes and avoid internal command/routing traces unless explicitly requested."
+  default_prompt: "Run Cadence prerequisite checks, verify Python availability, and persist pass state before lifecycle or delivery execution. Before running prerequisite actions, assert the workflow route with scripts/assert-workflow-route.py --skill-name prerequisite-gate and stop on mismatch. Keep user-facing messages focused on prerequisite outcomes and avoid internal command/routing traces unless explicitly requested."

package/skill/skills/scaffold/SKILL.md

@@ -6,27 +6,29 @@ description: Initialize Cadence project scaffolding for first-time setup. Use wh
 # Scaffold
 
 1. Run this only from the target project root.
-2. Run `python3 ../../scripts/run-scaffold-gate.py` (resolve this relative path from this sub-skill directory) and parse the JSON response.
-3. If the script errors, stop and surface the exact error to the user.
-4. Run `python3 ../../scripts/check-project-repo-status.py` and parse the JSON output.
-5. If `repo_enabled` is false, ask the user: `No GitHub remote is configured yet. Do you want to initialize a GitHub repo now? (yes/no)`.
-6. If the user answers yes:
+2. Run `python3 ../../scripts/assert-workflow-route.py --skill-name scaffold` and parse the JSON response.
+3. If route assertion fails, stop and surface the exact error to the user.
+4. Run `python3 ../../scripts/run-scaffold-gate.py` (resolve this relative path from this sub-skill directory) and parse the JSON response.
+5. If the script errors, stop and surface the exact error to the user.
+6. Run `python3 ../../scripts/check-project-repo-status.py` and parse the JSON output.
+7. If `repo_enabled` is false, ask the user: `No GitHub remote is configured yet. Do you want to initialize a GitHub repo now? (yes/no)`.
+8. If the user answers yes:
    - If `git_initialized` is false, run `git init`.
    - Ask for repo name and visibility, then run `gh repo create <name> --source . --remote origin --<public|private>`.
    - Rerun `python3 ../../scripts/check-project-repo-status.py` and verify `repo_enabled` is true.
    - If repo setup still fails, stop and surface the exact failure to the user.
-7. If the user answers no:
+9. If the user answers no:
    - If `git_initialized` is false, run `git init` so local commits can be stored.
    - Run `python3 ../../scripts/check-project-repo-status.py --set-local-only` to persist `state.repo-enabled=false`.
    - Continue in local-only commit mode until the user configures a GitHub repo later.
-8. Ask the user: `Do you want .cadence tracked in git history? (yes/no)`.
-9. If the user answers yes:
+10. Ask the user: `Do you want .cadence tracked in git history? (yes/no)`.
+11. If the user answers yes:
    - Run `python3 ../../scripts/configure-cadence-gitignore.py --mode track`.
    - At end of this skill conversation, run `python3 ../../scripts/finalize-skill-checkpoint.py --scope scaffold --checkpoint cadence-tracked --paths .`.
-10. If the user answers no:
+12. If the user answers no:
    - Run `python3 ../../scripts/configure-cadence-gitignore.py --mode ignore`.
    - At end of this skill conversation, run `python3 ../../scripts/finalize-skill-checkpoint.py --scope scaffold --checkpoint cadence-ignored --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. Execute scaffold actions serially. Do not run this flow in parallel with other setup gates.
-14. In user-facing replies, summarize only the result. Do not expose internal command lines, skill chains, or execution traces unless explicitly requested.
+13. If `finalize-skill-checkpoint.py` returns `status=no_changes`, continue without failure.
+14. If `finalize-skill-checkpoint.py` reports an error, stop and surface it verbatim.
+15. Execute scaffold actions serially. Do not run this flow in parallel with other setup gates.
+16. In user-facing replies, summarize only the result. Do not expose internal command lines, skill chains, or execution traces unless explicitly requested.

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

@@ -1,4 +1,4 @@
 interface:
   display_name: "Scaffold"
   short_description: "Initialize Cadence project scaffolding for first-time setup"
-  default_prompt: "Initialize Cadence project scaffolding in the target project root, creating .cadence state files only when they do not already exist. In user-facing replies, summarize outcome only and avoid internal command or routing traces unless explicitly requested."
+  default_prompt: "Initialize Cadence project scaffolding in the target project root, creating .cadence state files only when they do not already exist. Before running scaffold actions, assert the workflow route with scripts/assert-workflow-route.py --skill-name scaffold and stop on mismatch. In user-facing replies, summarize outcome only and avoid internal command or routing traces unless explicitly requested."