cadence-skill-installer 0.2.26 → 0.2.27

package/package.json

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

package/skill/SKILL.md

@@ -45,7 +45,8 @@ description: Structured project operating system for end-to-end greenfield or br
 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.
+4. If `.cadence` exists but `.cadence/cadence.json` is missing, invoke `skills/scaffold/SKILL.md` for recovery.
+5. If both `.cadence` and `.cadence/cadence.json` exist, skip scaffold.
 
 ## Workflow Route Gate (Mandatory At Entry And Transitions)
 1. After scaffold handling on Cadence entry, run `python3 scripts/read-workflow-state.py --project-root "$PROJECT_ROOT"` and parse the JSON response.
@@ -59,7 +60,12 @@ description: Structured project operating system for end-to-end greenfield or br
 
 ## Prerequisite Gate (Conditional)
 1. Invoke `skills/prerequisite-gate/SKILL.md` only when `route.skill_name` is `prerequisite-gate`.
-2. If `route.skill_name` is not `prerequisite-gate` (for example `ideator` or `researcher`), skip prerequisite gate and follow the active route instead.
+2. If `route.skill_name` is not `prerequisite-gate` (for example `brownfield-intake`, `ideator`, or `researcher`), skip prerequisite gate and follow the active route instead.
+
+## Project Mode Intake Gate (Conditional)
+1. Invoke `skills/brownfield-intake/SKILL.md` only when `route.skill_name` is `brownfield-intake`.
+2. Use this gate to classify `greenfield` vs `brownfield` execution mode and capture baseline inventory for existing codebases.
+3. If `route.skill_name` is not `brownfield-intake`, skip this gate and follow the active route instead.
 
 ## Progress / Resume Flow
 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?").
@@ -73,7 +79,7 @@ description: Structured project operating system for end-to-end greenfield or br
 5. Do not execute state-changing subskill steps when assertion fails.
 
 ## Ideation Flow
