What a workflow is
A workflow is a named, repeatable procedure that your AI coding tool follows for one kind of request. Instead of improvising every time, the AI works through the same stages in the same order, and paqad records what happened at each stage.
Every message you send is sorted into exactly one of eleven outcomes. This sorting is called routing. Ten outcomes are real workflows; the eleventh means "no workflow" and is used for small talk.
| Outcome | Used for |
|---|---|
feature-development | Any change to code: new features, bug fixes, refactors, clean-ups and migrations. A change made only inside docs/ or .paqad/ is not counted. |
project-question | Answering a question about the project. Nothing is changed. |
documentation-update | Creating or refreshing the project's foundation documentation. |
module-documentation | Documenting individual modules. |
pentest | A structured security self-review, with a retest mode. |
design-test | Auditing the user interface against the design system, with a retest mode. |
codebase-health | Looking for dead code, risky packages, secrets and stale docs, with a retest mode. |
site-map | Mapping the app's screens, navigation and user journeys, with a retest mode. |
rules-analyze | Working out which written rules can become automatic scripts. |
root-cause-analysis | Investigating an incident after the fact. |
| no workflow | Anything else. Nothing is loaded or recorded. |
How a message is routed, and how a code change is sized into a lane, is explained in Routing and lanes.
The feature-development stages
Most day-to-day work is feature-development. It runs in a fixed order of eight stages. Six are mandatory for every code change; the first and last are optional.
ticket_intake(optional): read the ticket the request refers to, so the work starts from what the ticket actually says.planning: check what already exists, then record a plan. See Planning a change.specification: write the acceptance criteria and invariants, then freeze the spec. See From plan to frozen spec.development: write the code against the frozen spec.review: review the change, with a machine-built digest of known findings on the table.checks: run the project's format, test and build commands.documentation_sync: update the documentation the change made out of date.delivery(optional): branch, commit, pull request and CI, following your delivery policy.
Each stage leaves a record in the change's evidence bundle: one folder per change under .paqad/ledger/feature-evidence/ that holds the plan, the frozen spec, the review, the check results and a log of when each stage started and ended. The files in it are written by paqad's own commands, not typed by the AI.
Who decides what
Three kinds of actor take part, and paqad keeps their roles separate.
| Actor | What it does | Examples |
|---|---|---|
| Scripts (machine checks) | Deterministic programs decide. The same input always gives the same result, and no AI model is involved. | Blocking a code edit until a plan is recorded; validating plan.json; refusing to freeze a spec with open questions; running the check commands; computing the end-of-change verdict. |
| The AI (judgement) | Your coding assistant does the thinking and the typing. | Choosing the route by intent, writing the plan and spec, writing code, deciding whether a review finding is serious, spotting which docs went stale. |
| You (human decisions) | You answer when the work reaches a choice that is yours to make. | Reuse an existing component or build a new one, a spec that no longer matches the goal, whether to open a pull request. |
The human decisions arrive as decision pauses: the AI writes a small decision request with paqad-ai decision create, stops, asks you, and continues only after the answer is recorded with paqad-ai decision resolve. On hosts with hooks, code edits stay blocked while a decision is open.
At the end of a change paqad gives one verdict: Safe to merge (every gate that ran passed; this attests the gates, not that the code is correct), Needs your attention (a gate is blocking) or Inconclusive (something could not be confirmed either way).
How strongly it is enforced depends on your tool
paqad can only enforce what your AI tool lets it hook into. A hook is a small program the tool runs automatically at fixed moments, such as just before a file is saved or when the AI finishes its turn.
- Claude Code and Codex CLI: hooks run before each edit and at the end of each turn. paqad can block an edit and hold the turn open on a hard failure. Codex CLI needs a one-time
/hookstrust step after onboarding. - Gemini CLI: a hook records evidence at the end of the turn but cannot block anything.
- Cursor, Windsurf, GitHub Copilot, Continue, Aider, Junie, Antigravity and JetBrains AI Assistant: no hook runs. The AI is instructed to run the same
paqad-aicommands itself so the evidence still gets written, but nothing stops it from skipping them.
See Adapters overview for each tool.
Stage isolation on larger changes
On Claude Code and Codex CLI, changes routed to the graduated or full lane run each mandatory stage in its own fresh subagent: a separate AI context that starts clean, does one stage, and returns. Your main chat becomes a coordinator that routes, narrates, asks the decision-pause questions and reports the verdict. Details are in Stage agents and specialist roles.
Where you can customise it
Onboarding a coding project writes docs/instructions/workflows/feature-development.yaml. It lets you add reading lists, instructions and check commands to each stage. paqad still owns the routing, the stage order and the mandatory stages. See Workflow files.