/synthex:write-implementation-plan/synthex:write-implementation-plan

#What it does, end-to-end

/synthex:write-implementation-plan/synthex:write-implementation-plan is the Plan-phase entry point: the command that takes a PRD and produces a peer-reviewed, milestone-and-task implementation plan you can hand to /synthex:next-priority/synthex:next-priority.

Each invocation:

1. Reads the PRD at docs/reqs/main.md (configurable via requirements_path or documents.requirements), plus technical context from docs/specs/, the project instruction file, and the codebase. The PRD is the input contract — every plan task points back to a PRD requirement.
2. PM interviews you. The Product Manager agent clarifies ambiguous requirements, priorities, scope, and constraints before drafting. Sub-agents can't ask you questions directly, so the PM returns its questions (3–5 at a time) and the command asks them for it, then hands your answers back. This repeats until the PM has no more questions.
3. PM drafts the plan. The PM structures the work into phases → milestones → tasks, assigns complexity estimates (S/M/L), surfaces dependencies, and tags acceptance criteria with their type ([T] / [H] / [O]). The draft is written to the plan path with a <!-- DRAFT --> marker.
4. Structural lint. A script (lint-plan.mjs, no model call) checks the draft against the plan template before any reviewer runs; the PM fixes every critical and high finding. Runs once per draft. Without Node, the agent self-checks against the same rubric.
5. Parallel reviewer pass. The Architect, Design System Agent, and Tech Lead review the draft in parallel. Each emits structured findings; the Findings Consolidator deduplicates and ranks them by severity. When multi-model review is active, the Multi-Model Review Orchestrator runs these reviewers plus external CLI reviewers and consolidates them instead. Plans have no complexity gate: if multi-model is on, it always runs.
6. PM iterates. The PM addresses every finding at or above min_severity_to_address (default high), editing the plan directly and asking you when a trade-off or conflicting feedback needs your call. Each cycle spawns fresh reviewers. The cycle repeats up to max_cycles times (default 3 for plans — one extra cycle since plan defects ripple downstream); anything unresolved lands in Open Questions.
7. Compactness pass, then save. The PM tightens the plan (it gets loaded into agent context windows), removes the draft marker, and leaves the final plan at docs/plans/main.md (configurable via plan_path or documents.implementation_plan). The plan includes phases, milestones, tasks, decisions, open questions, and parallelizable batches per milestone.

#Reviewer roster

Default reviewers (configurable in .synthex/config.yaml):

implementation_plan:
  reviewers:
    - agent: architect
      enabled: true
      focus: "Technical architecture, feasibility, NFR coverage, missing technical tasks"
    - agent: design-system-agent
      enabled: true
      focus: "Design tasks, UX impact, visual/interaction design clarity"
    - agent: tech-lead
      enabled: true
      focus: "Task clarity, acceptance criteria, parallelizability, dependency accuracy"

Add specialists for project-specific concerns:

implementation_plan:
  reviewers:
    - agent: compliance-reviewer
      enabled: true
      focus: "Regulatory compliance, audit-trail requirements"

An older config that lists agent: designer still works: there is no agent by that name, so this command reads it as design-system-agent.

A reviewer can also be a markdown prompt file in your project instead of a Synthex agent — - prompt: <path>, optionally with id:, enabled:, and focus:. Its feedback merges with the agent reviewers'. See Prompt-file reviewers.

#What makes a good plan

The reviewer prompts are tuned to surface the qualities a plan needs:

• Every task has acceptance criteria. No tag-less tasks. Each criterion is [T], [H], or [O]. Most tasks have at least one [T] because untestable claims tend to indicate unclear scope.
• Parallelizability is explicit. The plan calls out which tasks can run in parallel per milestone, and which sequence dependencies block which.
• Decisions are recorded. Plans include a Decisions table with rationale; the reviewers will flag implicit decisions made during planning that should have been surfaced explicitly.
• Open questions are named. A plan with no open questions is suspicious — most non-trivial work has at least one unresolved item. Calling it out lets future-you see what was unsolved and why a default was chosen.

#Common failure modes

The reviewers are calibrated to catch:

• Vague tasks. "Improve search" is not a task. "Reduce p95 search latency from 800ms to ≤300ms on the documented dataset" is.
• Missing acceptance criteria. Every task gets at least one criterion. The reviewers reject tasks that ship without.
• Untestable [T]s. A [T] tag commits the task to having a passing automated test. When the criterion is structurally untestable, the reviewers either downgrade it to [H] or split it.
• Cross-phase boundary creep. Tasks that span two phases (e.g., "ship to prod and run a retrospective") get split — phase boundaries exist for a reason.

#Parameters

#When to re-run it

Run /synthex:write-implementation-plan/synthex:write-implementation-plan once per PRD, then iterate the PRD and plan together as the project progresses. For mid-project re-planning (new PRD addendum, new constraint), re-running produces a new plan; preserve the old plan as docs/plans/<date>-archived.md if the lineage matters.

You usually do NOT regenerate the plan after a single completed task. Appending completion notes to the existing plan is the job of /synthex:next-priority/synthex:next-priority.

#Native looping

Pass --loop to iterate plan-writing until the plan stabilizes — useful when the PRD has enough open ends that one invocation isn't enough to converge. Iteration state lives in .synthex/loops/<loop-id>.json so a stalled or crashed session can be resumed cleanly. See Native looping for the full framework contract.

Emission rule. The loop terminates when all of:

• The plan file has been written to disk.
• Every PRD requirement is reflected in at least one task.
• The plan contains no TBD, <placeholder>, ???, or open-question markers in task descriptions or acceptance criteria.
• A follow-up iteration would not add new tasks or refine existing ones — typically when reviewers' suggested edits have been incorporated and no further drafts are pending.

The promise is not emitted while a review cycle is still in flight or unresolved markers remain.

Example. Drive a long PRD to a stable plan over many iterations:

/synthex:write-implementation-plan --loop \
  --completion-promise "PLAN_STABLE" \
  --max-iterations 15 \
  requirements_path=docs/reqs/payments-v2.md