SPM - Super Project Manager

Production-grade software project development skill for OpenClaw. WBS hash attestation, auto context injection, session recovery, parallel task pointers, and Minimal Mode. Use when starting new projects, implementing complex features, or executing multi-step development tasks that require structured end-to-end management.

zhbcher@zhbcher

Install

openclaw skills install @zhbcher/spm

SPM — Super Project Manager

Overview

SPM is a comprehensive skill for software project development in OpenClaw. It integrates:

Superpowers (13 workflows): Design brainstorming, implementation planning, TDD, subagent-driven development, code review, systematic debugging, git worktrees, and more
PM enhancements: Soul-searching protocol, assumption documentation, safe sandbox (/freeze & /guard), three-tier quality gates, project scaffolding, deployment pipeline
WBS Executor: Structured task ledger with exit criteria, evidence tracking, heartbeat logging, interruption recovery, delivery summary

Core Philosophy: SPM is an orchestrator, not a monolith. Each phase triggers the right workflow. The WBS task ledger is the single source of truth for tracking — now protected by hash attestation and auto-injected into context.

🆕 v3.0 New Features

Feature	Description	Priority
WBS Hash Attestation	SHA-256 integrity protection; tampered ledgers auto-detected	🔒 Security
Hook Auto-Injection	Active tasks auto-injected into context before every tool call	🤖 Automation
Session Recovery	Auto-generated recovery reports from heartbeat logs	🔄 Resilience
Parallel Task Pointers	`.active_ledger` symlink + `switch-ledger.sh` for multi-task isolation	📂 Multi-task
SPM Minimal Mode	5-rule lightweight mode for <10 task projects	🏃 Quick Start
Template/Script Separation	Clear distinction: user-project files vs skill internals	📋 UX

When to Use

Starting a new software project from scratch
Implementing complex multi-file features
Any task that spans multiple steps or sessions
Work that requires quality gates, code review, or TDD

When NOT to use:

Single-line fixes or typo corrections
Quick one-file changes with obvious scope
Pure brainstorming without execution intent

Architecture

text

┌──────────────────────────────────────────────────────────┐
│                      SPM ORCHESTRATOR                     │
│  SKILL.md — Detects task type → Routes to correct phase  │
└──────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌───────────────┐   ┌───────────────┐   ┌──────────────────┐
│  REQUIREMENT   │   │   PLANNING    │   │    EXECUTION     │
│ ─────────────  │   │  ──────────   │   │   ────────────   │
│ • Brainstorming│   │ • Write Plan  │   │ • Git Worktree   │
│ • Soul-Search  │   │ • WBS Ledger  │   │ • TDD Cycle      │
│ • Design Doc   │   │ • Review Plan │   │ • Subagent Dev   │
│ • Assumptions  │   │ • Dependencies│   │ • Parallel Tasks │
└───────┬───────┘   └───────┬───────┘   └────────┬─────────┘
        └───────────────────┼────────────────────┘
                            ▼
┌───────────────┐   ┌───────────────┐   ┌──────────────────┐
│    QUALITY     │   │   DELIVERY    │   │  TRACKING (ALL)  │
│ ─────────────  │   │  ──────────   │   │  ──────────────  │
│ • Verification │   │ • Finish Brch │   │ • WBS Ledger     │
│ • Code Review  │   │ • Deploy (opt)│   │ • Heartbeat Log  │
│ • 3-Tier Gates │   │ • Delivery    │   │ • State Tracking │
│ • Debugging    │   │ • Cleanup     │   │ • Recovery       │
└───────┬───────┘   └───────┬───────┘   └──────────────────┘
        └───────────────────┼────────────────────┘
                            ▼
              ┌─────────────────────────┐
              │    SUBAGENT DISPATCH     │
              │  ─────────────────────  │
              │  Impl. Subagent         │
              │  Spec Reviewer          │
              │  Code Quality Reviewer  │
              │  Parallel Subagents     │
              └─────────────────────────┘

The Complete Lifecycle

text

