Ss Coding

Multi-Agent Parallel TDD Development

Execute an implementation plan by dispatching multiple subagents in parallel, each following test-driven development, then hand off to the ss-code-review skill for one comprehensive review pass once every task passes its tests.

Core architecture: the orchestrator (you) never writes code. You read the plan, dispatch subagents, track progress, and collect results. All code is written by implementer subagents.

Zero-context assumption: each implementer subagent starts with a fresh context and no knowledge of the codebase. You must hand it everything it needs — full task text, context, specs, and a scope boundary.

Inputs

This skill expects one of:

• a path to a plan file already broken into tasks (produced by the ss-plan skill);
• a link to an external requirement or design document (wiki page, ticket, PRD);
• a plain-language description of the requirement.

If none of these is supplied, ask the user for one before proceeding.

Iron Rules

Violating any of these means stop and escalate to the user:

1. The orchestrator never writes code. You dispatch, track, and review status. You never directly edit source files. (Non-source edits — updating plan checkboxes, correcting plan text — are fine.)
2. Review is delegated to ss-code-review. Once all tasks complete and tests pass, invoke it in post-coding mode. Do not dispatch your own per-task reviewers.
3. Continuous execution. Don't pause between tasks to ask "should I continue?" Run until every task is done or blocked.
4. Respect parallel boundaries. Subagents in the same parallel group may run concurrently; subagents in different groups must run sequentially.
5. No file conflicts. Parallel subagents must never modify the same file. If the plan has parallel tasks touching the same file, run them sequentially instead.
6. Three strikes and you stop. The same error on the same task, three times, means stop and report to the user. "Same error" means the same failing test case, the same compiler/lint error at the same file:line, or the same exception type from the same stack-trace origin — different messages on different lines count as separate errors.
7. Scope breach is a hard stop. If a subagent modifies files outside its task's file list, reject the work and re-dispatch with an explicit constraint.
8. Specs are binding. Any specs discovered for the repository apply to every implementer prompt.
9. Never implement directly on the trunk branch (main/master). If the current branch is main/master, stop and ask the user to create a feature branch first (the ss-create-branch skill can do this).
10. Deliver full scope — no silent reduction. Execute every task in the plan. Never skip a task, stub out logic, or downgrade an implementation to a "simplified version" to finish faster, and never re-scope the plan into "MVP now, phase two later" on your own initiative. If the full plan can't be completed, stop and report the blocker — never present partial work as complete. Exception: scope the user explicitly cut, deferred, or accepted as blocked. Record that decision under a "User-Confirmed Scope Adjustments" section in the plan file (the persistent record the downstream review reads) and repeat it in the final report.

Input Routing

digraph input_routing {
    "User input" [shape=ellipse];
    "Has Task structure?" [shape=diamond];
    "Inline quick mode?" [shape=diamond];
    "Call ss-plan" [shape=box];
    "Full pipeline" [shape=box];
    "Inline mode" [shape=box];

    "User input" -> "Has Task structure?";
    "Has Task structure?" -> "Inline quick mode?" [label="yes"];
    "Has Task structure?" -> "Call ss-plan" [label="no"];
    "Inline quick mode?" -> "Inline mode" [label="≤2 tasks"];
    "Inline quick mode?" -> "Full pipeline" [label=">2 tasks"];
    "Call ss-plan" -> "Full pipeline";
}

How to detect Task structure: the document contains ### Task N headings with - [ ] Step checkboxes and **Files:** sections.

Validation gate: if a task has no **Files:** section, stop. The plan is incomplete — report it to the user.

| Input | Detection | Action | |---|---|---| | ss-plan output | file under docs/plans/, has Task/Step structure | execute (inline or full) | | Plain-language requirement | plain text, no Task structure | run ss-plan on the text, then execute | | Link to an external doc | a URL rather than a local file path | run ss-plan on the link, then execute | | Local markdown (requirement/proposal) | .md file without Task structure | run ss-plan on the path, then execute | | Proposal-writing output | file under docs/proposals/, has architecture but no Tasks | run ss-plan on the path, then execute |

Edge case — plan has 0 tasks: tell the user "the plan is empty, nothing to execute."

Edge case — tasks exist but no parallel-group markers: treat all tasks as one sequential group, executed in order.

Inline Quick Mode

When the plan has two tasks or fewer, skip the full parallel pipeline and execute directly:

1. Dispatch a single implementer subagent per task (sequentially).
2. Run the tests.
3. Invoke ss-code-review in post-coding mode (it skips Integration Review for small scope).
4. Handle any review feedback.
5. Report.

Small plans don't benefit from parallel-orchestration overhead — direct execution is faster. Inline mode still enforces TDD, spec compliance, the scope boundary, and the git strategy below.

Specs & Commands Discovery

Before dispatching any subagent:

