geniro-plan

name: geniro: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 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 allowed-tools: [Read, Write, Bash, Glob, Grep, Agent, AskUserQuestion, TodoWrite, WebSearch, WebFetch, Workflow] model: inherit argument-hint: " [--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 always-on Phase 7.5 spec-challenge; 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.

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.
• 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).

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 → 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 — the per-facet research, approach-critique, and spec-challenge scratch files left in a finished task-dir otherwise resurface as recurring migration warnings on every /geniro:update. Cleanup deletes only this run's scratch; the durable spec.md / state.md / plan-*.md / milestone-*.md survive.

Phase contracts are defined in ${CLAUDE_PLUGIN_ROOT}/skills/plan/plan-loop.md:

Execute plan-loop.md end-to-end. The loop encodes every defect fix and schema gap.

Loop invariants

These invariants apply throughout all phases; phase numbers and tool surface differ.

1. 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.
2. 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.
3. 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.
4. 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.
5. 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), never a hard cap. NO Class-A hard kill caps.
6. 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.
7. 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.
8. 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). Per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/loop-invariants.md §Turn-completion check: never stop on a statement of intent or an announced-but-unfired question — at every gate the render is followed immediately by its lean AskUserQuestion per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/gate-rendering.md §Turn-completion guard, and an answered question is continued with the next action, never a silent stop.

## 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

This skill has no hard kill caps. All limits are escalation gates that surface to the user, not abort triggers. User tokens are unlimited — no "task aborted: budget exhausted" failure modes.

Quality gates (Class-B — escalate to user, do 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.

Explicitly NOT capped: wall-time, total tool calls, total model turns, total cost. Same rationale. Rationale. The ≤3 AUQ gates guideline applies to /geniro:implement, NOT /geniro:plan. /geniro:plan is a clarification-heavy skill — its job IS to ask questions. Rich content is rendered to chat messages (the Gate presentation contract); each gate then fires ONE lean question: Phase 3 runs a decision-tree grill (one single-question AUQ per decision, depth-first, each preceded by its own framing, with a summarize-and-continue checkpoint every ~6 questions or at branch completion — variable count, no fixed cap) + Phase 4 ×1 + Phase 5 ×3 (one per cluster, not per section) + Phase 8 ×1. Phase 3 trades round-trips for per-question clarity (focused explanation + answers that reshape the tree frontier); the checkpoint is the off-ramp that keeps the grill bounded by the user's judgment rather than a fixed number. Phase 5 stays one-per-cluster (not one-per-section), keeping the questions the user answers there at 3 not ~11. Explain-further rounds add re-asks only when the user requests them.

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>     # optional, recommended for cross-worktree resume
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                   # optional, present only when --prd was passed (Phase 0)
deep-mode: <true|false>          # optional, set by the --deep flag (Phase 0); missing reads as false
artifact_mode: true              # optional, present only when the user opted into the visual artifact (Phase 0 question or --artifact)
artifact_status: pending|live|unavailable  # optional, present only in artifact mode — publish lifecycle state
artifact_url: "<url>"            # optional, present once the page is published live
---

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 and Phase 7.5 run their deeper paths 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, a Standard/Deep depth question is asked as the last question in the Phase 3 clarify sequence (skipped on a Trivial task → flag-only there); pick Deep there to set deep-mode: true.

Write contract. Every state.md AND spec.md mutation goes through atomic_state_write from ${CLAUDE_PLUGIN_ROOT}/lib/atomic-state-write.sh, never direct Edit/Write on canonical state paths — the enforce-state-helper hook hard-blocks such direct writes. The frontmatter allowed-tools omits Edit, and the hook hard-blocks direct Edit/Write to canonical state paths (.geniro/planning/**, .geniro/state/**), so both artifacts are written through the helper while a /geniro:plan run is active.

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
# Open recovery AskUserQuestion (delete-and-restart / open-in-editor / update-worktree-path / skip-emergency)
...
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.

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

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

0. 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.

1. Validate state.md if found (validate_state_file). On fail, open recovery AUQ.

2. 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 plan-artifact item is marked completed-skipped when the user declines the opt-in or the session can't publish.

3. Begin Phase 0. Execute ${CLAUDE_PLUGIN_ROOT}/skills/plan/plan-loop.md end-to-end.

Anti-rationalization

Do NOT reintroduce these anti-patterns: