🧠 Plan & Build — OpenClaw Skill

Think first. Build on approval. Debug automatically. Test everything. Report fidelity.

A dual-mode workflow for OpenClaw that brings OpenCode's Plan Mode philosophy — plus auto-debugging, auto-testing, Plan Fidelity scoring, and rollback — to any AI coding session.

---

📑 Table of Contents

• Features
• Plan & Build vs OpenCode
• Install
• Usage
• State Machine
• PLAN Mode
• Plan Template
• Pre-Build Gate
• BUILD Mode
• Auto-Debug (Self-Heal)
• Post-Build Verification
• Plan Fidelity Score
• Quick Triggers
• Anti-Patterns
• Token Cost
• Community

---

✨ Features

Feature	Description
PLAN Mode	Deep analysis → structured plan → approval gate → ZERO code changes
BUILD Mode	Step-by-step execution of the approved plan
Auto-Debugging	Self-heal cycle with error classification, ≤3 retries per failure
Auto-Testing	Structural + functional + acceptance criteria verification
Plan Fidelity Score	% match of the actual build to the original plan
Rollback	Guided git rollback with error reporting
Parallel BUILD	Subagent spawning for independent steps
Smart Sizing	Automatic plan depth based on task complexity
Bilingual	Natural language triggers in EN + RU

🆚 Plan & Build vs OpenCode's Plan Mode

Feature	OpenCode Plan Mode	Plan & Build
Tool lockdown	System-level (hard-disable)	Behavioral (GOLDEN RULE enforced by instructions)
Plan structure	Freeform	Structured: Impact Table, Architecture, Steps, Risks, Acceptance Criteria
Pre-Build Gate	None	Permission request with debug/test/rollback toggles
Auto-Debugging	None	Self-heal cycle with error classification (Syntax/Import/Runtime/Test/ENV), ≤3 retries
Auto-Testing	None	Structural + functional + acceptance criteria verification
Plan Fidelity Score	None	% completion across steps, criteria, and tests
Audit trail	Manual	Auto-save to .openclaw/plans/ with status tracking
Mode switching	UI keybind	Natural language triggers (EN + RU)
Plan → Build	Manual	Seamless pipeline with explicit gate
Smart sizing	None	Auto-adjusts plan depth by task complexity
Rollback	Manual	Guided with git + manual cleanup
Error classification	None	5-category system (Syntax/Import/Runtime/Test/ENV)
Edge case reporting	None	Post-build edge case discovery + recommendations
Parallel BUILD	No	Subagent spawning for independent steps
Build rigor	None	Per-step validate → commit → next step

📦 Install

1. Download SKILL.md from this repo or clone:

git clone https://github.com/NEET-nerd/plan-and-build.git

2. Place skills/plan-and-build/SKILL.md into your OpenClaw workspace skills/ folder
3. OpenClaw will auto-load it on next session — no restart needed.

Coming soon to ClawHub

🚀 Usage

Say any of these to activate PLAN Mode:

Trigger	Language
plan: <task>	EN
/plan <task>	EN
спланируй	RU
архитектура	RU

The skill also auto-detects complex tasks (3+ files, new features, refactoring, API design, DB schema) and will suggest planning.

Quick Triggers

You say	Action
plan: <task>	Enter PLAN mode
approve / ✅ / давай / го / build	Pre-Build Gate → BUILD
approve with: <changes>	Revise plan → Pre-Build Gate → BUILD
reject / nope / нет	Discard plan
no debug	BUILD without auto-debugging
no tests	BUILD without auto-testing
rollback	Revert all changes
status	Show current plan state
last plan	Show most recent plan

---

🔁 State Machine

