cadence-skill-installer 0.2.5 → 0.2.6

package/package.json

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

package/skill/SKILL.md

@@ -9,6 +9,28 @@ description: Structured project operating system for end-to-end greenfield or br
 1. Keep this root skill as an orchestrator.
 2. Delegate concrete execution to focused subskills.
 
+## Response Hygiene
+1. Keep user-facing replies outcome-focused and concise.
+2. Do not expose internal execution details unless the user explicitly asks for them:
+   - skill routing chains
+   - gate-by-gate status narration
+   - raw commands, terminal traces, or timing metadata
+
+## Repo Status Gate
+1. At the start of every Cadence turn, run `python3 scripts/check-project-repo-status.py` (resolve this relative path from this skill directory).
+2. Read `repo_enabled` from script output and treat it as the authoritative push mode.
+3. If `repo_enabled` is false, continue with local commits only until a GitHub remote is configured.
+
+## Git Checkpoints
+1. Enforce Cadence commit convention from `config/commit-conventions.json`.
+2. At the end of each successful subskill conversation, run `scripts/finalize-skill-checkpoint.py` with configured `--scope` and `--checkpoint` values.
+3. `finalize-skill-checkpoint.py` must check git diff first, split changes into atomic semantic batches, and create multiple small checkpoint commits when needed before push.
+4. `finalize-skill-checkpoint.py` must use repo status output so commits are local-only when `repo_enabled` is false.
+5. Use `--paths .` unless a narrower path is explicitly required, so commits include any files changed by the skill.
+6. Treat checkpoint or push failures as blocking; surface the exact script error to the user.
+7. If finalization returns `status=no_changes`, continue without failure.
+8. Do not gate checkpoint commits on test results yet; add that gate only when explicitly introduced later.
+
 ## Scaffold Gate (Mandatory On First Turn)
 1. Check for `.cadence` in the project root.
 2. If `.cadence` is missing, invoke `skills/scaffold/SKILL.md`.
@@ -26,7 +48,7 @@ description: Structured project operating system for end-to-end greenfield or br
 ## 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.
-3. Tell the user exactly: `now make a new chat and say "help me define my project" or provide a project brief.`
+3. Tell the user: `Start a new chat and either say "help me define my project" or share your project brief.`
 4. Stop here and wait for the user to continue in the new chat.
 
 ## Ideation Update Flow

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). 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: now make a new chat and say \"help me define my project\" or provide a 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. 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/assets/AGENTS.md

@@ -36,6 +36,10 @@
 - Zero context switching required from the user
 - Go fix failing CI tests without being told how
 
+### 7. User-Facing Hygiene
+- Keep user-facing messages outcome-focused
+- Do not expose internal routing, command traces, terminal transcripts, or timing metadata unless the user explicitly asks
+
 ## Task Management
 
 1. **Plan First**: Write plan to `.cadence/tasks/todo.md` with checkable items

package/skill/assets/cadence.json

