Under the hood
Technical details of the development assistant.
Everything on this page is the AIQT 1.1.0 design, in development: what you own, what you configure, what can travel back, how it fits your pipeline, and how it composes per-language depth. The overview is the place to start; this is the detail once you are interested.
What it creates
The directory it sets up, file by file
Everything AIQT keeps for your project lives in one directory,
.aiqt/, apart from the instruction files it generates for each assistant (at
the repository root and in folders such as .claude/). The directory is created
at setup if it does not already exist. During setup the
wizard asks which of these files you want, and the default is all of them, so your
assistant follows good practice from the first day rather than from when you remember to
ask.
your-project/ ├── .aiqt/ │ ├── config.md yours: own it, edit it, commit it │ ├── CHANGELOG.md what changed, and when │ ├── TODO.md the work coming up │ ├── DONE.md what has shipped │ ├── ROADMAP.md where the project is heading │ ├── open-findings.md defects, tracked to closure │ ├── pending-decisions.md decisions waiting on you │ ├── ... the QA audit registers (below) │ └── core/ the updater's only write location ├── src/ untouched └── ... untouched
- config.md: your configuration, including which guardrails are active and the sharing setting. Yours to own, edit, and commit, and updates never rewrite it. The next section covers it in full.
- The practice files (CHANGELOG.md, TODO.md, DONE.md, ROADMAP.md): what changed, the work coming up, what has shipped, and where the project is heading, so you and your assistant share one record of where things stand.
- The QA audit trail (open-findings.md, pending-decisions.md, the validation-sweep history, the publications-screening register, the deep-assessment register, the verifier-override log, and an improvement log): a committed, reviewable record of what the assistant's quality checks did, so a teammate or a manager can audit the QA itself.
- core/: the one directory AIQT's updater writes to. A guard refuses every write outside it, so a diff after any update shows changes in exactly one place, and nothing else in your repository changes without your say-so.
| Who | When | May create or change | Never touches |
|---|---|---|---|
| Setup wizard | Install, with your per-file consent | .aiqt/ and its files; the generated agent files at the repository root and in folders such as .claude/ | Your source |
| Updater | Update | .aiqt/core/ only (guard-enforced) | Everything else, including your config.md |
| Your assistant | While you work | The .aiqt/ practice and QA records; your project files as you direct it | .aiqt/core/ |
| Doctor | Verification | Nothing (read-only) | Everything |
| CI and local exec workers | Pipeline and desk checks | pending, documented before 1.1.0 ships | pending |
With your permission, AIQT sets these up, and every one is yours to keep, edit, or remove. They are committed with your project, not hidden away, so the record stays reviewable. They help you and your development assistant equally: the assistant reads them to pick up context and updates them as it works, so the two of you are never out of sync.
A tool that updates itself inside your repository earns a hard question: what else can it
touch? With AIQT you can check the answer yourself, because the updater writes only inside
.aiqt/core/, and reviewing an update takes the same shape as reviewing any
other change: read the diff, and the diff is small and contained.
Your configuration
The config file you own
Your choices live in .aiqt/config.md, and that file
is yours: you own it, you edit it, you commit it. In the 1.1.0 design, updates never
rewrite it.
Guardrails, individually
The config records which guardrails are active, and the switch is per guardrail, not all-or-nothing. Enable the ones that fit your project, disable the ones that do not, and the file is the record of what you chose.
A file, not a dashboard
Because the configuration is a file in your repository, it behaves like the rest of your project: it is versioned, it is diffed, it is reviewed, and a teammate can see exactly which guardrails your project runs and when that changed.
The config also carries the sharing setting described in the next section, so the decision about what leaves your project sits in a file you control, alongside every other decision you have made.
Sharing back
New-guardrail seed PRs
When a guardrail gap lets an issue through, the fifth rule closes the gap locally. The 1.1.0 design adds an optional last step: contributing the new guardrail back to the AIQT project as a seed PR, so a gap found once is closed for every developer who uses AIQT.
You choose it at install
Sharing is governed by one setting in your config file,
contribute_guardrails, with three values: never,
ask, or always. Setup asks you which you want, with
ask selected by default: the assistant checks with you before each
contribution, so nothing is submitted without your say-so. Choose never
and it is never offered. Choose always and each contribution is opened
automatically, using a credential you provide for that purpose, still as a pull request
to the AIQT project, never a merge into your own code.
What travels, and what never does
A seed is scrubbed to concept, trigger, and goal before anything leaves your machine:
the guardrail's concept, what triggers it, and the goal it serves, and nothing else.
The scrub is designed to remove your project's specifics, and you preview exactly what
a seed contains before it is submitted, so you confirm that the scrub did its job. Under
ask you open the pull request yourself from your own account; under
always it is opened from the credential you set. Either way the pull
request is openly attributable, and what stays private is your project's specifics,
not the fact that you contributed.
Why this is worth turning on. Every team's assistant misses different things. A seed PR turns one team's miss into everyone's guardrail, and because seeds are scrubbed to concept, trigger, and goal, you preview what travels before it goes. The exchange runs both ways: the guardrails your assistant ships with include the ones other developers contributed the same way, as Rule 5's voluntary Guardrail-Seed give-back, separate from the software licence.
How the credential works. The
always mode uses a credential scoped to opening pull requests on the AIQT
project, which you create and can revoke at any time. Before any seed is sent it is
scrubbed and shown to you in a preview, and the AIQT project reviews each pull request like
any other contribution.
Exact credential scope and preview format: pending, documented before 1.1.0 ships
Continuous integration (CI)
In your pipeline
CI integration
The development assistant integrates with your CI, so the standard that governs the assistant during development also holds at the gate. The same discipline applies on both sides: a check that passes has actually run, and a check that fails is surfaced, never quietly weakened to get a green build.
The findings loop
When a finding comes in, the loop validates it before it acts on it. A finding that survives validation is worth an action; a finding that fails validation is recorded as such. Acting on validated findings keeps the signal clean, and it is the five rules of AIQT at work: say what was caught, fix in-scope issues in the current change, and fix the rest in the next one. The five rules are on the overview page.
Standardizing quality assurance
One QA standard, whichever model checks the work
A review by a single model shares that model's blind spots. AIQT standardizes the check itself: for substantive work, independent verifiers from different model families are given the same brief, each instructed to refute the change rather than confirm it, and their verdicts are reconciled. Different families miss systematically different things, so cross-family review catches what any one alone would let through. AIQT itself is built and reviewed this way, across three families (Claude, GPT/Codex, and Gemini); in the 1.1.0 design, the development assistant brings the same standard to your project.
- Routine changes run the ordinary gates. Most work needs nothing heavier, and a review that fires on everything stops being read.
- Substantive changes get the dual-family pair: the same refute-brief to both families, verdicts reconciled, disagreements examined rather than averaged away.
- Delicate changes escalate to a heavier harness: where a wrong result is a correctness defect no simple check catches, the change is large or delicate, and an escaped error is costly, independent adversarial verifiers are briefed to refute the work, and the result is applied deterministically rather than by hand. The review is up-skilled for the work that warrants it, and only that work.
The point of the tiers is that the standard scales with the stakes instead of depending on who happened to run the check. A passing review means the review actually ran; a failing one is surfaced, never quietly weakened. That is the AIQT ordering applied to review itself.
Where it runs
The same check, in your pipeline and on your machine
A QA standard only standardizes anything if it holds in both places work happens: at the gate, and at the desk. In the 1.1.0 design it runs in both.
In your GitHub CI
The model-based checks run in the pipeline at the tier the change warrants (routine changes run the ordinary gates alone, substantive changes add the dual-family pair, and delicate changes escalate to the heavier harness), alongside your usual gates. A change is reviewed by the dual-family pair before it lands, under the same discipline as every other check: it passes because it ran, and a failure blocks rather than disappears.
In local development
Exec workers, separate worker processes on your machine, run the same dual-family QA at the relevant points while you work, and the heavier harness on the delicate ones, so a finding surfaces before the change ever reaches the pipeline. Exec workers run on Linux today; Windows support is planned.
The data flow, by tier
| Tier | What is sent | To which providers | Credentials | Retention | Cost and latency |
|---|---|---|---|---|---|
| Routine | Nothing to a model; the ordinary gates run locally | None | None | None | Gate time only |
| Substantive | pending | pending | pending | pending | pending |
| Delicate | pending | pending | pending | pending | pending |
The 1.1.0 data flow, providers, credentials, retention, and cost: pending, documented before 1.1.0 ships
The 1.1.0 design gives local and CI reviewers the same QA brief. Its intent is to reduce variation caused by who runs the check or which tool they use; provider behaviour and results remain to be verified.
Per-language depth
Language and framework depth, composed at install
The governance core is deliberately language-neutral. Deep per-language and per-framework guidance comes from vetted aligned sources, and the setup generator composes them in at install time.
During setup, the generator detects your stack and presents the aligned sources that apply to it. For each source you see the facts a decision needs: what it covers, its licence, when it was last reviewed, and the gaps it leaves. Then you choose, taking all that apply or deciding one by one. AIQT lists each source, shows you these facts, and credits and links the people who do that work. The decision to use a source is always yours.
- Coverage: what the source addresses in your stack.
- Licence: the terms it is published under.
- Last reviewed: when it was last checked, because per-language depth has a shelf life.
- Gaps: what it leaves uncovered, stated up front.
Ready to try it
Set it up, or read the source
The setup and verification steps are on the overview page, and where 1.1.0 stands is stated plainly there too.