# Workflow Specification Process > Specification Process - Skill: `leeovery/workflow-specification-process` (Agent Skill, multi-file: 16 files) - Install (CLI): `npx skillmds@latest add leeovery/workflow-specification-process` - Raw SKILL.md: https://api.skillmd.com/api/skills/leeovery/workflow-specification-process/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: leeovery (https://skillmd.com/u/leeovery) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/leeovery/workflow-specification-process --- # Specification Process Act as **expert technical architect** and **specification builder**. Collaborate with the user to transform source material into validated, standalone specifications. Your role is to synthesize reference material, present it for validation, and build a specification that formal planning can execute against. ## Purpose in the Workflow Follows discussion (or investigation for bugfix). Transform prior-phase source material — discussions, research notes, investigation findings — into a specification that's **standalone and approved**. ### What This Skill Needs - **Source material** (required) - Prior-phase artifacts to synthesize (discussions, research, investigation findings) - **Topic name** (required) - Used for the output filename **If source material seems incomplete or unclear:** > *Output the next fenced block as markdown (not a code block):* ``` I have the source material, but {concern}. Should I proceed as-is, or is there additional material I should review? ``` **STOP.** Wait for user response. **Multiple sources:** When multiple prior-phase artifacts are provided, extract exhaustively from ALL of them. Content may be scattered across sources — a decision in one discussion may have constraints or details in another. The specification consolidates everything into a single standalone document. --- ## Instructions Load **[framework.md](../workflow-shared/references/framework.md)** and follow its instructions as written. --- ## Resuming After Context Refresh Context refresh (compaction) summarizes the conversation, losing procedural detail. When you detect a context refresh has occurred — the conversation feels abruptly shorter, you lack memory of recent steps, or a summary precedes this message — follow this recovery protocol: 1. **Re-read this skill file completely, then re-load [framework.md](../workflow-shared/references/framework.md).** Do not rely on your summary of either, and re-read both even if you believe they are already loaded — that belief is what a summary feels like from the inside. The full process, steps, and rules must be reloaded. 2. **Read all tracking and state files** for the current topic — the specification file, review tracking files, or any working documents this skill creates. These are your source of truth for progress. 3. **Check git state.** Run `git status` and `git log --oneline -10` to see recent commits. Commit messages follow a conventional pattern that reveals what was completed. 4. **Announce your position** to the user before continuing: what step you believe you're at, what's been completed, and what comes next. Wait for confirmation. 5. **Check `finding_gate_mode` and `construction_gate_mode`** via `engine manifest` (`node .claude/skills/workflow-engine/scripts/engine.cjs manifest get {work_unit}.specification.{topic} finding_gate_mode` and `... construction_gate_mode`) — if either is `auto`, the user previously opted in during this session. Preserve that value. Do not guess at progress or continue from memory. The files on disk and git history are authoritative — your recollection is not. --- ## Hard Rules 1. **STOP AND WAIT** for explicit approval before any write to the specification. Present content, wait for the user to explicitly approve (`y/yes` or equivalent), then log. No exceptions. 2. **Log verbatim** — when approved, write exactly what was presented. No silent modifications. 3. **Commit frequently** — commit at natural breaks and before any context refresh. Context refresh = lost work. Commits go through the scoped helper, action-scoped to this topic — the specification directory and the work-unit manifest, never a sibling session's files: ```bash node .claude/skills/workflow-engine/scripts/engine.cjs commit {work_unit} -m "{message}" --topic specification/{topic} ``` --- ## Step 0: Resume Detection Refresh the tmux session label — a no-op unless the user opted in and this session runs inside tmux: ```bash node .claude/skills/workflow-engine/scripts/engine.cjs session label {work_unit} specification {topic} ``` Check if `.workflows/{work_unit}/specification/{topic}/specification.md` exists. #### If no file exists → Proceed to **Step 1**. #### If file exists > *Output the next fenced block as markdown (not a code block):* ``` **`□ Resume Detection`** ``` > *Output the next fenced block as markdown (not a code block):* ``` > An in-progress specification exists for this topic — choose whether to pick it up or start fresh. ``` Load **[resume-detection.md](../workflow-shared/references/resume-detection.md)** with artifact = `specification`, file = `.workflows/{work_unit}/specification/{topic}/specification.md`, continue_step = `Step 3`, restart_targets = `the specification file and all review tracking files (review-*-tracking-c*.md) in .workflows/{work_unit}/specification/{topic}/`, restart_resets = `every sources.{name}.status and consult_references.{name}.status row under {work_unit}.specification.{topic} to pending via engine manifest set — initialization never overwrites an existing row, so without this reset the fresh file would never get its content re-extracted — and the tracking subtree and review_baseline_words deleted where present (engine manifest delete {work_unit}.specification.{topic} tracking, then the same for review_baseline_words — an absent field's delete errors and is skipped) to match the deleted tracking files`, commit = `spec({work_unit}): restart specification`. --- ## Step 1: Verify Source Material Load **[verify-source-material.md](references/verify-source-material.md)** and follow its instructions as written. → On return, proceed to **Step 2**. --- ## Step 2: Initialize Specification Load **[initialize-specification.md](references/initialize-specification.md)** and follow its instructions as written. → On return, proceed to **Step 3**. --- ## Step 3: Session Setup Load **[session-setup.md](references/session-setup.md)** and follow its instructions as written. → On return, proceed to **Step 4**. --- ## Step 4: Load Specification Principles Load **[specification-principles.md](references/specification-principles.md)** and follow its instructions as written. → On return, proceed to **Step 5**. --- ## Step 5: Spec Construction > *Output the next fenced block as markdown (not a code block):* ``` **`□ Spec Construction`** ``` > *Output the next fenced block as markdown (not a code block):* ``` > Building the specification. Topics from your source material will be extracted and presented one at a time. Nothing gets written without your explicit approval. ``` Load **[spec-construction.md](references/spec-construction.md)** and follow its instructions as written. → On return, proceed to **Step 6**. --- ## Step 6: Document Dependencies #### If work_type is not `epic` → Proceed to **Step 7**. #### Otherwise > *Output the next fenced block as markdown (not a code block):* ``` **`□ Document Dependencies`** ``` > *Output the next fenced block as markdown (not a code block):* ``` > Recording cross-topic dependencies — for epics, specifications may depend on each other. ``` Load **[dependencies.md](references/dependencies.md)** and follow its instructions as written. → On return, proceed to **Step 7**. --- ## Step 7: Specification Review > *Output the next fenced block as markdown (not a code block):* ``` **`□ Specification Review`** ``` > *Output the next fenced block as markdown (not a code block):* ``` > Reviewing the specification. Agents will measure its claims against the codebase and analyse it against source material for gaps and inconsistencies. Settled findings carry their fix; genuine choices stop for your call, and any finding can be talked through — adjusted, challenged, or declined. ``` Load **[spec-review.md](references/spec-review.md)** and follow its instructions as written. → On return, proceed to **Step 8**. --- ## Step 8: Compliance Self-Check Load **[compliance-check.md](../workflow-shared/references/compliance-check.md)** and follow its instructions as written. → On return, proceed to **Step 9**. --- ## Step 9: Assess Cross-Cutting & Conclude > *Output the next fenced block as markdown (not a code block):* ``` **`□ Conclude`** ``` > *Output the next fenced block as markdown (not a code block):* ``` > Wrapping up. Final assessment, sign-off, and @if(work_type is cross-cutting) closure — the pipeline completes here @else handover to the planning phase @endif. ``` Load **[spec-completion.md](references/spec-completion.md)** and follow its instructions as written.