Skip to main content

SPOQ 1.1 · Practical guide

A workflow matched to the work

Give SPOQ a goal. It records the planning effort and strategy, saves the work, and keeps decisions and verification linked as implementation moves forward.

Choose the right planning effort

Routing uses recorded effort, uncertainty, impact, coupling and requested design outputs. Small effort with low uncertainty, impact and coupling uses compact Classic. Known scope can use standard Classic. High or unknown uncertainty, high impact or coupling, or requested design sources recommend PIQARD. A large task alone does not require PIQARD.

Illustrative example

Explore a sample flow. This is not connected to your workspace.

Choose an example strategy

Why this route?

This example has small effort, low uncertainty, low impact and low coupling. Compact Classic keeps both gates with a smaller planning effort.

Select a phase to see its purpose. Arrows show the forward flow; the rework path below returns to an earlier phase.

Execute

Example status: In progress

The coding client claims ready Tasks, performs the implementation and runs checks. Native subagents follow client and repository policy. Task claims and attempts persist across interruptions.

A failed planning gate returns to planning; a failed implementation gate returns to execution. Both paths have finite budgets. Compact Classic keeps the same gates.

The sample records above are illustrative. No skill, model, approval or CLI command runs when you use these controls.

Compact is a profile of Classic, with the same four phases and gates. You can request Classic or PIQARD explicitly. Classic cannot silently discard requested design sources. The saved route includes its inputs and reasons; it is a deterministic policy, not a prediction of time or cost.

/spoq "Add a CSV importer with validation and tests"
/spoq "Use PIQARD to rebuild billing with an ERD and tests"
/spoq-plan "Plan the importer without implementing it"

Enter these requests in your coding client. Codex uses $spoq and $spoq-plan skill mentions. Planning-only stops after saving and validating the plan.

Work items and strategy phases have different jobs

Project Plan
A DAG of Features connects the deliverables and their prerequisites.
Feature
One task DAG describes the bounded work, ownership and checks needed for that deliverable.
Strategy
A phase graph describes how the goal is discovered, designed, planned, implemented and verified. Its rework paths have finite budgets.

SQLite in .spoq/spoq.db is authoritative for Project Plans, Features, Tasks, journals and workflow history. Markdown design content and exported snapshots support review. Explore the work hierarchy.

Make decisions before decomposition

PIQARD means “plan it quickly, AI records decisions”. Discovery records the goal and open questions. Requested diagram, ERD, algorithm and formal-evidence branches feed a narrative plan. You review that exact narrative revision before SPOQ decomposes Tasks.

Narrative plan
Review the approach, scope, decisions and acceptance criteria as a readable plan. Markdown content is supported. A Confluence reference can accompany a reviewed export; 1.1 does not synchronize or publish Confluence pages.
Diagrams and ERDs
Request Mermaid diagrams or entity relationships when they help settle interfaces and data structure before implementation.
Algorithms
Record inputs, outputs, steps, invariants and edge cases for behavior that needs a precise definition.
Formal evidence
Keep specified, tested, proven, disproven and unverified states distinct. A proven record needs supplied verifier details and proof; the server does not run a theorem prover or independently establish that proof.

Your response is bound to the current attempt, artifact ID and SHA-256. Rejection creates a revision and a new review. Waiting, a peer message or an agent agreeing with itself cannot approve the plan. The local coding client records your action; no operating-system identity authentication is claimed.

Keep both quality gates

Classic and PIQARD both retain planning and implementation validation. Compact Classic adjusts planning effort while preserving the same thresholds.

Planning: 95 average / 90 floor
Review the saved scope, dependencies, acceptance criteria and integration approach before execution.
Implementation: 95 average / 80 floor
Review actual artifacts and observed tests, builds and acceptance checks. A failed required check blocks PASS.

The coding client performs the work and checks. The server computes gate verdicts from recorded evidence and scores; it does not re-run those checks. Read the validation methodology.

See the strategy and the work move

The bundled local viewer shows the selected strategy, routing reasons, phase states and bounded revision paths. Inspect a phase for attempts, artifacts, decisions and evidence; follow its linked Feature or Task to review acceptance criteria.

spoq workflow list --root /path/to/project
spoq workflow inspect RUN_ID --root /path/to/project
spoq ui --root /path/to/project --run RUN_ID --no-open

Replace RUN_ID with an actual saved run ID returned by workflow list. Open the loopback URL printed by spoq ui. The viewer is read-only and needs no Node runtime. It does not launch a model, approve a review or execute a skill. Use your coding client or the documented CLI/MCP actions to change work.

  • Use the strategy graph to understand why work is running, waiting, skipped or blocked.
  • Use the work DAG to inspect Feature and Task prerequisites, ownership and criteria.
  • Use attempt and artifact history to distinguish current evidence from earlier revisions.

Continue the saved work

/spoq YOUR_SAVED_PLAN_OR_FEATURE_ID

Continue in your coding client with the saved Project Plan or Feature ID. SPOQ inspects the stored specification, claims, attempts and evidence before progressing. A process restart, message retry or waiting poll does not reset an exhausted attempt budget.

Task implementation defaults to three total attempts. Workflow phases have separate pinned attempt and transition budgets. When a budget is exhausted, the blocker and its history remain visible; resuming does not grant another attempt.

For an explicitly paused workflow, inspect it first, then use the actual saved run ID:

spoq workflow inspect RUN_ID --root /path/to/project
spoq workflow resume RUN_ID --key resume-1 --root /path/to/project

That command resumes an explicitly paused workflow. An interrupted running phase can require lease inspection and recovery; /spoq handles the saved state through the coding client. A changed goal needs an explicit successor route, with applicable reviews retained or renewed. Use a distinct operation key for each logical action.

Coordinate through the shared message board · Preview and confirm an older database upgrade.