Revision control
++ # 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`.**