bigpowers 1.2.3 → 1.3.0

package/run-planning/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: run-planning
+model: sonnet
+description: Advance discover-phase workflows and update specs/planning-status.yaml. Use for survey, scope, research, plan-release chain without touching build epics.
+---
+
+# Run Planning
+
+Updates `specs/planning-status.yaml` as discover-phase skills complete.
+
+## Workflows (default keys)
+
+- `survey-context` → `scope-work` → `research-first` → `elaborate-spec` (optional) → `plan-release` → `slice-tasks`
+
+## Process
+
+1. Read `specs/planning-status.yaml` and `specs/state.yaml`.
+2. Find first workflow with `status: pending` or `optional` not yet run.
+3. Invoke the matching skill; on success set `status: done` for that workflow key.
+4. Set `state.yaml` `active_flow: planning` while in this chain.
+
+## Verify
+
+→ verify: `test -f specs/planning-status.yaml && grep -c 'status: done' specs/planning-status.yaml | awk '{if($1>=3) print "OK"; else print "INCOMPLETE"}'`

package/scope-work/SKILL.md

@@ -1,22 +1,22 @@
 ---
 name: scope-work
-description: Define what is in and out of scope for the current effort and save as specs/SCOPE.md. Use when user wants a PRD, scope definition, or before plan-release on a new initiative.
+description: Define what is in and out of scope for the current effort and save as specs/requirements/SCOPE_LATEST.yaml. Use when user wants a PRD, scope definition, or before plan-release on a new initiative.
 model: sonnet
 ---
 
 # Scope Work
 
-Turn the current conversation into a bounded PRD at `specs/SCOPE.md`.
+Turn the current conversation into a bounded PRD at `specs/requirements/SCOPE_LATEST.yaml`.
 
 ## Process
 
-1. Read existing `specs/` artifacts (CONTEXT.md, RELEASE-PLAN.md if any).
+1. Read existing `specs/` artifacts (`release-plan.yaml`, `plans/TECH_STACK_LATEST.md`, `requirements/VISION_LATEST.yaml` if any).
 2. Interview (if needed): goal, users, in-scope, out-of-scope, constraints, success metrics.
-3. Write `specs/SCOPE.md` with: Vision, In Scope, Out of Scope, Constraints, Success Criteria.
+3. Write `specs/requirements/SCOPE_LATEST.yaml` with: `core_value`, `summary`, `in_scope[]`, `out_of_scope[]`, `constraints`, `success_criteria`, `references`.
 4. Run `research-first` if external dependencies are proposed.
 
-> **HARD GATE** — Every "in scope" item must map to a future story ID or explicit "deferred" with reason.
+> **HARD GATE** — Every `in_scope` item must map to a future epic/story ID or explicit deferred note in `out_of_scope`.
 
 ## Verify
 
-→ verify: `test -f specs/SCOPE.md && grep -c "Out of Scope" specs/SCOPE.md | awk '{if($1>0) print "OK"; else print "MISSING"}'`
+→ verify: `test -f specs/requirements/SCOPE_LATEST.yaml && grep -c 'out_of_scope' specs/requirements/SCOPE_LATEST.yaml | awk '{if($1>0) print "OK"; else print "MISSING"}'`

package/scripts/bp-yaml-set.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# bp-yaml-set.sh — patch a dotted key in a specs YAML file
+# Usage: bp-yaml-set.sh <file> <dotted.key> <value>
+set -euo pipefail
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+FILE="${1:?file}"
+KEY="${2:?dotted.key}"
+VAL="${3:?value}"
+python3 "$REPO_ROOT/scripts/yaml-tools.py" set "$FILE" "$KEY" "$VAL"

package/scripts/bp-yaml-snapshot.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# bp-yaml-snapshot.sh — freeze release-plan + requirements into snapshots/
+# Usage: bp-yaml-snapshot.sh [version]  (default: read from release-plan.yaml)
+set -euo pipefail
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SPECS="$REPO_ROOT/specs"
+VER="${1:-}"
+
+if [[ -z "$VER" ]]; then
+  VER=$(grep -E '^\s+version:' "$SPECS/release-plan.yaml" | head -1 | sed 's/.*"\(.*\)".*/\1/')
+fi
+DEST="$SPECS/requirements/snapshots/release-$VER"
+mkdir -p "$DEST"
+
+for f in release-plan.yaml requirements/VISION_LATEST.yaml requirements/SCOPE_LATEST.yaml; do
+  src="$SPECS/$f"
+  [[ -f "$src" ]] || continue
+  base=$(basename "$f")
+  cp "$src" "$DEST/$base"
+done
+
+echo "bp-yaml-snapshot: wrote $DEST"
+ls -la "$DEST"

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-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"