@@ -2,7 +2,8 @@
     "prerequisites-pass": false,
     "state": {
         "ideation-completed": false,
-        "cadence-scripts-dir": ""
+        "cadence-scripts-dir": "",
+        "repo-enabled": false
     },
     "workflow": {
         "schema_version": 2,

package/skill/config/commit-conventions.json

@@ -0,0 +1,120 @@
+{
+    "schema_version": 1,
+    "commit_type": "cadence",
+    "subject_max_length": 72,
+    "default_remote": "origin",
+    "atomic": {
+        "max_files_per_commit": 4,
+        "group_order": [
+            "cadence-state",
+            "skill-instructions",
+            "docs",
+            "scripts",
+            "tests",
+            "config",
+            "source"
+        ],
+        "groups": {
+            "cadence-state": {
+                "tag": "state",
+                "label": "cadence state",
+                "patterns": [
+                    ".cadence/**"
+                ]
+            },
+            "skill-instructions": {
+                "tag": "skills",
+                "label": "skill instructions",
+                "patterns": [
+                    "**/SKILL.md",
+                    "**/AGENTS.md"
+                ]
+            },
+            "docs": {
+                "tag": "docs",
+                "label": "documentation",
+                "patterns": [
+                    "docs/**",
+                    "**/*.md"
+                ]
+            },
+            "scripts": {
+                "tag": "scripts",
+                "label": "automation scripts",
+                "patterns": [
+                    "scripts/**",
+                    "**/*.py",
+                    "**/*.sh"
+                ]
+            },
+            "tests": {
+                "tag": "tests",
+                "label": "test updates",
+                "patterns": [
+                    "tests/**",
+                    "**/*test*",
+                    "**/*.spec.*"
+                ]
+            },
+            "config": {
+                "tag": "config",
+                "label": "configuration",
+                "patterns": [
+                    ".gitignore",
+                    "**/.gitignore",
+                    "package.json",
+                    "package-lock.json",
+                    "pnpm-lock.yaml",
+                    "yarn.lock",
+                    "**/*.json",
+                    "**/*.yaml",
+                    "**/*.yml",
+                    "**/*.toml",
+                    "**/*.ini"
+                ]
+            },
+            "source": {
+                "tag": "src",
+                "label": "source changes",
+                "patterns": [
+                    "src/**",
+                    "app/**",
+                    "lib/**"
+                ]
+            }
+        }
+    },
+    "scopes": {
+        "scaffold": {
+            "description": "Scaffold and repository visibility policy",
+            "checkpoints": {
+                "cadence-tracked": "track .cadence and persist scaffold state",
+                "cadence-ignored": "ignore .cadence and persist scaffold state"
+            }
+        },
+        "prerequisite-gate": {
+            "description": "Prerequisite gate state transitions",
+            "checkpoints": {
+                "prerequisites-passed": "persist prerequisite gate pass state"
+            }
+        },
+        "ideator": {
+            "description": "Initial ideation persistence",
+            "checkpoints": {
+                "ideation-completed": "persist finalized ideation"
+            }
+        },
+        "ideation-updater": {
+            "description": "Iterative ideation updates",
+            "checkpoints": {
+                "ideation-updated": "persist ideation updates"
+            }
+        },
+        "project-progress": {
+            "description": "Project progress routing checks",
+            "checkpoints": {
+                "progress-checked": "check progress and route next action"
+            }
+        }
+    }
+}

package/skill/scripts/check-project-repo-status.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+"""Check GitHub repo status and persist state.repo-enabled when .cadence exists."""
+
+from __future__ import annotations
+
+import argparse
+import copy
+import json
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+from workflow_state import default_data, reconcile_workflow_state
+
+
+CADENCE_DIR = Path(".cadence")
+CADENCE_JSON_PATH = CADENCE_DIR / "cadence.json"
+
+
+def run_command(command: list[str], cwd: Path) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        command,
+        cwd=str(cwd),
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Check project repo readiness and persist Cadence repo-enabled state.",
+    )
+    parser.add_argument(
+        "--project-root",
+        default=".",
+        help="Project root where git and .cadence state should be evaluated.",
+    )
+    parser.add_argument(
+        "--set-local-only",
+        action="store_true",
+        help="Persist local-only mode (repo-enabled=false) when no GitHub remote is configured.",
+    )
+    return parser.parse_args()
+
+
+def load_cadence_data(project_root: Path) -> dict[str, Any] | None:
+    cadence_path = project_root / CADENCE_JSON_PATH
+    cadence_dir = project_root / CADENCE_DIR
+    if not cadence_path.exists():
+        return None
+
+    try:
+        with cadence_path.open("r", encoding="utf-8") as file:
+            raw = json.load(file)
+    except json.JSONDecodeError as exc:
+        print(f"INVALID_CADENCE_JSON: {exc}", file=sys.stderr)
+        raise SystemExit(1)
+
+    return reconcile_workflow_state(raw, cadence_dir_exists=cadence_dir.exists())
+
+
+def save_cadence_data(project_root: Path, data: dict[str, Any]) -> None:
+    cadence_path = project_root / CADENCE_JSON_PATH
+    cadence_path.parent.mkdir(parents=True, exist_ok=True)
+    with cadence_path.open("w", encoding="utf-8") as file:
+        json.dump(data, file, indent=4)
+        file.write("\n")
+
+
+def parse_remotes(remote_text: str) -> list[dict[str, str]]:
+    remotes: list[dict[str, str]] = []
+    seen: set[tuple[str, str]] = set()
+
+    for line in remote_text.splitlines():
+        parts = line.split()
+        if len(parts) < 2:
+            continue
+        name = parts[0].strip()
+        url = parts[1].strip()
+        key = (name, url)
+        if not name or not url or key in seen:
+            continue
+        seen.add(key)
+        remotes.append({"name": name, "url": url})
+
+    return remotes
+
+
+def detect_git_repo(project_root: Path) -> dict[str, Any]:
+    inside_result = run_command(["git", "rev-parse", "--is-inside-work-tree"], project_root)
+    git_initialized = inside_result.returncode == 0 and inside_result.stdout.strip() == "true"
+
+    repo_root = ""
+    if git_initialized:
+        root_result = run_command(["git", "rev-parse", "--show-toplevel"], project_root)
+        if root_result.returncode == 0:
+            repo_root = root_result.stdout.strip()
+
+    remotes: list[dict[str, str]] = []
+    github_remote_name = ""
+    github_remote_url = ""
+    if git_initialized:
+        remote_result = run_command(["git", "remote", "-v"], project_root)
+        if remote_result.returncode == 0:
+            remotes = parse_remotes(remote_result.stdout)
+
+        for remote in remotes:
+            url = remote.get("url", "")
+            if "github.com" in url.lower() or "github." in url.lower():
+                github_remote_name = remote.get("name", "")
+                github_remote_url = url
+                break
+
+    github_remote_configured = bool(github_remote_name and github_remote_url)
+    repo_enabled_detected = bool(git_initialized and github_remote_configured)
+
+    return {
+        "git_initialized": git_initialized,
+        "repo_root": repo_root,
+        "remotes": remotes,
+        "github_remote_configured": github_remote_configured,
+        "github_remote_name": github_remote_name,
+        "github_remote_url": github_remote_url,
+        "repo_enabled_detected": repo_enabled_detected,
+    }
+
+
+def ensure_default_state(data: dict[str, Any]) -> dict[str, Any]:
+    reconciled = reconcile_workflow_state(data, cadence_dir_exists=True)
+    state = reconciled.setdefault("state", {})
+    if not isinstance(state, dict):
+        state = {}
+        reconciled["state"] = state
+    state["repo-enabled"] = bool(state.get("repo-enabled", False))
+    return reconciled
+
+
+def main() -> int:
+    args = parse_args()
+    project_root = Path(args.project_root).resolve()
+
+    repo_status = detect_git_repo(project_root)
+    cadence_exists = (project_root / CADENCE_JSON_PATH).exists()
+    state_updated = False
+
+    data = load_cadence_data(project_root)
+    if data is None and cadence_exists:
+        # Safety fallback for race conditions between exists check and file read.
+        data = default_data()
+
+    repo_enabled_state = bool(repo_status["repo_enabled_detected"])
+    if data is not None:
+        original = copy.deepcopy(data)
+        data = ensure_default_state(data)
+        state = data["state"]
+
+        if repo_status["repo_enabled_detected"]:
+            state["repo-enabled"] = True
+        elif args.set_local_only:
+            state["repo-enabled"] = False
+        else:
+            state["repo-enabled"] = False
+
+        repo_enabled_state = bool(state.get("repo-enabled", False))
+        if data != original:
+            save_cadence_data(project_root, data)
+            state_updated = True
+
+    response = {
+        "status": "ok",
+        "project_root": str(project_root),
+        "cadence_state_path": str(project_root / CADENCE_JSON_PATH),
+        "cadence_state_available": data is not None,
+        "state_updated": state_updated,
+        "repo_enabled": repo_enabled_state,
+        "repo_enabled_detected": bool(repo_status["repo_enabled_detected"]),
+        "git_initialized": bool(repo_status["git_initialized"]),
+        "github_remote_configured": bool(repo_status["github_remote_configured"]),
+        "github_remote_name": repo_status.get("github_remote_name", ""),
+        "github_remote_url": repo_status.get("github_remote_url", ""),
+        "set_local_only": bool(args.set_local_only),
+    }
+    print(json.dumps(response))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skill/scripts/configure-cadence-gitignore.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""Update project .gitignore policy for .cadence visibility."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+
+TARGET_PATTERNS = {".cadence", ".cadence/"}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Configure whether .cadence should be tracked or ignored by git.",
+    )
+    parser.add_argument(
+        "--mode",
+        choices=["track", "ignore"],
+        required=True,
+        help="track removes .cadence ignore entries; ignore adds .cadence/ entry",
+    )
+    parser.add_argument(
+        "--gitignore-path",
+        default=".gitignore",
+        help="Path to .gitignore file",
+    )
+    return parser.parse_args()
+
+
+def normalize_lines(text: str) -> list[str]:
+    return text.splitlines()
+
+
+def apply_mode(lines: list[str], mode: str) -> list[str]:
+    filtered = [line for line in lines if line.strip() not in TARGET_PATTERNS]
+    if mode == "ignore":
+        filtered.append(".cadence/")
+    return filtered
+
+
+def render_lines(lines: list[str]) -> str:
+    if not lines:
+        return ""
+    return "\n".join(lines) + "\n"
+
+
+def main() -> int:
+    args = parse_args()
+    gitignore_path = Path(args.gitignore_path)
+
+    original_text = ""
+    if gitignore_path.exists():
+        original_text = gitignore_path.read_text(encoding="utf-8")
+
+    original_lines = normalize_lines(original_text)
+    updated_lines = apply_mode(original_lines, args.mode)
+    updated_text = render_lines(updated_lines)
+    changed = updated_text != original_text
+
+    if changed:
+        gitignore_path.write_text(updated_text, encoding="utf-8")
+
+    print(
+        json.dumps(
+            {
+                "status": "ok",
+                "mode": args.mode,
+                "path": str(gitignore_path),
+                "changed": changed,
+            }
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())