cadence-skill-installer 0.1.0

package/README.md

@@ -0,0 +1,46 @@
+# Cadence Skill Installer
+
+Install this repository's `skill/` contents into one or more AI tool skill paths (`.../skills/cadence/`) using `npx`.
+
+## Run
+
+```bash
+npx cadence-skill-installer
+```
+
+The installer shows a multi-select prompt (comma-separated choices) so you can install into multiple tools in one run.
+
+## Non-interactive examples
+
+```bash
+# Install to all supported tools
+npx cadence-skill-installer --all --yes
+
+# Install to specific tools
+npx cadence-skill-installer --tools codex,claude,gemini --yes
+```
+
+## Supported tool keys
+
+- `codex`
+- `agents`
+- `claude`
+- `gemini`
+- `copilot`
+- `github-copilot`
+- `windsurf`
+- `opencode`
+
+## CI/CD Trusted Publishing (recommended)
+
+This repo includes `/Users/sn0w/Documents/dev/cadence/.github/workflows/publish.yml` for npm trusted publishing (OIDC).
+
+1. Push this repo to GitHub.
+2. In npm package settings for `cadence-skill-installer`, add a Trusted Publisher:
+   - Provider: GitHub Actions
+   - Repository: your owner/repo
+   - Workflow file: `.github/workflows/publish.yml`
+   - Environment: leave empty unless you use one
+3. Trigger the workflow manually (`workflow_dispatch`) or push a tag like `v0.1.0`.
+
+No `NPM_TOKEN` secret is required in GitHub Actions when trusted publishing is configured.

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "cadence-skill-installer",
+  "version": "0.1.0",
+  "description": "Install the Cadence skill into supported AI tool skill directories.",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "cadence-skill-installer": "scripts/install-cadence-skill.mjs",
+    "cadence-install": "scripts/install-cadence-skill.mjs"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "skill/**",
+    "scripts/install-cadence-skill.mjs",
+    "README.md"
+  ]
+}