┌────────────────────────────────────────────────────────────────────┐
│  PHASE 1: REQUIREMENT                          PHASE 2: PLANNING  │
│  ┌────────────┐  ┌────────────┐              ┌──────────┐        │
│  │Brainstorm  │→ │Design Doc  │──Manual──▶  │WBS Plan  │         │
│  │(灵魂拷问)  │  │(明确假设)  │  Review     │(任务分解)│         │
│  └────────────┘  └────────────┘              └────┬─────┘        │
└────────────────────────────────────────────────────┼──────────────┘
                                                      │
┌─────────────────────────────────────────────────────┼──────────────┐
│  PHASE 3: EXECUTION (Automated after Manual Start) │              │
│                                                     ▼              │
│  ┌──────────┐  ┌──────────┐  ┌────────────┐  ┌─────────────┐    │
│  │Worktree  │→ │Subagent  │→ │Parallel    │→ │TDD + Commit │    │
│  │Setup     │  │Task Exec │  │Subagents   │  │Verify       │    │
│  └──────────┘  └──────────┘  └────────────┘  └──────┬──────┘    │
│                                                      │           │
└──────────────────────────────────────────────────────┼───────────┘
                                                       │
┌──────────────────────────────────────────────────────┼───────────┐
│  PHASE 4: QUALITY                PHASE 5: DELIVERY   │           │
│  ┌────────────┐  ┌────────────┐  ┌──────────────┐   │           │
│  │Verify Gate │→ │Code Review │→ │Finish Branch │   │           │
│  │(3-Tier)    │  │(3-Stage)   │  │Deploy (opt)  │   │           │
│  └────────────┘  └────────────┘  └──────┬───────┘   │           │
│                                          │           │           │
│  ┌────────────────────────────────────┐ │           │           │
│  │ DELIVERY SUMMARY + WBS CLOSEOUT    │◀┘           │           │
│  └────────────────────────────────────┘             │           │
└──────────────────────────────────────────────────────┘           │
                                                                    │
┌────────────────────────────────────────────────────────────────────┐
│  TRACKING LAYER (Runs Throughout All Phases)                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐   │
│  │ WBS Ledger   │  │ Heartbeat    │  │ State Tracking       │   │
│  │ (Single SOT) │  │ (10 min)     │  │ (project-state.json) │   │
│  └──────────────┘  └──────────────┘  └──────────────────────┘   │
└────────────────────────────────────────────────────────────────────┘

Core Artifact: WBS Task Ledger

The WBS task ledger is the single source of truth for the entire project. Every phase creates its artifacts AND updates the ledger.

Ledger location: docs/spm/ledger.md

Minimal ledger template:

markdown

# WBS Task Ledger — [Project Name]

## Task Summary
- Assignment: [one-line]
- Outcome: [what working software looks like]
- Success criteria: [how we verify]

## WBS
| ID | Work Package | Dependencies | Context Brief | Exit Criteria | Evidence | Status |
|----|-------------|---------|---------------|---------------|----------|--------|
| 1  | Setup scaffold | - | Cold-start: init project structure, install deps | Init script runs, tests pass | npm test output | done |
| 1.1| Install deps | 1 | Cold-start: after scaffold ready, npm install all packages | All deps installed | npm ls | done |
| 2  | Core feature A | 1 | Cold-start: after scaffold, implement API in src/routes/ | API returns correct data | curl output | todo |

## Mutation Log
| Time | Mutation Type | Affected IDs | Reason | New IDs |
|------|--------------|-------------|--------|---------|
| | split / insert / skip / reorder / abandon | | | |

## Active State
- Current item:
- Last completed:
- Last checkpoint:
- Resume from here:

## Heartbeat Log
| Time | Active | Completed | Evidence | Resume point |
|------|--------|-----------|----------|-------------|
| HH:MM | Task 2 | Task 1 | build passes | Task 2 subagent |

## Delivery Summary
[Final output mapping back to original assignment]

Allowed statuses: todo, doing, done, blocked, skipped

Rule: No item marked done without evidence (file diff, test output, command result).

Workflow by Phase

Phase 1: Requirement (Manual — User Review Required)

Trigger: User says "build X", "start project", "implement feature"

🆕 外部资源分析 (optional): 如果项目需要借鉴外部代码/技能/方案，先走 workflows/external-research.md → 结构化对比 → 输出采纳清单 → 再进入标准需求流程。

Sub-flow: Soul-Searching Protocol

Before any design work, throw back 3 lethal probing questions about scope/purpose/constraints
Surface assumptions explicitly: "I'm assuming X — correct me now or I'll proceed"

Sub-flow: Brainstorming (see workflows/brainstorming.md)

Explore project context
Ask clarifying questions (one at a time)
Propose 2-3 approaches with trade-offs
Present design in sections, user approves per section
Write design doc to docs/spm/specs/
Spec self-review (placeholder scan, consistency, scope)
User reviews written spec

Outputs:

docs/spm/specs/YYYY-MM-DD-xxx-design.md
Updated WBS ledger: "Spec phase complete"

Phase Gate: User must approve spec before proceeding.

Phase 2: Planning (Manual — User Review Required)

Sub-flow: Implementation Plan (see workflows/writing-plans.md)

Decompose spec into bite-sized tasks (2-5 min per step)
Write Context Brief for each task — self-contained cold-start context
Assign Model Tier to each task (fast/standard/strong)
Map file structure: which files created/modified
Create WBS ledger with all tasks (IDs, context brief, dependencies, exit criteria)
Self-review plan (spec coverage, placeholder scan, Context Brief audit)
🆕 Adversarial Plan Review — dispatch reviewer subagent against 5-dimension checklist before showing to user (see subagents/plan-reviewer-prompt.md)

Outputs:

docs/spm/plans/YYYY-MM-DD-xxx-plan.md
Updated WBS ledger with all task rows + context briefs + model tiers
docs/spm/reviews/YYYY-MM-DD-plan-review.md — adversarial review report

Phase Gate: User reviews plan + review report, chooses execution mode:

Subagent-Driven (recommended) — each task dispatched to fresh subagent
Inline Execution — execute in current session

Phase 3: Execution (Automated)

Sub-flow: Git Worktree Setup (see workflows/using-git-worktrees.md)

Create isolated worktree
Verify gitignore
Run project setup
Verify clean test baseline

Sub-flow: Task Execution

For Subagent-Driven: see workflows/subagent-driven-development.md
- Each subagent receives cold-start Context Brief + model tier routing (fast→step35, standard→SensenovaDeepSeek, strong→DeepSeekV4Pro — 三 provider 隔离避免速率限制)
- BLOCKED tasks trigger mutation protocol (see references/plan-mutation.md)
For Inline: see workflows/executing-plans.md
For Parallel Tasks: see workflows/dispatching-parallel-agents.md

Mandatory: WBS Binding Every subagent task MUST update the WBS ledger:

Before dispatch: set status to doing
On completion: set status to done + attach evidence
On block: set status to blocked + describe blocker → trigger mutation protocol

Sub-flow: TDD (see workflows/test-driven-development.md) Each implementation slice follows RED → Verify RED → GREEN → Verify GREEN → REFACTOR → Commit

🆕 RED validation accepts compile-time RED (test references non-existent API → compile failure counts as valid RED)

Heartbeat: Every 10 minutes Update the heartbeat log in the WBS ledger.

Phase 4: Quality (Automated)

Sub-flow: Verification Gate (see workflows/verification-before-completion.md) Iron Law: NO completion claims without fresh verification evidence.

🆕 Eval Delta: 每个任务完成前必须做 baseline vs current 对比（测试数、覆盖率、回归检查）
🆕 Standardized Report: 使用 templates/verification-report.md 模板，7 阶段顺序验证，输出 YES/NO 网格

Sub-flow: Three-Stage Code Review (see workflows/code-review.md)

Stage 1: Spec Compliance — Code matches spec exactly (no YAGNI)
Stage 2: Engineering Quality — Tests, security, clean code
Stage 3: Final Review — Full suite pass, integration verified

Sub-flow: Three-Tier Quality Gates (see workflows/quality-gates.md)

