bigpowers 1.2.3 → 1.3.1

package/scripts/convert-legado.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+# convert-legado.sh — RELEASE-PLAN.md + SCOPE.md → YAML layout (one-time migration helper)
+set -euo pipefail
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SPECS="$REPO_ROOT/specs"
+RP_MD="$SPECS/RELEASE-PLAN.md"
+SCOPE_MD="$SPECS/SCOPE.md"
+STATE_MD="$SPECS/STATE.md"
+
+mkdir -p "$SPECS/requirements/snapshots" "$SPECS/epics" "$SPECS/archive"
+
+if [[ ! -f "$RP_MD" ]]; then
+  echo "convert-legado: no $RP_MD — skip"
+  exit 0
+fi
+
+# Archive legacy MD if YAML already exists (idempotent)
+archive_if_needed() {
+  local src="$1"
+  [[ -f "$src" ]] || return 0
+  local base
+  base=$(basename "$src")
+  if [[ ! -f "$SPECS/archive/$base" ]]; then
+    cp "$src" "$SPECS/archive/$base"
+    echo "archived: specs/archive/$base"
+  fi
+}
+
+# Parse ### WSn — Title · WSJF X.X from RELEASE-PLAN.md
+python3 - "$RP_MD" "$SPECS" <<'PY'
+import json
+import re
+import sys
+from pathlib import Path
+
+rp = Path(sys.argv[1])
+specs = Path(sys.argv[2])
+text = rp.read_text(encoding="utf-8")
+
+version = "3.0.0"
+m = re.search(r"v(\d+\.\d+\.\d+)", text)
+if m:
+    version = m.group(1)
+
+epics = []
+for m in re.finditer(r"^### WS(\d+)\s+—\s+(.+?)\s+·\s+WSJF\s+([\d.]+)", text, re.M):
+    n, title, wsjf = m.groups()
+    eid = f"e{int(n):02d}"
+    slug = re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-")[:40]
+    epics.append((eid, title.strip(), float(wsjf), slug))
+
+epic_lines = []
+status_lines = []
+for eid, title, wsjf, slug in epics:
+    fname = f"epics/{eid}-{slug}.yaml"
+    tj = json.dumps(title.strip())
+    epic_lines.append(
+        f"  - id: {eid}\n    title: {tj}\n    wsjf: {wsjf}\n    file: {fname}\n    mode: flat"
+    )
+    status_lines.append(f"  {eid}: done")
+
+    epic_path = specs / fname
+    if not epic_path.exists():
+        epic_path.write_text(
+            f"id: {eid}\ntitle: {tj}\nwsjf: {wsjf}\ncovers: []\nstories: []\n",
+            encoding="utf-8",
+        )
+
+release_yaml = f"""release:
+  version: "{version}"
+  codename: Consolidation
+  status: in_progress
+  semantic_release: true
+  bump_hint: minor
+epics:
+{chr(10).join(epic_lines)}
+"""
+(specs / "release-plan.yaml").write_text(release_yaml, encoding="utf-8")
+
+exec_yaml = "development_status:\n" + "\n".join(status_lines) + "\n"
+(specs / "execution-status.yaml").write_text(exec_yaml, encoding="utf-8")
+print(f"convert-legado: wrote release-plan.yaml ({len(epics)} epics) + execution-status.yaml")
+PY
+
+# state.yaml from STATE.md or default
+branch=$(git -C "$REPO_ROOT" branch --show-current 2>/dev/null || echo "main")
+hash=$(git -C "$REPO_ROOT" rev-parse --short HEAD 2>/dev/null || echo "unknown")
+
+if [[ ! -f "$SPECS/state.yaml" ]]; then
+  cat > "$SPECS/state.yaml" <<EOF
+active_flow: build_epic
+active_epic_id: e01
+active_story_id: null
+release:
+  target_version: "3.0.0"
+  last_tag: null
+  last_publish: null
+epic_cycle:
+  current_step: null
+  next_skill: survey-context
+  completed_steps: []
+git:
+  branch: $branch
+  hash: $hash
+handoff:
+  last_step_completed: null
+  open_decisions: []
+  next_skill: survey-context
+EOF
+  echo "convert-legado: wrote state.yaml"
+fi
+
+# requirements/SCOPE stub from SCOPE.md if missing
+if [[ -f "$SCOPE_MD" && ! -f "$SPECS/requirements/SCOPE_LATEST.yaml" ]]; then
+  mkdir -p "$SPECS/requirements"
+  python3 - "$SCOPE_MD" "$SPECS/requirements/SCOPE_LATEST.yaml" <<'PY'
+import sys
+from pathlib import Path
+src = Path(sys.argv[1]).read_text(encoding="utf-8")
+out = Path(sys.argv[2])
+# Minimal YAML wrapper — full parse is manual follow-up
+body = src.replace('"', '\\"').replace("\n", "\\n")
+out.write_text(
+    'version: "1"\n'
+    'source: specs/SCOPE.md\n'
+    'migrated: true\n'
+    'summary: "See specs/archive/SCOPE.md for prose; refine this file with scope-work"\n',
+    encoding="utf-8",
+)
+print("convert-legado: wrote requirements/SCOPE_LATEST.yaml (stub)")
+PY
+fi
+
+if [[ ! -f "$SPECS/requirements/VISION_LATEST.yaml" ]]; then
+  mkdir -p "$SPECS/requirements"
+  cat > "$SPECS/requirements/VISION_LATEST.yaml" <<'EOF'
+version: "1"
+north_star: "Maintain senior-grade quality while scaling agentic autonomy"
+success_criteria:
+  - "Compliance suite >= 94%"
+  - "59 skills synced and documented"
+out_of_scope:
+  - "Domain-specific scaffold skills"
+  - "SaaS tracker integrations"
+EOF
+  echo "convert-legado: wrote requirements/VISION_LATEST.yaml"
+fi
+
+archive_if_needed "$RP_MD"
+archive_if_needed "$SCOPE_MD"
+archive_if_needed "$STATE_MD"
+
+bash "$REPO_ROOT/scripts/validate-specs-yaml.sh" "$SPECS"

