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.
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
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.
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-openReplace 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_IDContinue 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/projectThat 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.