Workflow Guide

July 12, 2026 · View on GitHub

Workflow Guide

Jump to: Interactive workflow · Headless PR Pipeline

The speq-skill workflow starts with a one-time Mission bootstrap, then repeats a Plan → Implement → Record cycle.

/speq:mission → specs/mission.md  (once per project)
                       │
      ┌────────────────┼────────────────┐
      ▼                ▼                ▼
/speq:plan    →  /speq:implement  →  /speq:record     (repeat)

Steps and references

Step	Description
/speq:mission	One-time project bootstrap
/speq:plan	Create spec deltas
/speq:implement	Implement plan deltas
/speq:record	Merge deltas into permanent specs
/speq:audit	Health-check the spec library and guide fixes
Headless PR Pipeline	Autonomous plan/implement via a feat/ branch + PR
Utility skills	Reusable skills

`/speq:mission`

Generate specs/mission.md through an interactive interview. Run once per project.

When to use: starting a new project with speq-skill, or adding specs to an existing codebase.

What it does

Project type — Determines brownfield (existing code) vs. greenfield (new project)
Exploration — For brownfield projects, explores tech stack, commands, structure
Interview — Asks clarifying questions about purpose, users, capabilities
Generation — Creates specs/mission.md with all gathered information

Interview topics

The agent covers 11 areas, grouping related questions to keep the interview focused:

Topic	What the agent asks about
Identity & Purpose	Project name, one-sentence summary, problem statement
Target Users	Personas, goals, typical workflows
Core Capabilities	3–5 things the system does (what, not how)
Out of Scope	Explicit non-goals and unsupported features
Domain Glossary	Project-specific terms and their meanings
Tech Stack	Language, runtime, framework, database, testing
Commands	Build, test, lint/format, coverage
Project Structure	Directory layout and purpose of each directory
Architecture	High-level pattern, key components, data flow
Constraints	Technical, business, and performance limits
External Dependencies	Services/APIs the project depends on

Note

/speq:mission runs once per project. The next three steps form the repeating development cycle.

`/speq:plan`

Create feature spec deltas and an implementation plan, staged in specs/_plans/<plan-name>/.

When to use: starting new feature development, modifying existing behavior, or refactoring spec-first.

Output structure

specs/_plans/<plan-name>/
├── plan.md                           # Implementation plan
├── decision-log.md                   # Design decisions (optional)
└── <domain>/<feature>/spec.md        # Delta specs

planner-agent creates decision-log.md during the planning interview, capturing Q&A, design choices, and alternatives considered. Entries marked Promotes to ADR: yes become a new specs/_decision/NNN-<plan-name>.md fragment when recorder-agent runs /speq:record. See Decision Log.

Before handoff, plan-reviewer adversarially challenges the plan (intent fidelity, feasibility, requirement quality, task breakdown, prose) and loops BLOCKER findings back to planner-agent for revision, capped at 2 rounds; unresolved blockers escalate to the human. Resolved blockers are logged as [plan-review]-prefixed ## Review Findings entries in decision-log.md.

Plan naming

Verb	When
`add`	New feature
`change`	Modify existing
`remove`	Deprecate/delete
`refactor`	Restructure, same behavior
`fix`	Bug or spec mismatch

Pattern: <verb>-<feature-scope>[-<qualifier>]

Examples: add-user-auth, fix-validation-edge-case, refactor-search-module

`/speq:implement`

Implement approved plan deltas — orchestrate tasks, delegate to sub-agents, review code, and produce a verification report.

When to use: after /speq:plan, to implement a plan:

/speq:implement <plan-name>

What it does

Loads the plan and creates a task breakdown
Partitions tasks by tag — [expert]-tagged tasks route to implementer-expert-agent, all others to implementer-agent (see Model Routing)
Spawns sub-agents to work through tasks (with context rotation)
Loads targeted guardrails for clean code, unit testing, and integration testing
Runs code review on changed files via code-reviewer
Executes build, test, and lint verification
Generates a verification report

