✨ feat(workflow): add superpowers planning and execution state tracking

scripts/playbook.py

@@ -5,6 +5,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from shutil import copy2, copytree, rmtree, which
 import subprocess
+import importlib.util
 
 try:
     import tomllib
@@ -22,6 +23,11 @@ ORDER = [
 ]
 SCRIPT_DIR = Path(__file__).resolve().parent
 PLAYBOOK_ROOT = SCRIPT_DIR.parent
+MAIN_LOOP_SCRIPT = SCRIPT_DIR / "main_loop.py"
+MAIN_LOOP_SPEC = importlib.util.spec_from_file_location("playbook_main_loop", MAIN_LOOP_SCRIPT)
+assert MAIN_LOOP_SPEC and MAIN_LOOP_SPEC.loader
+MAIN_LOOP = importlib.util.module_from_spec(MAIN_LOOP_SPEC)
+MAIN_LOOP_SPEC.loader.exec_module(MAIN_LOOP)
 PATH_CONFIG_KEYS = {"project_root", "deploy_root", "agents_home", "codex_home", "skill_link"}
 DOCS_INDEX_SECTION_HEADINGS = {
     "common": "## 跨语言（common）",
@@ -34,7 +40,23 @@ DOCS_INDEX_SECTION_HEADINGS = {
 
 
 def usage() -> str:
-    return "Usage:\n  python scripts/playbook.py -config <path>\n  python scripts/playbook.py -h"
+    return (
+        "Usage:\n"
+        "  python scripts/playbook.py -config <path>\n"
+        "  python scripts/playbook.py -record-spec <spec_path> -progress <path>\n"
+        "  python scripts/playbook.py -record-plan <plan_path> -progress <path>\n"
+        "  python scripts/playbook.py -h"
+    )
+
+
+def parse_cli_value(argv: list[str], flag: str) -> Optional[str]:
+    if flag not in argv:
+        return None
+    idx = argv.index(flag)
+    if idx + 1 >= len(argv):
+        return None
+    value = argv[idx + 1].strip()
+    return value or None
 
 
 def strip_inline_comment(value: str) -> str:
@@ -1393,6 +1415,47 @@ def main(argv: list[str]) -> int:
     if "-h" in argv or "-help" in argv:
         print(usage())
         return 0
+
+    spec_path = parse_cli_value(argv, "-record-spec")
+    if spec_path is not None:
+        progress_path = parse_cli_value(argv, "-progress")
+        if not progress_path:
+            print("ERROR: -progress is required.\n" + usage(), file=sys.stderr)
+            return 2
+        code, message = MAIN_LOOP.record_workflow_state(
+            Path(progress_path),
+            "planning",
+            spec_path,
+            None,
+            None,
+            None,
+        )
+        if code != 0:
+            print(message, file=sys.stderr)
+            return code
+        print(message)
+        return 0
+
+    plan_path = parse_cli_value(argv, "-record-plan")
+    if plan_path is not None:
+        progress_path = parse_cli_value(argv, "-progress")
+        if not progress_path:
+            print("ERROR: -progress is required.\n" + usage(), file=sys.stderr)
+            return 2
+        code, message = MAIN_LOOP.record_workflow_state(
+            Path(progress_path),
+            "planning",
+            None,
+            plan_path,
+            "executing-plans",
+            "karpathy-guidelines,.agents,AGENT_RULES",
+        )
+        if code != 0:
+            print(message, file=sys.stderr)
+            return code
+        print(message)
+        return 0
+
     if "-config" not in argv:
         print("ERROR: -config is required.\n" + usage(), file=sys.stderr)
         return 2