How it works
What happens to a request when your team works with Paqad
One request, followed from the moment it is picked up to the moment it reaches your code host. At each stage: what the AI does, what a script confirms and where a person decides. The example is invented, not a customer's change.
Describes paqad-ai 1.91.1. How firmly each stage is enforced depends on the AI tool; see the technical detail and integrations.
In short
A request is understood before it is built: the AI reads it as written, checks it against the project's knowledge and earlier decisions, and asks the team about anything left open. A plan and a specification are agreed and a person confirms them. The change is built inside the team's rules, reviewed, and checked by the project's own tests. The documentation the change affected is updated as part of the same work. Finally a person decides whether to open a pull request; the delivery step opens it through the team's code host and can attach the available verification record.
- Understand the requirements AI Read the request, consult project knowledge, research where configured, ask about open choices.
- Agree You Plan and specification, confirmed by a person. Small fixes may start after the plan.
- Build AI Inside the loaded rules.
- Review and test AI Check The AI records a review; your own commands run and their results are stored.
- Document AI Affected documents brought up to date.
- Deliver You AI A person decides; the tool opens the pull request and can attach the record.
The same six stages in order: on a wide screen they run left to right, on a phone they read across each row and then down.
The example
A team asks for one change
A product team keeps its work in a tracker and its code on a code host. One ticket asks for a change to how customers export their invoices: the export should include a new column and must keep working for customers on the old format. An engineer opens their AI tool in the project and refers to the ticket. Everything below follows that one ticket. The team, the ticket and the code are invented for the explanation.
Stage 1
Understand the request and its requirements AI
The AI fetches the ticket as it is written, rather than working from the ticket number and a guess. With GitHub issues that happens through the team's own GitHub login; with Jira it happens through an Atlassian connection configured in the AI tool. It then reads the project's own documentation for the export module and looks up decisions the team has already recorded, for example an earlier answer about how long old formats are supported.
Two things in the ticket are open: whether the new column applies to the old format too, and what to do with customers who never chose a format. The AI does not guess. It records a decision request with the options and the evidence, and in tools that support it, further edits are refused until a person answers. Answers are stored; where a later change raises a matching question, the earlier decision can be reused with its source shown, subject to the team's confirmation rules.
Where a team has configured it, the AI can also bring in research at this point, for example a market or design question that the request depends on. Those settings are off by default.
What is recorded: the fetched ticket, the questions asked and the answers the team gave.
Stage 2
Agree the approach You
The AI writes a plan: which existing code it examined, what it will reuse, why anything new is needed, and the steps in order. A command checks that the code the plan claims to reuse really exists and stores the plan. For a change of this size the AI then writes a specification: what the export must do, expressed as acceptance criteria that each say how they will be proven, plus things that must not change, such as the old format continuing to work.
The engineer reads the specification and confirms it. The specification is then frozen with that person's name. If the goal changes while building, or the work starts to contradict the specification, that is raised as a decision for the team rather than absorbed quietly.
What is recorded: the plan, and the frozen specification with its acceptance criteria, its invariants and the sign-off name.
Stage 3
Build inside the team's rules AI
Before the first edit, the team's rules that apply to the files about to change are loaded and that loading is recorded: naming and structure conventions, testing expectations, security practices, the conventions Paqad added for the project's framework. Only then does the AI change code, and only what the request and specification cover. A change that would grow beyond them is raised as a question, not made.
In Claude Code and Codex CLI, a small program runs before each edit and asks whether the plan, the specification and the rules record exist and whether a question is still waiting for a person. If not, the edit is refused and the AI is told what is missing. In other tools the same steps are instructions the AI is expected to follow.
What is recorded: which rules were loaded for which files, with a fingerprint of their text, and each edit as it happens.
Stage 4
Review and test AI Check
- Review. Paqad first assembles the facts it already has about the change: the files touched, findings from rule checks, duplication, failing checks. The AI then records a review with findings and a rollback plan. If the review ignores a serious finding the machine had already found, the change fails a check that looks for exactly that.
- Tests and checks. The project's own format, test and build commands run and their results are stored, including each test's outcome. In the example, one export test fails when run with the others but passes alone; it is recorded as unreliable and does not block the change, but the team sees it. A genuine failure is recorded as a failure and the change cannot end as Safe to merge until it is fixed.
- Rules as checks. Rules the team has turned into scripts run over the changed files. By default a failing rule script warns; a team can make it block.
What is recorded: the review with its findings, and each command's result: passed, failed, or not run.
Stage 5
Bring the documentation up to date AI
The change altered what the export does, so the module's documentation and the customer-facing description of the export format are now out of date. The AI works out which documents the change affected and updates them as part of the same change. Which documents are affected is the AI's judgment, and the record labels it that way; a reviewer sees the updates alongside the code.
Teams that let Paqad create their core documentation get this in both directions: the AI consulted those documents in stage 1, and it maintains them here.
What is recorded: which documents were identified as affected and updated.
Stage 6
Deliver through your tools You AI
Before the delivery command pushes a branch or opens a pull request, it checks that a person has decided: open a pull request now, open it as a draft, or only commit. The question is put to the team once per change and the answer is recorded; the command stops if no decision exists. The team's delivery conventions are then applied: the branch name, the commit message and the pull request title follow the templates the team configured, and the pull request links back to the ticket. The pull request is opened on the code host through the engineer's own login. Recording the decision shows that it was made; it does not verify the identity of the person who made it.
Depending on the team's setting, the command then waits for the continuous integration checks, reads their status once, or skips them. When they pass, it can post the available verification record as a comment on the pull request; the record also stays in the repository whether or not the comment succeeds. When they fail, that is a decision for a person. Updating the ticket's status is a separate action the AI can take through the configured tracker connection; the delivery command itself does not change the ticket. Git hooks link each commit and the eventual merge back to the change's record. Merging remains the team's call under its existing review rules; Paqad does not deploy anything.
What is recorded: the delivery decision, the branch, the commits, the pull request, the CI result and whether the verification record was posted.
Not every request is the same
Different requests take different paths
Before answering, Paqad decides what kind of request it has received. Only a code change takes the full path above. A question about the project is answered from its documentation and code without changing anything. A documentation task, a security review, a design check, a codebase health audit or a root cause analysis each have their own workflow. Small talk gets no workflow at all.
Code changes themselves are sized. A small, low-risk fix can start being built once a plan is recorded, and may take at most two build-and-fix rounds before the AI must stop and reassess; the completion checks still require its specification and verification records before it counts as complete. A typical feature needs the plan and the frozen specification before the first edit. High-risk work, migrations and anything touching a module the team has marked as sensitive, such as payments, take the fullest path. When no size was recorded, the strictest rules apply.
Who decides what
Three kinds of evidence, kept apart
| Kind | Examples from the story | How far to trust it |
|---|---|---|
| Confirmed by a script | The fetched ticket, the compiled plan, the frozen specification, the rules record, each edit, your test and build results, whether required records exist, the final result | A machine confirmed it. It can still only confirm what it was built to check. |
| The AI's judgment | What kind of request it was, the content of the plan and specification, the code, the review's findings, which documents went out of date | Useful, and labelled as judgment in the record. Read it as you would a colleague's opinion. |
| Your decision | The two open questions in the ticket, confirming the specification, a scope change, a failing build, opening the pull request, merging | Only a person should make these calls. The AI must stop and ask. |
The final result of a change is worked out by a separate program that reads only the records on disk, never the AI's chat. It reports Safe to merge when every check that ran passed and every required record exists, Needs your attention when a check failed or a record is missing, and Inconclusive when something could not be confirmed. Not confirmed is never reported as passed.
Technical detail
For engineers: the mechanisms behind the story
- Commands. The plan is stored by
paqad-ai plan compile, the specification bypaqad-ai spec freeze, the rules bypaqad-ai rules load, the review bypaqad-ai review record, the checks bypaqad-ai checks runand delivery bypaqad-ai deliver. Tickets are fetched withpaqad-ai intake fetchfor GitHub issues; for Jira the command tells the AI to use the Atlassian MCP connection in the session instead. - Enforcement by tool. Claude Code and Codex CLI run hooks before an edit and at the end of a turn, so a missing record can refuse an edit and a hard failure holds the turn open. Codex asks you to approve the hooks once. Gemini CLI writes the record at the end of a turn and never blocks. The other eight supported tools receive instructions only.
- What the pre-edit hook sees. It sees the tool's own file-editing actions. A change made through a shell command is not stopped beforehand, although the end-of-turn check still reads the files on disk.
- Sign-off. Freezing a specification records the name given to the command. The AI runs the command, so Paqad records the name it is given and cannot prove that a person, rather than the AI, confirmed it. Teams that want a firmer step set
spec_pipeline_final_review=strict, which requires a named person to approve before the freeze. The optional structured specification pipeline that this belongs to is off by default. - Delivery. The CI gate can be set to wait for green, to warn only, or off. In 1.91.1 the wait is bounded by a poll count rather than a reliable wall-clock limit, and the configured ticket transitions are computed but not applied by the command; moving a ticket is an action for the AI through the tracker connection. Paqad opens pull requests through the GitHub command line; it has no deployment step.
- Where the record lives. In a folder per change inside
.paqad/in your repository. The local dashboard,paqad-ai dashboard, shows the same records in a browser on your machine.
Deeper reading: the technical overview, guardrails by tool and workflow settings.
Questions
Common questions about the process
Does a one-line fix go through all of this?
It takes a lighter path. A small, low-risk change can start being built as soon as a plan is recorded, instead of waiting for a frozen specification. The completion checks still require the applicable specification and verification records before the change counts as complete, and the record shows what ran.
Could the AI fake the record?
The records are written by Paqad's commands and hooks rather than typed by the AI, and files are fingerprinted so later edits show. The final result is worked out by a separate program from what is on disk. In tools that only take instructions, an AI that skips the commands leaves an empty record, which reads as not verified rather than as passed.
Does Paqad deploy to production?
No. The demonstrated end of the process is a pull request on your code host with your continuous integration checks applied. Merging, releasing and deploying stay with your existing process.
Do we need Eliyce to use this?
No. Everything on this page is in the free, MIT-licensed framework. Eliyce offers guided adoption for teams as a separate service, and Paqad Spine, a separate product for viewing records across a team, is being finished.
Try it on one change in your own project.
Install Paqad, onboard a repository and ask your AI tool for a small change. Then open the change's folder and read what it recorded.