Ss plan

Build Execution Plan

Decompose a requirement or technical proposal into an executable, task-level implementation plan. Each task must be small enough for a single agent to complete independently, with explicit dependencies, exact file paths, and verification criteria.

Language of the plan: write the plan's prose in the same language as the input document (or the project's existing docs, if that's a clearer signal); default to English when neither gives a signal. Code, commands, and file paths always stay in their original form regardless of prose language.

Zero-context assumption: write the plan as if the executor has zero knowledge of the codebase and limited design taste. Every task must be fully self-contained — the executor should never need to "figure out" what to do. If a step changes code, show the code. If a step runs a command, show the command and its expected output.

Inputs

One of:

• A link to a requirement or proposal document that your document-reading tool can fetch.
• A local Markdown file path.
• Plain text describing the requirement directly.

If the input is missing or too thin to extract a goal, scope, and acceptance criteria, ask the user rather than guessing.

Iron Rules

Violating any of these means stop and start over:

1. Comprehend before planning — do not start decomposing until the entire input is read and understood. Skipping this voids the plan.
2. Never guess — if the input is ambiguous or missing information, ask the user. Do not assume and continue.
3. No placeholders — see "No Placeholders" below for the full list of forbidden patterns.
4. Every task must be independently verifiable, and acceptance traces to the spec — each task ends with a concrete acceptance command and expected output. When Phase 0 produced delta specs, the acceptance MUST cover a named Scenario from that delta (the Scenario is the single source of truth for expected behavior) — do not author parallel, independent acceptance prose that restates the Scenario.
5. Exact file paths — every referenced file is a real path from the project root. No vague descriptions.
6. TDD-driven — code tasks have test steps before implementation steps.
7. DRY / YAGNI — do not plan features that weren't requested; do not add abstraction layers for hypothetical future needs.
8. Self-contained tasks — each task produces a change that makes sense on its own, and the project still compiles/runs after it. Never write "similar to Task N" — repeat the code, since executors may work tasks out of order.
9. Plan the full scope, no unauthorized reduction — the plan must cover every requirement point in the input. Never defer work to "phase 2 / a later iteration / future enhancement," plan only an "MVP / P0 / core" subset, or quietly downgrade a requirement. Splitting the plan (see Scope Check) changes delivery packaging, not scope — every sub-plan still gets written. If the full scope can't be planned, stop and ask the user. The only valid reduction is one the user explicitly requested — record it in the plan header's "User-Confirmed Scope Adjustments" section, which downstream review also reads.

No Placeholders

These are plan failures — never write them:

• "TBD", "TODO", "to be added later", "fill in details"
• "Add appropriate error handling" / "add validation" / "handle edge cases"
• "Write tests for the above" without actual test code
• "Similar to Task N" — repeat the code, since executors may read tasks out of order
• "Refer to module X" without a concrete code path
• Steps that describe what to do without showing how (code steps need code blocks)
• References to types, functions, or methods not defined in any task
• "Add necessary imports" instead of listing them explicitly

Input Handling

Input type	Detection	Method
Document link	A URL your document-reading tool can fetch	Fetch and read it as Markdown/text
Local Markdown	Starts with / or ./, ends in .md	Read the file directly
Plain text	Neither of the above	Use the input as-is

Specs Discovery

Before starting any phase, discover the repository's own specs/conventions:

1. Read CLAUDE.md and/or AGENTS.md at the project root.
2. Extract any referenced spec files (paths, submodules, or inline rules).
3. Read the relevant spec files identified above (e.g., coding conventions, test conventions, commit-message conventions).

If specs are found, they apply to every subsequent phase:

• Plan structure and naming follow the spec's conventions.
• Task-level code complies with coding conventions (naming, error handling, testing patterns).
• Self-review verifies spec compliance.

OpenSpec config.yaml context injection: if openspec/config.yaml exists, its context block is binding project context and MUST be applied to every generated artifact (delta specs and the task plan alike). Specifically:

• Treat context as authoritative background for capability-ownership decisions, naming, and scope.
• Treat rules.delta and rules.spec entries as binding format/quality constraints on the Phase 0 delta; a violation is a plan failure.
• When handing work to a subagent, carry these constraints forward explicitly — they are not optional context.

If specs exist, note them — they become binding constraints for the plan.

OpenSpec Delta Phase

Before Phase 1, run Phase 0: Generate Delta Spec unless the request is clearly zero-spec.

Zero-spec Mode