-1. When scaffold and prerequisite both complete in this same conversation for a net-new project and route advances to `ideator`, force a subskill handoff and end with this exact line: `Start a new chat and either say "help me define my project" or share your project brief.`
+1. When scaffold, prerequisite, and project mode intake complete in this same conversation for a net-new project and route advances to `ideator`, force a subskill handoff and end with this exact line: `Start a new chat and either say "help me define my project" or share your project brief.`
 2. In subsequent conversations, if the workflow route is `ideator`, do not rerun prerequisite gate.
 3. If the user asks to define the project or provides a brief while route is `ideator`, invoke `skills/ideator/SKILL.md`.
 4. If route is `ideator` and the user has not provided ideation input yet, ask one kickoff ideation question in-thread and continue.

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. Do not announce successful internal checks; only surface them when a check fails and blocks progress. At Cadence entry (first assistant response in a conversation), resolve PROJECT_ROOT with scripts/resolve-project-root.py --project-root \"$PWD\". If \"$PROJECT_ROOT/.cadence\" exists, run scripts/check-project-repo-status.py --project-root \"$PROJECT_ROOT\" and treat repo_enabled as the authoritative push mode (if false, keep commits local-only). Never run scripts/check-project-repo-status.py without --project-root. If \"$PROJECT_ROOT/.cadence\" is missing, run scaffold first and let scaffold establish repo mode. After scaffold handling, run scripts/read-workflow-state.py --project-root \"$PROJECT_ROOT\" and treat route.skill_name as authoritative for the next state-changing skill. During normal multi-turn subskill conversation flow, do not rerun repo/route gates between each user reply; rerun them only when checkpointing into a new subskill, handling explicit resume/status/reroute requests, or recovering from assertion/gate failures. Invoke skills/prerequisite-gate/SKILL.md only when route.skill_name is prerequisite-gate. If scaffold and prerequisite complete in-thread and route advances to ideator, force subskill handoff with: Start a new chat and either say \"help me define my project\" or share your project brief. In later chats, if route.skill_name is ideator, do not rerun prerequisite; invoke skills/ideator/SKILL.md in the same chat, and if the user has not provided ideation input yet, ask one kickoff ideation question in-thread instead of handing off again. When route advances from ideator to researcher, force a handoff with: Start a new chat with a new agent and say \"plan my project\". If route.skill_name is researcher, invoke skills/researcher/SKILL.md and enforce one pass per conversation; when more passes remain, end with: Start a new chat and say \"continue research\". 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, resolve PROJECT_ROOT with scripts/resolve-project-root.py --project-root \"$PWD\" and then run scripts/assert-workflow-route.py --skill-name <subskill> --project-root \"$PROJECT_ROOT\" before any state-changing actions. Ensure direct subskill execution follows the same Git Checkpoints policy from this main skill: run scripts/finalize-skill-checkpoint.py with each subskill's configured --scope/--checkpoint and --paths ., allow status=no_changes without failure, and treat checkpoint or push failures as blocking errors surfaced verbatim."
+  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. Do not announce successful internal checks; only surface them when a check fails and blocks progress. At Cadence entry (first assistant response in a conversation), resolve PROJECT_ROOT with scripts/resolve-project-root.py --project-root \"$PWD\". If \"$PROJECT_ROOT/.cadence\" exists, run scripts/check-project-repo-status.py --project-root \"$PROJECT_ROOT\" and treat repo_enabled as the authoritative push mode (if false, keep commits local-only). Never run scripts/check-project-repo-status.py without --project-root. If \"$PROJECT_ROOT/.cadence\" is missing, run scaffold first and let scaffold establish repo mode. If `.cadence` exists but `.cadence/cadence.json` is missing, run scaffold in recovery mode before routing. After scaffold handling, run scripts/read-workflow-state.py --project-root \"$PROJECT_ROOT\" and treat route.skill_name as authoritative for the next state-changing skill. During normal multi-turn subskill conversation flow, do not rerun repo/route gates between each user reply; rerun them only when checkpointing into a new subskill, handling explicit resume/status/reroute requests, or recovering from assertion/gate failures. Invoke skills/prerequisite-gate/SKILL.md only when route.skill_name is prerequisite-gate. Invoke skills/brownfield-intake/SKILL.md only when route.skill_name is brownfield-intake so project mode and brownfield baseline capture happen before ideation. If scaffold, prerequisite, and brownfield-intake complete in-thread and route advances to ideator, force subskill handoff with: Start a new chat and either say \"help me define my project\" or share your project brief. In later chats, if route.skill_name is ideator, do not rerun prerequisite or brownfield-intake; invoke skills/ideator/SKILL.md in the same chat, and if the user has not provided ideation input yet, ask one kickoff ideation question in-thread instead of handing off again. When route advances from ideator to researcher, force a handoff with: Start a new chat with a new agent and say \"plan my project\". If route.skill_name is researcher, invoke skills/researcher/SKILL.md and enforce one pass per conversation; when more passes remain, end with: Start a new chat and say \"continue research\". 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, resolve PROJECT_ROOT with scripts/resolve-project-root.py --project-root \"$PWD\" and then run scripts/assert-workflow-route.py --skill-name <subskill> --project-root \"$PROJECT_ROOT\" before any state-changing actions. Ensure direct subskill execution follows the same Git Checkpoints policy from this main skill: run scripts/finalize-skill-checkpoint.py with each subskill's configured --scope/--checkpoint and --paths ., allow status=no_changes without failure, and treat checkpoint or push failures as blocking errors surfaced verbatim."

package/skill/assets/cadence.json

@@ -4,10 +4,12 @@
         "ideation-completed": false,
         "research-completed": false,
         "cadence-scripts-dir": "",
-        "repo-enabled": false
+        "repo-enabled": false,
+        "project-mode": "unknown",
+        "brownfield-intake-completed": false
     },
     "workflow": {
-        "schema_version": 3,
+        "schema_version": 4,
         "plan": [
             {
                 "id": "milestone-foundation",
@@ -44,6 +46,16 @@
                                             "reason": "Prerequisite gate has not passed yet."
                                         }
                                     },
+                                    {
+                                        "id": "task-brownfield-intake",
+                                        "kind": "task",
+                                        "title": "Capture project mode and baseline",
+                                        "route": {
+                                            "skill_name": "brownfield-intake",
+                                            "skill_path": "skills/brownfield-intake/SKILL.md",
+                                            "reason": "Project mode and existing codebase baseline have not been captured yet."
+                                        }
+                                    },
                                     {
                                         "id": "task-ideation",
                                         "kind": "task",
@@ -72,7 +84,10 @@
             }
         ]
     },
-    "project-details": {},
+    "project-details": {
+        "mode": "unknown",
+        "brownfield_baseline": {}
+    },
     "ideation": {
         "research_agenda": {
             "version": 1,

package/skill/config/commit-conventions.json

@@ -104,6 +104,12 @@
                 "ideation-completed": "persist finalized ideation"
             }
         },