[No Plan] ─────▶ [PLANNING] ─────▶ [WAITING_APPROVAL]
                     │                    │
                     │              ┌─────┴──────┐
                     │         "reject"    "approve"
                     │              │        │
                     │              ▼        ▼
                     │          [No Plan]  [PRE-BUILD GATE]
                     │                           │
                     │                    ┌──────┴──────┐
                     │              denied/abort    granted
                     │                    │        │
                     │                    ▼        ▼
                     │               [No Plan]  [BUILDING]
                     │                           │
                     │                    ┌──────┴──────┐
                     │              completed     error (≤3 retries)
                     │                    │        │
                     │                    ▼        ▼
                     │              [COMPLETED] ← self-heal
                     │                           │
                     │                    all retries fail
                     │                    │
                     │                    ▼
                     │              [WAITING_APPROVAL] (re-plan)
                     └────────────────────── (loop if user requests changes)

---

🧠 PLAN Mode

GOLDEN RULE: During PLAN mode — ZERO write/edit/destructive exec on the codebase.

What happens:

1. Recon — reads project structure, configs, key files
2. Analysis — builds mental model of architecture, dependencies, breakage points
3. Produces Plan — structured Markdown with tables, steps, risks, acceptance criteria

Allowed during PLAN:

read, grep, glob, list, exec (read-only: ls, cat, git log, find, tree, wc), web_fetch, web_search, memory_search

Forbidden during PLAN:

write, edit, patch, exec rm/del/install/pip/npm, destructive bash

---

📄 Plan Template (What It Looks Like)

# 🧠 Plan: <concise name>

## Context
1-2 sentences: what we're building and why.

## 📁 Impact Table
| File | Change | Risk | Why |
|------|--------|------|-----|
| src/auth.py | Modify (line ~42) | 🔴 High | Add JWT generation |
| src/models/user.py | Create | 🟢 Low | New User model |
| tests/test_auth.py | Create | 🟢 Low | 5 test cases |

## 📐 Architecture
Approach + patterns (MVC, repository, etc.). ASCII diagram if non-trivial.

## 🔧 Execution Steps
1. **[Create]** `src/models/user.py` — User model: id, email, hashed_password, timestamps
2. **[Modify]** `src/auth.py` — JWT generation + update /login route
3. **[Create]** `tests/test_auth.py` — register, login, invalid creds, expired, refresh
4. **[Validate]** Run pytest — expect 5/5 green
5. **[Update]** `README.md` — auth API docs

## ⚠️ Risks & Decisions Needed
- 🔴 **Risk:** Modifying `auth.py` may break OAuth sessions → backup first
- ❓ **Decision:** bcrypt vs argon2? (Recommend: bcrypt)

## ✅ Acceptance Criteria
- [ ] POST /api/register → 201 + user created
- [ ] POST /api/login → valid JWT
- [ ] Passwords never plaintext
- [ ] Tests: 5/5 passing
- [ ] No OAuth regressions

---

🔒 Pre-Build Gate

Never skipped. Before any BUILD mode begins, the skill MUST present a permission gate:

## 🔒 Pre-Build Check

| Check | Status | Detail |
|-------|--------|--------|
| Plan approved | ✅ | <plan name> |
| Backup created | ✅/⏳ | git commit / snapshot / N/A |
| Auto-debug retries | ⚙️ 3 |
| Auto-test | ⚙️ ON |
| Build steps | 🔢 5 |

### Permissions Requested
1. Auto-Debugging — Fix errors automatically (≤3 retries per step)
2. Auto-Testing — Run tests + Fidelity Score after BUILD
3. Rollback — Auto-revert on catastrophic failure

User can say no debug, no tests, or abort.

---

🛠️ BUILD Mode

After gate approval, the skill executes step by step:

1. Announce: "🔨 Step X/N: "
2. Execute the change (write/edit/create/modify)
3. Validate immediately:
   • Syntax check (python -m py_compile / node -c / equivalent)
   • Import check
   • Read-back verification
4. Pass → "✅ Step X/N done" → git commit
5. Fail → Self-Heal Cycle (if auto-debug ON)

Rules:

• No deviation from the approved plan
• One git commit per step
• Never push/deploy without explicit approval
• User mid-build changes: add to plan, don't restart