Always do: Run tests, follow naming, validate inputs
Ask first: DB changes, new deps, CI changes
Never do: Commit secrets, skip review for complex changes

Sub-flow: Systematic Debugging (if tests fail) — see workflows/systematic-debugging.md 4-phase root cause tracing: Error Capture → Hypothesis → Evidence → Fix & Verify

Outputs:

Code review report
Quality gate results (passed/failed per check)
Updated WBS ledger (tasks moved to done with evidence)

Phase 5: Delivery (Manual Decision)

Sub-flow: Finish Branch (see workflows/finishing-a-development-branch.md)

Verify all tests pass
Determine base branch
Present 4 options: Merge / PR / Keep / Discard
Execute choice + cleanup worktree

Sub-flow: Deploy (Optional — see workflows/shipping-and-launch.md) If deploying: release plan → rollback plan → monitoring → deploy → verify

Sub-flow: Delivery Summary Write WBS ledger's Delivery Summary section:

Completed work mapped to original assignment
Evidence package (test results, file diffs, command outputs)
Remaining blockers/skipped items
Residual risks
Final handoff note

Subagent Strategy

Task Dispatch (Single)

text

For each task from WBS ledger:
  1. Read task (ID, description, acceptance criteria)
  2. Update WBS: status=doing
  3. Dispatch implementer subagent
     → FULL task text + file context (not "read the file")
  4. Implementer completes → reports DONE/DONE_WITH_CONCERNS/BLOCKED
  5. Update WBS: attach evidence, status=done (or blocked)

Task Dispatch (Parallel - Independent Tasks)

text

For parallel-eligible tasks from WBS ledger:
  1. Identify tasks with NO inter-dependencies
  2. For each: update WBS (status=doing)
  3. Dispatch ALL implementer subagents simultaneously
  4. Wait for ALL to return
  5. For each completed: update WBS (status=done + evidence)
  6. For any blocked: update WBS (status=blocked + reason)
  7. Verify no conflicts between parallel results

Parallel eligibility: Tasks that touch DIFFERENT files/subsystems with no shared state.

Review Dispatch

text

After implementation:
  1. Dispatch spec compliance reviewer
  2. Issues found? → Dispatch implementer to fix → Re-review
  3. Dispatch code quality reviewer
  4. Issues found? → Dispatch implementer to fix → Re-review
  5. All clear? → Mark task complete

Prompt Templates

See subagents/ directory for full prompts:

subagents/implementer-prompt.md
subagents/spec-reviewer-prompt.md
subagents/quality-reviewer-prompt.md

Browser Automation

SPM integrates agent-browser as the recommended browser automation tool. When tasks involve web testing, data extraction, or UI automation, the orchestrator can dispatch browser-enabled subagents.

Supported Actions

navigate / go_back / refresh — Page navigation
click / type / select_option / hover — Element interaction
screenshot / wait_for / scroll — Page operations
get_attribute / get_text / evaluate — Data extraction
tabs / switch_tab / close_tab — Tab management
console_messages / network_requests — Debug monitoring

Usage Pattern

text

Task: "Test the login flow on example.com"
→ SPM creates WBS task with browser steps
→ Subagent dispatched with browser tool enabled
→ Subagent executes sequence: navigate → type credentials → click submit → verify success
→ Evidence: screenshot + console output attached to WBS

Browser automation tasks follow the same TDD and evidence requirements as code tasks.

Quality Gates

Three-Tier System

Always Do:

Run test suite before any commit
Follow project naming conventions
Validate all inputs (security baseline)
Perform code style checks
Keep documentation in sync

Ask First:

Database schema changes
Adding new dependencies
Modifying CI/CD configuration
Breaking API contracts
Changing performance-critical paths

Never Do:

Commit secrets or credentials
Edit vendor directories
Remove failing tests without approval
Skip code review for complex changes
Bypass security checks

Iron Laws

Law 1: No code without approved design. Spec must be written AND user-approved before any implementation.

Law 2: No production code without a failing test first. TDD Iron Law — if you wrote code before test, delete it and start over.

Law 3: No completion claims without fresh verification evidence. Run the exact verification command this turn. Show output. THEN claim.