Skip Phase 0 only when the request cannot affect observable system behavior:

• Documentation-only changes
• Comment-only changes
• Internal refactoring with no public API or behavior change
• Build/CI/dependency configuration updates
• Test-only changes

If uncertain, don't skip — generate a minimal delta instead.

Phase 0: Generate Delta Spec

This phase internalizes the ss-write-spec skill; you normally don't need to invoke that skill directly when running this one.

1. Read OpenSpec context:
   • openspec/config.yaml if present — treat context as binding project context and rules.delta/rules.spec as binding format constraints; inject them into every artifact generated below.
   • existing openspec/specs/*/spec.md
   • active openspec/changes/*/specs/*/spec.md, excluding archive/
   • relevant OpenAPI YAML files if the proposal mentions API paths
2. Derive a stable change-id in kebab-case from the proposal title, branch name, or requirement text.
3. Decide capability ownership:
   • Prefer existing capability directories.
   • New capability names are kebab-case business noun phrases.
   • If ownership is ambiguous, stop and ask the user to confirm — never guess.
4. Write delta files to openspec/changes/<change-id>/specs/<capability>/spec.md.
5. Copy the proposal or input summary to openspec/changes/<change-id>/proposal.md.

Delta format is strict:

## ADDED Requirements

### Requirement: <name>
The system SHALL ...

#### Scenario: <name>
- **WHEN** ...
- **THEN** ...
- **AND** ...

Allowed sections are exactly:

• ## ADDED Requirements
• ## MODIFIED Requirements
• ## REMOVED Requirements
• ## RENAMED Requirements

Rules:

• Every Requirement MUST have at least one #### Scenario:.
• Scenario headings MUST use four #.
• MODIFIED MUST copy the original Requirement from the source of truth in full, then edit it.
• REMOVED MUST include **Reason:** and **Migration:**.
• RENAMED uses FROM: <old> → TO: <new>.
• Keep SHALL/MUST/MAY/SHOULD in English regardless of the prose language used elsewhere in the delta.

Phase 0 Self-Review

Before proceeding:

• Every functional requirement maps to a Requirement or Scenario.
• Existing capabilities were reused where appropriate.
• MODIFIED content is complete, not a short diff note.
• REMOVED includes a Migration note.
• openspec/config.yaml's context was applied as binding project context, and every rules.delta/rules.spec entry is satisfied by the generated delta.
• Scenario headings use #### Scenario:.

Scope Check

This check runs before any planning work. If the input covers multiple independent subsystems, split it into separate plans.

Split ≠ cut. Splitting produces multiple plans that are all written and all delivered — it reorganizes the work, never removes or defers any requirement point. Dropping a subsystem from the plan requires an explicit user instruction.

When to split

Split into multiple plans when any of these hold:

Signal	Example	Action
Input spans 2+ services/repos	"Order service + Payment service"	One plan per service
Input spans frontend + backend	"React page + Go API + DB migration"	One plan per layer
Input has 2+ features with no shared code	"User login + Report export"	One plan per feature
Decomposition yields 20+ tasks with heavy cross-dependencies	—	Go back and split

When not to split

• Single service, single feature, even if complex (many tasks are fine as long as they form a clean DAG).
• Multiple tasks that share the same data model or interface (splitting would create duplication).

How to split

1. Identify independent subsystems from the input.
2. For each subsystem, create a separate plan file: YYYY-MM-DD-<name>-<module>.md.
3. Each sub-plan must be independently deliverable — after executing one plan, the system is in a valid state.
4. If sub-plans have ordering dependencies (e.g., the backend API must exist before the frontend calls it), state the execution order explicitly:

   Execution order:
   1. docs/plans/2026-05-10-payment-backend.md (creates APIs)
   2. docs/plans/2026-05-10-payment-frontend.md (consumes APIs)
   

5. Confirm the split approach with the user before proceeding to Phase 1.

Multi-repo split: master plan (required when the split spans 2+ git repositories)

When the sub-plans belong to different git repositories (not just different modules of the current repo), the split MUST also produce a master plan so the ss-multi-repo-workflow skill can execute the set:

1. Sub-plan header field: every sub-plan gets a **Repo:** <repo-name> line in its header, and its **Files:** paths are relative to that repository's root.
2. Repository path detection: probe ../<repo-name> (a sibling directory of the current repo). If it doesn't exist or its git remote doesn't match, ask the user for the correct local path — never guess.
3. Master plan file: docs/plans/YYYY-MM-DD-<slug>-master.md in the current repo:

# <Requirement Name> Multi-Repo Execution Master Plan

> **Agent execution guide:** use the `ss-multi-repo-workflow` skill to execute this master plan.

**Repos:**
| Repo | Local Path | Sub-plan | Batch | Depends On |
|---|---|---|---|---|
| payment-service | ../payment-service | 2026-07-03-refund-payment.md | 1 | — |
| order-service | ../order-service | 2026-07-03-refund-order.md | 2 | payment-service (consumes its API) |

**Unified branch name:** feat/<slug>
**Contract changes:** <path to the shared API-contract repo, if the contract change was prepared separately / none>
**User-Confirmed Scope Adjustments:** none

4. Batching rules: repos with no cross-repo dependency share a batch (parallel); an API consumer is always in a later batch than its provider. The batch/dependency columns are hard constraints for downstream execution.
5. Splits within a single repository are unaffected — no master plan, no **Repo:** field, behavior unchanged.

If already split upstream

If the input comes from the ss-proposal skill and was already scoped to one subsystem, skip this check and proceed directly to Phase 1.

Phase 1: Comprehend

Gate: do not proceed to Phase 2 until every item below is extracted.

1. Read the entire input document.
2. Read openspec/changes/<change-id>/specs/ generated by Phase 0, if present, and treat it as binding requirement input.
3. Extract and list:
   • Goal: what problem does this solve? (one sentence)
   • Scope: which modules/services/layers are involved?
   • Constraints: technical, timeline, and dependency constraints.
   • Acceptance criteria: how do we know it's done? When Phase 0 produced delta specs, the acceptance criteria ARE the Scenarios in openspec/changes/<change-id>/specs/<cap>/spec.md — each Scenario's WHEN/THEN is one criterion; reference them by name instead of re-inventing or rephrasing them. Only in zero-spec mode, extract criteria from the input or confirm with the user.

If any item above can't be extracted from the input, ask the user — do not assume and proceed.

Phase 2: Architect

File Structure

Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.

Design principles:

• Each file has one clear responsibility.
• Files that change together live together — split by responsibility, not technical layer.
• Prefer smaller, focused files over large ones that do too much.
• In existing codebases, follow established patterns; don't unilaterally restructure.
• If a file you're modifying has grown unwieldy, including a split in the plan is reasonable.

Format:

- Create: src/service/payment/handler.go       # payment callback handler
- Modify: src/service/order/service.go:45-80   # add payment status update
- Create: src/service/payment/handler_test.go  # unit tests

This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.

Dependency Graph

Identify task dependencies:

• Which tasks have no dependencies and can run in parallel?
• Which tasks must be sequential (B depends on A's output)?

Technical Decisions

If the proposal offers multiple implementation paths, state the chosen one and the reason in one line.

Diagrams

Use diagrams to clarify architecture and flow where text alone would be ambiguous:

• Architecture / sequence / activity diagrams: use PlantUML syntax in fenced ```plantuml code blocks.
• Simple structural diagrams (directory trees, data flow, component layout): use ASCII art.
• Prefer diagrams over long text for system interactions, call chains, and state transitions.
• Every diagram needs a title (title ... in PlantUML) and must be referenced from a task or the dependency graph.

Phase 3: Decompose

Break the architecture into appropriately-sized tasks.

Granularity criteria:

• One task = one focused concern (one endpoint, one model, one feature point).
• After each task, the project still compiles/runs.
• Each task is self-contained — an executor with zero codebase context can complete it.

Bite-Sized Step Granularity

Each step within a task is one action (2–5 minutes):

• "Write the failing test" — step
• "Run it to confirm it fails" — step
• "Implement the minimal code to make the test pass" — step
• "Run the tests and confirm they pass" — step
• "Commit" — step

Do not bundle multiple actions into one step.

Task Template

### Task N: [Concrete name, not generic]

**Depends on:** Task X (or "None")
**Parallel group:** A (tasks in the same group can execute concurrently)

**Files:**
- Create: `exact/path/to/file.ext`
- Modify: `exact/path/to/existing.ext:line-range`
- Test: `tests/exact/path/to/test_file.ext`

**Steps:**

- [ ] Step 1: Write the failing test

```language
// Complete test code — not pseudocode, not "add test here"
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

- [ ] Step 2: Run the test to verify it fails

Run: `exact test command`
Expected: FAIL — "specific error message"

- [ ] Step 3: Write the minimal implementation

```language
// Complete implementation code — every import, every line
def function(input):
    return expected
```

- [ ] Step 4: Run the test to verify it passes

Run: `exact test command`
Expected: PASS

- [ ] Step 5: Commit

```bash
git add exact/path/to/file.ext tests/exact/path/to/test_file.ext
git commit -m "type(scope): description"
```

**Covers Scenario:** `<capability>/<Scenario name>` (from `openspec/changes/<change-id>/specs/`; use "None" only in zero-spec mode)

**Acceptance:** `verification command` → expected output (the assertion MUST verify the WHEN/THEN of the covered Scenario)

Remember

• Exact file paths, always.
• Complete code in every step — if a step changes code, show the code.
• Exact commands with expected output.
• Never "similar to Task N" — repeat the full code.
• DRY, YAGNI, TDD, frequent commits.

Phase 4: Self-Review

After completing the plan, review it with fresh eyes. This is not a rubber stamp — actively search for issues.

1. Requirement coverage

Skim each section/requirement in the source. Can you point to a task that implements it? List any gaps and add the missing task.

2. Scope reduction scan

Search the plan for phasing/deferral language: MVP, Phase 2, staged rollout, later iteration, simplified version, core-only, P0-only, "out of scope." Every hit must trace to an explicit user instruction recorded in the plan's "User-Confirmed Scope Adjustments" section; otherwise add the missing tasks now.

3. Placeholder scan

Search the plan for every pattern in "No Placeholders" above. Fix every occurrence immediately.

4. Exact paths

For every file path in the plan, verify it's a real path from the project root (check against the codebase). Vague paths like "in the service directory" get replaced with exact paths.

5. Name consistency

Do the types, method signatures, and property names used in later tasks match what earlier tasks defined? A function called processPayment() in Task 3 but handlePayment() in Task 7 is a bug — fix it.

6. No circular dependencies

Trace the dependency graph. If Task A depends on Task B which depends on Task A, restructure.

7. Every task has acceptance, traced to a Scenario

Each task ends with a runnable verification command and expected output. When delta specs exist: every task names the Scenario it covers (**Covers Scenario:**), and every Scenario in the delta is covered by at least one task. If a Scenario has no task, add it. If a non-zero-spec task lacks a Covers Scenario link, fix the linkage rather than inventing parallel acceptance prose.

8. Parallel groups annotated

Tasks with no interdependency are marked with a parallel group label.

9. Spec compliance

If repo specs were discovered: verify naming conventions, error-handling patterns, test structure, and commit-message format all conform.

10. PlantUML validation

For each plantuml fenced block:

• Render it via a PlantUML server — the public instance at https://www.plantuml.com/plantuml, or a local/self-hosted renderer if the project configures one — by encoding the source and requesting /png/{encoded} (or /svg/{encoded}).
• Verify the returned image contains no "Syntax Error" text.
• If image rendering isn't available in your environment, at minimum validate @startuml/@enduml presence and correct diagram-type keywords.

Found issues get fixed inline — no need to re-run the full process.

Phase 5: Independent Agent Review

If your tool supports spawning a subagent with fresh context:

Spawn an independent review agent that has NOT seen the generation process:

Review agent prompt:

You are a plan reviewer. Review the execution plan below against:
1. The original requirement/spec (provided)
2. Repository coding specs (if any, provided)

Focus areas:
- Does every requirement point map to a task?
- Any requirement silently deferred ("Phase 2", "MVP scope", "future iteration") or downgraded without a user instruction recorded in the plan's "User-Confirmed Scope Adjustments" section? Flag as MUST-FIX.
- Do code snippets follow the repository's naming/style conventions?
- Are test patterns consistent with the spec's test guidelines?
- Are file paths valid for this project structure?
- Any placeholder violations (TBD/TODO/"refer to"/"similar to")?
- Is the dependency graph a valid DAG?
- Are PlantUML diagrams syntactically correct?
- Is every task self-contained for a zero-context executor?
- When delta specs exist: does every Scenario map to at least one task's `Covers Scenario`, and does each task's acceptance verify that Scenario's WHEN/THEN rather than restating it as separate prose?

Output: a list of issues, each with severity (MUST-FIX / SHOULD-FIX / NIT) and location (Task N, Step M).
If no issues: confirm "LGTM — plan is ready for execution."

Input to the review agent:

• The generated plan markdown
• The original requirement source (link or text)
• Paths to repository specs, if discovered

After review:

• MUST-FIX items get fixed immediately, before saving.
• SHOULD-FIX items get fixed, or the plan documents why they were skipped.
• NIT items get fixed if trivial, otherwise ignored.

If subagents aren't available: the Phase 4 self-review is sufficient — skip this phase.

Output: Plan Document

Save location: docs/plans/

Naming convention: YYYY-MM-DD-<requirement-name>[-<module-name>].md

• Date: today's date
• requirement-name: an English slug of the requirement/proposal (lowercase, hyphens)
• module-name: only when splitting into multiple sub-plans

Examples:

• Single plan: docs/plans/2026-05-10-user-payment.md
• Multiple plans: docs/plans/2026-05-10-user-payment-backend.md, docs/plans/2026-05-10-user-payment-frontend.md

Document header:

# [Requirement Name] Execution Plan

> **Agent execution guide:** use the `ss-coding` skill to execute these tasks in parallel per this plan.

**Goal:** [one-sentence goal]
**Architecture:** [2-3 sentences: pattern used, layering approach, core data flow]
**Tech Stack:** [key technologies/frameworks/middleware involved]
**Scope:** [modules/services touched]
**Source:** [link or description of the input document]
**Date:** YYYY-MM-DD
**OpenSpec Change:** openspec/changes/<change-id>/ (if applicable)
**User-Confirmed Scope Adjustments:** [record each instruction, verbatim, only when the user explicitly asked to reduce/phase/accept a blocker; otherwise "none"]

---

## File Map
[Phase 2 file structure map]

## Dependency Graph
[Dependency graph with parallel group annotations]

## Task List
[All tasks from Phase 3]

The execution plan lives only in docs/plans/. Do not write a separate openspec/changes/<change-id>/tasks.md — nothing consumes it, and docs/plans/ is the single source for tasks. The OpenSpec change directory holds only proposal.md and the delta specs/.

Execution Handoff

After saving the plan, present execution options:

Plan saved to docs/plans/<filename>.md. Execution options:

1. ss-coding — multi-agent parallel execution (recommended for medium/large plans)
2. Sequential execution — execute tasks one by one in this session (for small plans, ≤5 tasks)
3. Manual review first — have the team review the plan before execution

Which approach?

If a multi-repo master plan was generated (see Scope Check), recommend the multi-repo path instead:

Multi-repo plan set saved:
- Master: docs/plans/<date>-<slug>-master.md
- Sub-plans: <list>

Recommended next step: run the ss-multi-repo-workflow skill on docs/plans/<date>-<slug>-master.md
(one sub-process per repository, batched by dependency order)

Anti-Patterns

Anti-pattern	Why it's harmful	Correct approach
Single task modifies 5+ files	Too large, hard to verify, hard to roll back	Split by concern into multiple tasks
"Implement XXX" with no code	Executor guesses implementation details	Show complete code in every step
Implementation without tests	Cannot verify correctness	TDD: test first, implement second
Implicit dependencies between tasks	Conflicts during parallel execution	Explicitly annotate dependencies
Skipping Phase 1 and jumping to tasks	Incomplete understanding, missed tasks	Extract goal/scope/constraints first
Over-engineering (unneeded abstraction)	Adds complexity, deviates from the requirement	YAGNI: only plan what's requested
Silently deferring requirements ("MVP first", "Phase 2", "P0 only")	User receives a partial delivery they never agreed to	Plan 100% of the input; phased delivery only on explicit user request, recorded in the plan
"Similar to Task N"	Executor may work out of order and can't find Task N	Repeat the full code — always self-contained
Bundling multiple actions in one step	Agent skips sub-actions when a step looks "done"	One action per step: write / run / implement / run / commit

Red Flags — Stop

If you catch yourself doing any of these, stop and return to the appropriate phase:

• Writing tasks before finishing the input → back to Phase 1
• Writing "TBD" or "to be confirmed" → ask the user instead
• A task description has no file paths → back to Phase 2
• Code steps use pseudocode or "add appropriate handling" → write complete code
• Referencing "similar to Task N" → repeat the code in full
• 20+ tasks with heavy interdependencies → back to Scope Check, split into sub-plans
• A step contains two actions ("write test and run it") → split into two steps

Examples

Input can be any of:

• A link to an issue or requirement document, e.g., https://github.com/<owner>/<repo>/issues/123
• A local proposal file, e.g., docs/proposals/2026-05-08-payment-refund.md
• Plain text, e.g., "Implement user login: support phone+SMS-code and WeChat-style QR scan"