| name | plan |
| description | Use when turning a vague idea or feature request into an approved spec.md before /geniro:implement. Spec-first planning workflow: explore → grill (decision-tree clarification) → propose 2-3 approaches → approve sections → write spec.md → mechanical validate → user approve → handoff. Skip for well-formed specs already authored — use /geniro:implement <path> directly. Optional --deep deepens the analysis — a wider approach search plus a 3-vote majority verification of the spec's cited claims (higher quality, higher cost). Optional --artifact builds a live, auto-updating visual artifact of the plan as it develops. |
| context | main |
| model | inherit |
| allowed-tools | ["Read","Write","Bash","Glob","Grep","Agent","AskUserQuestion","TodoWrite","Workflow"] |
| argument-hint | <topic-string-or-design-doc-path> [--prd] [--deep] [--artifact] |
/geniro:plan — spec-first planning
Contents
- When to use / When NOT to use
- Phase structure
- Loop invariants
- Budgets — quality-first framing
- State persistence
- Memory I/O
- ACI per-phase tool surface
- Task execution entry
- Anti-rationalization
Turn a vague idea into an approved spec.md that /geniro:implement can consume directly. This skill is a thin wrapper around the canonical planning loop (Phases 0–9 plus the conditional Phase 0.5 problem-discovery and the Phase 7.5 spec-challenge, which fires on Big effort tier or --deep; Phase 2 Visual Companion is UI-conditional — fires only when the UI trigger matches) in ${CLAUDE_PLUGIN_ROOT}/skills/plan/plan-loop.md. It applies the loop verbatim.
Runtime portability. ${CLAUDE_PLUGIN_ROOT} is set by Claude Code. When it is unset (another Agent-Skills runtime, e.g. Cursor), resolve it before following any reference: the plugin root is the ancestor directory of this file containing .claude-plugin/plugin.json — substitute it for every ${CLAUDE_PLUGIN_ROOT} occurrence and export it as CLAUDE_PLUGIN_ROOT in every Bash call. Tool and hook substitutions for non-Claude-Code runtimes: ${CLAUDE_PLUGIN_ROOT}/skills/_shared/runtime-portability.md.
Output:
- spec.md at
.geniro/planning/<task-slug>/spec.md with the fixed 11-section schema, goal-state frontmatter, and all three design-doc detection markers per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/design-doc-detect.md.
- For Big tasks: sibling
milestone-N.md files.
- state.md at the same task-dir tracking phase progress + AUQ answers.
git commit of spec.md (+ milestones) — fires at Phase 8 post-approve, NOT Phase 6; skipped, with the spec left on disk, when the project ignores .geniro/planning/ (the default .gitignore does).- Phase 8.7 executes any user-authored
### After user-approve steps loaded from .geniro/instructions/plan.md — the generic extension point for project-specific post-plan work (e.g. duplicating the approved plan into an OpenSpec change via the project's own tooling). The plugin stays tool-agnostic; the procedure lives in the project's instruction file.
- Phase 9 handoff — prints the milestone-aware
/geniro:implement <path> command (no question — the spec is already saved, and committed at Phase 8 wherever the planning dir is tracked).
The HARD-GATE in plan-loop.md prevents any implementation invocation until Phase 8 user-approve returns "Approve".
Flags & presets: --prd, --deep, --artifact, and the launch modifiers (workspace / ship / freshness:) that pre-fill the spec's launch_config are cataloged in ${CLAUDE_PLUGIN_ROOT}/skills/_shared/flags-reference.md.
When to use
- User has an idea but no spec yet.
- $ARGUMENTS contains a topic string OR a path to an existing design doc.
- Topic spans new functionality (vs a bug fix, which routes to
/geniro:debug).
- Pre-implementation refinement (vs in-implementation tweaks, which route to
/geniro:implement with the original spec + adjustment description as new $ARGUMENTS).
When NOT to use
- Spec already written → use
/geniro:implement <design-path> directly. Detection is automatic per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/design-doc-detect.md.
- Bug to fix →
/geniro:debug for root cause; /geniro:implement for the patch.
- Code-file path (NOT a design doc) passed as $ARGUMENTS → error per Phase 0 (design-doc-detect CODE_REFERENCE branch).
Phase structure
mode-detect → [problem-discovery: --prd only] → explore → [visual-companion: UI-conditional] → clarify → approaches → section-approve → write-spec → validate → [spec-challenge: Big tier or --deep] → user-approve → handoff → done
Any phase may branch to the aborted terminal on cancel; phase-8 revision / validator hard-fail re-enters write-spec or section-approve.
Terminal states: done, aborted. The SessionStart hook treats both as "planning complete or cancelled — no resume needed". Every transition into a terminal state first runs the transient cleanup in ${CLAUDE_PLUGIN_ROOT}/skills/plan/plan-loop.md §9.2 (clean_task_transients against the planning task-dir) before the terminal phase: write; rationale and the preserved-durables list live there.
Phase contracts are defined in ${CLAUDE_PLUGIN_ROOT}/skills/plan/plan-loop.md:
| Phase | Purpose | Plan-loop section |
|---|
| 0 | Mode detect (also detects the opt-in --prd, --deep, and --artifact flags; asks the visual-artifact opt-in question when --artifact is absent, per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/plan-artifact.md) | §"Phase 0 — Mode detect" |
| 0.5 | Problem discovery (opt-in — fires only with --prd: problem-first interview before explore, feeds the spec's optional ## Problem & Evidence section) | §"Phase 0.5 — Problem discovery" |
| 1 | Explore (effort-tier-scaled spawns + custom-instructions/project-snapshot/past-learnings refresh + workflow_refs fetch) | §"Phase 1 — Explore" |
| 2 | Visual Companion (UI-conditional — calls ui-preview-gate.md) | §"Phase 2 — Visual Companion" |
| 3 | Grill — depth-first decision-tree clarification, one message-first framing + lean single-question AUQ per decision; uncapped, checkpoint-bounded; Standard/Deep depth question at wrap-up when --deep is absent | §"Phase 3 — Grill (decision-tree clarification)" |
| 4 | Approaches — 2-3 rendered message-first in the visual language, then ONE lean AUQ with Recommended first; build-vs-buy folded into the trade-offs per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/library-reuse-audit.md MODE: plan; --deep path per ${CLAUDE_PLUGIN_ROOT}/skills/plan/deep-mode-reference.md | §"Phase 4 — Approaches" |
| 5 | Cluster approval — the fixed 11-section schema in 3 dependency-ordered clusters, each rendered message-first then gated by ONE lean AUQ (Approve all / Explain a section further / Revise specific sections / Cancel); milestone-mode | §"Phase 5 — Section approval" |
| 6 | Write spec.md (NO auto-commit; workflow_refs[] copied from state.md) | §"Phase 6 — Write spec.md" |
| 7 | Mechanical validator (full check set — adds workflow_refs_consistency and launch_config_consistency) | §"Phase 7 — Mechanical validator" |
| 7.5 | Spec challenge (Big tier or --deep — adversarial pass: verify claims, generate alternatives, red-team; advisory, fail-open; skipped runs transition validate → user-approve directly; --deep: 3× verify per cited claim with majority vote) | §"Phase 7.5 — Spec challenge" |
| 8 | User approve (visual summary message + lean AUQ + git commit; §8.7 executes any user-authored ### After user-approve steps from .geniro/instructions/plan.md) | §"Phase 8 — User approval" |
| 9 | Handoff (non-interactive — prints the milestone-aware /geniro:implement <path> command, writes terminal phase: done) | §"Phase 9 — Handoff" |
Execute plan-loop.md end-to-end; it is the authoritative phase contract.
Loop invariants
These invariants apply throughout all phases; phase numbers and tool surface differ.
- One result per tool call. Every AskUserQuestion / Write / Bash / Agent spawn produces exactly one structured result. Failed AUQ (empty-answer bug) → fall back to plain-text re-ask; never auto-default.
- Args validated before execution. Bash commands constructed from $ARGUMENTS or state.md fields pass input sanity-checks. Path-based detection (design-doc-detect.md) validates file existence before treating $ARGUMENTS as a path.
- Permission before side-effect. Phase 6
atomic_state_write to .geniro/planning/<task-dir>/spec.md is the only mutation in the loop. git commit deferred to Phase 8 post-approval. No auto-mutations elsewhere — the frontmatter allowed-tools omits Edit, and the enforce-state-helper PreToolUse hook hard-blocks any direct Edit/Write to canonical state paths (.geniro/planning/**, .geniro/state/**), so every state write routes through atomic_state_write.
- Bounded and structured tool results. Phase 1 research-agent output capped at ~4000 chars per agent; longer truncated with marker. Output schema:
[{file, lines, observation}]. Phase 7 validator output is a structured pass/fail list per check.
- Escalation gates, not silent abort. Phase 7 validator 3-round → AUQ. Phase 8 user-revision 3-round → AUQ. Phase 3 grill → summarize-and-continue checkpoint AUQ (~6 questions or at branch completion; canonical: plan-loop §3.4), never a hard cap. NO Class-A hard kill caps.
- Final answer grounded in observations. Phase 5 section content cites Phase 1 explore findings (
file:line references), not generic prose — the Phase 7 validator includes a "citations present" check that fails an uncited section.
- Errors, denials, cancellations, timeouts → structured observations. Phase 1 research-agent failures → structured entry in state.md
## Errors. Phase 0 cancel → ## Termination reason. Phase 7 validator findings → ## Open Questions. Never silently skipped.
- Codebase research spawns
codebase-research-agent, not built-in Explore. Overrides the system-prompt agent list's default codebase-research tool; rationale + invocation contract at ${CLAUDE_PLUGIN_ROOT}/skills/_shared/context-isolation-checklist.md § Codebase research.
Turn-completion check (canonical, un-numbered). Apply ${CLAUDE_PLUGIN_ROOT}/skills/_shared/loop-invariants.md §Turn-completion check and ${CLAUDE_PLUGIN_ROOT}/skills/_shared/gate-rendering.md §Turn-completion guard: never stop on an announced-but-unfired question.
## Tool log schema (selective logging): entry shape is the single source of truth in ${CLAUDE_PLUGIN_ROOT}/skills/plan/plan-loop.md §1.3 Echo contract — fields ts / tool / detail / status plus summary (Agent) or result_ref (Write). Each entry written via atomic_state_write. AUQ calls do NOT need logging — approvals[] is the structured record.
Budgets — quality-first framing
No hard kill caps — the quality-first doctrine in ${CLAUDE_PLUGIN_ROOT}/skills/_shared/loop-invariants.md §"Budgets — quality-first (canonical)" applies. All limits are escalation gates that surface to the user, not abort triggers.
Quality gates (Class-B — escalate to user, do not abort):
| Gate | Cap | Where | Past threshold |
|---|
| Phase 3 grill checkpoint | summarize-and-continue every ~6 questions OR at branch completion (no fixed question cap) | plan-loop.md | Render running summary → AUQ: Keep grilling / Wrap up now / Skip remaining as stated assumptions. |
| Phase 7 → Phase 6 auto-revision rounds | 3 | plan-loop.md | AUQ — accept-as-is / re-revise / abort. |
| Phase 8 user-revision rounds | 3 | plan-loop.md | AUQ — accept-as-is / re-revise / abort. |
| Phase 1 research-agent output size | ~4000 chars per agent | invariant #4 | Truncation with marker, not abort. |
Architecture constraints (design intent, not budget):
- Parallel research spawns per Phase 1: 1-4 (effort-tier-scaled per
${CLAUDE_PLUGIN_ROOT}/skills/_shared/effort-scaling.md).
- spec.md section count: exactly 11.
Rationale. /geniro:plan is a clarification-heavy skill — its job IS to ask questions; every limit above escalates to the user instead of aborting. Question cadence per gate is defined in the phase table above and invariant 5 (Phase 3 uncapped grill with the checkpoint off-ramp; Phase 4 ×1; Phase 5 ×3, one per cluster; Phase 8 ×1).
State persistence
Task directory: .geniro/planning/<task-slug>/
state.md frontmatter:
---
tier: T1.5
producer: plan
schema-version: 1
branch: <git-branch>
worktree: <git-rev-parse-show-toplevel>
timestamp: <ISO-8601 UTC>
phase: <state-machine-enum>
status: in-progress
non-resumable-actions: []
approvals: []
task_slug: <slug>
mode: <IDEA|DESIGN_DOC>
prd_mode: true
deep-mode: <true|false>
artifact_mode: true
artifact_status: pending|live|unavailable
artifact_url: "<url>"
---
The visual-artifact lifecycle is owned by ${CLAUDE_PLUGIN_ROOT}/skills/_shared/plan-artifact.md; the captured claude.ai URL persists in state.md so a later session re-targets the same page instead of publishing a duplicate.
When deep-mode: true, Phase 4 runs its deeper path and Phase 7.5 fires on any effort tier (deep mode satisfies its Big-tier-or-deep gate) with 3× claim verification, both via an internal Workflow(...) per ${CLAUDE_PLUGIN_ROOT}/skills/plan/deep-mode-reference.md; persist the activation to approvals[] category deep_mode_choice so a resume re-applies it. When --deep is absent, the Standard/Deep depth question fires at Phase 3 wrap-up per ${CLAUDE_PLUGIN_ROOT}/skills/plan/plan-auq-reference.md §2a.
Write contract. Every state.md AND spec.md mutation goes through atomic_state_write from ${CLAUDE_PLUGIN_ROOT}/lib/atomic-state-write.sh — direct Edit/Write on canonical state paths is hook-blocked per invariant #3, so the helper is the only working write path for both artifacts.
Validation before resume. When Phase 0 detects a pre-existing state.md (resume path), pre-flight via validate_state_file:
source "${CLAUDE_PLUGIN_ROOT}/lib/validate-state-file.sh"
if ! validate_state_file ".geniro/planning/<task-slug>/state.md"; then
...
fi
Memory I/O
Full Phase 1 entry inventory + per-phase write sites. See ${CLAUDE_PLUGIN_ROOT}/skills/plan/plan-loop.md for full call signatures.
| Phase | Helper | Direction | Notes |
|---|
| Phase 1 entry | load-custom-instructions (MODE: refresh) | read L4 | scope = plan + global + code-style |
| Phase 1 entry | load_semantic | read L3 | top-2 default; fingerprint drift check |
| Phase 1 entry | query_learnings | read L2 | tags inferred from $ARGUMENTS topic |
| Phase 1 entry | resolve-conflicts | read protocol | fires only if L4/L3/L2 disagree |
| Phase 1.4 (conditional) | matching tracker MCP (mcp__linear__get_issue, etc.) | read external | fires only when $ARGUMENTS carries a tracker URL/ID; payload → state.md ## Workflow Refs |
| Phase 1.4 (conditional) | atomic_state_write | write T1.5 | state.md ## Workflow Refs body section |
| Phase 2 (conditional) | ${CLAUDE_PLUGIN_ROOT}/skills/_shared/ui-preview-gate.md | helper procedure | fires only when UI trigger matches; approved description → state.md ## UI Preview |
| Phase 6 | atomic_state_write | write T1.5 | state.md ## Tool log after the spec.md write |
| Phase 6 | atomic_state_write | write T1.5 | spec.md frontmatter workflow_refs[] copied from state.md ## Workflow Refs when present |
| Phase 7 (hard-fail) | atomic_state_write | write T1.5 | state.md ## Open Questions |
| Phase 8.4 | atomic_state_write | write T1.5 | state.md non-resumable-actions[] after git commit |
| Phase 8.5 (conditional) | emit_learning | write L2 | decision type when Phase 4 had ≥2 approaches with trade-off |
Default trust for L2 emits: verified (planning decisions are user-validated via Phase 8 AUQ).
Cross-layer conflict surfacing: when L4/L3/L2 reads disagree, apply ${CLAUDE_PLUGIN_ROOT}/skills/_shared/resolve-conflicts.md protocol — soft conflict prints notice and continues; hard conflict halts with AUQ.
ACI per-phase tool surface
| Phase | Allowed | Blocked |
|---|
| Phase 0 (Mode detect) | Read / Bash (read-only: ls, file) | All mutations |
| Phase 1 (Explore) | Read / Grep / Glob / Bash (read-only) / Agent (research spawn — OMIT model=) / tracker MCP read (mcp__linear__get_issue, etc.) / native Artifact publish (when artifact mode is on, via ${CLAUDE_PLUGIN_ROOT}/skills/_shared/plan-artifact.md — deliberately absent from the frontmatter allowed-tools, so the first publish raises the one-time consent prompt for publishing to claude.ai — per that helper's § Availability detection & create, let it fire rather than pre-allowing the tool) | Edit / Write outside state.md |
| Phase 2 (Visual Companion, UI-conditional) | Read / Agent (UI description spawn, OMIT model= — inherits orchestrator tier per ui-preview-gate.md) / AskUserQuestion / atomic_state_write (state.md ## UI Preview) | Edit / Write outside state.md |
| Phase 3-5 (Clarify / Approaches / Section approve) | Read / Grep / Glob / AskUserQuestion / atomic_state_write (state.md only) / Agent (Phase 3 codebase-research + Phase 4 stress-test critic spawns — OMIT model=) / Workflow (Phase 4 approach panel + critics, deep-mode: true only — OMIT model=) | Edit / mutating Bash |
| Phase 6 (Write spec) | atomic_state_write (spec.md + state.md) | Edit / direct Write / mutating Bash |
| Phase 7 (Validate) | Read / atomic_state_write (state.md ## Open Questions) | All other mutations |
Phase 7.5 (Spec challenge — Big tier or --deep) | Read / Grep / Glob / Bash (read-only) / Agent (claim-verifier spawn — OMIT model=) / Workflow (3× claim verify, deep-mode: true only) / atomic_state_write (state.md ## Errors) | Edit / Write outside state.md / mutating Bash |
| Phase 8 (User approve) | AskUserQuestion / Bash (git add, git commit only) / atomic_state_write | Edit / general-purpose Bash |
| Phase 9 (Handoff) | Read / Bash (terminal state.md write via atomic_state_write; clean_task_transients rm of this run's own scratch in the planning task-dir) | All file mutations except the state.md terminal write and the transient-scratch cleanup (deleting the skill's own scratch is not a source mutation) |
Mutation enforcement: frontmatter allowed-tools excludes Edit (this skill never edits in place).
Existing safety layer: file-protection hook, git-guardrails, .geniro/ deletion guard apply across all phases.
Task execution entry
- Check for existing state.md. Glob
.geniro/planning/*/state.md for a file matching the resolved task slug:
- No state.md → fresh run. Proceed to Phase 0.
- state.md exists, phase in non-terminal set → resume from
phase: value. The SessionStart hook re-injects context.
- state.md exists, phase in terminal set (
done / aborted) → task complete. Surface terminal state to user; if $ARGUMENTS carries a new topic, derive a new slug, fresh run.
-
Validate state.md if found (validate_state_file). On fail, open recovery AUQ.
-
TodoWrite checklist. Add: Detect mode / Problem discovery (--prd only) / Offer the plan artifact / Explore codebase / Visual companion / Grill the design decisions / Propose approaches / Approve plan in groups / Write spec / Validate spec / Challenge spec / User approval / Handoff. Mark the first item in_progress; update each as it completes. The problem-discovery item is marked completed-skipped when --prd was not passed; Phase 2 is marked completed-skipped when the UI trigger doesn't fire; the challenge-spec item is marked completed-skipped when its gate doesn't fire (effort tier below Big and standard depth); the plan-artifact item is marked completed-skipped when the user declines the opt-in or the session can't publish.
-
Begin Phase 0. Execute ${CLAUDE_PLUGIN_ROOT}/skills/plan/plan-loop.md end-to-end.
Anti-rationalization
Do NOT reintroduce these anti-patterns. Loop-level rows (commit timing, empty-AUQ defaults, message-first rendering, refine/edit mode, kill caps, --no-verify, Phase 3 persistence) live in ${CLAUDE_PLUGIN_ROOT}/skills/plan/plan-loop.md §Anti-rationalization — co-loaded with this file; this table keeps only the skill-scope rows:
| Your reasoning | Why it's wrong |
|---|
| "Skip Phase 2 Visual Companion — UI intent fits in Phase 5 sections later." | Phase 2 fires only when the UI trigger matches (Phase 1 found UI files OR topic carries a UI noun). When it fires, the approved description IS the substrate Phase 5 sections 6 + 9 cite. Skipping it forces the user to describe visual intent twice (once in Phase 3 prose, again to /geniro:implement when the rendered UI doesn't match). |
| "Phase 7 mechanical validator misses cases a smart LLM would catch." | The validator checks cover the mechanical surface (including workflow_refs_consistency). Phase 8 user-approve catches everything else — the user IS the smart-LLM check. |
| "The state-write enforcement is over-engineered — model can be trusted." | The model can be reasoned-with, jailbroken, or instructed via a compromised CLAUDE.md. The frontmatter allowed-tools field (omits Edit) + the enforce-state-helper PreToolUse hook (hard-blocks direct Edit/Write to canonical state paths) are the only mechanical layers between a bad-intent prompt and a modified source tree. Belt + suspenders. |
| "Re-cap Phase 3 at ~5 questions like before, OR just grill forever without pausing." | Phase 3 is an uncapped decision-tree grill, bounded by the checkpoint gate — summarize-and-continue every ~6 questions or when a branch resolves (plan-loop §3.4). Re-imposing a flat cap drops the relentless property the grill exists to provide; skipping the checkpoint drops the user's off-ramp. Keep both: no fixed cap, always a checkpoint. |
| "11-section spec.md schema is too rigid for small tasks." | Sections 4 / 5 / 10 can be "none with rationale" for Trivial. The schema is structural commitment (every consumer can rely on section presence), not content commitment. |
| "Phase 7 validator hard-fail blocks user — they're stuck with auto-revision rounds." | 3-round escalation cap. On round 3, AUQ surfaces to user with "accept as-is" option. User has agency at all times. |
| "Drop the milestone-mode AUQ — a Big task can just emit a spec and the user decides later." | Slicing into milestones IS a planning decision. Punting it to /geniro:implement time means the user discovers a 50-step spec is unmanageable, and must come back to re-plan. Phase 5 surfaces the choice when context AND attention are present. |