Law 4: No fixes without root cause investigation. Symptom fixes are failure. Complete Phase 1-3 of Systematic Debugging before any fix.

Law 5: No WBS done without evidence. File diffs, test output, command results — something verifiable.

Quality Enhancements (Optional but Recommended)

To further strengthen delivery confidence, SPM supports optional Checkpoint and Checklist systems. These are inspired by professional engineering practices and can be adopted incrementally.

See docs/quality-enhancements.md for complete documentation.

Quick enable:

bash

cd your-spm-project
bash skills/spm/scripts/setup-checkpoints.sh

This installs:

Checkpoint templates (CHECKPOINTS/) for hard phase stops
Checklist templates (CHECKLISTS/) for self-review
Automation scripts (scripts/checkpoint.sh, scripts/verify_checklists.py)
npm scripts: npm run checkpoint, npm run verify:code, npm run verify:deploy

After setup, each phase can generate a checkpoint report (./scripts/checkpoint.sh phase-1) and tasks can be verified against the appropriate checklist before marking done.

Instruction Priority

User's explicit instructions (AGENTS.md, direct commands) — highest
SPM skill rules (Iron Laws, workflows) — default process
Default system prompt — lowest

If user says "skip TDD" or "skip review", follow the user. Iron Laws are defaults, not overrides.

Project Structure

text

openclaw-spm/
├── SKILL.md                      # SPM 编排器 (14 workflows)
├── skills/                       # 🆕 子技能 (SPM 自动发现)
│   ├── spm-frontend/             # 前端代码规范
│   │   └── SKILL.md
│   └── spm-design-system/        # 视觉设计规范
│       └── SKILL.md
├── workflows/                    # 14 个工作流
├── references/                   # 参考文件
├── subagents/                    # 子代理 prompt 模板
├── schemas/                      # JSON Schema
├── templates/                    # 文档模板
├── scripts/                      # 自动化脚本
├── examples/                     # 完整示例项目
├── config/                       # SPM 配置
└── docs/                         # 设计文档

Integration with OpenClaw

Enable SPM in ~/.openclaw/openclaw.json:

json

{
  "skills": {
    "entries": {
      "SPM": {
        "enabled": true,
        "config": {
          "heartbeat_interval": "10m",
          "auto_checkpoint": true,
          "quality_gates_enabled": true,
          "wbs_ledger_path": "docs/spm/ledger.md",
          "parallel_subagents": true,
          "deployment_enabled": false
        }
      }
    }
  }
}

Quick Start

text

1. User: "Build a user authentication system"
2. SPM triggers brainstorming → 3 soul-searching questions
3. Design doc written → user approves
4. Plan written → WBS ledger created → user reviews
5. User: "Go" → automated execution begins
6. Worktree setup → Subagent dispatch (with WBS binding)
7. Each task: TDD → commit → review → ledger update
8. Parallel tasks if independent (WBS tracks each)
9. All tasks done → Quality gate → Finish branch
10. Delivery summary written to ledger

各阶段文件读取指南

不同阶段读不同的文件，避免盲目全读浪费 token。

阶段	必读（每次都看）	一次性看完 / 按需查
Phase 0 外部研究	`workflows/external-research.md`	—
Phase 1 需求	`workflows/brainstorming.md`	`templates/prd-template.md`
Phase 2 规划	`workflows/writing-plans.md` + `references/task-ledger-template.md`	`schemas/task-ledger.schema.json`
Phase 3 执行（每任务）	`references/TASK-EXECUTION.md` 单一入口	`workflows/test-driven-development.md`（卡壳时）
Phase 3 子代理调度	`workflows/subagent-driven-development.md` + `subagents/implementer-prompt.md`	`subagents/spec-reviewer-prompt.md` + `subagents/quality-reviewer-prompt.md`
Phase 3 并行	`workflows/dispatching-parallel-agents.md`	—
Phase 4 质量	`workflows/verification-before-completion.md` + `workflows/code-review.md`	`workflows/quality-gates.md` + `CHECKLISTS/CODE-COMPLETION.md`
Phase 4 调试	`workflows/systematic-debugging.md`	—
Phase 5 交付	`workflows/finishing-a-development-branch.md`	`workflows/shipping-and-launch.md` + `CHECKLISTS/DEPLOYMENT-READINESS.md`
全局追踪	`schemas/project-state.schema.json`	`references/recovery-patterns.md`（中断恢复时）
Git Worktree	`workflows/using-git-worktrees.md`	—