---

🩹 Self-Heal Cycle (Auto-Debugging)

When a step fails and auto-debug is ON:

Iteration	What happens
1/3	Diagnose error type → read failing code → minimal fix → re-validate
2/3	Read broader context (10 lines around error) → second fix → re-validate
3/3	Last attempt. If fails → STOP, report, offer options

Error classification categories:

• SYNTAX — missing bracket, wrong indentation, typo
• IMPORT — wrong module path, missing dependency, circular import
• RUNTIME — null reference, wrong args, unhandled exception
• TEST — logic error, wrong assertion, missing fixture
• ENV — missing package, wrong Python/Node version, permission denied

After 3 failed attempts: STOP, report what was tried, suggest options.

---

📊 Post-Build Verification

After all BUILD steps complete:

1. Structural Verification

• All created files exist
• All modified files are readable
• No syntax errors in any changed file
• No broken imports

2. Functional Testing

Run available test suites (pytest, npm test, cargo test, etc.) or smoke tests.

3. Acceptance Criteria — verify each against actual output.

---

📊 Plan Fidelity Score

### Step Completion
| Step | Description | Status | Notes |
|------|-------------|--------|-------|
| 1 | Create user model | ✅ Done | 42 lines, all fields correct |
| 2 | Modify auth.py | ✅ Done | JWT added, route updated |
| 3 | Create test file | ✅ Done | 5/5 tests passing |
| 4 | Run validation | ✅ Done | pytest green |
| 5 | Update README | ✅ Done | Auth section added |

### Metrics
- Steps completed: 5/5 → 100%
- Acceptance criteria met: 5/5 → 100%
- Tests passing: 5/5 → 100%
- Auto-debug cycles used: 1/3

🏆 Plan Fidelity: 100%
  100%  → Perfect. Executed exactly as designed.
  90-99% → Excellent. Minor deviations, no functional impact.
  75-89% → Good. Acceptable with minor tradeoffs.
  60-74% → Partial. Some criteria unmet — review needed.
  < 60%  → Incomplete. Significant re-work recommended.

4. Edge Cases Discovered

Post-build discovery of edge cases and recommendations for next iteration.

---

🚫 Anti-Patterns (What NOT to Do)

• ❌ Start writing code during PLAN mode
• ❌ Skip Pre-Build Gate or present it as a formality
• ❌ Auto-debug more than 3 times per failure
• ❌ Auto-install dependencies without asking
• ❌ Deploy or push without explicit post-build approval
• ❌ Silently deviate from the plan — if you discover a better way, REPORT it
• ❌ Continue building after catastrophic failure — STOP and re-plan
• ❌ Skip structural verification even if auto-test is off

---

📂 Audit Trail

📂 Audit Trail

Plans are saved to .openclaw/plans/ with status tracking:

.openclaw/plans/
├── 2026-04-02-auth-system.md          (status: completed)
├── 2026-04-05-dashboard-redesign.md    (status: draft)
└── 2026-04-10-api-v2-migration.md      (status: rejected)

---

⚙️ Token Usage

Metric	Value
Context overhead	~5k tokens per message
Typical session	30–400k tokens
Free models (qwen/qwen3:free on OpenRouter)	$0
Budget (DeepSeek V3.2 — $0.14/$0.28 per 1M)	~$0.01–$0.10/session
Mid-tier (Claude Sonnet 4.5 — $3/$15, Gemini 2.5 Pro — $1.25/$10, GPT-5.4 — $2.50/$10)	~$0.04–$5.00/session
Top-tier (Claude Opus 4.6 — $5/$25, OpenAI o3)	~$0.15–$10.00/session

Only use for non-trivial tasks (3+ files, new features, refactors). Overkill for one-liner fixes.

---

🐛 Bug Reports & Feature Requests

Telegram: @gym_rat1488

Found a bug? Want a feature? Message directly — the author reads every report.

---

Plan & Build — because shipping without thinking is just gambling.