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

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:

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 | Base SHA | Sub-plan | Batch | Depends On |
|---|---|---|---|---|---|
| payment-service | ../payment-service | `<planning-time HEAD>` | 2026-07-03-refund-payment.md | 1 | — |
| order-service | ../order-service | `<planning-time HEAD>` | 2026-07-03-refund-order.md | 2 | payment-service (consumes its API) |

**Unified branch name:** feat/<slug>
**Problem ID:** <required for troubleshooting input; otherwise omit>
**Investigation Report:** <exact path for troubleshooting input; otherwise omit>
**Violated Invariant:** <required for troubleshooting input; otherwise omit>
**Owning Boundary:** <required for troubleshooting input; otherwise omit>
**Patch-Style Alternative Rejected:** <required for troubleshooting input; otherwise omit>
**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.

Baseline Freshness

Before finalizing any execution plan, record git rev-parse HEAD for the repository whose code was read as canonical **BASE_SHA:** metadata. Each multi-repo sub-plan records its own repository's base; the master plan repeats those refs in its **Repos:** table. Validate refs as 7–64 lowercase hex characters. BASE_SHA is a freshness snapshot, not test evidence or the delivered ref.

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.

When the input is an ss-inspect investigation report, also require all of the following before planning: a stable **Problem ID:**; Confidence: HIGH with no material evidence gaps; a verified root cause and evidence chain; complete impact-scoped design/implementation understanding; the canonical **Violated Invariant:**, **Owning Boundary:**, and **Patch-Style Alternative Rejected:** fields; canonical one-entry-per-bullet **Affected Paths:** and **Repositories Requiring Fix:** lists; and repair, rollback, observability, compatibility/migration, and regression-verification guidance. An incomplete report returns to investigation rather than being filled in by the planner. A confirmed multi-repository list is binding: produce the matching master/sub-plan set and never silently drop a repository.

Phase 2: Architect

Troubleshooting Repair Design

For a plan sourced from an investigation report:

• Gate before architecture or task writing: restate and validate the report's relevant component responsibilities/ownership, end-to-end flow, dependencies, contracts/invariants, existing mechanisms, healthy analogous paths, included/excluded scope, and affected paths. If the planner cannot explain how they connect, return to ss-inspect; do not invent a local repair.
• Restore the violated invariant at the correct abstraction or ownership boundary; do not turn a symptom-only conditional at the failure line into the permanent design unless the evidence proves that boundary owns the behavior.
• Reuse an existing mechanism or extension point where the report identifies one.
• Map every **Affected Paths:** bullet from the report to at least one implementation task and one verification task or acceptance command.
• Include compatibility and downstream effects, migration work, rollback, observability, focused regression tests, full-suite verification, and runtime recovery signals in the architecture and task graph.
• Link the plan header to the exact Problem ID and investigation report path so downstream resume checks cannot confuse it with another incident.

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.

For troubleshooting plans, also verify that every **Affected Paths:** and **Repositories Requiring Fix:** bullet in the confirmed investigation report remains covered; the design restores the named invariant at the correct boundary; and compatibility, migration, rollback, observability, regression, and runtime recovery work is present. Any omission is a plan defect, not an allowed scope reduction.

10. Baseline freshness metadata

Verify every execution plan/sub-plan has a valid canonical **BASE_SHA:** equal to the repository snapshot used for code and interface assumptions; verify each multi-repo master row repeats the matching sub-plan ref. Refresh stale assumptions before saving.

11. 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?
- Can a fresh-context implementer locate the exact task by plan path + heading and execute it using the task-referenced specs, every repository-spec/guardrail path supplied by dispatch, concise dispatch context, and permitted repository exploration?
- Is `**BASE_SHA:**` valid and does the plan still match relevant files/symbols/interfaces at that snapshot? For multi-repo plans, do master rows match sub-plans?
- For troubleshooting input, is `Troubleshooting Repair Basis` complete, are canonical invariant/boundary/patch-rejection fields preserved, and does every affected path map to implementation plus verification?
- 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]
**Repo:** [required for a multi-repo sub-plan; repository name matching the master table; otherwise omit]
**Source:** [link or description of the input document]
**Problem ID:** [required for plans sourced from an investigation report; otherwise omit]
**Investigation Report:** [exact path when applicable; otherwise omit]
**BASE_SHA:** [7–64 lowercase hex planning-time HEAD for this repository]
**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"]

---

## Troubleshooting Repair Basis
<!-- Required only for plans sourced from an investigation report; otherwise omit this section. -->

**Relevant design and implementation:** [responsibilities/ownership, end-to-end flow, dependencies, contracts/invariants, existing mechanisms, healthy analogous paths, included/excluded scope]
**Violated Invariant:** [exact invariant and evidence]
**Owning Boundary:** [where the behavior belongs and why]
**Patch-Style Alternative Rejected:** [tempting symptom/local-special-case patch and why it fails to restore the invariant]

| Affected path from report | Implementation task | Verification task/command |
|---|---|---|
| `<repo>:<path>` | Task N | Task M / `<command>` |

## 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 capability-checked repository runner per real repo cwd, batched by dependency order)

Anti-Patterns

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"