Skip to content

workflow.md

Latest commit

 

History

History
206 lines (144 loc) · 9.44 KB

workflow.md

File metadata and controls

206 lines (144 loc) · 9.44 KB
Raw

speq-skill / Docs / Workflow

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

  1. Project type — Determines brownfield (existing code) vs. greenfield (new project)
  2. Exploration — For brownfield projects, explores tech stack, commands, structure
  3. Interview — Asks clarifying questions about purpose, users, capabilities
  4. 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

  1. Loads the plan and creates a task breakdown
  2. Partitions tasks by tag — [expert]-tagged tasks route to implementer-expert-agent, all others to implementer-agent (see Model Routing)
  3. Spawns sub-agents to work through tasks (with context rotation)
  4. Loads targeted guardrails for clean code, unit testing, and integration testing
  5. Runs code review on changed files via code-reviewer
  6. Executes build, test, and lint verification
  7. 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

  1. Verify — Checks verification-report.md exists
  2. Load — Reads plan and delta specs
  3. 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
  1. Clean — Strips all DELTA markers
  2. Validate — Runs speq feature validate
  3. 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
  4. Promote decisions — Entries marked Promotes to ADR: yes in decision-log.md are written to a new specs/_decision/NNN-<plan-name>.md fragment
  5. 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.