package/scripts/enrich-epics-from-archive.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# enrich-epics-from-archive.sh — populate specs/epics from archive RELEASE-PLAN.md
+set -euo pipefail
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+ARCHIVE="${1:-$REPO_ROOT/specs/archive/RELEASE-PLAN.md}"
+SPECS="$REPO_ROOT/specs"
+
+python3 - "$ARCHIVE" "$SPECS" <<'PY'
+import json
+import re
+import sys
+from pathlib import Path
+
+archive = Path(sys.argv[1])
+specs = Path(sys.argv[2])
+text = archive.read_text(encoding="utf-8")
+
+epic_re = re.compile(
+    r"^### WS(\d+)\s+—\s+(.+?)\s+·\s+WSJF\s+([\d.]+)\s*$", re.M
+)
+sections = []
+for m in epic_re.finditer(text):
+    start = m.end()
+    nxt = epic_re.search(text, start)
+    end = nxt.start() if nxt else len(text)
+    sections.append((m.group(1), m.group(2).strip(), float(m.group(3)), text[start:end]))
+
+status_lines = []
+for n, title, wsjf, body in sections:
+    eid = f"e{int(n):02d}"
+    slug = re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-")[:40]
+    fname = f"epics/{eid}-{slug}.yaml"
+    epic_path = specs / fname
+
+    tasks_raw = []
+    for line in body.splitlines():
+        lm = re.match(r"^-\s+\[[ xX]\]\s+(.+)$", line.strip())
+        if lm:
+            tasks_raw.append(lm.group(1).strip())
+    verify_m = re.search(r"→\s*verify:\s*`([^`]+)`", body)
+    epic_verify = verify_m.group(1) if verify_m else None
+
+    sid = f"{eid}s01"
+    story_tasks = []
+    for i, t in enumerate(tasks_raw, start=1):
+        tid = f"{eid}s{i:02d}" if len(tasks_raw) > 1 else sid
+        story_tasks.append({"desc": t, "verify": epic_verify or "true"})
+        status_lines.append(f"  {tid}: done")
+
+    if not story_tasks and epic_verify:
+        story_tasks.append({"desc": title, "verify": epic_verify})
+
+    stories_yaml = []
+    if len(story_tasks) == 1:
+        stories_yaml.append(
+            {
+                "id": sid,
+                "title": title,
+                "tasks": story_tasks,
+            }
+        )
+        status_lines.append(f"  {eid}: done")
+    else:
+        for i, t in enumerate(tasks_raw, start=1):
+            tid = f"{eid}s{i:02d}"
+            stories_yaml.append(
+                {
+                    "id": tid,
+                    "title": t[:80],
+                    "tasks": [{"desc": t, "verify": epic_verify or "true"}],
+                }
+            )
+        status_lines.append(f"  {eid}: done")
+
+    tj = json.dumps(title)
+    lines = [
+        f"id: {eid}",
+        f"title: {tj}",
+        f"wsjf: {wsjf}",
+        "covers: []",
+        "stories:",
+    ]
+    for st in stories_yaml:
+        lines.append(f"  - id: {st['id']}")
+        lines.append(f"    title: {json.dumps(st['title'])}")
+        lines.append("    tasks:")
+        for task in st["tasks"]:
+            lines.append(f"      - desc: {json.dumps(task['desc'])}")
+            lines.append(f"        verify: {json.dumps(task['verify'])}")
+    epic_path.parent.mkdir(parents=True, exist_ok=True)
+    epic_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+exec_path = specs / "execution-status.yaml"
+exec_path.write_text(
+    "development_status:\n" + "\n".join(dict.fromkeys(status_lines)) + "\n",
+    encoding="utf-8",
+)
+print(f"enrich-epics: wrote {len(sections)} epics + execution-status.yaml")
+PY
+
+bash "$REPO_ROOT/scripts/validate-specs-yaml.sh" "$SPECS"

