feat: add plan-only orchestration command

Author: juancarlosrodicio

README.md

@@ -22,6 +22,12 @@ Scoped research/spec flow:
 scoper -> researcher -> scoper synthesis -> specifier
 ```
 
+Plan-only flow:
+
+```text
+lead -> researcher -> specifier -> reviewer
+```
+
 Design flow:
 
 ```text
@@ -148,13 +154,14 @@ Do not expose Open Design directly to the Internet without authentication, VPN,
 
 ```text
 /feature Create onboarding with plan selection and welcome screen
+/plan Add a dry-run flag to the harness check without implementing it yet
 /scope Research Stripe Checkout integration and generate an MVP spec
 /mvp-spec Email notifications when an agent finishes a task
 /design Read PRODUCT.md and DESIGN.md, create an editable Open Design project, and generate a first version
 /review
 ```
 
-Without a slash command, simple implementation requests go directly through `developer`. Use `/feature` when you want the full orchestration flow.
+Without a slash command, simple implementation requests go directly through `developer`. Use `/plan` when you want research, spec, and reviewer feedback without implementation; use `/feature` when you want the full orchestration flow.
 
 ## Validate the kit
 

docs/commands.md

@@ -1,6 +1,7 @@
 # Commands
 
 - `/feature`: full feature orchestration.
+- `/plan`: research, implementation-ready spec, and reviewer pass with no implementation.
 - `/scope`: research plus scoped spec, no implementation.
 - `/mvp-spec`: strict MVP spec with small tasks and clear out of scope.
 - `/design`: design via PRODUCT.md/DESIGN.md, optional Impeccable, and Open Design.

docs/configuration.md

@@ -14,6 +14,6 @@ The kit is organized as an OpenCode config directory:
 
 The default permissions are conservative: reads are allowed, edits and bash ask by default, and external directories are denied.
 
-The default agent is `developer`, with `mode: all`, so free-form small changes can be implemented directly. Slash commands still route to their explicit agents, for example `/feature` to `lead`, `/scope` to `scoper`, and `/design` to `designer`.
+The default agent is `developer`, with `mode: all`, so free-form small changes can be implemented directly. Slash commands still route to their explicit agents, for example `/feature` and `/plan` to `lead`, `/scope` to `scoper`, and `/design` to `designer`.
 
 Run `node scripts/check-harness.mjs` from an installed OpenCode config directory to validate the core harness contracts. In this repository, `npm run check` runs the same validator against `opencode/`.

docs/quickstart.md

@@ -23,34 +23,42 @@ Use the base URL only.
 
 Expected flow: researcher -> scoper synthesis -> specifier.
 
-## 4. Try direct mode
+## 4. Try plan
+
+```text
+/plan Add a dry-run flag to the harness check without implementing it yet
+```
+
+Expected flow: lead -> researcher -> specifier -> reviewer, with no implementation.
+
+## 5. Try direct mode
 
 ```text
 Change the Settings heading to Account settings and run the smallest relevant validation.
 ```
 
 Expected flow: developer handles the small change directly. No full feature orchestration.
 
-## 5. Try design
+## 6. Try design
 
 ```text
 /design Read PRODUCT.md and DESIGN.md, create an editable Open Design project for onboarding, and return the URL
 ```
 
 Expected flow: designer checks docs, optionally uses Impeccable, then uses Open Design.
 
-## 6. Try feature
+## 7. Try feature
 
 ```text
 /feature Add a small settings page with a saved theme preference
 ```
 
 Expected flow: lead decides research/design needs, then specifier -> developer -> reviewer.
 
-## 7. Validate harness contracts
+## 8. Validate harness contracts
 
 ```bash
 npm run check
 ```
 
-The check validates config JSON, agent/command frontmatter, the default `developer` direct mode, `/feature` sidecar boundaries, and the agent-readable docs under `opencode/docs/ai/harness/`.
+The check validates config JSON, agent/command frontmatter, the default `developer` direct mode, `/feature` sidecar boundaries, the `/plan` contract, and the agent-readable docs under `opencode/docs/ai/harness/`.

docs/workflows.md

@@ -12,6 +12,12 @@ If the request has ambiguity, visual/product impact, medium or large scope, or c
 
 The lead decides whether design or research is needed. Specifier waits for relevant discovery. Developer waits for spec. Reviewer waits for diff.
 
+## Plan
+
+`lead -> researcher -> specifier -> reviewer`
+
+Plan-only mode always starts with researcher, then specifier creates the implementation-ready plan, and reviewer audits the plan/spec without requiring a diff. It never invokes developer and allows only one correction pass before returning the plan with risks or a blocked state.
+
 ## Scope
 
 `scoper -> researcher -> scoper synthesis -> specifier`

opencode/AGENTS.md

@@ -7,8 +7,8 @@ This file is the short map for the harness. Detailed contracts live in
 
 - For normal messages without a slash command, use the simplest path.
 - If a change is small, clear, and low risk, direct mode goes to `developer`.
-- Full flows activate through slash commands such as `/feature`, `/scope`,
-  `/design`, `/review`, or `/evolve`.
+- Full flows activate through slash commands such as `/feature`, `/plan`,
+  `/scope`, `/design`, `/review`, or `/evolve`.
 - Before implementing, understand the stack, scope, and minimum validation.
 - At closure, summarize changes, validation, and risks.
 
@@ -31,6 +31,7 @@ See `docs/ai/harness/agents.md` for full contracts.
 
 - Small free-form request: `developer`.
 - Full feature: `lead -> designer if applicable -> researcher -> specifier -> developer -> reviewer`.