关键：Phase 3 执行单任务时，references/TASK-EXECUTION.md 是唯一必读——它合并了 TDD 铁律 + Gate Function + WBS 更新规则 + 完工自检清单。不要再跳转多个文件。

🆕 v3.0 Scripts Reference

Script	Purpose	When to Use
`scripts/init-spm.sh`	Initialize SPM project structure	New project setup
`scripts/attest-wbs.sh`	Generate SHA-256 hash of WBS Ledger	After each WBS update
`scripts/verify-wbs.sh`	Verify WBS Ledger integrity	Before trusting WBS content
`scripts/inject-wbs-context.py`	Inject active tasks into agent context	Hook: PreToolUse
`scripts/session-recovery.py`	Generate session recovery report	After interruption, returning to project
`scripts/switch-ledger.sh <name>`	Switch between multiple WBS ledgers	Multi-task parallel work

Hook Configuration (Recommended)

Add to openclaw.json SPM plugin config to auto-inject WBS state:

json

{
  "hooks": {
    "preToolUse": {
      "command": "python3 scripts/inject-wbs-context.py",
      "maxChars": 1500
    }
  }
}

Integrity check before injection:

json

{
  "hooks": {
    "preToolUse": {
      "command": "bash scripts/verify-wbs.sh && python3 scripts/inject-wbs-context.py",
      "maxChars": 1500
    }
  }
}

🏃 SPM Modes

Full Mode (Default)

5-phase lifecycle, 13 workflows, 3-tier quality gates, subagent dispatch, TDD.

Minimal Mode

5 rules for <10 task projects. See docs/spm-minimal-mode.md.

Switch: /spm:mode minimal or /spm:mode full

📁 Project Structure (v3.0)

text

spm/
├── SKILL.md           ← Skill definition (do not copy)
├── UPGRADE.md         ← Version migration guide
├── scripts/           ★ User runs or auto-triggers
│   ├── init-spm.sh
│   ├── attest-wbs.sh
│   ├── verify-wbs.sh
│   ├── inject-wbs-context.py
│   ├── session-recovery.py
│   └── switch-ledger.sh
├── templates/         ★ User copies to project
│   ├── wbs-ledger.md          → docs/spm/ledger.md
│   ├── design-doc.md          → docs/spm/specs/
│   ├── plan-doc.md            → docs/spm/plans/
│   └── checkpoint.md          → docs/spm/checkpoints/
├── workflows/         ← Agent reference
├── subagents/         ← Agent reference
├── references/        ← Agent reference
└── CHECKLISTS/        ← Quality assurance

SPM - Super Project Manager

Install

SPM — Super Project Manager

Overview

🆕 v3.0 New Features

When to Use

Architecture

The Complete Lifecycle

Core Artifact: WBS Task Ledger

Workflow by Phase

Phase 1: Requirement (Manual — User Review Required)

Phase 2: Planning (Manual — User Review Required)

Phase 3: Execution (Automated)

Phase 4: Quality (Automated)

Phase 5: Delivery (Manual Decision)

Subagent Strategy

Task Dispatch (Single)

Task Dispatch (Parallel - Independent Tasks)

Review Dispatch

Prompt Templates

Browser Automation

Supported Actions

Usage Pattern

Quality Gates

Three-Tier System

Iron Laws

Quality Enhancements (Optional but Recommended)

Instruction Priority

Project Structure

Integration with OpenClaw

Quick Start

See Also

各阶段文件读取指南

🆕 v3.0 Scripts Reference

Hook Configuration (Recommended)

🏃 SPM Modes

Full Mode (Default)

Minimal Mode

📁 Project Structure (v3.0)

Related skills