Revision control
Copy as Markdown
# Contributing
How to add an agent, a skill, a pipeline stage, an instruction, or a
doc page to the Qt Doc Agent Framework.
If you only want to know what already exists, read the tree — every
agent has a row in [`agents/README.md`](agents/README.md) and every
skill has a row in [`skills/README.md`](skills/README.md).
## Architecture context
The framework runs as a four-layer chain: **harness → orchestrator →
agent → skill.** Every added artifact lands in exactly one layer, and
that decision drives everything else — which directory it lives in,
whether it needs frontmatter, and how it's dispatched. See
[`CLAUDE.md`](CLAUDE.md) for the layer table.
## Ground rules
1. **Only verified, working changes land in qtqa.** Planned work,
drafts, and sketches live outside the commit. A row appears in
`agents/README.md` or `skills/README.md` only when the artifact is
real and exercised.
2. **Every rule an agent enforces is codified as S / R / T.**
- **S-source** if the rule comes from an external authority (QUIP,
Qt Writing Guidelines, Microsoft Style Guide).
- **R-rule** if it's a concrete language do/do-not distilled from an
S-source (`skill-language-style`).
- **T-rule** if it's an AI tell to suppress (`skill-ai-tells`).
Rules that don't fit any of the three are either written down for AI
use or explicitly excluded. Silent conventions don't survive.
3. **Pin the model.** New agents pin `claude-opus-5-5` in frontmatter,
not the `opus` alias.
4. **Copyright year is the current calendar year** for new files
(2026 as of this writing).
5. **Prose that ships gets checked against `skill-ai-tells`.** Tier 1
hits are hard failures; Tier 2 hits need rewrites; Tier 3 is
tolerated (Qt's own corpus uses those patterns).
6. **Deterministic first.** If a script or tool can produce the result
(grep, Vale, QDoc, ImageMagick, a format checker), the artifact
calls it instead of asking the LLM. Deterministic results repeat
across runs and cost no tokens. Each agent marks which of its steps
are deterministic (tool call) and which need LLM judgment. Checks
that repeat go into `tools/` as scripts.
7. **Trace and test every rule claim.** Before a rule, exemption, or
"never"/"always" lands in a skill or agent:
- **Trace** it down the chain (C/G rule → R-rule → S-source) and quote
the S-source text. A claim that exists only in a derived rule is
unverified. Rewording at each step can change the meaning
("renders in bold" became "bold instead of `\uicontrol`").
- **Test** it against the corpus with grep: qt5.git, and the repo
the rule targets (for example, qt-creator for C9). Record the
count and the commit. If the corpus contradicts the claim, the
claim is wrong or needs a scope.
- **Separate markup from output.** "Bold", "italic", and "code font"
describe rendering; name the QDoc command that produces it.
## Adding an agent
1. **Decide fan-out or stage.** Fan-out agents dispatch further
subagents; stage agents only load skills. Default is stage. Fan-out
is only for orchestrator-shaped work (batch, multi-repo, parallel
research).
2. **Create `agents/{name}.md`** with YAML frontmatter:
```yaml
---
name: {name}
description: One sentence, action-first, states the pipeline stage.
model: claude-opus-5-5
# tools: only include Agent if this is a fan-out agent.
---
```
3. **In the body, declare:**
- Which pipeline (A / B / C / D) the agent serves.
- Which skills it loads, when, and via which of the seven loading
patterns (see
[`doc/loading-patterns.md`](doc/loading-patterns.md)).
- Its own verification gate (what it checks before returning).
4. **Add a row to `agents/README.md`** in the pipeline mapping table.
5. **Extend the orchestrator.** Update `agents/orchestrator.md`
dispatch table with the new task-to-agent mapping.
6. **Write the instruction.** Add
`doc/instructions/how-to-use-{name}.md` (short, task-oriented;
long-form goes elsewhere in `doc/`).
7. **Run the initial check.** Load
[`skills/skill-framework-fitness/SKILL.md`](skills/skill-framework-fitness/SKILL.md)
and
[`skills/skill-security-hygiene/SKILL.md`](skills/skill-security-hygiene/SKILL.md)
and apply both to the new agent. Framework fitness catches pipeline,
registration, and chain defects; security hygiene catches secrets,
PII, and public/internal boundary breaches. Landing is blocked on
either producing a High or Critical finding.
## Adding a skill
1. **Create `skills/skill-{name}/SKILL.md`** with the standard skill
frontmatter (`name`, `description`, `metadata`). Description drives
discovery; be specific about triggers.
2. **Choose the loading pattern** (see the seven patterns in
[`doc/loading-patterns.md`](doc/loading-patterns.md)).
Document the choice in the SKILL.md header.
3. **If the skill codifies a rule set**, mark the entries S / R / T so
agents can cite them.
4. **Add a row to `skills/README.md`** under the pipeline mapping.
5. **Link from every agent that uses it.** Agents declare their skill
dependencies in their own body.
## Adding a pipeline stage
Pipelines B, C, and D are still being built. To add or refine a stage:
1. **Update the pipeline flow.** Edit `README.md` and
`agents/orchestrator.md` so the pipeline table reflects the new
stage.
2. **Add or extend the agent.** Follow "Adding an agent" above.
3. **Write the how-to.** `doc/instructions/how-to-{pipeline-verb}.md`.
4. **Add the doc page.** `doc/{topic}.html`, once the stage is real
enough to document for external readers.
## Adding an instruction
Instructions live in `doc/instructions/` and are short, task-oriented
Markdown. Convention: filenames start with `how-to-`.
1. **Create `doc/instructions/how-to-{action}.md`.**
2. **State the target pipeline in the opening line.**
3. **Include copy-paste-ready sample prompts** pinned to
`claude-opus-5-5`.
4. **Cross-link to the S / R / T rules the pipeline enforces.**
## Adding a doc page
Doc pages are long-form reference material for readers who run or
extend the framework; Qt Group renders them as a site internally.
1. **Mirror the internal `qt-doc-agent-guide` shape.** Markdown source
next to the HTML output, `images/` for referenced media.
2. **Add the page to `doc/README.md`** expected-pages table.
3. **Deploy separately** from qtqa via rsync (see the deploy note in
`doc/README.md` once the script lands).
## Naming conventions
- **Agents.** `{verb}-{scope}` or `{scope}-{role}`. Existing shapes:
`qt-doc-reviewer`, `doc-shaper`, `qdoc-warning-fixer`, `orchestrator`.
Lowercase, hyphenated, no `agent-` prefix.
- **Skills.** `skill-{topic}`. Lowercase, hyphenated, `skill-` prefix
mandatory. Example: `skill-ai-tells`, `skill-qdoc-output`.
- **Instructions.** `how-to-{action}.md`. Lowercase, hyphenated,
Markdown.
- **Doc pages.** `{topic}.html` (+ `{topic}-content.md` when the HTML
is generated from Markdown). Lowercase, hyphenated.
- **Pipelines.** Referenced by letter (A / B / C / D). Names are
descriptive but the letter is the identifier.
- **Rules.** S1, S2, ...; R1, R2, ...; T1, T2, .... Sequential,
never renumber after publication.
## Verification requirements before landing
Every added agent runs through the orchestrator's verification gates
(see `agents/orchestrator.md`, "Post-agent verification"). Additionally:
- **All new agent and doc prose:** run through `skill-ai-tells` Tier
1 + Tier 2 patterns. Zero hits at Tier 1.
- **All new rule entries:** confirm the source citation. R-rules link
to their S-source; T-rules cite the corpus calibration.
- **Initial check** on any new agent, skill, or doc page:
[`skill-framework-fitness`](skills/skill-framework-fitness/SKILL.md)
and
[`skill-security-hygiene`](skills/skill-security-hygiene/SKILL.md).
Framework fitness applies the 9-layer methodology adapted for this
framework; security hygiene catches secrets, PII, and the
public/internal boundary.
## Scale strategy
As the framework grows past the first handful of agents and skills:
- **Flat directories hold to ~20 entries.** Beyond that, subdivide by
pipeline (`agents/pipeline_b/`, etc.) rather than by alphabet.
- **Only verified, working artifacts land in the tree.** Planned or
half-built work lives outside the commit — the subdir READMEs are
the authoritative "what exists" list.
- **Cross-links use relative paths**, so moves don't break them.
- **Every subdir README opens with a one-line role statement and a
link back to top-level `README.md` and `CONTRIBUTING.md`.**