`/speq:record`

Merge implemented spec deltas into the permanent spec library.

When to use: after a successful /speq:implement:

/speq:record <plan-name>

What it does

Verify — Checks verification-report.md exists
Load — Reads plan and delta specs
Merge — Applies deltas to permanent specs using markers:

Marker	Action
`DELTA:NEW`	Append scenario
`DELTA:CHANGED`	Replace scenario with same name
`DELTA:REMOVED`	Delete scenario with same name

Clean — Strips all DELTA markers
Validate — Runs speq feature validate
Check thresholds — Flags any feature over 10 scenarios or domain over 8 features and asks you how to split it; never reorganizes without your decision
Promote decisions — Entries marked Promotes to ADR: yes in decision-log.md are written to a new specs/_decision/NNN-<plan-name>.md fragment
Archive — Moves the plan to specs/_recorded/NNN-<plan-name>/, where NNN is a record-time sequence number

Headless PR Pipeline

/speq:plan-pr and /speq:implement-pr run the same Plan → Implement → Record cycle unattended. Without a live interview, each decision that would normally prompt with AskUserQuestion either takes a documented default or becomes an open question posted on the PR for later reply.

/speq:plan-pr <intent>  →  PR (draft; + open questions if blocked)
                                   │
                    (reply on the PR, or /speq:plan <name> locally)
                                   │
                                   ▼
             /speq:implement-pr <name>  →  same PR, updated + marked ready

One branch per plan: feat/<plan-name>, created by /speq:plan-pr and reused by /speq:implement-pr. Both push to the same PR; there is no separate plan-only branch.
Blocked state: if planning hits a decision that genuinely needs a human (irreversible, architecturally divergent, or security/compliance relevant), specs/_plans/<plan-name>/open-questions.md is written, plan.md is flagged blocked, and the PR opens as a draft with the questions posted as a comment. /speq:implement-pr refuses to proceed while this file exists.
Resuming: either reply on the PR and re-run /speq:plan-pr <plan-name> (it re-fetches new comments and reviews as answers), or check out the branch and finish interactively with /speq:plan <plan-name>.
Headless defaults: /speq:implement-pr auto-answers yes to /speq:record's library-split question.
PR title & lifecycle: the PR title uses a conventional-commit feature title <type>(<scope>): <slug> derived from the plan-name (add-search-candle ⇒ feat(search): add search candle), not the spec(plan): commit prefix. /speq:plan-pr opens it as a draft; /speq:implement-pr marks it ready once the implementation is pushed.
Git/PR mechanics: both skills delegate every branch, commit, push, and PR operation to git-agent — the one sub-agent permitted to write git history or touch a remote. See Model Routing.

`/speq:audit`

Health-check a speq project in one read-only pass, then fix each finding after asking permission for the change.

Use when:

Inheriting or cloning a speq project and gauging its state
Periodically, to catch spec-library drift

Checks: spec-library <domain>/<feature> structure, speq feature validate, decision-log format and validity, mission.md ↔ spec-library sync (delegated to audit-agent), unrecorded plans in _plans/, gitignore hygiene (_recorded ignored; _decision/_plans tracked), recorded-folder naming, library thresholds, and git hygiene.

Output: a BLUF summary — a verdict, a ✓/✗/⚠ checks table, and numbered remediations. Structural fixes (migrate an old decision-log.md, restructure domains) and the /speq:mission handoff for mission drift run only after the user confirms.

Utility skills

Reusable guidance invoked by workflow skills:

Skill	Purpose
`/speq:code-tools`	Semantic code navigation via Serena Model Context Protocol (MCP)
`/speq:ext-research`	External docs via Context7 and WebSearch
`/speq:code-guardrails`	Code quality guardrails
`/speq:git-discipline`	Git read-only rules
`/speq:cli`	speq CLI usage patterns
`/speq:writing-guardrails`	Prose style rules for speq artifacts and GitHub PRs/issues/comments

See MCP Servers for details on Serena and Context7.