| name | Qgenerate-spec |
| description | Use when a plan or task needs spec documents: TASK_REQUEST and VERIFY_CHECKLIST. Use Qplan for roadmap/phases; use Qexecute after the spec exists. |
| invocation_trigger | When a new project, task, or bug fix spec needs to be defined. |
| user_invocable | true |
| recommendedModel | haiku |
Project Spec Document Generation (Qplan Component)
Role
You are a specialist document writer acting as a sub-component of the Qplan ecosystem. Your primary goal is to transform a high-level roadmap Phase into Haiku-Ready Atomic Tasks.
Role Constraints (Absolute Rules)
- When this skill is invoked, focus exclusively on writing the 3 spec documents.
- Do not perform any actions outside of document writing, such as writing code, fixing bugs, or answering general questions.
- User confirmation MUST go through the interaction adapter. Claude MUST use
AskUserQuestion and MUST NOT print options as plain text. Codex interactive may print concise plain-text choices because AskUserQuestion is not a Codex primitive. Codex non-interactive MUST select the deterministic recommended default and report it.
Client Adapter Compatibility
Interaction rules:
- Claude: use
AskUserQuestion for Step 3 and any other structured choice.
- Codex interactive: ask concise plain-text choices with the same option labels.
- Codex non-interactive: choose Generate Only unless the task is already chained or the user explicitly requested execution.
Command rendering rules:
- Render handoff commands through
adapter.commandPrefix.
- Claude examples use
/Q..., for example /Qexecute {UUID}.
- Codex examples use
$Q..., for example $Qexecute {UUID}.
Documents to Generate
| # | Filename | Path | Description |
|---|
| 1 | Project instruction artifact | Project root | Client-specific project context when needed. Claude adapter writes CLAUDE.md; Codex-capable projects may use AGENTS.md or an existing instruction artifact. Must reference QE_CONVENTIONS.md for QE rules. Task history is in .qe/TASK_LOG.md. |
| 2 | TASK_REQUEST_{UUID}.md | .qe/tasks/pending/ | Task request — what, how, checklist, notes |
| 3 | VERIFY_CHECKLIST_{UUID}.md | .qe/checklists/pending/ | Verification checklist — validation criteria, additional notes |
- A single task shares the same UUID across both documents.
- Multiple tasks get separate TASK_REQUEST / VERIFY_CHECKLIST pairs.
- Newly generated documents always go in
pending/.
SIVS Engine Routing
Before executing the spec generation workflow, resolve SIVS engine routing:
- Read
.qe/sivs-config.json from the project root (via scripts/lib/codex_bridge.mjs → loadSivsConfig()).
- Call
resolveEngine("spec", config).
- Base client = Claude, stage engine =
claude (default): Proceed with the standard workflow below. Claude owns the spec, but may delegate bounded repo search/context gathering to Codex when useful.
- Base client = Claude, stage engine =
codex: Delegate spec generation through codex_bridge.mjs / codex-plugin-cc. If the bridge is unavailable, warn and fall back to Claude.
- Base client = Codex, stage engine =
codex: Use the native Codex execution path. If native subagent delegation is unavailable, keep the work in the lead session as a role-separated inline pass and mark the route degraded-inline.
- Base client = Codex, stage engine =
claude: Delegate through Qclaude-rescue / claude_bridge.mjs when available. If the bridge is unavailable, warn and run the spec stage on Codex with crossmodel=false.
- Check for legacy config: call
detectLegacyConfig(). If non-null, display the migration warning to the user before proceeding.
Codex Spec Delegation Format:
When delegating to Codex, pass the following prompt structure:
Generate a TASK_REQUEST and VERIFY_CHECKLIST for: {user's task description}
Project context: {from active project instruction artifact, e.g. CLAUDE.md or AGENTS.md}
Phase context: {from ROADMAP.md active phase}
Format: Markdown with checklist items
Fallback guarantee: If .qe/sivs-config.json does not exist, all stages default to Claude. This preserves existing single-engine workflows while Codex routing remains available through SIVS config.
Optional MCP Preflight
If spec generation depends on a user-requested MCP server, invoke
{adapter.commandPrefix}Qmcp ensure to check local client configuration before
using that server.
PASS → the requested MCP server may be used.WARN → continue with local-only spec generation and record the degraded MCP path.FAIL → stop only when the requested spec explicitly depends on that MCP server;
otherwise continue without claiming MCP coverage.
Workflow
Step 1: Context Acquisition (Mandatory)
Before collecting user info, identify the strategic context:
- Resolve active plan (slug-based Named Plan layout):
- If the first CLI token matches
{slug}: (where slug is [a-z0-9][a-z0-9-]{0,63}), use that as the plan slug and strip it from the argument string.
- Else read
.qe/state/current-session.json → extract session_id → read .qe/planning/.sessions/{session_id}.json → extract activePlanSlug.
- Else read
.qe/planning/ACTIVE_PLAN (single-line slug pointer).
- Else (no slug resolvable): fall back to legacy flat
.qe/planning/ROADMAP.md + STATE.md and proceed as before.
- Check Roadmap: When a slug is resolved, read
.qe/planning/plans/{slug}/ROADMAP.md and plans/{slug}/STATE.md. When falling back, read the flat files.
- Identify Phase: If an active Phase exists in the resolved STATE.md, use its Success Criteria and Requirement IDs as the primary source of truth for the spec.
- Missing Roadmap: If no plan is resolvable and no flat roadmap exists either, STOP and suggest running
{adapter.commandPrefix}Qplan first to maintain the PSE Chain integrity.
Step 1.5: Brainstorming Gate (conditional, scale-aware)
Before gathering spec details, run a lightweight ambiguity check. If the incoming requirement is ambiguous AND the task scale is Small or larger, perform a concise Socratic clarification pass before drafting. (Source: adapted from Superpowers' brainstorming stage — but scale-aware, not mandatory; see D019 in .qe/planning/DECISION_LOG.md.)
This is our deliberate differentiator from Superpowers' blanket-mandatory brainstorming: a one-line bug fix must never be forced through a clarification round.
Gate condition = ambiguous(requirement) AND scale ≥ Small.
- Scale is judged with the same heuristic as
Qplan Step 0.7 (Micro / Small / Full / Workflow). Micro tasks always skip this gate.
- Ambiguity is true when any 2 of these 3 objective signals hold:
- Core verb/noun unspecified — the action or the target object is vague ("개선해", "정리해", "make it better") with no concrete subject.
- No acceptance criteria — nothing in the request or the resolved Phase Success Criteria states how "done" is verified.
- Alternatives unconsidered — the request fixes a solution without stating the problem, so no design choice was weighed.
On gate trigger: produce one of:
PASS → ambiguity resolved (or never present); continue to Step 2 with the sharpened requirement.CLARIFY → unresolved gaps remain; surface its questions to the user before drafting. Do not draft specs from an unclarified CLARIFY requirement.
Skip the gate entirely when: scale is Micro, the requirement already cites specific file paths / functions / reproduction steps, or the task type is docs/analysis with a clear target. The gate is a clarification prompt, not a hard block — a PASS proceeds immediately with no added friction.
Step 2: Information Gathering
... (omitted) ...
Required information:
- Project name, description (one-paragraph summary)
- Goals (1-5 items), Constraints (tech stack, performance, security, etc.), Decisions (finalized)
- Task list — for each task: what, how, steps (checklist), expected output files (optional), notes, type (
code|analysis|docs|other), validation criteria (checks), verification notes, and optional decision rationale (chosen approach, alternatives, consequences)
- Code Risk Register — for every
type: code task, include a mandatory risk section that names worst-case failure, data loss/corruption risk, security/permission risk, concurrency/race risk, rollback strategy, and unverified assumptions. If a category is not applicable, write N/A with the reason; do not omit it.
Step 2: Draft Documents
Write drafts using templates from templates/ directory (TASK_REQUEST_TEMPLATE.md, VERIFY_CHECKLIST_TEMPLATE.md). For any generated project instruction artifact, reference QE_CONVENTIONS.md (project root) for QE rules (file naming, task status, completion criteria) and include a reference line pointing to it. Replace {{placeholder}} with actual content.
- Model Preference: Use Haiku for drafting standardized templates to reduce latency.
Step 2.4: Premise Verification (Mandatory for external dependencies)
Before drafting specs, verify that any external platform features, APIs, or tools referenced in the task actually exist and work as claimed.
When to run: Any task that depends on features outside the project's own codebase — Claude Code CLI features, npm packages, OS commands, API endpoints, plugin.json fields, hook events, etc.
Procedure:
- CLI feature claims → Run
command --help or command --version via Bash and check the output
- Plugin.json fields → Compare against a known working plugin.json (the one before changes)
- Hook events → Check against the project's existing working
hooks.json events
- API features → Fetch official documentation URL or run a minimal test call
- npm packages → Run
npm info {package} version to confirm existence
Outcome:
- Verified → proceed normally
- Unverified → tag the item with
[UNVERIFIED] in TASK_REQUEST and alert the user via additionalContext: "This task depends on unverified external feature: {feature}. Confirm before proceeding."
- Disproved → remove the item from the spec and report to user
Skip conditions: Tasks with no external dependencies (pure local logic, documentation, analysis).
Step 2.5: Spec Verification (Automatic)
After drafting, verify spec quality. Skip conditions (fast path): checklist ≤ 3 items OR type: docs/analysis → skip entirely, proceed to Step 3.
When verification runs, perform both structural and executability checks in a single pass:
Structural criteria (S1-S5) — Use Haiku:
- Single responsibility per item
- Specific and verifiable (yes/no)
- TASK_REQUEST/VERIFY_CHECKLIST consistency
- No constraint conflicts
- No missing dependencies
Executability criteria (E1-E4) — Use Sonnet:
| # | Criterion | Fail Example |
|---|
| E1 | Single-action executability | "Design API and implement routes" — two distinct edits |
| E2 | Output path validity | → output: src/utils/helper — missing extension |
| E3 | Logical ordering | Item 3 references file from Item 5 |
| E4 | Verifiable completion | "Refactor code appropriately" — subjective |
For complex tasks (8+ items): Spawn Plan agent (subagent_type: "Plan", model: Haiku) for S1-S5 review while self-checking E1-E4 in parallel using Sonnet. Max 2 iterations.
For simple tasks (4-7 items): Self-check all 9 criteria without agent spawn. Use Sonnet for full-pass or Haiku for S1-S5 if splitting. Max 1 iteration.
Any fail → fix automatically. After max iterations, proceed with best version.
Step 2.6: Spec Self-Reference Gate (MANDATORY — no skip)
Step 2.5 checks spec quality with the same model that drafted it — which cannot
catch errors rooted in that model's own blind spots (the self-reference
problem, acute when the SIVS engine is homogeneously all-Claude or all-Codex).
Step 2.6 closes that gap with an independent adversarial gate.
This gate ALWAYS runs. Unlike Step 2.5, it has no skip conditions — it
runs regardless of item count or task type (DECISION_LOG D011). Spec-stage errors
are independent of size, so size-based skipping would reopen the exact hole this
gate exists to close.
Procedure:
- Invoke
{adapter.commandPrefix}Qcritical-review --stage spec against the just-drafted TASK_REQUEST
(+ VERIFY_CHECKLIST). The gate spawns the Structural Reviewer + Critical
Reviewer + Edge Case Finder in parallel and returns a PASS/WARN/FAIL verdict.
Engine routing is automatic: same-engine baseline always, with the Critical
Reviewer auto-upgraded to codex when reachable — no config required. Full
protocol: skills/Qcritical-review/reference/spec-gate-protocol.md.
- On FAIL: the spec contains CRITICAL/HIGH problems. Revise the TASK_REQUEST
/ VERIFY_CHECKLIST to address them and re-run the gate (max 2 iterations).
Then enter Step 3 in blocked mode (see below) if still FAIL.
- On WARN/PASS: proceed to Step 3 normally, carrying any WARN notes forward.
Skip conditions: none. (Autonomous mode still runs the gate; on FAIL it
auto-revises up to the iteration cap, then proceeds Generate-Only.)
Step 3: Review, Create, and Execute (The High-Performance Path)
- GATE-BLOCKED (Step 2.6 FAIL): If the Spec self-reference gate returned FAIL
after its iteration cap, this is a hard gate — do NOT offer
"Generate & Execute". Present only "Generate Only"
(so the draft is saved) and "Fix spec & re-run gate", and list the
CRITICAL/HIGH findings as required fixes. Execution options unlock only after the
gate reaches WARN/PASS, or the user explicitly overrides with full awareness of
the findings.
- MANDATORY: Use the interaction adapter to present these options.
- Claude:
AskUserQuestion.
- Codex interactive: concise plain-text choices.
- Codex non-interactive: Generate Only by default and report
selected_default=Generate Only.
- Recommend Wave: If the checklist has 4+ independent items, clearly label "Generate & Execute (Wave)" as the [Recommended] path. Explain that Qexecute auto-selects parallel wave execution for maximum speed.
- Auto-Chain: Once the user selects an execution option, immediately invoke
{adapter.commandPrefix}Qexecute with the generated UUIDs.
On "Generate & Execute":
- Auto-create directories and files
- Invoke
{adapter.commandPrefix}Qexecute {UUID} immediately. (Sets <!-- chained-from: Qgenerate-spec --> flag so Qexecute skips approval)
On "Generate Only":
Output status summary after file creation:
✅ Generation complete (spec documents only):
- Project instruction artifact when this invocation created or migrated one
- .qe/tasks/pending/TASK_REQUEST_{UUID}.md
- .qe/checklists/pending/VERIFY_CHECKLIST_{UUID}.md
❌ Not yet created (actual deliverables):
- {expected output files from TASK_REQUEST checklist}
On "Generate & Execute" with multiple tasks:
- Multiple tasks → invoke
{adapter.commandPrefix}Qexecute {UUID1} {UUID2} ... {UUIDn} with all generated UUIDs space-separated in a single call. Qexecute handles parallel execution.
Autonomous Mode Support
When called from Qexecute -utopia (autonomous mode), Qgenerate-spec:
- Skips all interaction prompts — auto-selects the documented default
- Auto-proceeds through Steps 1-3 without user confirmation
- Sets
<!-- chained-from: Qgenerate-spec --> on generated TASK_REQUEST files
See Qexecute -utopia for autonomous execution modes (-utopia, -utopia -verify).
Document Writing Rules
Language Matching (Required)
TASK_REQUEST and VERIFY_CHECKLIST must match the user's language.
- Korean user → Korean documents; English user → English documents; mixed/unclear → English
- Scope: TASK_REQUEST and VERIFY_CHECKLIST only. Internal framework files stay English. CLAUDE.md follows user language when specified.
Project Instruction Artifact
- Single Source of Truth for client-specific project context; Claude adapter uses
CLAUDE.md, Codex-capable projects may use AGENTS.md or an equivalent QE-managed instruction file.
- Do NOT write task lists in the instruction artifact. Task history lives in
.qe/TASK_LOG.md. The instruction artifact only contains a reference pointer: ## Task Log → see .qe/TASK_LOG.md
TASK_REQUEST
VERIFY_CHECKLIST
- Each criterion answerable as yes/no
- Task complete when all items checked
- Include note to update
.qe/TASK_LOG.md task list to ✅
- Auto-include by type:
type: code → add: "No security vulnerabilities (OWASP Top 10) in changed code", "All existing tests pass", "Worst-case failure path is identified", "Data loss/corruption, security/permission, and concurrency/race risks are explicitly evaluated or marked N/A with reason", "Unverified assumptions and residual risks are reported in the final handoff", "High-risk findings are mitigated by tests, defensive code, or an explicit defer rationale"type: code + auth/crypto/payment → add: "Authentication/encryption implementation is secure (Esecurity-officer or manual review)"type: docs → add: "All links in documentation are valid", "Terminology and formatting are consistent"
UUID Generation Rules
- 8-character hex (e.g.,
a1b2c3d4), generated randomly
- Same UUID shared between TASK_REQUEST and VERIFY_CHECKLIST for same task
- Collision check: Before using a UUID, verify no file matching
TASK_REQUEST_{UUID}.md already exists in .qe/tasks/pending/ or .qe/tasks/completed/. If it exists, generate a new random UUID and check again.
- Generate UUIDs via bash:
openssl rand -hex 4 (produces 8-char hex)
Self-Evolving
- After completing tasks, if recurring patterns found, suggest template improvements
- On user approval, reflect patterns in future generation
Contract Candidate Extraction (Optional)
After draft creation (Step 2) and before handing off, check whether the TASK_REQUEST opts into contract candidate extraction.
Opt-in marker: If the TASK_REQUEST body contains the exact HTML-comment marker <!-- contract-candidates: auto -->, enter this flow. If absent, skip entirely.
Flow:
- Read the newly drafted TASK_REQUEST text.
- Call
extractCandidates(taskRequestText) from hooks/scripts/lib/contract-candidate-extractor.mjs.
- For each candidate
{name, targetPath, suggestedSignature}:
- Read
.qe/contracts/TEMPLATE.md as the base.
- Fill in a draft:
- Replace the example
Signature body with a code block containing suggestedSignature (empty string initially — user fills in later).
- Replace the example
Purpose with a single line: Business-logic contract for \${targetPath}``
- Leave
Constraints, Invariants, Error Modes as lightly pre-filled placeholders (e.g., - TBD (candidate draft)).
- Omit
Flow (optional section) unless the user fills it.
- Write to
.qe/contracts/pending/${name}.md.
- Do not write to
.qe/contracts/active/ — user must review and promote manually. This preserves the opt-in, user-in-the-loop principle (D011).
- Report to the user: a bulleted list of newly created pending drafts with their paths, and a note that they can be promoted via
{adapter.commandPrefix}Qcontract approve after review.
Skip conditions:
- Marker absent → skip silently.
extractCandidates returns [] → skip with a short note ("Marker present but no .mjs output items found in checklist.").- A pending draft with the same name already exists → skip that one, warn the user ("Draft already pending: {name}.md").
Reference: See .qe/contracts/README.md and D011 in .qe/planning/DECISION_LOG.md (DECISION_LOG stays global across all plans).
Handoff
After generating spec files (on "Generate Only"), display using the standard handoff format from QE_CONVENTIONS.md:
Phase {X}: {PhaseName} — Spec complete
PSE: [x] Plan [x] Spec [>] Execute [ ] Verify
{TaskDescription — 다음 작업 내용 한 줄 요약}
Next: {adapter.commandPrefix}Qexecute {UUID}
Note: "Generate & Execute" auto-chains, so the handoff is only needed for "Generate Only".
Output Format
- Wrap document content in markdown code blocks when displaying
- Pure markdown only, no JSON
