| name | hybrid-planning |
| description | Activate this skill ONLY by using the `/hybrid-plan` slash command. Use `/hybrid-plan` to initiate ARCHITECT mode (for planning) and `/hybrid-plan execute <file>` to initiate BUILDER mode (for execution). This skill enforces two strict operating modes — ARCHITECT (plan only, zero application code) and BUILDER (execute only, zero theory) — and must be consulted before writing any plan document or implementation code. Never mix the two modes in a single response.
|
Hybrid Planning & High-Signal Execution Skill
Overview
This skill enforces a strict two-phase discipline for software development: think exhaustively
first, then execute precisely. Every response must belong to exactly one mode. Mixed-mode
responses are a skill violation.
┌──────────────────────────────────────────────────────────────────┐
│ NEW TASK / FEATURE REQUEST │
│ │ │
│ ▼ │
│ ┌─────────────────┐ Plan exists & ┌───────────────────┐ │
│ │ ARCHITECT MODE │ ──── approved? ───▶ │ BUILDER MODE │ │
│ │ (Plan Only) │ │ (Code Only) │ │
│ └─────────────────┘ └───────────────────┘ │
│ ▲ │ │ │
│ └──── Scope gap detected ──────────┘ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ _debt.md Log │ │
│ │ (non-blocking) │ │
│ └─────────────────┘ │
│ │
│ SESSION START → Context Snapshot → resume correct step │
└──────────────────────────────────────────────────────────────────┘
1. MODE DETECTION
Determine the correct mode based on the /hybrid-plan command used. ARCHITECT is the default mode for all new tasks.
| Command | Mode |
|---|
/hybrid-plan | ARCHITECT |
/hybrid-plan execute <file> | BUILDER |
User says "continue build", "next step", or "c" and a plan is IN PROGRESS | BUILDER → run Context Snapshot first |
| User explicitly approves a plan and says "start building" | BUILDER |
| A Builder step requires changes not covered by the plan | → Pause → ARCHITECT (mini-plan) |
Strict Mode Boundary:
- Never auto-switch to BUILDER mode simply because a plan exists or is APPROVED.
- Never assume BUILDER mode for generic follow-up questions or unrelated comments.
- Require an explicit directive (slash command or "Start building") to enter BUILDER mode for the first time in a session.
Always state the active mode on the first line of your response:
[ARCHITECT MODE] — Planning: <feature-name>
[BUILDER MODE] — Executing: <plan-file>.md / Step <N> of <total>
2. ARCHITECT MODE
2.1 Trigger Conditions
Activate when:
- User invokes
/hybrid-plan command to start a new task
- No
plan/ file exists for the current task
- An existing plan is incomplete, stale, or contradicts the current codebase state
- Builder mode discovers a scope gap (undocumented dependency, missing type, unhandled edge case)
2.2 Hard Rules
- ZERO application code. Do not write, edit, or suggest code outside
plan/.
- ZERO shortcuts. A lazy plan (< 300 lines, vague steps, missing interfaces) is a direct skill violation.
- ONE plan, ONE file. Each feature/migration gets its own file:
plan/<feature-name>.plan.md.
- Remind the user to add
plan/ to .gitignore if not already done.
2.3 Pre-Planning Checklist (run before writing the plan)
Before drafting, perform a silent codebase audit and answer these internally:
2.4 Plan Document Structure (Mandatory)
Every plan/*.plan.md must follow this exact structure. Sections cannot be skipped.
# Plan: <Feature / Task Name>
**Version:** 1.0
**Status:** DRAFT | APPROVED | IN PROGRESS | COMPLETE
**Created:** YYYY-MM-DD
**Estimated Steps:** <N>
---
## 1. Context & Goals
> 3–6 sentence high-signal summary. Why does this task exist?
> What problem does it solve? What does success look like?
**Out of Scope:** (explicitly list what this plan does NOT cover)
---
## 2. Affected Files Map
### Created
- `src/...` — reason
### Modified
- `src/...` — what changes and why
### Deleted
- `src/...` — why removed
---
## 3. Architectural Design
### 3.1 Component / Module Hierarchy
(Tree diagram or bullet structure showing relationships)
### 3.2 State Management (Pinia / Zustand / Context)
(Store names, state shape, actions, getters)
### 3.3 API & Data Layer (Firebase / Laravel / tRPC / REST)
(Endpoint definitions, collection paths, query structure)
### 3.4 Routing Changes
(New routes, guards, redirects)
---
## 4. Strict Contract Definitions
> All types must be defined HERE before a single line of code is written.
> Builder mode will treat these as the source of truth.
### 4.1 TypeScript Interfaces & Types
```ts
interface ExampleEntity {
id: string;
createdAt: Timestamp;
// ...
}
```
4.2 API Payloads / Response Shapes
type ExampleRequest = { ... }
type ExampleResponse = { ... }
4.3 Database Schema / Firebase Rules Snapshot
/collection/{docId}: {
field: type // constraints
}
4.4 Component Props
interface ComponentProps {
prop: type;
optionalProp?: type;
}
5. Edge Cases & Security Audit
| # | Scenario | Expected Behavior | Mitigation |
|---|
| 1 | Network loss mid-write | | |
| 2 | Concurrent updates (race condition) | | |
| 3 | Invalid / missing input | | |
| 4 | Unauthorized access attempt | | |
| 5 | Empty state / zero results | | |
Firebase Security Rules Impact: (list any rule changes required)
Auth State Dependencies: (which steps require the user to be authenticated)
6. Step-by-Step Execution Checklist
Each step must be:
- Self-contained (no hidden dependencies on a future step)
- Small enough to execute in one Builder turn
- Specific enough that there is only one correct way to implement it
7. Rollback Plan
What needs to be undone if this plan is abandoned mid-execution?
- Files to delete: ...
- DB migrations to revert: ...
- Feature flags to disable: ...
8. Validation Criteria
How do we know this plan has been successfully executed?
### 2.5 Plan Versioning
If a plan is revised mid-execution:
- Increment version: `1.0 → 1.1`
- Add a `## Changelog` section at the bottom
- Do **not** delete completed steps; strike them out: `~~Step 1~~` ✅
---
## 3. BUILDER MODE
### 3.0 Session Start: Context Snapshot Protocol
**Trigger:** Activate this protocol automatically at the start of every Builder session where
context from a previous session may be missing — i.e., when the user says "continue", "resume",
"where were we", or when a plan is `IN PROGRESS` but no prior Builder output exists in the
current context window.
**Goal:** Reconstruct the exact execution state in under 5 seconds so the user doesn't have to
re-brief you.
**Steps (run silently before any code output):**
1. Read the active `plan/*.plan.md` file
2. Count completed (`✅`) vs pending (`⬜`) steps in the checklist
3. Identify the last completed step and the next pending step
4. Check if any open scope gaps exist (look for `⚠️ SCOPE GAP` markers in the plan or chat)
5. Read `plan/_debt.md` if it exists — note any debt items tagged to the active plan
6. Output the snapshot block below, then proceed immediately to the next step
**Snapshot Output Format:**
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 CONTEXT SNAPSHOT — .plan.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Plan Version : 1.2
Status : IN PROGRESS
Progress : 5 / 12 steps complete
Last Done : ✅ Step 5 —
Resuming At : ⚙️ Step 6 —
Remaining : ⬜ Steps 6–12
Open Gaps : none | ⚠️
Debt Items : 2 logged (see plan/_debt.md)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Resuming Step 6 now...
**Rules:**
- Never ask the user "where did we leave off?" — always derive this from the plan file
- If the plan file is missing or unreadable, output:
⛔ SNAPSHOT FAILED — Cannot locate active plan in plan/
Please confirm the plan file path to resume.
- Snapshot must fit in one output block. Do not paginate or split it.
---
### 3.1 Trigger Conditions
Activate only when:
- User invokes `/hybrid-plan execute <plan-file>` command.
- A `plan/*.plan.md` exists with **Status: APPROVED** AND the user explicitly directs to start execution (e.g., "Start building", "Begin execution").
- The plan is already `IN PROGRESS` and the user provides a continuation command ("c", "next", "continue").
- **Never** auto-switch to BUILDER mode based on generic follow-up questions or unrelated comments.
### 3.2 Token Optimization — Strict Protocol
**Zero Filler Policy.** The following are banned in Builder mode:
- ❌ "Sure, I can help with that!"
- ❌ "Here is the updated code:"
- ❌ "Let me know if you need anything else."
- ❌ "Great question!"
- ❌ Explaining how code works unless explicitly asked
- ❌ Restating the plan step before implementing it
**Allowed preamble (maximum 1 line):**
[BUILDER MODE] — Step 4/12: Add fetchItems() action to ExampleStore
Then go straight to code.
### 3.3 Code Output Rules
1. **Full block replacements only.** Never output partial files with `// ... rest of code` unless the omitted section is completely unchanged boilerplate (e.g., import blocks in a file you're not touching at all).
2. **Adhere strictly to plan contracts.** Use interface names, type shapes, and field names exactly as defined in Section 4 of the plan. Deviation is a bug.
3. **One step per turn (Default).** Implement one checklist item per turn to ensure precision and avoid race conditions.
4. **Autonomous Flow (Optional).** If the user requests "auto" mode or "execute until done", you may proceed to the next step immediately in the same response if the files involved are different from the previous step. If they are the same, finish the current step and prompt the user to continue.
5. **Mark completion.** After each turn, output a single-line status:
✅ Step 4 complete. Next: Step 5 — .
6. **Scope creep guard.** If implementing a step reveals an undocumented dependency, **stop immediately** and output:
⚠️ SCOPE GAP DETECTED
Step N requires: <what's missing>
Not covered in plan: plan/.plan.md
Recommended action: Return to ARCHITECT MODE for a mini-plan update before continuing.
### 3.4 Diff Discipline
Prefer targeted `str_replace`-style edits for small changes. Use full-file replacement only when:
- > 40% of the file changes
- The file is new
- Structural changes make a diff ambiguous
### 3.5 Step Completion Tracking
At the end of each Builder turn, output the updated checklist state (only the current + next 2 steps):
Progress: 4 / 12 steps complete
─────────────────────────────────
✅ Step 3 — Created ExampleStore skeleton
⚙️ Step 4 — [ACTIVE] Add fetchItems() action ← current
⬜ Step 5 — Wire store to ExampleList.vue
### 3.6 Debt Log Protocol
**Purpose:** During Builder execution, you will often notice things that *should* be fixed but
are outside the current plan's scope. Do not ignore them. Do not raise a full scope gap for them.
Log them to `plan/_debt.md` and move on — zero disruption to the current build.
**Debt vs Scope Gap — Know the Difference:**
| Situation | Classification | Action |
|---|---|---|
| Missing type that **blocks** current step | Scope Gap | ⚠️ Stop, notify, switch to ARCHITECT |
| Inconsistent naming in an unrelated file | Debt | Log to `_debt.md`, continue |
| A `TODO` comment left by a previous developer | Debt | Log to `_debt.md`, continue |
| Security issue in a file you're **not** touching | Debt | Log to `_debt.md`, continue |
| A pattern that contradicts the plan contract | Scope Gap | ⚠️ Stop, notify, switch to ARCHITECT |
| Dead code / unused import in adjacent file | Debt | Log to `_debt.md`, continue |
**When logging debt, output a single inline notice (1 line max):**
📝 Debt logged: → plan/_debt.md
Then continue with the current step. Do not expand on it unless asked.
**`_debt.md` Entry Format:**
Each entry appended to `plan/_debt.md`:
```markdown
## [DEBT-<N>] <Short Title>
**Logged:** YYYY-MM-DD
**Logged During:** <plan-file>.plan.md / Step <N>
**Severity:** Low | Medium | High
**Location:** `path/to/file.ts` (line ~N)
**Description:**
> What the issue is and why it matters.
**Suggested Fix:**
> One-paragraph description of the ideal resolution.
**Blocked By:** <plan name> IN PROGRESS | Ready to fix
---
_debt.md File Header (create once if file doesn't exist):
# Technical Debt Log
> Auto-maintained by Builder Mode. Do not edit manually during active builds.
> Review and triage after each plan is marked COMPLETE.
| ID | Title | Severity | File | Status |
| --- | ----- | -------- | ---- | ------ |
Debt Triage (run after a plan reaches COMPLETE status):
After archiving a plan, output a triage prompt:
🧹 DEBT TRIAGE — <N> items logged during <plan-name>
─────────────────────────────────────────────────────
[DEBT-1] Medium — <title> — Ready to fix
[DEBT-2] Low — <title> — Ready to fix
[DEBT-3] High — <title> — Ready to fix
Recommended: Address High severity items before starting next plan.
Run: "fix debt items" to begin, or "skip triage" to proceed.
3.7 Continuous Execution (Autonomous Flow)
To minimize manual "continue" typing, especially for low-tier models:
- Shorthand "c": Always accept "c" as a valid command to proceed to the next step.
- Batching: If two steps are small and touch different files, you are encouraged to execute them both in one turn.
- Auto-Prompt: End every Builder response with a clear, concise call to action:
Ready for Step N+1? Type "c" to continue.
- Execute Until Done: If the user grants "until done" permission, you should proactively summarize your intent to finish the remaining steps and ask the user to say "c" for each iteration, while you handle the logic and code without further theory.
4. MODE TRANSITION PROTOCOL
Architect → Builder (Plan Approval Gate)
Before Builder mode is active, the plan must pass this gate. Check:
If any item is unchecked, do not enter Builder mode. Output:
⛔ Plan not ready for execution.
Missing: <list of gaps>
Update the plan to resolve these before proceeding.
Builder → Architect (Scope Gap)
When a scope gap is detected mid-execution:
- Output the
⚠️ SCOPE GAP DETECTED block (see 3.3)
- Do not write any code for the affected step
- Wait for user confirmation to switch modes
- On confirmation: switch to ARCHITECT, update the plan (bump version), then return to BUILDER
5. DIRECTORY CONVENTIONS
plan/
├── <feature>.plan.md ← primary plan documents
├── <migration>.plan.md
├── _debt.md ← auto-maintained debt log (never delete)
└── _archive/ ← completed plans (move here, don't delete)
└── <feature>.plan.md
⚠️ Add plan/ to your .gitignore to keep version control clean.
Exception: if your team wants shared visibility into plans, commit selectively.
Naming convention: kebab-case matching the feature branch name where possible.
Example: auth-email-verification.plan.md
6. QUICK REFERENCE CARD
┌─────────────────────────────────────────────────────┐
│ ARCHITECT MODE │ BUILDER MODE │
│───────────────────────────│───────────────────────────│
│ ✅ Write plan/*.md │ ✅ Context Snapshot first│
│ ✅ Define interfaces │ ✅ Write application code│
│ ✅ Map edge cases │ ✅ Follow plan contracts │
│ ❌ No app code │ ✅ Log debt to _debt.md │
│ ❌ No shortcuts │ ❌ No theory/explanation │
│ ❌ No lazy steps │ ❌ No filler phrases │
│ │ ❌ No partial code blocks│
└─────────────────────────────────────────────────────┘
Plan Status Flow:
DRAFT → APPROVED → IN PROGRESS → COMPLETE → (archive)
↓
Debt Triage
7. ANTI-PATTERNS TO AVOID
| Anti-Pattern | Why It's Bad | Correct Behavior |
|---|
| Writing app code during Architect mode | Skips validation, creates unreviewed code | Plan only; no exceptions |
| "// TODO: implement later" in Builder output | Leaves the codebase broken | Implement fully or raise a scope gap |
| 500+ line plan steps | Builder turns become ambiguous and error-prone | Break into sub-steps of ≤ 30 LOC change each |
| Changing an interface name mid-build without updating the plan | Type drift, silent bugs | Bump plan version first, then code |
| Mixing explanation and code in Builder mode | Wastes tokens, reduces signal density | Code only + single status line |
| Skipping Section 5 (Edge Cases) | Security holes and runtime crashes slip through | Required; not optional |
| Asking "where did we leave off?" at session start | Wastes user time, breaks flow | Run Context Snapshot silently from the plan file |
| Raising a scope gap for minor out-of-scope issues | Blocks momentum unnecessarily | Log to _debt.md, continue building |
Ignoring _debt.md after plan completes | Debt accumulates, codebase degrades silently | Run debt triage after every COMPLETE plan |
Deleting completed plans from plan/ | Loses architectural history and rationale | Move to plan/_archive/, never delete |
