sudokar/openspec-plus/openspec-plus-apply

OpenSpec Plus Apply

Mission

Wrap vanilla /opsx-apply step 6 (task implementation loop) with subagent orchestration, two-stage review, strict TDD via openspec-plus-tdd, four implementation principles, conditional parallelism over a dependency-validated graph, per-slice + final lint/format/test/other gates, never-ignore-failures rule.

Vanilla owns:

• Step 1 — Select change
• Step 2 — openspec status --change <name> --json
• Step 3 — openspec instructions apply --change <name> --json
• Step 4 — Read context files
• Step 5 — Show progress
• Step 7 — Final status (this skill EMULATES output, not invokes vanilla)

This skill takes over Step 6 only.

RIGID. NEVER skip Phase 0 mode question when `settings.apply.executionMode` is `ask`. NEVER read affected source code files into the main agent's context — pass PATHS to subagents who read them. NEVER mark a slice `[x]` while a relevant test is failing or skipped. NEVER run code-quality review before spec-compliance ✅. NEVER dispatch parallel implementer subagents within a change without dependency analysis + user confirmation. NEVER modify spec/design from inside the implementer — escalate to plus-design / plus-spec. NEVER commit code. NEVER take over vanilla steps 1-5 or invoke openspec-verify-change or auto-trigger /opsx-archive.

Red flags — STOP, you are about to violate this skill:

• "Re-read the artifacts to be safe" — vanilla loaded them, in context
• "Let me read the affected source files before dispatching the subagent" — NO (subagent mode). Pass paths. Subagent reads. (Inline mode is different — main agent reads directly.)
• "Critique the spec/design before starting" — done; trust them
• "Fix the spec/design from here while implementing" — escalate, don't edit
• "Mark the test .skip to move on" — never. Failing tests block progress
• "Slice is small, skip the spec-compliance reviewer" — never
• "Implementer's report says DONE, good enough" — verify with reviewer subagents
• "Both reviewers found issues, fix simultaneously" — spec-compliance first, re-review, then code-quality
• "Reviewing is generic, I'll write the review prompt myself" — NO. Every reviewer dispatch reads its *-prompt.md and sends the body verbatim; improvising it is the #1 failure mode
• "This prompt is long, I'll tighten it / drop the obvious parts when passing it on" — NO. Copy the template's prompt: block verbatim, substitute only {PLACEHOLDER}s. Every bullet is load-bearing; simplifying silently strips instructions from the subagent
• "Should I continue to the next slice?" — never ask. Continuous unless BLOCKED
• "Three fixes failed, try a fourth" — STOP. Artifacts wrong. Pause and exit
• "Run all tests instead of just affected" — wastes time; per-slice gate is scoped
• "Commit as I go" — vanilla doesn't commit; we don't either
• "Run /opsx-archive once everything is done" — only suggest, never auto-trigger
• "Run openspec-verify-change as part of final gate" — out of scope
• "Implementer wrote all tests upfront, that's fine" — TDD violation. One test at a time.
• "Implementer skipped REFACTOR because nothing to refactor" — refactor assessment is mandatory; skipping the assessment is the violation, not the skipping of action
• "AGENTS.md has many rules, implementer applied the ones that felt relevant" — cherry-picking the project's documented rules. Follow them strictly, end-to-end.
• "Implementer did test 1 RED-GREEN-REFACTOR correctly, then batched the rest" — the per-test state machine applies to EVERY test, not just the first
• "Implementer only wrote acceptance tests (one per Gherkin scenario), skipped all unit/edge tests" — acceptance coverage is mandatory but granular tests are encouraged for non-trivial branches, edges, error paths

None justify re-reading artifacts, reading affected code into main context, editing spec/design, ignored failures, skipped reviewers, batched fixes, per-slice check-ins, fix-attempt #4, full-suite tests, commits, archive auto-trigger, verify-change handoff, batched scenario tests, skipped REFACTOR assessment, or cherry-picked project rules.

Inputs

Already in conversation context (loaded by vanilla /opsx-apply steps 2-4):

• proposal.md, spec.md (or specs/**/*.md), design.md, tasks.md
• Output of openspec status --change <name> --json
• Output of openspec instructions apply --change <name> --json

Project standards (AGENTS.md / CLAUDE.md / GEMINI.md) — opencode auto-loads as project instructions; authoritative for code style, file organization, naming, build/test/lint commands.

Build files (package.json, Cargo.toml, go.mod, etc.) — source of lint/format/test commands for gates.

If artifacts NOT in context, surface error:

OpenSpec change artifacts are not in context. Run `/opsx-apply <change>` to load
them, then I will take over the implementation loop.

NEVER read source code outside what slices touch.

Workflow

Four phases (0-3) plus hand-back. NEVER skip, merge, or reorder.

[ ] Phase 0: Pre-Flight (verify inputs, discover commands, choose mode)
[ ] Phase 1: Dependency analysis & parallelism check
[ ] Phase 2: Per-slice execution loop
[ ] Phase 3: Whole-change review & final gate

Flow: Phase 0 → Phase 1 → (blocked? → suggest /opsx-continue, exit) → (all_done? → suggest /opsx-archive, exit) → Phase 2 per-slice: implementer → (DONE → spec-compliance review → code-quality review → per-slice gate → mark [x]) | (NEEDS_CONTEXT → provide, re-dispatch) | (BLOCKED → 4-step assessment → recoverable: retry | fundamental/3+ retries: pause and exit). After all slices → Phase 3: whole-change review + final gate → emulate vanilla step 7.

Reviewers cap at 3 fix cycles. Beyond 3 → STOP, artifacts wrong, escalate.

Workflow Visibility (MANDATORY)