package/scripts/land-branch.sh

@@ -88,7 +88,11 @@ run_verify_suite() {
     if jq -e '.scripts.test' package.json >/dev/null 2>&1; then
       local test_script
       test_script=$(jq -r '.scripts.test' package.json)
-      if [ "$test_script" != "echo \"Error: no test specified\" && exit 1" ] && [ "$test_script" != "false" ]; then
+      if [ "$test_script" = "echo \"Error: no test specified\" && exit 1" ]; then
+        :
+      elif [ "$test_script" = "false" ]; then
+        :
+      else
         npm test
         return
       fi

package/scripts/project-survey.sh

@@ -8,10 +8,14 @@ has_conventions=$([[ -f "CONVENTIONS.md" ]] && echo "true" || echo "false")
 has_claude=$([[ -f "CLAUDE.md" ]] && echo "true" || echo "false")
 has_specs=$([[ -d "specs" ]] && echo "true" || echo "false")
 
-# 2. Scan specs/
+# 2. Scan specs/ (YAML-first)
 specs_files=""
 if [[ "$has_specs" == "true" ]]; then
-  specs_files=$(ls specs/*.md 2>/dev/null | xargs -n1 basename | tr '\n' ',' | sed 's/,$//')
+  specs_files=$( {
+    ls specs/*.yaml 2>/dev/null || true
+    ls specs/requirements/*.yaml 2>/dev/null || true
+    ls specs/*.md 2>/dev/null || true
+  } | xargs -n1 basename 2>/dev/null | sort -u | tr '\n' ',' | sed 's/,$//')
 fi
 
 # 3. Git state
@@ -19,13 +23,18 @@ current_branch=$(git branch --show-current 2>/dev/null || echo "not-a-repo")
 git_status=$(git status --short 2>/dev/null | head -n 5 | tr '\n' ' ' | sed 's/"/\\"/g')
 recent_logs=$(git log --oneline -3 2>/dev/null | tr '\n' ' ' | sed 's/"/\\"/g')
 
-# 4. Phase mapping logic (simplified for script)
+# 4. Phase mapping logic (YAML-first)
 phase="Discover"
-if [[ -f "specs/PLAN.md" ]]; then
-  phase="Execute"
-elif [[ -f "specs/TASKS.md" ]]; then
+if [[ -f "specs/state.yaml" ]]; then
+  flow=$(grep -E '^active_flow:' specs/state.yaml | sed 's/active_flow:[[:space:]]*//')
+  case "$flow" in
+    fix_bug) phase="Bug" ;;
+    build_epic) phase="Execute" ;;
+    planning) phase="Plan" ;;
+  esac
+elif [[ -f "specs/release-plan.yaml" ]]; then
   phase="Plan"