+- Plan without implementation: `lead -> researcher -> specifier -> reviewer`.
 - Scope/spec without implementation: `scoper -> researcher -> scoper synthesis -> specifier`.
 - Design: `designer -> open design`.
 - AHE evolution: `evaluator -> debugger -> evolver -> lead approval -> developer -> evaluator -> debugger -> reviewer`.

opencode/agents/reviewer.md

@@ -35,6 +35,8 @@ You are the senior code reviewer.
 
 - Do not edit files.
 - Base the review on `git diff`, the spec, and repository context.
+- In `/plan`, review planning artifacts even when there is no diff.
+- In `/plan`, base the review on the objective, research, plan/spec, assumptions, risks, and acceptance criteria.
 - Classify issues by severity.
 - Classify relevant findings by category: correctness, design, risk, tests, or observability.
 - Avoid nitpicks unless they affect clarity or maintenance.

opencode/commands/plan.md

@@ -0,0 +1,59 @@
+---
+description: Create an implementation-ready plan without applying changes: research, spec, and plan review.
+agent: lead
+---
+
+
+Objective:
+
+$ARGUMENTS
+
+Run a deterministic plan-only flow.
+
+Contract: `lead -> researcher -> specifier -> reviewer`.
+
+## Mandatory flow
+
+1. Ground the user objective with assumptions, questions, scope, non-scope, and verifiable success criteria.
+2. Always invoke `researcher` first; wait for the full result before continuing.
+3. Synthesize research findings: verified facts, inferences, risks, recommended decisions, and open questions.
+4. Invoke `specifier` only after research has been consolidated.
+5. Ask `specifier` for an implementation-ready plan, acceptance criteria, validation, and ordered tasks.
+6. Invoke `reviewer` to review the plan/spec against the objective, research, assumptions, risks, and acceptance criteria.
+7. If `reviewer` finds no significant issues, deliver the final plan.
+8. If `reviewer` finds significant issues, allow exactly 1 correction pass.
+9. After the second review, deliver the plan with explicit risks or declare the state blocked.
+
+## Dependency rules
+
+- Do not invoke developer.
+- Do not invoke `designer`; if the work needs design, mark that dependency in the plan or recommend `/design` or `/feature`.
+- Do not implement code or modify application files.
+- Do not invoke `specifier` while `researcher` has pending work.
+- Do not invoke `reviewer` before a reviewable plan/spec exists.
+- Do not use `evaluator`, `debugger`, or `evolver`; this command plans, it does not evolve or validate the harness.
+- Do not parallelize phases; this flow is sequential by design.
+- If there is a blocking question, stop the flow and state it instead of inventing a decision.
+
+## Single correction pass
+
+If `reviewer` returns `requires changes`:
+
+- If evidence, context, or research is missing, send a bounded task back to `researcher` and then to `specifier`.
+- If research is sound but the plan is incomplete or inconsistent, send a bounded task only to `specifier`.
+- If there is an unresolvable contradiction or blocking product decision, stop and deliver a blocked state.
+- After that correction, invoke a second and final `reviewer` pass.
+- Do not run additional cycles even if observations remain; deliver risks, pending items, and the next human decision.
+
+## Expected output
+
+Deliver:
+
+1. Research summary.
+2. Decisions made.
+3. Assumptions and open questions.
+4. Implementation-ready plan.
+5. Acceptance criteria.
+6. Validation plan.
+7. Reviewer result.
+8. Risks and pending items.

opencode/docs/ai/harness/agents.md

@@ -9,7 +9,7 @@
 | `designer` | UX/UI, brand, layout, interaction, or Open Design matters | Technical change has no visual impact | Visual handoff with observable criteria |
 | `researcher` | Technical/product uncertainty, APIs, libraries, risks | Fact is already clear in repo | Sources reviewed and unknowns remaining |
 | `specifier` | There is enough context to turn goal into tasks | Critical research/design is pending | Acceptance criteria and validation plan |
-| `reviewer` | A diff or implementation exists | There is no reviewable change | Findings by severity or explicit approval |
+| `reviewer` | A diff, implementation, or `/plan` artifact exists | There is no reviewable change or planning artifact | Findings by severity or explicit approval |
 | `scoper` | User wants research -> spec without implementation | User asks for direct implementation | Scoped spec and ordered tasks |
 | `evaluator` | Benchmark/smoke evidence or `/evolve` is needed | Normal feature already has clear validation | pass/fail/not_run results |
 | `debugger` | Failures, traces, results, or attribution need analysis | There is no concrete evidence | Root cause or not-ready state |
@@ -20,6 +20,6 @@
 - `developer` is the harness `default_agent`.
 - `lead` must not force the full flow for small free-form messages.
 - `specifier` waits for research/design when those results affect requirements.
-- `reviewer` waits for a diff or reviewable implementation.
+- `reviewer` waits for a diff, reviewable implementation, or `/plan` artifact.
 - `evaluator`, `debugger`, and `evolver` are optional sidecars.
 - `evolver` works only on the OpenCode harness.

opencode/docs/ai/harness/checks.md

@@ -20,6 +20,7 @@ The harness check validates:
 - `default_agent: developer`;
 - minimum frontmatter in `agents/*.md` and `commands/*.md`;
 - local `/feature` contract;
+- local `/plan` contract;
 - main docs in `docs/ai/harness/`;
 - benchmark references to replay and evidence taxonomy;
 - AHE run lifecycle under `docs/ai/evolution/runs/`;