changes

.config/opencode/skills/writing-plans/SKILL.md

@@ -1,95 +1,35 @@
 ---
 name: writing-plans
-description: Create implementation plans detailed enough for an executor with little project context
+description: Planner workflow for producing execution-ready approved plans with explicit scope, lanes, and verification oracle
 permalink: opencode-config/skills/writing-plans/skill
 ---
 
 # Writing Plans
 
-## When to Use
+Use this skill when converting intent into an execution-ready `plans/<slug>` note.
 
-Use this skill when you have requirements for a non-trivial implementation and need a clear plan before editing code.
+## Required Plan Shape
 
-## Core Goal
+Every approved plan must include:
 
-Write a comprehensive implementation plan that assumes the executor lacks prior context. The plan must include exact tasks, file paths, expected code shape, and verification commands.
+- Objective
+- Scope and out-of-scope boundaries
+- Constraints and assumptions
+- Concrete task list
+- Parallelization lanes and dependency notes
+- Verification oracle
+- Risks and open findings
 
-## Scope Check
+## Workflow
 
-If requirements contain multiple independent features/subsystems, split into separate plans so each can be implemented and verified independently.
+1. Gather enough evidence to remove guesswork.
+2. Decompose work into bounded tasks with clear owners.
+3. Define verification per task and for final integration.
+4. Check contract alignment with planner -> builder handoff rules.
+5. Mark `Status: approved` only when execution can proceed without improvisation.
 
-## Plan Storage (basic-memory)
+## Quality Gates
 
-Store plans as basic-memory notes in the repo project under `plans/`.
-
-- Project: `opencode-config` (or current repo project)
-- Note path: `plans/<feature-or-workstream-name>`
-- Use only basic-memory `plans/` notes for plan storage.
-
-## Plan Header Template
-
-```markdown
-# [Feature Name] Implementation Plan
-
-> For implementation: use `subagent-driven-development` when subagents are available; otherwise use `executing-plans`.
-
-**Goal:** [one sentence]
-
-**Architecture:** [2-3 concise sentences]
-
-**Tech Stack:** [languages, frameworks, tools]
-```
-
-## Build the Plan in This Order
-
-1. **Map file structure first**
-   - List files to create/modify/test using exact paths.
-   - State each file's responsibility.
-   - Prefer small, focused files and clear interfaces.
-
-2. **Decompose into small actionable tasks**
-   - Tasks should be independently understandable and testable.
-   - Use checkbox syntax for steps: `- [ ]`.
-   - Keep each step concrete (write test, run command, implement minimal code, re-run checks).
-
-3. **Include code shape guidance**
-   - Show function/class signatures, data flow, and key logic constraints.
-   - Avoid vague instructions like "add validation" without describing expected behavior.
-
-4. **Include exact verification commands (when known)**
-   - Provide commands with scope and expected result.
-   - Example: `pytest tests/path/test_file.py::test_case -v` → expected FAIL before implementation, PASS after.
-   - If exact commands are unknown, state how to discover them from repo scripts/docs.
-
-## Task Template
-
-````markdown
-### Task N: [Name]
-
-**Files:**
-- Create: `path/to/new_file.ts`
-- Modify: `path/to/existing_file.ts`
-- Test: `path/to/test_file.ts`
-
-- [ ] Step 1: Write/extend failing test for [specific behavior]
-- [ ] Step 2: Run: `<exact command>` and confirm expected failure
-- [ ] Step 3: Implement minimal code for [specific behavior]
-- [ ] Step 4: Run: `<exact command>` and confirm pass
-- [ ] Step 5: Run broader verification: `<exact command>`
-````
-
-## Plan Review Loop (required)
-
-After each plan chunk:
-
-1. Review for completeness, scope alignment, actionable decomposition, and verification quality.
-2. Fix identified issues in the same chunk.
-3. Re-review until the chunk is implementation-ready.
-
-Suggested chunking: use `## Chunk N: <name>` headings for large plans.
-
-## Completion Handoff
-
-When done, state where the plan is stored in basic-memory (for example `plans/<name>`) and whether execution should proceed via:
-- `subagent-driven-development` (preferred when available), or
-- `executing-plans` (single-agent execution).
+- No ambiguous acceptance criteria.
+- No hidden scope expansion.
+- Verification is specific and runnable.