.qe reads → DB: .qe/ content is stored in the SQLite store (qe_files), so a path may have no file on disk. Read .qe/ content with node scripts/qe-cat.mjs <path> (or --ls/--exists) and structured state with node scripts/qe-query.mjs … — do not assume the raw file exists. See QE_CONVENTIONS.md.

Project Spec Document Generation (Qplan Component)

Internal PSE unit. Users start work with {adapter.commandPrefix}Qgoal {목표}; user_invocable is catalog/documentation metadata only. Runtime enforcement is the G010 PreToolUse gate.

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.

Before generating a spec internally, ensure the shared QE.md and active-client instruction pointer exist. The supported public intake is Qgoal or Qplan; this stage is not directly invocable.

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	Shared QE context is `QE.md`; the Claude adapter points from `CLAUDE.md` and Codex from `AGENTS.md`. 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 Single-AI Role Contract

The active client owns every SIVS stage; do not delegate Spec to another AI client or bridge. The main thread creates TASK_REQUEST and VERIFY_CHECKLIST, then runs the mandatory spec critical gate with isolated subagent roles. If native subagents are unavailable, use role-separated inline passes and record mode=degraded-inline.

.qe/sivs-config.json may set an active-client model or effort, but it cannot route this stage to Claude or Codex. See core/SIVS_SINGLE_AI_MODEL.md.

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.

Steps 1.4–1.5: Context dump and clarification

Accept long or unstructured context without asking the user to reformat it. For Small-or-larger ambiguous work, ask only the highest-impact missing questions; Micro tasks and exact file/reproduction requests skip clarification. Record every AI-chosen default under ## 가정 (AI 결정) as [ASSUMED]. Full thresholds, signals, and question dimensions: ./reference/spec-workflow.md.

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.

Frontmatter substitution (per core/DOC_CONVENTIONS.md): the title-following qe-doc-frontmatter block placeholders are filled deterministically — {{kind}} = the generator mapping value (TASK_REQUEST → spec, VERIFY_CHECKLIST → verify), {{plan}} = the active plan slug, {{phase}} = the requested/current phase name, {{created}} = today's date (YYYY-MM-DD), {{status}} = pending at creation. Keep the H1 title on line 1 so the completion hook still extracts it; the frontmatter block goes on the line immediately after.
Model Preference: Use Haiku for drafting standardized templates to reduce latency.

Steps 2.4–2.6: Premise and spec gates

Verify external CLI, manifest, hook, API, and npm claims before drafting. Mark unresolved claims [UNVERIFIED] and remove disproved premises. Check structural and executability criteria, then always run Qcritical-review --stage spec with isolated roles. FAIL remains execution-blocking after at most two revisions; WARN/PASS may proceed with notes. Full workflow: ./reference/spec-workflow.md.

This gate ALWAYS runs. Unlike Step 2.5, it has no skip conditions.

Step 3: Review, Create, and Execute

Use the interaction adapter to choose Generate Only or Generate & Execute. A gate-blocked spec may only be saved or revised. Recommend a wave for four or more independent items. Non-interactive Codex defaults to Generate Only unless execution was explicitly requested or chained. Create artifacts in pending/ and chain execution internally; never ask the user to orchestrate internal PSE stages. Detailed choices and output reporting: ./reference/spec-workflow.md.

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

What vs How: Clearly separate the business goal from the technical implementation logic (from QE planning patterns).
Atomic Items: Every checklist item must be independent and verifiable.
Dependency Mapping: If an item depends on another, mark it: - [ ] {desc} .
Haiku-Ready: Ensure items are small enough to be implemented without Sonnet-level reasoning.
Output files: Always append → output: {file-path} for direct accountability.
Assumed defaults: Any decision the user delegated ("나머지는 알아서") and the AI resolved goes in an optional ## 가정 (AI 결정) section, one [ASSUMED] line per decision with a one-phrase rationale. This keeps delegated choices reviewable instead of buried in the draft.
Role ownership: In role-separated or tiered orchestration, identify the expected implementer-owned files or modules so the reviewer can later judge boundary violations.
Code Risk Register (mandatory for type: code): Add this section before the checklist and fill every field:
```
## Risk Register
- Worst-case failure:
- Data loss / corruption risk:
- Security / permission risk:
- Concurrency / race risk:
- Rollback strategy:
- Unverified assumptions:
```
The register is a hard SIVS contract. Empty fields, placeholder text, or omitted categories block execution until fixed.

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)

Only  enables extraction. Write generated contracts to .qe/contracts/pending/, preserve existing drafts, and require explicit human approval before promotion. Full rules: ./reference/document-contracts.md.

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

Fresh-context hint: If the spec conversation was long (context dump + multi-round clarification), append one line recommending execution from a fresh session: "이 세션의 컨텍스트가 무겁습니다 — 새 세션에서 {adapter.commandPrefix}Qexecute {UUID} 실행을 권장합니다." The spec file already carries everything Qexecute needs; LLMs perform best with a lean context, so don't drag the spec-drafting conversation into execution.

Output Format

Wrap document content in markdown code blocks when displaying
Pure markdown only, no JSON

Qgenerate-spec

SKILL.mdskills/Qgenerate-spec/SKILL.md