-elif [[ -f "specs/SCOPE.md" ]]; then
+elif [[ -f "specs/requirements/SCOPE_LATEST.yaml" ]] || [[ -f "specs/SCOPE.md" ]]; then
   phase="Design"
 elif [[ "$current_branch" != "main" && "$current_branch" != "master" ]]; then
   phase="Initiate"
@@ -49,6 +58,6 @@ Welcome to Bigpowers. I have analyzed the project state.
 You are currently in the '$phase' phase on the '$current_branch' branch.
 EOF
 
-if [[ -f "specs/PLAN.md" ]]; then
-  echo "Current PLAN.md found. I am ready to implement the next step."
+if [[ -f "specs/release-plan.yaml" ]]; then
+  echo "release-plan.yaml found. Read specs/state.yaml for active epic/story."
 fi

package/scripts/sync-bugs-registry.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# sync-bugs-registry.sh — rebuild specs/bugs/registry.yaml from BUG-*.md frontmatter
+set -euo pipefail
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+BUGS="$REPO_ROOT/specs/bugs"
+mkdir -p "$BUGS"
+
+python3 - "$BUGS" <<'PY'
+import re
+import sys
+from pathlib import Path
+
+bugs_dir = Path(sys.argv[1])
+entries = []
+for path in sorted(bugs_dir.glob("BUG-*.md")):
+    text = path.read_text(encoding="utf-8")
+    if not text.startswith("---"):
+        continue
+    end = text.find("---", 3)
+    if end < 0:
+        continue
+    fm = text[3:end]
+    data = {}
+    for line in fm.splitlines():
+        if ":" not in line:
+            continue
+        k, _, v = line.partition(":")
+        data[k.strip()] = v.strip().strip('"').strip("'")
+    bug_id = data.get("bug_id") or path.stem
+    entries.append(
+        {
+            "id": bug_id,
+            "status": data.get("status", "open"),
+            "severity": data.get("severity", "medium"),
+            "scope": data.get("scope", "general"),
+            "title": data.get("title", path.stem),
+            "file": f"bugs/{path.name}",
+        }
+    )
+
+out = bugs_dir / "registry.yaml"
+lines = ["# AUTO-GENERATED — sync-bugs-registry.sh", "bugs:"]
+for e in entries:
+    lines.append(f"  - id: {e['id']}")
+    lines.append(f"    status: {e['status']}")
+    lines.append(f"    severity: {e['severity']}")
+    lines.append(f"    scope: {e['scope']}")
+    lines.append(f"    title: \"{e['title'].replace(chr(34), '')}\"")
+    lines.append(f"    file: {e['file']}")
+lines.append("")
+out.write_text("\n".join(lines), encoding="utf-8")
+print(f"sync-bugs-registry: {len(entries)} bugs -> {out}")
+PY

package/scripts/sync-skills.sh

@@ -31,7 +31,7 @@ for skill_dir in "$REPO_ROOT"/*/; do
   description=$(awk '/^---/{f++} f==1 && /^description:/{p=1} p && !/^---/{print} f==2{exit}' "$skill_md" \
     | sed 's/^description:[[:space:]]*//' \
     | tr -d '\n' \
-    | sed 's/[[:space:]]\+/ /g')
+    | sed -E 's/[[:space:]]+/ /g')
 
   [[ -z "$name" ]] && continue
 
@@ -85,13 +85,13 @@ for skill_dir in "$REPO_ROOT"/*/; do
   skill_count=$((skill_count + 1))
 done
 
-# Assemble final gemini-extension.json
-pkg_version=$(grep '"version":' "$REPO_ROOT/package.json" | sed 's/.*: "\(.*\)".*/\1/')
-pkg_desc=$(grep '"description":' "$REPO_ROOT/package.json" | sed 's/.*: "\(.*\)".*/\1/')
+# Assemble final gemini-extension.json (top-level fields only — not scripts.version)
+pkg_version=$(jq -r '.version' "$REPO_ROOT/package.json")
+pkg_desc=$(jq -r '.description' "$REPO_ROOT/package.json")
 
 jq -n --arg name "bigpowers" \
       --arg version "$pkg_version" \
-      --arg desc "$skill_count+ $pkg_desc" \
+      --arg desc "${skill_count} skills — ${pkg_desc}" \
       '{name: $name, version: $version, description: $desc}' > "$GEMINI_MANIFEST"
 
 # 4. Write OpenCode configuration: opencode.json (minimal project-level config)

package/scripts/sync-status-from-epics.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# sync-status-from-epics.sh — seed execution-status.yaml keys from epic shards
+set -euo pipefail
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SPECS="$REPO_ROOT/specs"
+OUT="$SPECS/execution-status.yaml"
+EPICS="$SPECS/epics"
+
+python3 - "$EPICS" "$OUT" <<'PY'
+import re
+import sys
+from pathlib import Path
+
+epics_dir = Path(sys.argv[1])
+out = Path(sys.argv[2])
+keys: dict[str, str] = {}
+
+existing_path = epics_dir.parent / "execution-status.yaml"
+if existing_path.exists():
+    existing = existing_path.read_text(encoding="utf-8")
+    for m in re.finditer(r"^  ([a-z0-9._-]+):\s*(\S+)", existing, re.M):
+        keys[m.group(1)] = m.group(2)
+
+for epic_file in sorted(epics_dir.glob("e*.yaml")):
+    text = epic_file.read_text(encoding="utf-8")
+    em = re.search(r"^id:\s*(e\d+)", text, re.M)
+    if em:
+        eid = em.group(1)
+        keys.setdefault(eid, "backlog")
+    for sm in re.finditer(r"^\s+- id:\s*(e\d+s\d+)", text, re.M):
+        keys.setdefault(sm.group(1), "backlog")
+
+for folder in sorted(epics_dir.glob("e*/")):
+    epic_yaml = folder / "epic.yaml"
+    if epic_yaml.exists():
+        text = epic_yaml.read_text(encoding="utf-8")
+        em = re.search(r"^id:\s*(e\d+)", text, re.M)
+        if em:
+            keys.setdefault(em.group(1), "backlog")
+    for story in (folder / "stories").glob("e*s*.md"):
+        m = re.match(r"(e\d+s\d+)", story.name)
+        if m:
+            keys.setdefault(m.group(1), "backlog")
+
+lines = ["development_status:"]
+for k in sorted(keys.keys()):
+    lines.append(f"  {k}: {keys[k]}")
+lines.append("")
+out.write_text("\n".join(lines), encoding="utf-8")
+print(f"sync-status-from-epics: wrote {out} ({len(keys)} keys)")
+PY