+        "brownfield-intake": {
+            "description": "Project mode classification and brownfield baseline capture",
+            "checkpoints": {
+                "baseline-captured": "capture project mode and baseline inventory"
+            }
+        },
         "ideation-updater": {
             "description": "Iterative ideation updates",
             "checkpoints": {

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

@@ -29,7 +29,9 @@ def load_state(project_root: Path, requested_skill: str) -> dict:
             )
             raise SystemExit(2)
         data = default_data()
-        return reconcile_workflow_state(data, cadence_dir_exists=cadence_exists)
+        # When `.cadence` exists but cadence.json is missing, recover through the
+        # scaffold route instead of treating scaffold as already complete.
+        return reconcile_workflow_state(data, cadence_dir_exists=False)
 
     try:
         with cadence_json_path.open("r", encoding="utf-8") as file:

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Check GitHub repo status and persist state.repo-enabled when .cadence exists."""
+"""Check repository remote status and persist state.repo-enabled when .cadence exists."""
 
 from __future__ import annotations
 
@@ -42,7 +42,13 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument(
         "--set-local-only",
         action="store_true",
-        help="Persist local-only mode (repo-enabled=false) when no GitHub remote is configured.",
+        help="Persist local-only mode (repo-enabled=false) when remote policy is not satisfied.",
+    )
+    parser.add_argument(
+        "--remote-policy",
+        choices=("any", "github"),
+        default="any",
+        help="Remote policy for repo-enabled detection.",
     )
     return parser.parse_args()
 
@@ -90,7 +96,7 @@ def parse_remotes(remote_text: str) -> list[dict[str, str]]:
     return remotes
 
 
-def detect_git_repo(project_root: Path) -> dict[str, Any]:
+def detect_git_repo(project_root: Path, *, remote_policy: str) -> 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"
 
@@ -101,12 +107,17 @@ def detect_git_repo(project_root: Path) -> dict[str, Any]:
             repo_root = root_result.stdout.strip()
 
     remotes: list[dict[str, str]] = []
+    primary_remote_name = ""
+    primary_remote_url = ""
     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)
+            if remotes:
+                primary_remote_name = remotes[0].get("name", "")
+                primary_remote_url = remotes[0].get("url", "")
 
         for remote in remotes:
             url = remote.get("url", "")
@@ -115,13 +126,21 @@ def detect_git_repo(project_root: Path) -> dict[str, Any]:
                 github_remote_url = url
                 break
 
+    remote_configured = bool(primary_remote_name and primary_remote_url)
     github_remote_configured = bool(github_remote_name and github_remote_url)
-    repo_enabled_detected = bool(git_initialized and github_remote_configured)
+    if remote_policy == "github":
+        repo_enabled_detected = bool(git_initialized and github_remote_configured)
+    else:
+        repo_enabled_detected = bool(git_initialized and remote_configured)
 
     return {
         "git_initialized": git_initialized,
         "repo_root": repo_root,
         "remotes": remotes,
+        "remote_policy": remote_policy,
+        "remote_configured": remote_configured,
+        "primary_remote_name": primary_remote_name,
+        "primary_remote_url": primary_remote_url,
         "github_remote_configured": github_remote_configured,
         "github_remote_name": github_remote_name,
         "github_remote_url": github_remote_url,
@@ -166,7 +185,7 @@ def main() -> int:
 
     write_project_root_hint(SCRIPT_DIR, project_root)
 
-    repo_status = detect_git_repo(project_root)
+    repo_status = detect_git_repo(project_root, remote_policy=args.remote_policy)
     cadence_exists = (project_root / CADENCE_JSON_PATH).exists()
     state_updated = False
 
@@ -202,6 +221,10 @@ def main() -> int:
         "state_updated": state_updated,
         "repo_enabled": repo_enabled_state,
         "repo_enabled_detected": bool(repo_status["repo_enabled_detected"]),
+        "remote_policy": str(repo_status.get("remote_policy", args.remote_policy)),
+        "remote_configured": bool(repo_status.get("remote_configured", False)),
+        "primary_remote_name": repo_status.get("primary_remote_name", ""),
+        "primary_remote_url": repo_status.get("primary_remote_url", ""),
         "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", ""),

package/skill/scripts/finalize-skill-checkpoint.py

@@ -32,6 +32,14 @@ def run_cmd(command: list[str], cwd: Path) -> subprocess.CompletedProcess[str]:
     )
 
 
+def resolve_repo_root(project_root: Path) -> Path:
+    result = run_cmd(["git", "rev-parse", "--show-toplevel"], project_root)
+    if result.returncode != 0:
+        detail = result.stderr.strip() or result.stdout.strip() or "NOT_A_GIT_REPOSITORY"
+        raise FinalizeError(detail)
+    return Path(result.stdout.strip()).resolve()
+
+
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(
         description="Create atomic checkpoint commits for changed files at skill finalization.",
@@ -129,6 +137,61 @@ def sanitize_tag(tag: str) -> str:
     return compact[:10]
 
 
+def project_relative_root(repo_root: Path, project_root: Path) -> str:
+    try:
+        relative = project_root.resolve().relative_to(repo_root.resolve())
+    except ValueError as exc:
+        raise FinalizeError("PROJECT_ROOT_OUTSIDE_REPOSITORY") from exc
+    text = normalize_path(relative.as_posix())
+    return "." if text in {"", "."} else text
+
+
+def normalize_requested_pathspecs(
+    *,
+    requested_pathspecs: list[str],
+    project_root: Path,
+    repo_root: Path,
+) -> list[str]:
+    project_rel = project_relative_root(repo_root, project_root)
+    normalized_specs: list[str] = []
+
+    for raw in requested_pathspecs:
+        text = str(raw).strip()
+        if not text or text == ".":
+            normalized = project_rel
+        else:
+            candidate = Path(text)
+            if candidate.is_absolute():
+                try:
+                    relative = candidate.resolve().relative_to(repo_root.resolve())
+                except ValueError as exc:
+                    raise FinalizeError(f"PATHSPEC_OUTSIDE_REPOSITORY: {text}") from exc
+                normalized = normalize_path(relative.as_posix())
+            else:
+                parts = candidate.parts
+                if any(part == ".." for part in parts):
+                    raise FinalizeError(f"PATHSPEC_OUTSIDE_PROJECT_ROOT: {text}")
+                rel_text = normalize_path(text)
+                if project_rel == ".":
+                    normalized = rel_text
+                else:
+                    normalized = normalize_path(f"{project_rel}/{rel_text}")
+
+        if project_rel != ".":
+            project_prefix = project_rel.rstrip("/")
+            if normalized != project_prefix and not normalized.startswith(f"{project_prefix}/"):
+                raise FinalizeError(f"PATHSPEC_OUTSIDE_PROJECT_ROOT: {text}")
+
+        if not normalized:
+            normalized = "."
+        if normalized not in normalized_specs:
+            normalized_specs.append(normalized)
+
+    if not normalized_specs:
+        return [project_rel]
+    return normalized_specs
+
+
 def classify_path(
     path: str,
     group_order: list[str],
@@ -324,6 +387,17 @@ def main() -> int:
         print("LOCAL_GIT_REPOSITORY_NOT_INITIALIZED", file=sys.stderr)
         return 2
 
+    try:
+        repo_root = resolve_repo_root(project_root)
+        scoped_pathspecs = normalize_requested_pathspecs(
+            requested_pathspecs=[str(path) for path in args.paths],
+            project_root=project_root,
+            repo_root=repo_root,
+        )
+    except FinalizeError as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+
     push_enabled = bool(repo_status.get("repo_enabled", False))
 
     status_result = run_cmd(
@@ -356,7 +430,7 @@ def main() -> int:
         )
         return 0
 
-    eligible_files = filter_paths(changed_files, args.paths)
+    eligible_files = filter_paths(changed_files, scoped_pathspecs)
     if not eligible_files:
         print(
             json.dumps(
@@ -399,20 +473,21 @@ def main() -> int:
 
     print(
         json.dumps(
-            {
-                "status": "ok",
-                "scope": args.scope,
-                "checkpoint": args.checkpoint,
-                "atomic": True,
+                {
+                    "status": "ok",
+                    "scope": args.scope,
+                    "checkpoint": args.checkpoint,
+                    "atomic": True,
                 "changed_file_count": len(eligible_files),
                 "batch_count": len(batches),
-                "commit_count": len(commits),
-                "push_enabled": push_enabled,
-                "repo_status": repo_status,
-                "commits": commits,
-            }
+                    "commit_count": len(commits),
+                    "push_enabled": push_enabled,
+                    "scoped_pathspecs": scoped_pathspecs,
+                    "repo_status": repo_status,
+                    "commits": commits,
+                }
+            )
         )
-    )
     return 0
 
 

package/skill/scripts/read-workflow-state.py

@@ -38,7 +38,9 @@ def load_state(project_root: Path):
 
     if not cadence_json_path.exists():
         data = default_data()
-        data = reconcile_workflow_state(data, cadence_dir_exists=cadence_exists)
+        # When `.cadence` exists without cadence.json, initialize recovery state
+        # with scaffold pending so route guards can re-enter scaffold safely.
+        data = reconcile_workflow_state(data, cadence_dir_exists=False)
         if cadence_exists:
             save_state(project_root, data)
         return data