package/scripts/install-cadence-skill.mjs

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { stdin as input, stdout as output } from "node:process";
+
+const CADENCE_SKILL_NAME = "cadence";
+
+const TOOL_TARGETS = [
+  { key: "codex", label: "Codex", relPath: [".codex", "skills", CADENCE_SKILL_NAME] },
+  { key: "agents", label: "Agents", relPath: [".agents", "skills", CADENCE_SKILL_NAME] },
+  { key: "claude", label: "Claude", relPath: [".claude", "skills", CADENCE_SKILL_NAME] },
+  { key: "gemini", label: "Gemini", relPath: [".gemini", "skills", CADENCE_SKILL_NAME] },
+  { key: "copilot", label: "Copilot", relPath: [".copilot", "skills", CADENCE_SKILL_NAME] },
+  {
+    key: "github-copilot",
+    label: "GitHub Copilot",
+    relPath: [".config", "github-copilot", "skills", CADENCE_SKILL_NAME]
+  },
+  {
+    key: "windsurf",
+    label: "Codeium Windsurf",
+    relPath: [".codeium", "windsurf", "skills", CADENCE_SKILL_NAME]
+  },
+  {
+    key: "opencode",
+    label: "OpenCode",
+    relPath: [".config", "opencode", "skills", CADENCE_SKILL_NAME]
+  }
+];
+
+const SKIP_NAMES = new Set([".DS_Store", "__pycache__"]);
+
+function printHelp(binName) {
+  const validTools = TOOL_TARGETS.map((tool) => tool.key).join(",");
+  output.write(
+    [
+      `Usage: ${binName} [options]`,
+      "",
+      "Options:",
+      "  --tools <comma-list>  Install to specific tools (skips interactive selection).",
+      "                         Valid keys:",
+      `                         ${validTools}`,
+      "  --all                  Install to all supported tools.",
+      "  --yes                  Skip confirmation prompt.",
+      "  --home <path>          Override home directory for destination paths.",
+      "  --help                 Show this message."
+    ].join("\n") + "\n"
+  );
+}
+
+function parseArgs(argv) {
+  const parsed = {
+    all: false,
+    yes: false,
+    tools: null,
+    home: null,
+    help: false
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--all") {
+      parsed.all = true;
+      continue;
+    }
+    if (arg === "--yes") {
+      parsed.yes = true;
+      continue;
+    }
+    if (arg === "--help" || arg === "-h") {
+      parsed.help = true;
+      continue;
+    }
+    if (arg === "--tools") {
+      parsed.tools = argv[i + 1] ?? "";
+      i += 1;
+      continue;
+    }
+    if (arg === "--home") {
+      parsed.home = argv[i + 1] ?? "";
+      i += 1;
+      continue;
+    }
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  if (parsed.all && parsed.tools) {
+    throw new Error("Use either --all or --tools, not both.");
+  }
+
+  return parsed;
+}
+
+function resolveSourceDir() {
+  const scriptPath = fileURLToPath(import.meta.url);
+  const scriptDir = path.dirname(scriptPath);
+  return path.resolve(scriptDir, "..", "skill");
+}
+
+async function ensureSourceDir(sourceDir) {
+  let stat;
+  try {
+    stat = await fs.stat(sourceDir);
+  } catch {
+    throw new Error(`Missing skill directory: ${sourceDir}`);
+  }
+
+  if (!stat.isDirectory()) {
+    throw new Error(`Expected a directory at: ${sourceDir}`);
+  }
+}
+
+function buildTargets(homeDir) {
+  return TOOL_TARGETS.map((tool) => ({
+    ...tool,
+    targetDir: path.join(homeDir, ...tool.relPath)
+  }));
+}
+
+function parseToolKeyList(toolList) {
+  const keys = String(toolList)
+    .split(",")
+    .map((part) => part.trim().toLowerCase())
+    .filter(Boolean);
+
+  if (keys.length === 0) {
+    throw new Error("No tool keys provided after --tools.");
+  }
+
+  const deduped = [...new Set(keys)];
+  const unknown = deduped.filter((key) => !TOOL_TARGETS.some((tool) => tool.key === key));
+  if (unknown.length > 0) {
+    throw new Error(`Unknown tool keys: ${unknown.join(", ")}`);
+  }
+
+  return deduped;
+}
+
+function parseInteractiveSelection(selection, targets) {
+  const raw = selection.trim().toLowerCase();
+  if (!raw) {
+    throw new Error("No selection received.");
+  }
+  if (raw === "all") {
+    return targets;
+  }
+
+  const values = raw
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean);
+
+  if (values.length === 0) {
+    throw new Error("No valid selection received.");
+  }
+
+  const selectedIndexes = [];
+  for (const value of values) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > targets.length) {
+      throw new Error(`Invalid selection: ${value}`);
+    }
+    selectedIndexes.push(parsed - 1);
+  }
+
+  const uniqueIndexes = [...new Set(selectedIndexes)];
+  return uniqueIndexes.map((idx) => targets[idx]);
+}
+
+async function chooseTargets(parsed, targets) {
+  if (parsed.all) {
+    return targets;
+  }
+
+  if (parsed.tools) {
+    const selectedKeys = parseToolKeyList(parsed.tools);
+    return targets.filter((target) => selectedKeys.includes(target.key));
+  }
+
+  const rl = readline.createInterface({ input, output });
+  try {
+    output.write("Select tools to install Cadence skill into (multi-select).\n");
+    output.write("Enter numbers separated by commas, or type 'all'.\n\n");
+    targets.forEach((target, idx) => {
+      output.write(`${idx + 1}. ${target.label} (${target.targetDir})\n`);
+    });
+    const answer = await rl.question("\nSelection: ");
+    return parseInteractiveSelection(answer, targets);
+  } finally {
+    rl.close();
+  }
+}
+
+async function copyEntry(srcPath, destPath) {
+  const stat = await fs.lstat(srcPath);
+
+  if (stat.isDirectory()) {
+    await fs.mkdir(destPath, { recursive: true });
+    const entries = await fs.readdir(srcPath);
+    for (const entry of entries) {
+      if (SKIP_NAMES.has(entry)) {
+        continue;
+      }
+      await copyEntry(path.join(srcPath, entry), path.join(destPath, entry));
+    }
+    return;
+  }
+
+  if (stat.isSymbolicLink()) {
+    const linkTarget = await fs.readlink(srcPath);
+    try {
+      await fs.unlink(destPath);
+    } catch {
+      // Ignore if destination does not exist.
+    }
+    await fs.symlink(linkTarget, destPath);
+    return;
+  }
+
+  await fs.mkdir(path.dirname(destPath), { recursive: true });
+  await fs.copyFile(srcPath, destPath);
+}
+
+async function copySkillContents(sourceDir, targetDir) {
+  await fs.mkdir(targetDir, { recursive: true });
+  const entries = await fs.readdir(sourceDir);
+  for (const entry of entries) {
+    if (SKIP_NAMES.has(entry)) {
+      continue;
+    }
+    await copyEntry(path.join(sourceDir, entry), path.join(targetDir, entry));
+  }
+}
+
+async function confirmInstall(parsed, selectedTargets) {
+  if (parsed.yes) {
+    return true;
+  }
+
+  const rl = readline.createInterface({ input, output });
+  try {
+    output.write("\nInstall Cadence skill into:\n");
+    selectedTargets.forEach((target) => output.write(`- ${target.targetDir}\n`));
+    const answer = await rl.question("Continue? [y/N]: ");
+    return answer.trim().toLowerCase() === "y" || answer.trim().toLowerCase() === "yes";
+  } finally {
+    rl.close();
+  }
+}
+
+async function main() {
+  const binName = path.basename(process.argv[1] || "cadence-install");
+  let parsed;
+  try {
+    parsed = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    output.write(`Error: ${error.message}\n\n`);
+    printHelp(binName);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (parsed.help) {
+    printHelp(binName);
+    return;
+  }
+
+  const homeDir = parsed.home || os.homedir();
+  const sourceDir = resolveSourceDir();
+  await ensureSourceDir(sourceDir);
+  const targets = buildTargets(homeDir);
+
+  let selectedTargets;
+  try {
+    selectedTargets = await chooseTargets(parsed, targets);
+  } catch (error) {
+    output.write(`Error: ${error.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (selectedTargets.length === 0) {
+    output.write("No tools selected. Nothing to install.\n");
+    return;
+  }
+
+  const confirmed = await confirmInstall(parsed, selectedTargets);
+  if (!confirmed) {
+    output.write("Installation cancelled.\n");
+    return;
+  }
+
+  for (const target of selectedTargets) {
+    await copySkillContents(sourceDir, target.targetDir);
+    output.write(`Installed to ${target.label}: ${target.targetDir}\n`);
+  }
+
+  output.write("\nCadence skill installation complete.\n");
+}
+
+main().catch((error) => {
+  output.write(`Installation failed: ${error.message}\n`);
+  process.exitCode = 1;
+});

package/skill/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: cadence
+description: Structured project operating system for end-to-end greenfield or brownfield delivery. Use when users want the AI to guide the full lifecycle from initialization, requirements, roadmap, and phased execution through milestone audit and completion with deterministic gates, traceability, and rollback-safe execution.
+---
+
+# Cadence
+
+## Overview
+1. Keep this root skill as an orchestrator.
+2. Delegate concrete execution to focused subskills.
+
+## Scaffold Gate (Mandatory On First Turn)
+1. Check for `.cadence` in the project root.
+2. If `.cadence` is missing, invoke `skills/scaffold/SKILL.md`.
+3. Scaffold initializes and persists `state.cadence-scripts-dir` for later subskill commands.
+4. If `.cadence` exists, skip scaffold.
+
+## Prerequisite Gate (Mandatory On First Turn)
+1. Invoke `skills/prerequisite-gate/SKILL.md`.
+2. Continue lifecycle and delivery execution only after prerequisite gate pass.
+
+## Ideation Flow
+1. Invoke `skills/ideator/SKILL.md` when the user is creating a new project idea from scratch and needs guided discovery to a finalized concept.
+2. Continue downstream planning only after ideation is persisted in `.cadence/cadence.json`.
+
+## Ideation Update Flow
+1. If the user wants to modify or discuss existing ideation, invoke `skills/ideation-updater/SKILL.md`.
+2. Use this update flow only for existing project ideation changes; use `skills/ideator/SKILL.md` for net-new ideation discovery.

package/skill/agents/openai.yaml

@@ -0,0 +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). If user intent indicates resuming/continuing work (in any natural-language phrasing), run CADENCE progress, determine the active milestone/phase, and continue with the routed workflow while explicitly notifying the user of current location and next step."

package/skill/assets/AGENTS.md

@@ -0,0 +1,52 @@
+## Workflow Orchestration
+
+### 1. Plan Node Default
+- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
+- If something goes sideways, STOP and re-plan immediately - don't keep pushing
+- Use plan mode for verification steps, not just building
+- Write detailed specs upfront to reduce ambiguity
+
+### 2. Subagent Strategy
+- Use subagents liberally to keep main context window clean
+- Offload research, exploration, and parallel analysis to subagents
+- For complex problems, throw more compute at it via subagents
+- One tack per subagent for focused execution
+
+### 3. Self-Improvement Loop
+- After ANY correction from the user: update `.cadence/tasks/lessons.md` with the pattern
+- Write rules for yourself that prevent the same mistake
+- Ruthlessly iterate on these lessons until mistake rate drops
+- Review lessons at session start for relevant project
+
+### 4. Verification Before Done
+- Never mark a task complete without proving it works
+- Diff behavior between main and your changes when relevant
+- Ask yourself: "Would a staff engineer approve this?"
+- Run tests, check logs, demonstrate correctness
+
+### 5. Demand Elegance (Balanced)
+- For non-trivial changes: pause and ask "is there a more elegant way?"
+- If a fix feels hacky: "Knowing everything I know now, implement the elegant solution"
+- Skip this for simple, obvious fixes - don't over-engineer
+- Challenge your own work before presenting it
+
+### 6. Autonomous Bug Fixing
+- When given a bug report: just fix it. Don't ask for hand-holding
+- Point at logs, errors, failing tests - then resolve them
+- Zero context switching required from the user
+- Go fix failing CI tests without being told how
+
+## Task Management
+
+1. **Plan First**: Write plan to `.cadence/tasks/todo.md` with checkable items
+2. **Verify Plan**: Check in before starting implementation
+3. **Track Progress**: Mark items complete as you go
+4. **Explain Changes**: High-level summary at each step
+5. **Document Results**: Add review section to `.cadence/tasks/todo.md`
+6. **Capture Lessons**: Update `.cadence/tasks/lessons.md` after corrections
+
+## Core Principles
+
+- **Simplicity First**: Make every change as simple as possible. Impact minimal code.
+- **No Laziness**: Find root causes. No temporary fixes. Senior developer standards.
+- **Minimat Impact**: Changes should only touch what's necessary. Avoid introducing bugs.

package/skill/assets/cadence.json

@@ -0,0 +1,9 @@
+{
+    "prerequisites-pass": false,
+    "state": {
+        "ideation-completed": false,
+        "cadence-scripts-dir": ""
+    },
+    "project-details": {},
+    "ideation": {}
+}

package/skill/scripts/expose-ideation.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+"""Expose .cadence/cadence.json ideation payload for AI consumption."""
+
+import json
+from pathlib import Path
+
+
+CADENCE_JSON_PATH = Path(".cadence") / "cadence.json"
+
+
+def load_ideation():
+    if not CADENCE_JSON_PATH.exists():
+        return {}
+
+    with CADENCE_JSON_PATH.open("r", encoding="utf-8") as file:
+        data = json.load(file)
+
+    ideation = data.get("ideation", {})
+    if isinstance(ideation, dict):
+        return ideation
+    return {}
+
+
+print(json.dumps(load_ideation(), indent=4))

package/skill/scripts/get-ideation.py

@@ -0,0 +1,17 @@
+#!/usr/bin/env python3
+"""Read and print the ideation payload from .cadence/cadence.json."""
+
+import json
+from pathlib import Path
+
+
+CADENCE_JSON_PATH = Path(".cadence") / "cadence.json"
+
+
+if CADENCE_JSON_PATH.exists():
+    with CADENCE_JSON_PATH.open("r", encoding="utf-8") as file:
+        data = json.load(file)
+else:
+    data = {"ideation": {}}
+
+print(json.dumps(data.get("ideation", {}), indent=4))

package/skill/scripts/handle-prerequisite-state.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""Read or update prerequisite pass state in .cadence/cadence.json."""
+
+import json
+import sys
+from pathlib import Path
+
+
+CADENCE_JSON_PATH = Path(".cadence") / "cadence.json"
+
+
+def default_data():
+    return {
+        "prerequisites-pass": False,
+        "state": {
+            "ideation-completed": False,
+            "cadence-scripts-dir": "",
+        },
+        "project-details": {},
+        "ideation": {},
+    }
+
+
+def load_data():
+    if not CADENCE_JSON_PATH.exists():
+        return default_data()
+    with CADENCE_JSON_PATH.open("r", encoding="utf-8") as file:
+        return json.load(file)
+
+
+def save_data(data):
+    CADENCE_JSON_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with CADENCE_JSON_PATH.open("w", encoding="utf-8") as file:
+        json.dump(data, file, indent=4)
+        file.write("\n")
+
+
+def main():
+    if len(sys.argv) > 2:
+        print("Usage: handle-prerequisite-state.py [0|1]", file=sys.stderr)
+        return 2
+
+    if len(sys.argv) == 2 and sys.argv[1] not in {"0", "1"}:
+        print("Usage: handle-prerequisite-state.py [0|1]", file=sys.stderr)
+        return 2
+
+    data = load_data()
+
+    if len(sys.argv) == 1:
+        print("true" if bool(data.get("prerequisites-pass", False)) else "false")
+        return 0
+
+    data["prerequisites-pass"] = sys.argv[1] == "1"
+    save_data(data)
+    print("true" if data["prerequisites-pass"] else "false")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skill/scripts/init-cadence-scripts-dir.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Persist Cadence helper scripts directory in .cadence/cadence.json."""
+
+import json
+from pathlib import Path
+
+
+CADENCE_DIR = Path(".cadence")
+CADENCE_JSON_PATH = CADENCE_DIR / "cadence.json"
+GETTER_PATH = CADENCE_DIR / "get-cadence-scripts-dir.py"
+
+
+def default_data():
+    return {
+        "prerequisites-pass": False,
+        "state": {
+            "ideation-completed": False,
+            "cadence-scripts-dir": "",
+        },
+        "project-details": {},
+        "ideation": {},
+    }
+
+
+def load_data():
+    if not CADENCE_JSON_PATH.exists():
+        return default_data()
+    with CADENCE_JSON_PATH.open("r", encoding="utf-8") as file:
+        return json.load(file)
+
+
+def save_data(data):
+    CADENCE_DIR.mkdir(parents=True, exist_ok=True)
+    with CADENCE_JSON_PATH.open("w", encoding="utf-8") as file:
+        json.dump(data, file, indent=4)
+        file.write("\n")
+
+
+def write_getter_script():
+    content = """#!/usr/bin/env python3
+import json
+import sys
+from pathlib import Path
+
+cadence_json_path = Path(".cadence") / "cadence.json"
+if not cadence_json_path.exists():
+    print("MISSING_CADENCE_JSON", file=sys.stderr)
+    raise SystemExit(1)
+
+try:
+    with cadence_json_path.open("r", encoding="utf-8") as file:
+        data = json.load(file)
+except json.JSONDecodeError as exc:
+    print(f"INVALID_CADENCE_JSON: {exc}", file=sys.stderr)
+    raise SystemExit(1)
+
+scripts_dir = data.get("state", {}).get("cadence-scripts-dir", "")
+if not scripts_dir:
+    print("MISSING_CADENCE_SCRIPTS_DIR", file=sys.stderr)
+    raise SystemExit(1)
+
+print(scripts_dir)
+"""
+    GETTER_PATH.write_text(content, encoding="utf-8")
+
+
+def main():
+    if not CADENCE_DIR.exists():
+        print("MISSING_CADENCE_DIR")
+        return 1
+
+    scripts_dir = str(Path(__file__).resolve().parent)
+
+    data = load_data()
+    state = data.setdefault("state", {})
+    state["cadence-scripts-dir"] = scripts_dir
+    save_data(data)
+    write_getter_script()
+
+    print(json.dumps({"status": "ok", "cadence_scripts_dir": scripts_dir, "getter_path": str(GETTER_PATH)}))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skill/scripts/inject-ideation.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""Inject finalized ideation payload into .cadence/cadence.json."""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+CADENCE_JSON_PATH = Path(".cadence") / "cadence.json"
+
+
+def default_data():
+    return {
+        "prerequisites-pass": False,
+        "state": {
+            "ideation-completed": False,
+            "cadence-scripts-dir": "",
+        },
+        "project-details": {},
+        "ideation": {},
+    }
+
+
+def load_cadence():
+    if not CADENCE_JSON_PATH.exists():
+        return default_data()
+    try:
+        with CADENCE_JSON_PATH.open("r", encoding="utf-8") as file:
+            return json.load(file)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Invalid JSON in {CADENCE_JSON_PATH}: {exc}") from exc
+
+
+def save_cadence(data):
+    CADENCE_JSON_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with CADENCE_JSON_PATH.open("w", encoding="utf-8") as file:
+        json.dump(data, file, indent=4)
+        file.write("\n")
+
+
+def deep_merge(base, patch):
+    merged = dict(base)
+    for key, value in patch.items():
+        if key in merged and isinstance(merged[key], dict) and isinstance(value, dict):
+            merged[key] = deep_merge(merged[key], value)
+        else:
+            merged[key] = value
+    return merged
+
+
+def parse_payload(args):
+    payload_file_path = None
+    if args.file:
+        payload_file_path = Path(args.file)
+        try:
+            payload_text = payload_file_path.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise ValueError(f"Unable to read payload file {args.file}: {exc}") from exc
+    elif args.json:
+        payload_text = args.json
+    elif args.stdin:
+        payload_text = sys.stdin.read()
+    else:
+        raise ValueError("One payload input source is required.")
+
+    try:
+        payload = json.loads(payload_text)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Invalid JSON payload: {exc}") from exc
+
+    if not isinstance(payload, dict):
+        raise ValueError("Payload must be a JSON object.")
+    return payload, payload_file_path
+
+
+def apply_completion_state(data, completion_state):
+    state = data.setdefault("state", {})
+    if completion_state == "complete":
+        state["ideation-completed"] = True
+    elif completion_state == "incomplete":
+        state["ideation-completed"] = False
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(
+        description="Inject finalized ideation payload into .cadence/cadence.json."
+    )
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument("--file", help="Read ideation payload JSON from file path")
+    group.add_argument("--json", help="Read ideation payload JSON from inline string")
+    group.add_argument("--stdin", action="store_true", help="Read ideation payload JSON from stdin")
+    parser.add_argument(
+        "--completion-state",
+        choices=["complete", "incomplete", "keep"],
+        default="complete",
+        help="How to update state.ideation-completed",
+    )
+    parser.add_argument(
+        "--merge",
+        action="store_true",
+        help="Merge payload into existing ideation object instead of replacing it",
+    )
+    return parser.parse_args()
+
+
+def main():
+    args = parse_args()
+
+    try:
+        data = load_cadence()
+        payload, payload_file_path = parse_payload(args)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+
+    existing_ideation = data.get("ideation", {})
+
+    if args.merge and isinstance(existing_ideation, dict):
+        data["ideation"] = deep_merge(existing_ideation, payload)
+    else:
+        data["ideation"] = payload
+
+    apply_completion_state(data, args.completion_state)
+    save_cadence(data)
+
+    payload_deleted = False
+    if payload_file_path is not None:
+        try:
+            payload_file_path.unlink()
+            payload_deleted = True
+        except OSError as exc:
+            print(f"Unable to delete payload file {payload_file_path}: {exc}", file=sys.stderr)
+            return 3
+
+    print(
+        json.dumps(
+            {
+                "status": "ok",
+                "path": str(CADENCE_JSON_PATH),
+                "completion_state": args.completion_state,
+                "payload_deleted": payload_deleted,
+            }
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skill/scripts/render-ideation-summary.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""Render .cadence/cadence.json ideation payload in human-readable text."""
+
+import json
+from pathlib import Path
+
+
+CADENCE_JSON_PATH = Path(".cadence") / "cadence.json"
+
+
+def humanize_key(key):
+    return str(key).replace("_", " ").replace("-", " ").strip().title()
+
+
+def scalar_to_text(value):
+    if isinstance(value, bool):
+        return "Yes" if value else "No"
+    if value is None:
+        return "None"
+    return str(value)
+
+
+def render_value(value, indent=0):
+    space = " " * indent
+    lines = []
+
+    if isinstance(value, dict):
+        if not value:
+            return [f"{space}(empty)"]
+        for key, inner in value.items():
+            label = humanize_key(key)
+            if isinstance(inner, (dict, list)):
+                lines.append(f"{space}- {label}:")
+                lines.extend(render_value(inner, indent + 2))
+            else:
+                lines.append(f"{space}- {label}: {scalar_to_text(inner)}")
+        return lines
+
+    if isinstance(value, list):
+        if not value:
+            return [f"{space}(empty list)"]
+        for idx, item in enumerate(value, start=1):
+            if isinstance(item, (dict, list)):
+                lines.append(f"{space}- Item {idx}:")
+                lines.extend(render_value(item, indent + 2))
+            else:
+                lines.append(f"{space}- {scalar_to_text(item)}")
+        return lines
+
+    return [f"{space}{scalar_to_text(value)}"]
+
+
+def load_ideation():
+    if not CADENCE_JSON_PATH.exists():
+        return {}
+    with CADENCE_JSON_PATH.open("r", encoding="utf-8") as file:
+        data = json.load(file)
+    ideation = data.get("ideation", {})
+    return ideation if isinstance(ideation, dict) else {}
+
+
+def main():
+    ideation = load_ideation()
+    print("Current Project Ideation")
+    print("========================")
+    if not ideation:
+        print("No ideation is currently saved.")
+        return
+
+    for line in render_value(ideation):
+        print(line)
+
+
+if __name__ == "__main__":
+    main()

package/skill/scripts/resolve-project-scripts-dir.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""Resolve Cadence helper scripts dir for the current project.
+
+Behavior:
+- If .cadence/get-cadence-scripts-dir.py exists, use it.
+- If missing but .cadence exists, regenerate project path state by running
+  init-cadence-scripts-dir.py from this skill's scripts directory.
+- Print the resolved scripts directory to stdout.
+"""
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+CADENCE_DIR = Path(".cadence")
+GETTER_PATH = CADENCE_DIR / "get-cadence-scripts-dir.py"
+SCRIPT_DIR = Path(__file__).resolve().parent
+INIT_SCRIPT_PATH = SCRIPT_DIR / "init-cadence-scripts-dir.py"
+
+
+def run_command(command):
+    return subprocess.run(command, capture_output=True, text=True, check=False)
+
+
+def ensure_getter():
+    if GETTER_PATH.exists():
+        return
+
+    if not CADENCE_DIR.exists():
+        print("MISSING_CADENCE_DIR", file=sys.stderr)
+        raise SystemExit(1)
+
+    result = run_command([sys.executable, str(INIT_SCRIPT_PATH)])
+    if result.returncode != 0:
+        stderr = result.stderr.strip() or "FAILED_TO_INIT_CADENCE_SCRIPTS_DIR"
+        print(stderr, file=sys.stderr)
+        raise SystemExit(result.returncode)
+
+
+def load_scripts_dir():
+    result = run_command([sys.executable, str(GETTER_PATH)])
+    if result.returncode != 0:
+        stderr = result.stderr.strip() or "MISSING_CADENCE_SCRIPTS_DIR"
+        print(stderr, file=sys.stderr)
+        raise SystemExit(result.returncode)
+
+    scripts_dir = result.stdout.strip()
+    if not scripts_dir:
+        print("MISSING_CADENCE_SCRIPTS_DIR", file=sys.stderr)
+        raise SystemExit(1)
+
+    print(scripts_dir)
+
+
+def main():
+    ensure_getter()
+    load_scripts_dir()
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Run Cadence prerequisite gate and persist pass state."""
+
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+RESOLVE_SCRIPT = SCRIPT_DIR / "resolve-project-scripts-dir.py"
+
+
+def run_command(command):
+    return subprocess.run(command, capture_output=True, text=True, check=False)
+
+
+def resolve_scripts_dir():
+    result = run_command([sys.executable, str(RESOLVE_SCRIPT)])
+    if result.returncode != 0:
+        stderr = result.stderr.strip() or "MISSING_CADENCE_SCRIPTS_DIR"
+        print(stderr, file=sys.stderr)
+        raise SystemExit(result.returncode)
+
+    scripts_dir = result.stdout.strip()
+    if not scripts_dir:
+        print("MISSING_CADENCE_SCRIPTS_DIR", file=sys.stderr)
+        raise SystemExit(1)
+
+    return scripts_dir
+
+
+def read_prerequisite_state(scripts_dir):
+    script_path = Path(scripts_dir) / "handle-prerequisite-state.py"
+    result = run_command([sys.executable, str(script_path)])
+    if result.returncode != 0:
+        stderr = result.stderr.strip() or "PREREQUISITE_STATE_READ_FAILED"
+        print(stderr, file=sys.stderr)
+        raise SystemExit(result.returncode)
+    return result.stdout.strip()
+
+
+def write_prerequisite_state(scripts_dir, pass_state):
+    script_path = Path(scripts_dir) / "handle-prerequisite-state.py"
+    result = run_command([sys.executable, str(script_path), pass_state])
+    if result.returncode != 0:
+        stderr = result.stderr.strip() or "PREREQUISITE_STATE_WRITE_FAILED"
+        print(stderr, file=sys.stderr)
+        raise SystemExit(result.returncode)
+
+
+def main():
+    scripts_dir = resolve_scripts_dir()
+    state = read_prerequisite_state(scripts_dir)
+
+    if state == "true":
+        print(json.dumps({"status": "ok", "prerequisites_pass": True, "source": "cache"}))
+        return
+
+    if shutil.which("python3") is None:
+        print("MISSING_PYTHON3", file=sys.stderr)
+        raise SystemExit(1)
+
+    write_prerequisite_state(scripts_dir, "1")
+    print(json.dumps({"status": "ok", "prerequisites_pass": True, "source": "fresh-check"}))
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""Run Cadence scaffold gate in one deterministic command."""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+CADENCE_JSON_PATH = Path(".cadence") / "cadence.json"
+GETTER_PATH = Path(".cadence") / "get-cadence-scripts-dir.py"
+SCRIPT_DIR = Path(__file__).resolve().parent
+SCAFFOLD_SCRIPT = SCRIPT_DIR / "scaffold-project.sh"
+INIT_SCRIPT = SCRIPT_DIR / "init-cadence-scripts-dir.py"
+
+
+def run_command(command):
+    return subprocess.run(command, capture_output=True, text=True, check=False)
+
+
+def run_scaffold():
+    result = run_command(["bash", str(SCAFFOLD_SCRIPT)])
+    if result.returncode != 0:
+        stderr = result.stderr.strip() or "SCAFFOLD_FAILED"
+        print(stderr, file=sys.stderr)
+        raise SystemExit(result.returncode)
+
+    return result.stdout.strip() or "scaffold-created"
+
+
+def initialize_scripts_dir():
+    result = run_command([sys.executable, str(INIT_SCRIPT)])
+    if result.returncode != 0:
+        stderr = result.stderr.strip() or "INIT_CADENCE_SCRIPTS_DIR_FAILED"
+        print(stderr, file=sys.stderr)
+        raise SystemExit(result.returncode)
+
+
+def verify_expected_files():
+    if not CADENCE_JSON_PATH.exists():
+        print("CADENCE_JSON_MISSING", file=sys.stderr)
+        raise SystemExit(1)
+
+    if not GETTER_PATH.exists():
+        print("MISSING_CADENCE_GETTER", file=sys.stderr)
+        raise SystemExit(1)
+
+
+def main():
+    scaffold_status = run_scaffold()
+
+    if scaffold_status == "scaffold-created" or not GETTER_PATH.exists():
+        initialize_scripts_dir()
+
+    verify_expected_files()
+
+    print(json.dumps({"status": "ok", "scaffold_status": scaffold_status}))
+
+
+if __name__ == "__main__":
+    main()

package/skill/scripts/scaffold-project.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ -d ".cadence" ]; then
+  echo "scaffold-skipped"
+  exit 0
+fi
+
+mkdir -p ".cadence"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEMPLATE_PATH="${SCRIPT_DIR}/../assets/cadence.json"
+TARGET_PATH=".cadence/cadence.json"
+
+if [ -f "${TEMPLATE_PATH}" ]; then
+  cp "${TEMPLATE_PATH}" "${TARGET_PATH}"
+else
+  cat > "${TARGET_PATH}" <<'JSON'
+{
+    "prerequisites-pass": false,
+    "state": {
+        "ideation-completed": false,
+        "cadence-scripts-dir": ""
+    },
+    "project-details": {},
+    "ideation": {}
+}
+JSON
+fi
+
+echo "scaffold-created"

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

@@ -0,0 +1,40 @@
+---
+name: ideation-updater
+description: Discuss, audit, and update existing project ideation in .cadence/cadence.json while preserving full-project context. Use when the user wants to add missing aspects, revise assumptions, remove scope, or explore tradeoffs within an already defined project idea.
+---
+
+# Ideation Updater
+
+1. Invoke this skill only when user intent is to discuss or modify already-saved ideation.
+2. Route first-time concept discovery to `skills/ideator/SKILL.md`.
+3. Resolve helper scripts dir by running `python3 ../../scripts/resolve-project-scripts-dir.py` and store stdout in `CADENCE_SCRIPTS_DIR`.
+4. First message behavior in this skill conversation:
+   - Run `python3 "$CADENCE_SCRIPTS_DIR/expose-ideation.py"` and use the JSON output as active AI context.
+   - Run `python3 "$CADENCE_SCRIPTS_DIR/render-ideation-summary.py"` and show that human-readable summary to the user.
+   - Ask one intent-setting question: discussion only, add, change, or remove.
+5. Run the conversation one step at a time:
+   - Ask exactly one question per turn.
+   - Keep the full current project idea in mind while focusing on the selected area.
+   - After each user answer, restate what changed and what remains unchanged.
+6. Support deep-dive updates for missing aspects:
+   - If user says they forgot a topic, zoom into that topic and drill until clear.
+   - Adapt topic depth to domain context (for example mechanics/systems, audience, scope boundaries, tech/process, risks, success criteria).
+   - Avoid hard-coded question trees; derive next question from current context.
+7. Distinguish interaction modes clearly:
+   - Discussion mode: analyze options and tradeoffs, do not persist.
+   - Add or modify mode: prepare a minimal patch payload and merge.
+   - Remove mode: rebuild the full ideation object without removed fields and replace.
+8. Before any write, present a short change plan with:
+   - Fields to add
+   - Fields to update
+   - Fields to remove
+   - Fields unchanged
+9. Persist only after user confirmation.
+10. For add or modify mode:
+   - Write changed fields to `.cadence/ideation_payload.json`.
+   - Run `python3 "$CADENCE_SCRIPTS_DIR/inject-ideation.py" --file .cadence/ideation_payload.json --merge --completion-state keep`.
+11. For remove mode or structural rewrites:
+   - Write the complete updated ideation object to `.cadence/ideation_payload.json`.
+   - Run `python3 "$CADENCE_SCRIPTS_DIR/inject-ideation.py" --file .cadence/ideation_payload.json --completion-state keep`.
+12. After persistence, confirm result by running `python3 "$CADENCE_SCRIPTS_DIR/render-ideation-summary.py"`.
+13. Ask whether to continue refining another aspect or stop.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Ideation Updater"
+  short_description: "Discuss and update existing project ideation"
+  default_prompt: "Review current project ideation, discuss changes, and persist approved updates."

package/skill/skills/ideator/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: ideator
+description: Guide users from a rough concept to a fully defined project idea through adaptive, one-question-at-a-time discovery. Use when users want to shape or refine what they want to build, write, or create across any domain, then persist final ideation into .cadence/cadence.json.
+---
+
+# Ideator
+
+1. Start from the user's seed idea and briefly restate your understanding.
+2. Ask exactly one question at a time. Never ask a batch of questions in a single turn.
+3. After each user answer:
+   - Summarize what changed in one short sentence.
+   - Decide the next highest-leverage unknown.
+   - Ask one natural follow-up question.
+4. Keep discovery domain-agnostic and adaptive:
+   - Derive the question path from the user's domain 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.
+5. 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)
+6. Do not hard-code assumptions. If you infer something, label it explicitly and ask for confirmation.
+7. When coverage is deep enough, present a final ideation summary and ask for confirmation.
+8. Resolve helper scripts dir by running `python3 ../../scripts/resolve-project-scripts-dir.py` and store stdout in `CADENCE_SCRIPTS_DIR`.
+9. 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).
+10. Verify persistence by running `python3 "$CADENCE_SCRIPTS_DIR/get-ideation.py"`.
+11. If the user requests revisions later, regenerate the payload and rerun `inject-ideation.py`.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Ideator"
+  short_description: "Step-by-step domain-agnostic ideation"
+  default_prompt: "Guide the user from a rough concept to a fully defined idea with one question at a time, then persist the final ideation payload."

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

@@ -0,0 +1,12 @@
+---
+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.
+---
+
+# 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. Surface script failures verbatim instead of adding custom fallback logic.

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

@@ -0,0 +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."

package/skill/skills/scaffold/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: scaffold
+description: Initialize Cadence project scaffolding for first-time setup. Use when the target project root does not yet contain a .cadence directory and Cadence must create initial state files before other workflow gates run.
+---
+
+# 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).
+3. If the script reports `scaffold-skipped`, treat scaffold as already satisfied and continue.
+4. If it errors, stop and surface the exact error to the user.
+5. Execute scaffold gate serially. Do not run it in parallel with other setup gates.

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

@@ -0,0 +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."