package/scripts/validate-specs-yaml.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# validate-specs-yaml.sh — required keys for state, release-plan, execution-status
+set -euo pipefail
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SPECS="${1:-$REPO_ROOT/specs}"
+
+err=0
+need() {
+  local file="$1" pattern="$2" msg="$3"
+  if [[ ! -f "$file" ]]; then
+    echo "missing: $file"
+    err=1
+    return
+  fi
+  if ! grep -qE "$pattern" "$file"; then
+    echo "$file: $msg"
+    err=1
+  fi
+}
+
+need "$SPECS/state.yaml" '^active_flow:' 'missing active_flow'
+need "$SPECS/release-plan.yaml" '^release:' 'missing release block'
+need "$SPECS/release-plan.yaml" 'version:' 'missing release.version'
+need "$SPECS/release-plan.yaml" '^epics:' 'missing epics list'
+need "$SPECS/execution-status.yaml" '^development_status:' 'missing development_status'
+
+if [[ -f "$SPECS/release-plan.yaml" ]]; then
+  while IFS= read -r f; do
+    [[ -z "$f" ]] && continue
+    path="$SPECS/$f"
+    if [[ ! -f "$path" ]]; then
+      echo "release-plan: missing epic file $path"
+      err=1
+    fi
+  done < <(grep -E '^\s+file:' "$SPECS/release-plan.yaml" | sed 's/.*file:[[:space:]]*//')
+fi
+
+if [[ "$err" -ne 0 ]]; then
+  exit 1
+fi
+echo "validate-specs-yaml: OK"