1. Read CLAUDE.md and/or AGENTS.md at the project root for project-specific rules.
2. Always inject the shared guardrails: ../ss-guardrails/core.md, plus the guardrails file matching the project's primary stack (../ss-guardrails/java.md, go.md, cpp.md, web.md, android.md, ios.md, or flutter.md). Detect the stack from the project's build files/manifests; inject all files that apply if more than one stack is present.
3. Discover test and lint commands:

• check CLAUDE.md/AGENTS.md for documented commands;
• check package.json scripts (Node projects);
• check Makefile, build.gradle, or pom.xml (for the respective stack);
• check Taskfile.yml or CI workflow files.

Record these as TEST_COMMAND and LINT_COMMAND for use during execution.

1. If neither CLAUDE.md nor AGENTS.md exists, skip project-specific spec injection (the guardrails still apply) and note in the final report: "No project-specific specs were found."

OpenSpec Discovery

Before dispatching any implementer:

1. Discover active changes under openspec/changes/, excluding archive/.
2. If the plan file references an OpenSpec change, use that change ID.
3. If exactly one active change exists, use it.
4. If multiple active changes exist and none is referenced by the plan, ask the user which one applies.
5. Read every delta spec under openspec/changes//specs/*/spec.md and inject them into implementer prompts as binding requirements.

If the project has no openspec/ structure yet, this discovery step simply finds nothing — creating that structure is out of scope here (see the ss-write-spec / ss-reverse-spec skills).

Git Strategy

Environment: work in whatever directory the branch-creation step produced — an isolated worktree or the main checkout in place both work identically here. This skill never creates or removes worktrees or branches itself. Before starting, confirm the guardrails files are present (../ss-guardrails/core.md exists); if not, proceed without guardrails injection and note it in the final report.

All implementers work on the same feature branch (the current branch):

1. Before starting, verify the current branch is not main/master (Iron Rule 9).
2. Each implementer commits using the task's specified commit-message format.
3. Parallel-agent conflict handling: if an implementer can't commit because of a conflict with a parallel agent, it reports CONFLICT. Resolve it by pausing the rest of that group, resolving the conflict sequentially, then re-running tests for the affected tasks.
4. After all tasks complete, do not push — leave that decision to the user.

Progress tracking: update the plan file's checkboxes as tasks complete (- [x]). This lets execution resume if the session is interrupted.

Execution Process

digraph process {
    rankdir=TB;

    "Read plan, extract all Tasks" [shape=box];
    "Group by parallel group" [shape=box];
    "More groups remain?" [shape=diamond];
    "Dispatch group" [shape=box];
    "Per-task lifecycle" [shape=box];
    "All tasks in group done?" [shape=diamond];
    "Fix loop" [shape=box];
    "Plan issue?" [shape=diamond];
    "Pause and correct plan" [shape=box];
    "Full test suite" [shape=diamond];
    "Fix failing tests" [shape=box];
    "Comprehensive review (ss-code-review)" [shape=box];
    "Review verdict" [shape=diamond];
    "Fix review issues" [shape=box];
    "Report to user" [shape=box];

    "Read plan, extract all Tasks" -> "Group by parallel group";
    "Group by parallel group" -> "More groups remain?";
    "More groups remain?" -> "Dispatch group" [label="yes"];
    "More groups remain?" -> "Full test suite" [label="no"];
    "Dispatch group" -> "Per-task lifecycle";
    "Per-task lifecycle" -> "All tasks in group done?";
    "All tasks in group done?" -> "Plan issue?" [label="yes"];
    "All tasks in group done?" -> "Fix loop" [label="no"];
    "Fix loop" -> "Per-task lifecycle";
    "Plan issue?" -> "Pause and correct plan" [label="yes"];
    "Plan issue?" -> "More groups remain?" [label="no"];
    "Pause and correct plan" -> "More groups remain?";
    "Full test suite" -> "Comprehensive review (ss-code-review)" [label="pass"];
    "Full test suite" -> "Fix failing tests" [label="fail"];
    "Fix failing tests" -> "Full test suite" [label="retry (max 3)"];
    "Fix failing tests" -> "Report to user" [label="3 retries failed"];
    "Comprehensive review (ss-code-review)" -> "Review verdict";
    "Review verdict" -> "Report to user" [label="APPROVED"];
    "Review verdict" -> "Fix review issues" [label="NEEDS_CHANGES / CRITICAL_ISSUES"];
    "Fix review issues" -> "Full test suite" [label="retry (max 2 cycles)"];
}

Step 1: Read the Plan & Extract Tasks

1. Read the plan file once; extract every task with its full text.
2. Note parallel-group assignments and dependency relationships.
3. Order groups by dependency (group A before group B if B depends on A).
4. Mark the plan file with progress as tasks complete (update checkboxes).

Step 2: Dispatch by Parallel Group

For each parallel group, in dependency order:

• 1 task: dispatch a single implementer subagent.
• 2-5 tasks: dispatch implementer subagents in parallel, one per task.
• 6+ tasks: batch into sub-groups of at most 5, run sub-groups sequentially.

Parallel dispatch limit: 5 subagents at a time. For long operations (build, install, full test suite), run them in the background rather than blocking on anything that takes more than about 30 seconds.

Step 3: Per-Task Lifecycle

For every task, whether parallel or sequential:

1. Dispatch an implementer subagent using the ../ss-references/implementer-prompt.md template.
2. Handle the status it reports:

• DONE → task complete, update the plan checkbox.
• DONE_WITH_CONCERNS → check the blocking_concerns field: non-empty means address it first and re-dispatch; only observations means the task is complete (log the observations for the final report).
• NEEDS_CONTEXT → supply the missing context and re-dispatch.
• BLOCKED → escalate (see "Handling Subagent Status" below).
• PLAN_ISSUE → pause execution (see "Plan Correction").
• CONFLICT → resolve sequentially (see "Git Strategy").

There is no per-task review — code review happens collectively via ss-code-review in post-coding mode after all tasks complete and tests pass (Step 6). This avoids redundant per-task reviews and enables cross-task integration analysis.

Implementer self-checks are still required. Each implementer must follow TDD (write a failing test, implement, verify it passes), run the lint command on changed files, self-verify against specs before reporting DONE, and include test output in its status report.

Step 4: Plan Correction (mid-execution)

If an implementer discovers the plan has factual errors (wrong file paths, wrong assumptions, missing dependencies):

1. Pause — stop dispatching new tasks.
2. Assess — is this localized to one task, or systemic (an architectural assumption is wrong)?
3. Localized fix — correct the specific task in the plan file and continue.
4. Systemic issue — report to the user and wait for confirmation before continuing.

This is not license to redesign the plan — only factual errors warrant correction.

Step 5: Full Test Suite

Run TEST_COMMAND (discovered during Specs & Commands Discovery).

If all tests pass: record the current HEAD commit SHA (git rev-parse HEAD) and proceed to the comprehensive review (Step 6). Include this test-verified SHA in the final report so a downstream ss-create-pr run can skip a redundant re-test.

If tests fail:

1. Identify which tasks caused the failures by correlating failing tests with changed files.
2. Re-dispatch the affected implementers with the failure details.
3. Re-run the full test suite.
4. Maximum 3 full-suite retry cycles; after 3 failures, report to the user with the failing tests listed.

Also run LINT_COMMAND if one was discovered — lint failures follow the same fix cycle.

Step 5.5: Spec Compliance Gate

Run this after tests/lint pass and before ss-code-review:

1. Check for delta specs under openspec/changes//specs/.
2. If none exist, decide whether this is zero-spec mode: auto-allow only when the changed files are limited to docs, comments, CI/build configuration, dependency metadata, or tests. Otherwise stop with: "This change affects system capability but has no delta spec. Run the ss-write-spec skill to add one, then continue — or explicitly confirm this is a zero-spec change."
3. If a delta exists, verify coverage: for every Requirement and every Scenario, find an automated test covering its WHEN/THEN behavior (test names should map to Requirement/Scenario names where practical). If coverage is missing, report NEEDS_TEST with the uncovered scenarios listed.
4. Re-dispatch implementers to add the missing tests, then rerun tests and this gate.
5. Maximum 2 compliance cycles; if still uncovered, stop and escalate to the user.

This gate validates spec coverage only — it doesn't rewrite or invent specs during coding. Missing or incorrect specs get fixed by going back to ss-plan or ss-write-spec.

Step 5.6: Full-Scope Gate

Run this after the Spec Compliance Gate and before ss-code-review. It verifies nothing was silently narrowed during execution:

1. Task completeness — every task in the plan is checked off, and a task may only be checked off once all of its steps are done. A stubbed or partially implemented task stays unchecked and blocks this gate.
2. Scope-reduction scan — grep the newly added/modified code for deferral markers: TODO, FIXME, "for now", "simplified", "not implemented", "placeholder", "stub", and hardcoded values standing in for real logic. Each hit is a judgment call, not an automatic failure: a genuine deferral must be completed before proceeding; a confirmed false positive (a UI placeholder= attribute, a test double, deliberate fail-fast on an unsupported path, ordinary comment phrasing) gets dismissed with a one-line reason in the report.
3. On failure — re-dispatch the affected implementers to finish the work. Don't rationalize a gap as "MVP scope," "phase two," "optional," or "nice to have" — re-scoping decisions belong to the user alone.
4. Exception — scope the user explicitly cut, deferred, or acc

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lbk-open
• Source: lbk-open/super-spec
• License: Apache-2.0
• Homepage: https://www.npmjs.com/package/@lbk-open/super-spec

Install and usage instructions live in the source repository linked above.