skillshop 2.0.0 → 2.1.0

package/skills-content/architecture-scanner/scan.sh

@@ -0,0 +1,823 @@
+#!/usr/bin/env bash
+#
+# scan.sh — Architecture scanner
+#
+# Scans the repository for architecturally significant files, maintains
+# a files.json index, and generates architecture documentation index.
+#
+# Usage: .agents/skills/architecture-scanner/scan.sh
+#   --discover   Scan repo, create/update files.json (preserves user-set priorities)
+#   --manifest   Print JSON array of non-low files to document (full scan)
+#   --full       Run discover + placeholders + index skeleton + verify
+#   --enrich     Run agent-enrichment planning pass only (no file writes)
+#   --enrich-all Run full agent-enrichment planning pass for all files (no file writes)
+#   --stale      Print manifest of files changed since last architecture commit (incremental)
+#   --verify     Validate manifest coverage and index/doc link consistency
+#   --index      Create the index skeleton if it does not exist
+#   --steps LIST  Run selected steps from: discover, manifest, docs, stale, enrich, enrich-all, index, verify
+
+set -euo pipefail
+shopt -s globstar nullglob
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+ARCH_DIR="$REPO_ROOT/.agents/architecture"
+SKILL_DIR="$REPO_ROOT/.agents/skills/architecture-scanner"
+FILES_JSON="$SKILL_DIR/files.json"
+export REPO_ROOT ARCH_DIR SKILL_DIR FILES_JSON
+
+# ── Discovery rules ──────────────────────────────────────────
+# Maps glob patterns to category|default_importance.
+# Globs are evaluated relative to REPO_ROOT.
+# Order matters: first match wins for a given file.
+DISCOVERY_RULES=(
+  # Root and package-level configuration
+  "config|high|vite.config.js"
+  "config|high|package*.json"
+  "config|high|pyproject.toml"
+  "config|high|Cargo.toml"
+  "config|high|go.mod"
+  "config|medium|eslint.config.js"
+  "config|low|playwright.config.*"
+
+  # Tests first so they stay low priority
+  "test|low|app/src/**/*.test.jsx"
+  "test|low|app/src/**/*.test.js"
+  "test|low|src/**/*.test.ts"
+  "test|low|src/**/*.test.tsx"
+  "test|low|src/**/*.spec.ts"
+  "test|low|src/**/*.spec.tsx"
+  "test|low|scripts/**/*.test.js"
+  "test|low|test/**/*.test.js"
+  "test|low|tests/**/*.py"
+  "test|low|tests/**/*.go"
+  "test|low|tests/**/*.rs"
+
+  # Common application entry points and interfaces
+  "entry|high|app/src/main.jsx"
+  "entry|high|src/main.js"
+  "entry|high|src/main.ts"
+  "entry|high|src/index.js"
+  "entry|high|src/index.ts"
+  "interface|high|app/src/**/*.jsx"
+  "interface|high|app/src/**/*.tsx"
+  "interface|medium|app/src/**/*.js"
+  "interface|medium|app/src/**/*.ts"
+
+  # Core implementation
+  "core|high|src/**/*.js"
+  "core|high|src/**/*.mjs"
+  "core|high|src/**/*.ts"
+  "core|high|src/**/*.tsx"
+  "core|high|src/**/*.py"
+  "core|high|src/**/*.go"
+  "core|high|src/**/*.rs"
+  "core|low|src/**/*.json"
+
+  # Common workspace package layouts
+  "config|high|packages/*/package.json"
+  "config|high|apps/*/package.json"
+  "config|high|crates/*/Cargo.toml"
+)
+
+# ── Helpers ──────────────────────────────────────────────────
+
+# Read existing importance for a path from files.json, or return empty string
+get_existing_importance() {
+  local filepath="$1"
+  if [ -f "$FILES_JSON" ]; then
+    # Use python3 for reliable JSON parsing
+    python3 -c "
+import json, sys
+with open('$FILES_JSON') as f:
+    data = json.load(f)
+files = data.get('files', data) if isinstance(data, dict) else data
+for entry in files:
+    if entry['path'] == '$filepath':
+        print(entry.get('importance', ''))
+        sys.exit(0)
+print('')
+" 2>/dev/null
+  fi
+}
+
+discover_files() {
+  # Collect discovered files
+  declare -A seen
+  declare -A discovered_cat
+  declare -A discovered_imp
+  local ordered_paths=()
+
+  for rule in "${DISCOVERY_RULES[@]}"; do
+    IFS='|' read -r category importance glob_pattern <<< "$rule"
+    for file in $REPO_ROOT/$glob_pattern; do
+      [ -f "$file" ] || continue
+      local relpath="${file#$REPO_ROOT/}"
+      if [[ -n "${seen[$relpath]+x}" ]]; then
+        continue
+      fi
+      seen[$relpath]=1
+      discovered_cat[$relpath]="$category"
+      discovered_imp[$relpath]="$importance"
+      ordered_paths+=("$relpath")
+    done
+  done
+
+  # Build new files.json, preserving existing importance values and categories
+  local tmp_json
+  tmp_json="$(mktemp)"
+
+  # Preserve existing categories array if present
+  python3 -c "
+import json
+try:
+    with open('$FILES_JSON') as f:
+        data = json.load(f)
+    if isinstance(data, dict) and 'categories' in data:
+        print(json.dumps(data['categories'], indent=4))
+    else:
+        print('null')
+except:
+    print('null')
+" > "${tmp_json}.cats"
+
+  local cats
+  cats="$(cat "${tmp_json}.cats")"
+  rm -f "${tmp_json}.cats"
+
+  if [ "$cats" = "null" ]; then
+    echo "{" > "$tmp_json"
+    echo '  "files": [' >> "$tmp_json"
+  else
+    echo "{" > "$tmp_json"
+    echo '  "categories": '"$cats"',' >> "$tmp_json"
+    echo '  "files": [' >> "$tmp_json"
+  fi
+
+  local first=true
+  for relpath in "${ordered_paths[@]}"; do
+    local category="${discovered_cat[$relpath]}"
+    local default_importance="${discovered_imp[$relpath]}"
+
+    # Preserve user-set importance if file already exists in files.json
+    local existing_importance
+    existing_importance="$(get_existing_importance "$relpath")"
+    local importance="${existing_importance:-$default_importance}"
+
+    if [ "$first" = true ]; then
+      first=false
+    else
+      echo "," >> "$tmp_json"
+    fi
+    printf '    { "path": "%s", "category": "%s", "importance": "%s" }' \
+      "$relpath" "$category" "$importance" >> "$tmp_json"
+  done
+
+  echo "" >> "$tmp_json"
+  echo "  ]" >> "$tmp_json"
+  echo "}" >> "$tmp_json"
+
+  mkdir -p "$SKILL_DIR"
+  mv "$tmp_json" "$FILES_JSON"
+
+  # Report what was found
+  echo "Discovered ${#ordered_paths[@]} files. Index updated:"
+  echo "  $FILES_JSON"
+  echo ""
+  echo "Files:"
+  for relpath in "${ordered_paths[@]}"; do
+    local category="${discovered_cat[$relpath]}"
+    local existing_importance
+    existing_importance="$(get_existing_importance "$relpath")"
+    local importance="$existing_importance"
+    printf "  %-12s %-6s %s\n" "[$category]" "$importance" "$relpath"
+  done
+}
+
+print_manifest() {
+  if [ ! -f "$FILES_JSON" ]; then
+    echo "files.json not found. Run --discover first." >&2
+    exit 1
+  fi
+  python3 -c "
+import json
+with open('$FILES_JSON') as f:
+    data = json.load(f)
+files = data.get('files', data) if isinstance(data, dict) else data
+categories = data.get('categories', []) if isinstance(data, dict) else []
+cat_map = {c['id']: c for c in categories}
+out = [e for e in files if e.get('importance') != 'low']
+for e in out:
+    e['doc'] = e['path'] + '.md'
+    cat = cat_map.get(e.get('category'), {})
+    e['category_priority'] = cat.get('priority', 'normal')
+print(json.dumps(out, indent=2))
+"
+}
+
+generate_placeholders() {
+  if [ ! -f "$FILES_JSON" ]; then
+    echo "files.json not found. Run --discover first." >&2
+    exit 1
+  fi
+  python3 - <<'PY'
+import json
+import os
+from pathlib import Path
+
+repo_root = os.environ["REPO_ROOT"]
+arch_dir = os.environ["ARCH_DIR"]
+files_json = os.environ["FILES_JSON"]
+
+with open(files_json) as f:
+    data = json.load(f)
+
+files = data.get("files", data) if isinstance(data, dict) else data
+tracked = [e for e in files if e.get("importance") != "low"]
+tracked_set = {e["path"] for e in tracked}
+
+Path(arch_dir).mkdir(parents=True, exist_ok=True)
+created = 0
+
+for entry in tracked:
+    source_path = os.path.join(repo_root, entry["path"])
+    if not os.path.isfile(source_path):
+        continue
+    doc_path = os.path.join(arch_dir, f"{entry['path']}.md")
+    if os.path.isfile(doc_path):
+        continue
+    Path(doc_path).parent.mkdir(parents=True, exist_ok=True)
+    index_link = os.path.relpath(os.path.join(arch_dir, "architecture.index.md"), os.path.dirname(doc_path)).replace(os.sep, "/")
+    doc_lines = [
+        f"# `{entry['path']}`",
+        "",
+        "<!--",
+        f"source: {entry['path']}",
+        f"category: {entry.get('category', 'core')}",
+        f"importance: {entry['importance']}",
+        "-->",
+        "",
+        f"> [\u2190 Architecture Index]({index_link})",
+        "",
+        "## Meaning",
+        "",
+        "<!-- Agent: explain what this file means in the architecture, why it exists, and what would be lost if it disappeared. -->",
+        "",
+        "## Composition",
+        "",
+        "<!-- Agent: describe the important exports, control flow, data shapes, and invariants using source evidence. Include small real code samples when useful. -->",
+        "",
+        "## Dependencies",
+        "",
+        "<!-- Agent: list meaningful dependencies and what each relationship contributes. Link architecture docs where they exist. -->",
+        "",
+        "## Dependents",
+        "",
+        "<!-- Agent: identify the important consumers and why they depend on this file. -->",
+        "",
+        "## Notes",
+        "",
+        "<!-- Agent: record sturdy-bit contracts, edge cases, decisions, and documentation/CR implications. -->",
+        "",
+    ]
+    with open(doc_path, "w", encoding="utf-8") as f:
+        f.write("\n".join(doc_lines))
+    created += 1
+
+for existing in Path(arch_dir).rglob("*.md"):
+    if existing.name == "architecture.index.md":
+        continue
+    rel = os.path.relpath(existing, repo_root).replace(os.sep, "/")
+    if rel.startswith("."):
+        continue
+    src = rel[:-3]
+    if src not in tracked_set:
+        existing.unlink()
+
+print(f"created_placeholders={created}")
+PY
+}
+
+print_stale() {
+  if [ ! -f "$FILES_JSON" ]; then
+    echo "files.json not found. Run --discover first." >&2
+    exit 1
+  fi
+  python3 -c "
+import json, os, subprocess, sys
+
+files_json = '$FILES_JSON'
+arch_dir = '$ARCH_DIR'
+repo_root = '$REPO_ROOT'
+index_file = os.path.join(arch_dir, 'architecture.index.md')
+
+with open(files_json) as f:
+    data = json.load(f)
+
+files = data.get('files', data) if isinstance(data, dict) else data
+categories = data.get('categories', []) if isinstance(data, dict) else []
+cat_map = {c['id']: c for c in categories}
+
+def git_name_only(args):
+    try:
+        out = subprocess.check_output(args, cwd=repo_root, text=True).strip()
+    except subprocess.CalledProcessError:
+        return set()
+    return set(out.splitlines()) if out else set()
+
+# Find the most recent commit that touched .agents/architecture/
+try:
+    last_arch_commit = subprocess.check_output(
+        ['git', 'log', '-1', '--format=%H', '--', '.agents/architecture/'],
+        cwd=repo_root, text=True
+    ).strip()
+except subprocess.CalledProcessError:
+    last_arch_commit = ''
+
+# Get list of source files changed since that commit (or all if no commit)
+changed_files = set()
+if last_arch_commit:
+    changed_files.update(git_name_only(['git', 'diff', '--name-only', last_arch_commit, 'HEAD']))
+    # Also include uncommitted changes (staged + unstaged)
+    changed_files.update(git_name_only(['git', 'diff', '--name-only', 'HEAD']))
+    changed_files.update(git_name_only(['git', 'diff', '--name-only', '--cached']))
+
+tracked = [e for e in files if e.get('importance') != 'low']
+tracked_paths = {e['path'] for e in tracked}
+
+results = []
+removed = []
+removed_docs = set()
+total_non_low_existing = 0
+
+for entry in tracked:
+    src_rel = entry['path']
+    src = os.path.join(repo_root, src_rel)
+    doc_rel = src_rel + '.md'
+    doc = os.path.join(arch_dir, doc_rel)
+    cat = cat_map.get(entry.get('category'), {})
+    category_priority = cat.get('priority', 'normal')
+
+    if os.path.isfile(src):
+        total_non_low_existing += 1
+        status = None
+        if not os.path.isfile(doc):
+            status = 'missing'
+        elif not last_arch_commit:
+            # No architecture commits exist yet — everything is stale
+            status = 'stale'
+        elif src_rel in changed_files:
+            status = 'stale'
+
+        if status:
+            e = {**entry, 'doc': doc_rel, 'status': status, 'category_priority': category_priority}
+            if status == 'missing' and src_rel in changed_files:
+                e['change_type'] = 'added'
+            results.append(e)
+    elif os.path.isfile(doc):
+        removed.append({
+            **entry,
+            'doc': doc_rel,
+            'status': 'removed',
+            'reason': 'source_deleted',
+            'category_priority': category_priority
+        })
+        removed_docs.add(doc_rel)
+
+# Find orphan docs for deleted/moved/untracked source files.
+for root, _, filenames in os.walk(arch_dir):
+    for name in filenames:
+        if not name.endswith('.md') or name == 'architecture.index.md':
+            continue
+        doc_abs = os.path.join(root, name)
+        doc_rel = os.path.relpath(doc_abs, arch_dir).replace(os.sep, '/')
+        if doc_rel in removed_docs:
+            continue
+        src_rel = doc_rel[:-3]
+        src = os.path.join(repo_root, src_rel)
+        if src_rel not in tracked_paths:
+            reason = 'untracked_source' if os.path.isfile(src) else 'source_deleted_or_moved'
+            removed.append({
+                'path': src_rel,
+                'doc': doc_rel,
+                'status': 'removed',
+                'reason': reason
+            })
+            removed_docs.add(doc_rel)
+
+index_reasons = []
+if not os.path.isfile(index_file):
+    index_reasons.append('index_missing')
+if results or removed:
+    index_reasons.append('assets_changed')
+if '.agents/skills/architecture-scanner/files.json' in changed_files:
+    index_reasons.append('category_config_changed')
+if any(
+    p.startswith('.agents/architecture/')
+    and p != '.agents/architecture/architecture.index.md'
+    for p in changed_files
+):
+    index_reasons.append('docs_changed')
+
+output = {
+    'index': {
+        'status': 'stale' if index_reasons else 'fresh',
+        'reasons': index_reasons
+    },
+    'files': results,
+    'removed': removed
+}
+
+# Suggest full scan if >50% of existing non-low files need regeneration.
+if total_non_low_existing > 0 and len(results) > total_non_low_existing * 0.5:
+    output['suggestion'] = 'full_scan'
+    output['message'] = (
+        f'{len(results)} of {total_non_low_existing} documented files need updates. '
+        'Consider running --manifest (or --full) for a full scan instead.'
+    )
+
+print(json.dumps(output, indent=2))
+"
+}
+
+verify_architecture() {
+  if [ ! -f "$FILES_JSON" ]; then
+    echo "files.json not found. Run --discover first." >&2
+    exit 1
+  fi
+  python3 - <<'PY'
+import json
+import os
+
+repo_root = os.environ["REPO_ROOT"]
+arch_dir = os.environ["ARCH_DIR"]
+files_json = os.environ["FILES_JSON"]
+
+with open(files_json) as f:
+    data = json.load(f)
+
+files = data.get("files", data) if isinstance(data, dict) else data
+tracked = [entry for entry in files if entry.get("importance") != "low"]
+tracked_docs = {f"{entry['path']}.md" for entry in tracked}
+tracked_sources = {entry["path"] for entry in tracked}
+
+index_file = os.path.join(arch_dir, "architecture.index.md")
+index_lines = []
+if os.path.isfile(index_file):
+    with open(index_file, "r", encoding="utf-8") as f:
+        index_lines = f.read().splitlines()
+
+results = {
+    "status": "ok",
+    "missing_docs": [],
+    "orphan_docs": [],
+    "index_missing": False,
+    "docs_missing_backlink": [],
+    "index_unlinked_docs": []
+}
+
+if not os.path.isfile(index_file):
+    results["status"] = "warn"
+    results["index_missing"] = True
+else:
+    indexed_docs = set()
+    for line in index_lines:
+        line = line.strip()
+        if line.startswith("- [") and "(" in line and ")" in line:
+            start = line.find("(")
+            end = line.find(")", start + 1)
+            if start != -1 and end != -1:
+                link = line[start + 1:end]
+                if link.startswith("./"):
+                    link = link[2:]
+                if link.endswith(".md"):
+                    indexed_docs.add(link)
+
+for relpath in sorted(tracked_docs):
+    doc = os.path.join(arch_dir, relpath)
+    if not os.path.isfile(doc):
+        results["status"] = "warn"
+        results["missing_docs"].append(relpath)
+        continue
+    with open(doc, "r", encoding="utf-8") as f:
+        text = f.read()
+    if "Architecture Index" not in text:
+        results["status"] = "warn"
+        results["docs_missing_backlink"].append(relpath)
+
+for root, _, filenames in os.walk(arch_dir):
+    for name in filenames:
+        if not name.endswith(".md") or name == "architecture.index.md":
+            continue
+        rel = os.path.relpath(os.path.join(root, name), arch_dir).replace(os.sep, "/")
+        if rel not in tracked_docs:
+            results["status"] = "warn"
+            results["orphan_docs"].append(rel)
+            continue
+        if rel not in indexed_docs:
+            results["status"] = "warn"
+            results["index_unlinked_docs"].append(rel)
+
+print(json.dumps(results, indent=2))
+PY
+}
+
+generate_index() {
+  mkdir -p "$ARCH_DIR"
+  local index_file="$ARCH_DIR/architecture.index.md"
+  if [ -f "$index_file" ]; then
+    echo "Preserved existing index: $index_file"
+    return
+  fi
+
+  python3 - <<'PY'
+import json
+import os
+from pathlib import Path
+
+repo_root = os.environ["REPO_ROOT"]
+arch_dir = Path(os.environ["ARCH_DIR"])
+files_json = os.environ["FILES_JSON"]
+index_path = arch_dir / "architecture.index.md"
+
+with open(files_json) as f:
+    data = json.load(f)
+
+files = data.get("files", data) if isinstance(data, dict) else data
+categories = data.get("categories", []) if isinstance(data, dict) else []
+category_map = {item["id"]: item for item in categories}
+tracked = [item for item in files if item.get("importance") != "low"]
+
+lines = [
+    "# Architecture Index",
+    "",
+    "> Structural index generated by the architecture-scanner skill.",
+    "> The agent owns the repository overview, category concepts, and file descriptions.",
+    "",
+    "## Repository overview",
+    "",
+    "<!-- Agent: explain what this repository is, the user/problem it serves, its major runtime surfaces, and the path of data through them. Ground this in package manifests and source. -->",
+    "",
+]
+
+ordered_categories = sorted(categories, key=lambda item: item.get("order", 99))
+for category in ordered_categories:
+    members = [item for item in tracked if item.get("category") == category.get("id")]
+    if not members:
+        continue
+    lines.extend([
+        f"## {category.get('name', category.get('id'))}",
+        "",
+        f"<!-- Agent: explain the concept represented by this category, its role in the repository, and how it relates to other categories. Priority: {category.get('priority', 'normal')}. -->",
+        "",
+    ])
+    for item in sorted(members, key=lambda value: value["path"]):
+        doc = f"{item['path']}.md"
+        lines.append(f"- [`{item['path']}`](./{doc}) <!-- Agent: add a concise meaning statement. -->")
+    lines.append("")
+
+index_path.write_text("\n".join(lines), encoding="utf-8")
+print(f"Created index skeleton: {index_path}")
+PY
+}
+
+build_enrich_plan() {
+  local enrich_mode="${1:-changed}"
+  if [ ! -f "$FILES_JSON" ]; then
+    echo "files.json not found. Run --discover first." >&2
+    exit 1
+  fi
+
+  ARCH_ENRICH_MODE="$enrich_mode" python3 - <<'PY'
+import json
+import os
+import subprocess
+
+repo_root = os.environ["REPO_ROOT"]
+arch_dir = os.environ["ARCH_DIR"]
+files_json = os.environ["FILES_JSON"]
+mode = os.environ.get("ARCH_ENRICH_MODE", "changed")
+
+with open(files_json) as f:
+    data = json.load(f)
+
+files = data.get("files", data) if isinstance(data, dict) else data
+tracked = [e for e in files if e.get("importance") != "low"]
+tracked_paths = {entry["path"] for entry in tracked}
+
+def changed_files(since_commit):
+    if not since_commit:
+        return set()
+    changed = set()
+    for args in (
+        ["git", "diff", "--name-only", since_commit, "HEAD"],
+        ["git", "diff", "--name-only", "HEAD"],
+        ["git", "diff", "--name-only", "--cached"],
+    ):
+        try:
+            out = subprocess.check_output(args, cwd=repo_root, text=True).strip()
+        except subprocess.CalledProcessError:
+            continue
+        if out:
+            changed.update(out.splitlines())
+    return changed
+
+
+try:
+    last_arch_commit = subprocess.check_output(
+        ["git", "log", "-1", "--format=%H", "--", ".agents/architecture/"],
+        cwd=repo_root,
+        text=True,
+    ).strip()
+except subprocess.CalledProcessError:
+    last_arch_commit = ""
+
+changed = changed_files(last_arch_commit)
+if not changed:
+    changed = set()
+
+create = []
+update = []
+delete = []
+
+for entry in tracked:
+    path = entry["path"]
+    category = entry.get("category", "core")
+    importance = entry.get("importance", "medium")
+    source_path = os.path.join(repo_root, path)
+    doc_rel = f"{path}.md"
+    doc_path = os.path.join(arch_dir, doc_rel)
+
+    if not os.path.isfile(source_path):
+        continue
+
+    task = {
+        "path": path,
+        "doc": doc_rel,
+        "category": category,
+        "importance": importance,
+        "enrichment_focus": [
+            "Write the file's architectural meaning and why it exists.",
+            "Explain behavior, data flow, contracts, and important relationships from source evidence.",
+            "Record edge cases, sturdy-bit implications, and relevant records."
+        ],
+        "status": "",
+        "reason": "",
+    }
+
+    try:
+        with open(doc_path, "r", encoding="utf-8") as doc_file:
+            existing_text = doc_file.read()
+    except Exception:
+        existing_text = ""
+
+    if existing_text:
+        lines = existing_text.splitlines()
+        for i, line in enumerate(lines):
+            if line.startswith("## Goal") and i + 1 < len(lines):
+                task["existing_goal_preview"] = lines[i + 1].strip()
+                break
+
+    if mode == "all":
+        if not os.path.isfile(doc_path):
+            task["status"] = "create"
+            task["reason"] = "missing_doc"
+            create.append(task)
+        else:
+            task["status"] = "update"
+            task["reason"] = "full_rewrite"
+            update.append(task)
+    else:
+        if not os.path.isfile(doc_path):
+            task["status"] = "create"
+            task["reason"] = "missing_doc"
+            create.append(task)
+        elif path in changed:
+            task["status"] = "update"
+            task["reason"] = "source_changed"
+            update.append(task)
+
+for root, _, names in os.walk(arch_dir):
+    for name in names:
+        if not name.endswith(".md") or name == "architecture.index.md":
+            continue
+        rel = os.path.relpath(os.path.join(root, name), arch_dir).replace(os.sep, "/")
+        src_rel = rel[:-3]
+        if src_rel not in tracked_paths and os.path.isfile(os.path.join(repo_root, src_rel)):
+            delete.append({"path": src_rel, "doc": rel, "reason": "not_tracked"})
+        elif src_rel not in tracked_paths:
+            delete.append({"path": src_rel, "doc": rel, "reason": "source_deleted_or_untracked"})
+
+output = {
+    "mode": "agent_enrichment",
+    "status": "ready",
+    "count": {
+        "create": len(create),
+        "update": len(update),
+        "delete": len(delete),
+    },
+    "notes": "The scanner provides structure only. The agent must read source and write the prose.",
+    "create": create,
+    "update": update,
+    "delete": delete,
+    "next_steps": [
+        "For each path in create/update, read the source and write the complete architecture document.",
+        "For each entry in delete, remove the stale architecture doc file.",
+        "Read and update architecture.index.md with the repository overview, category concepts, and file meanings; preserve authored prose.",
+        "Run .agents/skills/architecture-scanner/scan.sh --verify to confirm consistency.",
+    ],
+}
+
+print(json.dumps(output, indent=2))
+PY
+}
+
+run_steps() {
+  local steps_csv="${1:-}"
+  if [ -z "$steps_csv" ]; then
+    echo "--steps requires a comma-separated list" >&2
+    exit 1
+  fi
+
+  local old_ifs="$IFS"
+  IFS=','
+  for step in $steps_csv; do
+    case "$step" in
+      discover)
+        discover_files
+        ;;
+      manifest)
+        print_manifest
+        ;;
+      docs)
+        generate_placeholders
+        ;;
+      stale)
+        print_stale
+        ;;
+      enrich)
+        build_enrich_plan changed
+        ;;
+      enrich-all)
+        build_enrich_plan all
+        ;;
+      index)
+        generate_index
+        ;;
+      verify)
+        verify_architecture
+        ;;
+      *)
+        echo "Unknown step: $step" >&2
+        echo "Supported: discover, manifest, docs, stale, enrich, enrich-all, index, verify" >&2
+        exit 1
+        ;;
+    esac
+  done
+  IFS="$old_ifs"
+}
+
+case "${1:-}" in
+  --discover)
+    discover_files
+    ;;
+  --manifest)
+    print_manifest
+    ;;
+  --full)
+    discover_files
+    generate_placeholders
+    generate_index
+    verify_architecture
+    ;;
+  --enrich)
+    build_enrich_plan changed
+    ;;
+  --enrich-all)
+    build_enrich_plan all
+    ;;
+  --stale)
+    print_stale
+    ;;
+  --verify)
+    verify_architecture
+    ;;
+  --index)
+    generate_index
+    ;;
+  --steps)
+    run_steps "${2:-}"
+    ;;
+  *)
+    echo "Usage: $0 [--discover | --manifest | --full | --enrich | --enrich-all | --stale | --verify | --index | --steps]"
+    echo "  --discover   Scan repo and create/update files.json (preserves priorities)"
+    echo "  --manifest   Print JSON manifest of non-low files to document (full scan)"
+    echo "  --full       Discover + placeholders + index skeleton + verify"
+    echo "  --enrich     Generate an agent-only enrichment worklist (changed files only)"
+    echo "  --enrich-all Generate an agent-only enrichment worklist for all non-low files"
+    echo "  --stale      Print manifest of files changed since last architecture commit (incremental)"
+    echo "  --verify     Validate manifest coverage and index/doc links"
+    echo "  --index      Create the index skeleton if it does not exist"
+    echo "  --steps LIST  Run comma-separated steps"
+    exit 1
+    ;;
+esac