package/scripts/yaml-tools.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""Minimal YAML helpers for bigpowers specs (no external deps)."""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def _parse_simple_yaml(text: str) -> dict[str, Any]:
+    """Parse flat and one-level-nested YAML (no lists of objects)."""
+    root: dict[str, Any] = {}
+    stack: list[tuple[int, dict[str, Any]]] = [(0, root)]
+    for raw in text.splitlines():
+        if not raw.strip() or raw.strip().startswith("#"):
+            continue
+        indent = len(raw) - len(raw.lstrip())
+        line = raw.strip()
+        if ":" not in line:
+            continue
+        key, _, val = line.partition(":")
+        key = key.strip()
+        val = val.strip()
+        while stack and indent < stack[-1][0]:
+            stack.pop()
+        cur = stack[-1][1]
+        if val == "":
+            nxt: dict[str, Any] = {}
+            cur[key] = nxt
+            stack.append((indent + 2, nxt))
+        else:
+            if val in ("true", "false"):
+                cur[key] = val == "true"
+            elif val.startswith('"') and val.endswith('"'):
+                cur[key] = val[1:-1]
+            elif val.startswith("'") and val.endswith("'"):
+                cur[key] = val[1:-1]
+            else:
+                try:
+                    if "." in val:
+                        cur[key] = float(val)
+                    else:
+                        cur[key] = int(val)
+                except ValueError:
+                    cur[key] = val
+    return root
+
+
+def _dump_value(val: Any, indent: int) -> str:
+    sp = " " * indent
+    if isinstance(val, dict):
+        lines = []
+        for k, v in val.items():
+            if isinstance(v, dict):
+                lines.append(f"{sp}{k}:")
+                lines.append(_dump_value(v, indent + 2).rstrip())
+            elif isinstance(v, bool):
+                lines.append(f"{sp}{k}: {'true' if v else 'false'}")
+            elif isinstance(v, (int, float)):
+                lines.append(f"{sp}{k}: {v}")
+            else:
+                s = str(v).replace('"', '\\"')
+                lines.append(f'{sp}{k}: "{s}"')
+        return "\n".join(lines) + "\n"
+    return f"{sp}{val}\n"
+
+
+def dump_yaml(data: dict[str, Any]) -> str:
+    return _dump_value(data, 0)
+
+
+def set_path(path: Path, dotted_key: str, value: str) -> None:
+    text = path.read_text(encoding="utf-8") if path.exists() else ""
+    data = _parse_simple_yaml(text) if text.strip() else {}
+    parts = dotted_key.split(".")
+    cur: Any = data
+    for part in parts[:-1]:
+        if part not in cur or not isinstance(cur[part], dict):
+            cur[part] = {}
+        cur = cur[part]
+    last = parts[-1]
+    if value.lower() in ("true", "false"):
+        cur[last] = value.lower() == "true"
+    else:
+        try:
+            cur[last] = int(value)
+        except ValueError:
+            try:
+                cur[last] = float(value)
+            except ValueError:
+                cur[last] = value.strip('"').strip("'")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(dump_yaml(data), encoding="utf-8")
+
+
+def validate_file(path: Path, required_keys: list[str]) -> list[str]:
+    errors: list[str] = []
+    if not path.exists():
+        return [f"missing: {path}"]
+    text = path.read_text(encoding="utf-8")
+    data = _parse_simple_yaml(text)
+    for key in required_keys:
+        parts = key.split(".")
+        cur: Any = data
+        for part in parts:
+            if not isinstance(cur, dict) or part not in cur:
+                errors.append(f"{path}: missing key '{key}'")
+                break
+            cur = cur[part]
+    return errors
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print("usage: yaml-tools.py set <file> <dotted.key> <value>", file=sys.stderr)
+        return 2
+    cmd = sys.argv[1]
+    if cmd == "set":
+        _, _, file, key, val = sys.argv
+        set_path(Path(file), key, val)
+        return 0
+    if cmd == "validate":
+        root = Path(sys.argv[2]) if len(sys.argv) > 2 else Path("specs")
+        errors: list[str] = []
+        errors += validate_file(root / "state.yaml", ["active_flow"])
+        errors += validate_file(
+            root / "release-plan.yaml", ["release", "release.version", "epics"]
+        )
+        errors += validate_file(
+            root / "execution-status.yaml", ["development_status"]
+        )
+        if errors:
+            for e in errors:
+                print(e)
+            return 1
+        print("OK")
+        return 0
+    print(f"unknown command: {cmd}", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/seed-conventions/SKILL.md

@@ -73,7 +73,7 @@ Stack: [language, framework, runtime]
 ## Agent Rules
 - **Workflow Mandate:** You MUST use the bigpowers skills (e.g. `plan-work`, `develop-tdd`, `orchestrate-project`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".
 - Read specs/ before writing code.
-- All planning and specifications MUST be written to `specs/` (e.g. `specs/PLAN.md`) before any code is generated.
+- All planning and specifications MUST be written to `specs/` (`requirements/SCOPE_LATEST.yaml`, `release-plan.yaml`, `epics/`) before any code is generated.
 - Write the minimum code that solves the stated problem. Nothing extra.
 - Never refactor, rename, or reorganize code outside the task scope.
 - Run tests after every change. Show evidence before declaring done.
@@ -113,7 +113,7 @@ Stack: [language, framework, runtime]
 ## Agent Rules
 - **Workflow Mandate:** You MUST use the bigpowers skills (e.g. `plan-work`, `develop-tdd`, `orchestrate-project`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".
 - Read specs/ before writing code.
-- All planning and specifications MUST be written to `specs/` (e.g. `specs/PLAN.md`) before any code is generated.
+- All planning and specifications MUST be written to `specs/` (`requirements/SCOPE_LATEST.yaml`, `release-plan.yaml`, `epics/`) before any code is generated.
 - Write the minimum code that solves the stated problem. Nothing extra.
 - Never refactor, rename, or reorganize code outside the task scope.
 - Run tests after every change. Show evidence before declaring done.
@@ -153,7 +153,7 @@ Stack: [language, framework, runtime]
 ## Agent Rules
 - **Workflow Mandate:** You MUST use the bigpowers skills (e.g. `plan-work`, `develop-tdd`, `orchestrate-project`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".
 - Read specs/ before writing code.
-- All planning and specifications MUST be written to `specs/` (e.g. `specs/PLAN.md`) before any code is generated.
+- All planning and specifications MUST be written to `specs/` (`requirements/SCOPE_LATEST.yaml`, `release-plan.yaml`, `epics/`) before any code is generated.
 - Write the minimum code that solves the stated problem. Nothing extra.
 - Never refactor, rename, or reorganize code outside the task scope.
 - Run tests after every change. Show evidence before declaring done.