Display workflow phases via todowrite at start; update as phases complete. Add per-slice todos under Phase 2 once slicing is finalized.

Core Principles

• Take Over Step 6 Only — vanilla owns steps 1-5 and 7; after Phase 3, emulate step 7 output and stop.
• Trust The Artifacts — earlier phases validated them; NEVER re-critique; implementation reveals a gap → escalate (pause/exit, suggest plus-design/plus-spec); never edit from inside this skill.

Main Agent Context Hygiene (subagent mode ONLY)

In subagent mode, the main agent NEVER reads slice's affected source files — pass PATHS only. Subagents read files in their isolated context:

• Implementer: pass affected file paths. Implementer reads them.
• Spec-compliance reviewer: pass paths to changed files. Reviewer reads them.
• Code-quality reviewer: pass changed file paths. Reviewer diffs via git diff HEAD; falls back to reading files if git unavailable.
• Final reviewer: pass artifact paths + all changed file paths. Same diff strategy.

Artifacts (proposal.md, spec.md, design.md, tasks.md) are already in main context from vanilla — using them for subagent prompt excerpts is fine. Source code files are NOT.

• Inline Mode Reading (inline mode only) — main agent IS the implementer; reads files directly; reads project standards + affected files for Pre-RED; edits directly during TDD; self-reviews own changes; reviews cumulative diff at Phase 3. Each file read once.
• Pre-RED Reading (both modes) — before any code, implementer reads project standards (AGENTS.md/CLAUDE.md/GEMINI.md + referenced docs); enforced by openspec-plus-tdd Phase 0; follow every documented rule strictly, end-to-end (no cherry-picking).

Strict TDD Through openspec-plus-tdd

Iron Law: NO PRODUCTION CODE WITHOUT A FAILING TEST. One test at a time — full cycle (RED → VERIFY-RED → GREEN → VERIFY-GREEN → REFACTOR) before starting next. Applies to all tests: acceptance (mandatory per Gherkin scenario) and granular (encouraged). REFACTOR assessment mandatory per test — skipping assessment is the violation, not skipping action.

Implementation Principles For Both Modes

Apply in every slice:

1. Think Before Coding — surface assumptions, ask when uncertain, never silently pick between interpretations.
2. Simplicity First — minimum code that solves the problem; nothing speculative.
3. Surgical Changes — every changed line traces to a task in this slice; never improve adjacent code.
4. Goal-Driven Execution — each test—Gherkin or granular—is a verifiable goal; loop independently until it passes.

• Code Style — canonical rules in openspec-plus-tdd § Code Style Rules; code is self-documenting; comments are exceptional last resort.
• Never Ignore Failing Tests — .skip, .todo, xtest, it.skip, commented-out tests, or --bail shortcuts are anti-patterns; pre-mark gate blocks on any failure.
• Continuous Execution — do NOT pause between slices; pause only on BLOCKED (unrecoverable), 3+ failed fix cycles, or 3+ NEEDS_CONTEXT in a row.
• No Commits — vanilla doesn't commit; this skill doesn't either.
• Resumability Is Free — openspec instructions apply is the source of truth; re-running picks up at next pending slice.
• Respect Project Standards — AGENTS.md/CLAUDE.md/GEMINI.md capture lint/format/test commands, code style, file organization, naming conventions.

Phase 0: Pre-Flight

0.0 Resolve Apply Config

Read openspec/.plus/config.yaml once (missing/unreadable/unrecognized value → default, zero behavior change): settings.apply.executionMode (ask default | subagent | inline, anything else → ask — skips 0.3 only for subagent/inline), settings.apply.parallelism (ask default | always | never, anything else → ask — skips 1.4 only for always/never).

0.1 Verify In-Context Artifacts

Confirm vanilla's steps 2-4 produced these in conversation context:

• Output of openspec instructions apply --change <name> --json showing state, tasks, contextFiles
• Content of proposal.md, spec.md / specs/**/*.md, design.md, tasks.md

If absent → surface error above, stop.

State handling:

• "blocked" → suggest /opsx-continue, exit
• "all_done" → suggest /opsx-archive, exit
• "ready" → continue

0.2 Discover Pre-Mark Gate Commands

Identify ONCE at Phase 0 (used by per-slice + final gates):

• Lint — e.g., bun run lint
• Format — e.g., bun run format
• Test — e.g., bun test
• Other — type-check (tsc --noEmit), schema-check, build-check, etc.

Discovery order:

1. package.json "scripts" (or Cargo.toml, go.mod, pyproject.toml)
2. AGENTS.md / CLAUDE.md / GEMINI.md documented commands
3. Project README or build file conventions

Missing or ambiguous → ask user ONCE via question tool.

0.3 Mode Question (MANDATORY, blocking)

If settings.apply.executionMode ≠ ask (from 0.0), skip this question — use the configured mode directly, state it in one line, proceed to Phase 1.

Otherwise, use question tool with ONE question. Subagent mode is the recommended default for ALL changes — small, medium, and large. Inline mode exists only as a fallback for environments where subagent dispatch is unavailable. Phrase the question so this preference is unmistakable.

How should the change be implemented?
 
1. Subagent mode (Strongly Recommended — default for all changes) —
   fresh subagent per slice with two-stage review (spec-compliance then
   code-quality), isolated context per slice, main agent stays clean.
   This produces the highest quality output and is the recommended
   choice unless subagent dispatch is unavailable in your environment.
 
2. Inline mode (Fallback only) — main agent runs each slice with the
   same TDD discipline, implementation principles, and self-review
   checklists. Reviews are self-checks rather than independent
   reviewer subagents. Use only when subagent dispatch is unavailable
   or when you have an explicit reason to avoid it.