409 lines
10 KiB
Markdown
409 lines
10 KiB
Markdown
# Unified Playbook CLI Implementation Plan
|
|
|
|
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
|
|
|
**Goal:** Replace legacy sh/ps1/bat scripts with a single Python CLI driven by TOML config, and update docs/tests/CI accordingly.
|
|
|
|
**Architecture:** `scripts/playbook.py` reads `playbook.toml`, validates config, then executes actions in a fixed order based on section presence. Actions are implemented as pure-Python helpers to keep cross-platform behavior.
|
|
|
|
**Tech Stack:** Python 3.11 (`tomllib`), standard library only; Prettier via local install if available.
|
|
|
|
---
|
|
|
|
### Task 1: Create CLI test harness and basic argument handling
|
|
|
|
**Files:**
|
|
|
|
- Create: `tests/cli/test_playbook_cli.py`
|
|
- Modify: `tests/README.md`
|
|
|
|
**Step 1: Write failing tests for CLI usage/exit codes**
|
|
|
|
```python
|
|
import subprocess
|
|
import sys
|
|
from pathlib import Path
|
|
|
|
ROOT = Path(__file__).resolve().parents[2]
|
|
SCRIPT = ROOT / "scripts" / "playbook.py"
|
|
|
|
|
|
def run(*args):
|
|
return subprocess.run([sys.executable, str(SCRIPT), *args], capture_output=True, text=True)
|
|
|
|
|
|
def test_help_shows_usage():
|
|
result = run("-h")
|
|
assert result.returncode == 0
|
|
assert "Usage:" in result.stderr or "Usage:" in result.stdout
|
|
|
|
|
|
def test_missing_config_is_error():
|
|
result = run()
|
|
assert result.returncode != 0
|
|
assert "-config" in (result.stderr + result.stdout)
|
|
```
|
|
|
|
**Step 2: Run tests to verify failure**
|
|
|
|
Run: `python -m unittest tests/cli/test_playbook_cli.py -v`
|
|
Expected: FAIL (script missing)
|
|
|
|
**Step 3: Implement minimal CLI skeleton**
|
|
|
|
```python
|
|
# scripts/playbook.py
|
|
import sys
|
|
|
|
def usage():
|
|
return "Usage:\n python scripts/playbook.py -config <path>\n python scripts/playbook.py -h"
|
|
|
|
|
|
def main(argv):
|
|
if "-h" in argv or "-help" in argv:
|
|
print(usage())
|
|
return 0
|
|
if "-config" not in argv:
|
|
print("ERROR: -config is required.\n" + usage(), file=sys.stderr)
|
|
return 2
|
|
return 0
|
|
|
|
if __name__ == "__main__":
|
|
raise SystemExit(main(sys.argv[1:]))
|
|
```
|
|
|
|
**Step 4: Run tests to verify pass**
|
|
|
|
Run: `python -m unittest tests/cli/test_playbook_cli.py -v`
|
|
Expected: PASS
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add scripts/playbook.py tests/cli/test_playbook_cli.py tests/README.md
|
|
git commit -m ":white_check_mark: test(cli): add basic playbook cli tests"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 2: Parse TOML config and enforce dispatch order
|
|
|
|
**Files:**
|
|
|
|
- Modify: `scripts/playbook.py`
|
|
- Create: `playbook.toml.example`
|
|
- Modify: `README.md`
|
|
|
|
**Step 1: Write failing test for TOML parsing + action order**
|
|
|
|
```python
|
|
def test_action_order(tmp_path):
|
|
config = tmp_path / "playbook.toml"
|
|
config.write_text("""
|
|
[playbook]
|
|
project_root = "."
|
|
|
|
[format_md]
|
|
|
|
[sync_standards]
|
|
langs = ["tsl"]
|
|
""")
|
|
result = run("-config", str(config))
|
|
assert result.returncode == 0
|
|
# Expect order: vendor -> sync_templates -> sync_standards -> install_skills -> format_md
|
|
# Only sections present should log as executed.
|
|
assert "sync_standards" in result.stdout
|
|
assert "format_md" in result.stdout
|
|
```
|
|
|
|
**Step 2: Run test to verify failure**
|
|
|
|
Run: `python -m unittest tests/cli/test_playbook_cli.py -v`
|
|
Expected: FAIL (no TOML parser/action logs)
|
|
|
|
**Step 3: Implement TOML parser + order dispatch**
|
|
|
|
```python
|
|
import tomllib
|
|
from pathlib import Path
|
|
|
|
ORDER = ["vendor", "sync_templates", "sync_standards", "install_skills", "format_md"]
|
|
|
|
|
|
def load_config(path: Path) -> dict:
|
|
return tomllib.loads(path.read_text(encoding="utf-8"))
|
|
|
|
|
|
def main(argv):
|
|
# parse -config value
|
|
# load config
|
|
# for section in ORDER: if section in config, call action
|
|
# print "[action] ..." for visibility
|
|
```
|
|
|
|
**Step 4: Run test to verify pass**
|
|
|
|
Run: `python -m unittest tests/cli/test_playbook_cli.py -v`
|
|
Expected: PASS
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add scripts/playbook.py playbook.toml.example README.md
|
|
git commit -m ":sparkles: feat(cli): add toml config and dispatch order"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 3: Implement `vendor` action (snapshot only)
|
|
|
|
**Files:**
|
|
|
|
- Modify: `scripts/playbook.py`
|
|
- Modify: `playbook.toml.example`
|
|
- Modify: `README.md`
|
|
|
|
**Step 1: Write failing test for vendoring output**
|
|
|
|
```python
|
|
def test_vendor_creates_snapshot(tmp_path):
|
|
config = tmp_path / "playbook.toml"
|
|
config.write_text("""
|
|
[playbook]
|
|
project_root = "{root}"
|
|
|
|
[vendor]
|
|
langs = ["tsl"]
|
|
""".format(root=tmp_path))
|
|
result = run("-config", str(config))
|
|
assert result.returncode == 0
|
|
assert (tmp_path / "docs/standards/playbook/SOURCE.md").is_file()
|
|
```
|
|
|
|
**Step 2: Run test to verify failure**
|
|
|
|
Run: `python -m unittest tests/cli/test_playbook_cli.py -v`
|
|
Expected: FAIL (vendor not implemented)
|
|
|
|
**Step 3: Implement vendor snapshot copy**
|
|
|
|
```python
|
|
from shutil import copy2, copytree
|
|
|
|
# Copy: scripts/, codex/, rulesets/, docs/common, docs/<lang>, templates/ci, templates/<lang>
|
|
# Generate docs/index.md, README.md, SOURCE.md
|
|
# Backup existing snapshot with timestamp
|
|
```
|
|
|
|
**Step 4: Run test to verify pass**
|
|
|
|
Run: `python -m unittest tests/cli/test_playbook_cli.py -v`
|
|
Expected: PASS
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add scripts/playbook.py playbook.toml.example README.md tests/cli/test_playbook_cli.py
|
|
git commit -m ":sparkles: feat(vendor): add playbook snapshot generation"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 4: Implement `sync_templates` and `sync_standards`
|
|
|
|
**Files:**
|
|
|
|
- Modify: `scripts/playbook.py`
|
|
- Modify: `playbook.toml.example`
|
|
- Modify: `templates/README.md`
|
|
|
|
**Step 1: Add failing tests for template sync + standards sync**
|
|
|
|
```python
|
|
def test_sync_templates_creates_memory_bank(tmp_path):
|
|
config = tmp_path / "playbook.toml"
|
|
config.write_text("""
|
|
[playbook]
|
|
project_root = "{root}"
|
|
|
|
[sync_templates]
|
|
project_name = "Demo"
|
|
""".format(root=tmp_path))
|
|
result = run("-config", str(config))
|
|
assert result.returncode == 0
|
|
assert (tmp_path / "memory-bank" / "project-brief.md").is_file()
|
|
|
|
|
|
def test_sync_standards_creates_agents(tmp_path):
|
|
config = tmp_path / "playbook.toml"
|
|
config.write_text("""
|
|
[playbook]
|
|
project_root = "{root}"
|
|
|
|
[sync_standards]
|
|
langs = ["tsl"]
|
|
""".format(root=tmp_path))
|
|
result = run("-config", str(config))
|
|
assert result.returncode == 0
|
|
assert (tmp_path / ".agents" / "tsl" / "index.md").is_file()
|
|
```
|
|
|
|
**Step 2: Run tests to verify failure**
|
|
|
|
Run: `python -m unittest tests/cli/test_playbook_cli.py -v`
|
|
Expected: FAIL
|
|
|
|
**Step 3: Implement `sync_templates`**
|
|
|
|
```python
|
|
# Copy templates/memory-bank -> <root>/memory-bank (rename *.template.md)
|
|
# Copy templates/prompts -> <root>/docs/prompts (rename *.template.md)
|
|
# Copy AGENTS.template.md -> AGENTS.md (merge/append section)
|
|
# Copy AGENT_RULES.template.md -> AGENT_RULES.md (backup optional)
|
|
```
|
|
|
|
**Step 4: Implement `sync_standards`**
|
|
|
|
```python
|
|
# Copy rulesets/<lang> -> <root>/.agents/<lang>
|
|
# Update AGENTS.md playbook block (robust to blank lines)
|
|
# Update .gitattributes according to gitattr_mode
|
|
```
|
|
|
|
**Step 5: Run tests to verify pass**
|
|
|
|
Run: `python -m unittest tests/cli/test_playbook_cli.py -v`
|
|
Expected: PASS
|
|
|
|
**Step 6: Commit**
|
|
|
|
```bash
|
|
git add scripts/playbook.py playbook.toml.example templates/README.md tests/cli/test_playbook_cli.py
|
|
git commit -m ":sparkles: feat(sync): add templates and standards actions"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 5: Implement `install_skills` and `format_md`
|
|
|
|
**Files:**
|
|
|
|
- Modify: `scripts/playbook.py`
|
|
- Modify: `playbook.toml.example`
|
|
- Modify: `README.md`
|
|
|
|
**Step 1: Add failing tests for skills install + md format**
|
|
|
|
```python
|
|
def test_install_skills(tmp_path):
|
|
config = tmp_path / "playbook.toml"
|
|
target = tmp_path / "codex"
|
|
config.write_text(f"""
|
|
[playbook]
|
|
project_root = "{tmp_path}"
|
|
|
|
[install_skills]
|
|
codex_home = "{target}"
|
|
mode = "list"
|
|
skills = ["brainstorming"]
|
|
""")
|
|
result = run("-config", str(config))
|
|
assert result.returncode == 0
|
|
assert (target / "skills" / "brainstorming" / "SKILL.md").is_file()
|
|
```
|
|
|
|
**Step 2: Run tests to verify failure**
|
|
|
|
Run: `python -m unittest tests/cli/test_playbook_cli.py -v`
|
|
Expected: FAIL
|
|
|
|
**Step 3: Implement `install_skills` and `format_md`**
|
|
|
|
```python
|
|
# install_skills: copy codex/skills/<name> -> <codex_home>/skills/<name>
|
|
# format_md: call `prettier` with configured globs if available
|
|
```
|
|
|
|
**Step 4: Run tests to verify pass**
|
|
|
|
Run: `python -m unittest tests/cli/test_playbook_cli.py -v`
|
|
Expected: PASS
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add scripts/playbook.py playbook.toml.example tests/cli/test_playbook_cli.py README.md
|
|
git commit -m ":sparkles: feat(actions): add install_skills and format_md"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 6: Remove legacy scripts and update CI/test docs
|
|
|
|
**Files:**
|
|
|
|
- Delete: `scripts/*.sh`, `scripts/*.ps1`, `scripts/*.bat`
|
|
- Delete: `tests/scripts/*.bats`
|
|
- Modify: `.gitea/workflows/test.yml`
|
|
- Modify: `tests/README.md`
|
|
- Modify: `README.md`, `templates/README.md`
|
|
|
|
**Step 1: Remove legacy scripts and obsolete tests**
|
|
|
|
```bash
|
|
rm scripts/*.sh scripts/*.ps1 scripts/*.bat
|
|
rm tests/scripts/*.bats
|
|
```
|
|
|
|
**Step 2: Update CI to run new Python tests + existing template/link checks**
|
|
|
|
```yaml
|
|
- name: Run CLI tests
|
|
run: python -m unittest discover -s tests/cli -v
|
|
- name: Validate templates
|
|
run: |
|
|
sh tests/templates/validate_python_templates.sh
|
|
sh tests/templates/validate_cpp_templates.sh
|
|
sh tests/templates/validate_ci_templates.sh
|
|
sh tests/templates/validate_project_templates.sh
|
|
- name: Check doc links
|
|
run: sh tests/integration/check_doc_links.sh
|
|
```
|
|
|
|
**Step 3: Update docs to new CLI + TOML**
|
|
|
|
- Replace old script usage with `python scripts/playbook.py -config playbook.toml`.
|
|
- Document config sections and example file name.
|
|
|
|
**Step 4: Run full test suite**
|
|
|
|
Run: `python -m unittest discover -s tests/cli -v && sh tests/templates/validate_project_templates.sh && sh tests/integration/check_doc_links.sh`
|
|
Expected: PASS
|
|
|
|
**Step 5: Commit**
|
|
|
|
```bash
|
|
git add .
|
|
git commit -m ":wastebasket: remove(legacy): drop old scripts and tests"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 7: Final cleanup and formatting
|
|
|
|
**Files:**
|
|
|
|
- Modify: `README.md`, `templates/README.md`, `tests/README.md`
|
|
|
|
**Step 1: Run Markdown format (exclude third-party skills)**
|
|
|
|
Run: `npm run format:md -- --ignore-path .prettierignore`
|
|
Expected: No unexpected diffs
|
|
|
|
**Step 2: Commit formatting-only changes (if any)**
|
|
|
|
```bash
|
|
git add README.md templates/README.md tests/README.md
|
|
git commit -m ":art: style(docs): format markdown"
|
|
```
|