Framework Development

---
name: framework-development
description: "Framework evolution mode — evolves the QA boilerplate itself (KATA, fixtures, cli/, scripts/, api/schemas/ pipeline, package.json deps). Self-contained Plan → Code → Verify → Archive pipeline; needs nothing outside the repo (no SDD-* skills). Use when adding new fixture APIs, refactoring KATA base classes, evolving the installer, modifying the OpenAPI sync pipeline, or any change to the framework infrastructure that is NOT per-ticket test writing or manual QA. Triggers on: /framework-development, \"evolve framework\", \"framework refactor\", \"new fixture API\", \"modify KATA base\", \"refactor cli\", \"boilerplate evolution\", \"sync AI context\", \"sync AI memory\" (the docs follow-through after a boilerplate change), and mode `instructions` for any edit to AGENTS.md, an instruction section, the ROUTER or a section's triggers (\"edit AGENTS.md\", \"add a rule\", \"where does this rule go\", \"router row\", \"tune the triggers\", \"new instruction section\"). Do NOT use for: writing tests for a ticket (use /test-automation), manual QA per ticket (use /sprint-testing), documenting test cases (use /test-documentation), running regression suites (use /regression-testing)."
license: MIT
compatibility: [claude-code, copilot, cursor, codex, opencode]
complementary_categories: [framework-evolution, meta-skill]
metadata:
  kind: workflow
  stage_owner: true

---

# Framework Development — Evolve the QA Boilerplate

Gateway skill for changes to the framework itself: KATA layers, fixtures, installer, OpenAPI pipeline, scripts, doctrine docs. Per-ticket QA work, test specs, and TMS documentation are owned by other workflow skills (`/sprint-testing`, `/test-documentation`, `/test-automation`, `/regression-testing`) and MUST NOT trigger this skill.

The skill exists because framework-surface changes — new fixture, new layer helper, installer rewrite, manifest extractor — deserve a planning gate before code. Per-ticket test writing already has its own gate in `/test-automation` Plan → Code → Review; this skill is its architectural-surface counterpart.

---

## Compact Rules

- DO NOT: use this skill for per-ticket work — test writing is `/test-automation`, manual QA is `/sprint-testing`, TMS docs are `/test-documentation`, suite runs are `/regression-testing`. This skill governs the architectural surface only.
- DO: clear the readiness preflight, then run the Phase 0 path self-check against `references/kata-invariants.md` §10 before dispatching anything. A FORBIDDEN path aborts and redirects to the skill named in the row; a path in neither table is ASKED about, never assumed.
- WHEN one change spans both ALLOWED and FORBIDDEN paths: split it. This skill changes the base; `/test-automation` migrates the consuming specs in a follow-up.
- DO: run Plan → Code → Verify → Archive in order for every non-trivial framework change. The pipeline IS the gate; "it's a quick refactor" is not an exemption.
- DO NOT: edit per-ticket tests from a framework-development session: the specs under `tests/e2e/` and `tests/integration/` and the per-module Page / Api / Steps components are `/test-automation` surface. The KATA bases (`TestContext.ts`, `ApiBase.ts`, `UiBase.ts`) and the fixture files ARE yours (`references/kata-invariants.md` §10.1).
- DO NOT: collapse the KATA layers (TestContext / Base / Domain / Fixture) under a simplicity argument. They are framework architecture, not speculative abstraction.
- DO NOT: add a new fixture API without updating the matching fixture file AND `kata-manifest.json` AND citing at least one existing test that consumes it. Orphan fixtures rot, and the manifest is the anti-duplication gate.
- DO NOT: bump a major version of Playwright / Bun / TypeScript without a regression run on a representative E2E suite — lockstep upgrades hide breaks in fixture lifecycle, locator engines, and type emit.
- DO NOT: refactor `cli/install.ts` without exercising the full install flow on a clean clone. Verification on an already-installed repo proves nothing, and the installer is the one surface where a bug ships silently to every new user.
- WHEN the chosen approach reshapes test architecture (KATA layers, a fixture API, the runner, the isolation/parallelization model, the OpenAPI/type pipeline) AND is hard to reverse: record an ADR under `.context/ADR/` after plan approval and before coding. The plan approval IS the decision, so the ADR is written `Accepted` citing it, never handed back for acceptance (`Proposed` only for a question still open). ADRs are append-only — supersede, never rewrite.
- DO: verify with all four checks (test, types, lint, skills) and treat any non-zero exit as REJECT — present retry / skip-and-document / abort, never auto-fix. A skill that itself broke (a wrong step, a missing verifier, a stale rule) is reported upstream per `../agentic-qa-core/references/upstream-feedback.md`: drafted and redacted locally, filed only on explicit OK, verified with `gh issue view`.
- WHEN the change IS a skill (a new or restructured `.agents/skills/<slug>/`): scaffold it per `../agentic-qa-core/references/skill-scaffold.md` (frontmatter incl. `metadata.kind`, per-kind files and sections, Definition of Done). `skill-creator` (T3, installed at project level) is ALWAYS the builder: load it for the draft, the test prompts, the evals and the description pass; the scaffold contract stays this repo's. Missing on the machine → scaffold from the reference's template and say so. Consumer SUT context skills are NOT this skill's job: `project-context` mode `context-skill` owns them.
- DO NOT: let a subagent write `progress.md`; it is orchestrator-only. Code subagents return one-line summaries per task, and the orchestrator does not read their diffs.
- DO: close every change that adds, renames or retires a skill, a `package.json` script or a doc path, OR changes a behaviour a page describes, with the docs follow-through (Phase 3): patch `.agents/instructions/agent-context-map.md` and `.agents/instructions/agent-skills-and-mcps.md`, `README.md`, `INSTALLER.md`, `CONTEXT.md`, the `docs/core/` pages, the decks (`packages/decks/**`) and the Pages home (`packages/pages-home/**`) in the same PR. `bun run docs:check` proves the router and the quoted scripts; the prose is judgment.
- WHEN an edit lands inside a `LINT.IfChange(<label>)` region (the hook prints a `DOCS:` line; ADR-0016): update EVERY page its `LINT.ThenChange(...)` names in the same push. Only when the documented behaviour did not change, add `Docs-Checked: <label> <reason>` to a commit message; NEVER add it by reflex or without a reason. Pre-push and CI block otherwise. A drift found later gets a new marker.
- WHEN the change touches `cli/`, `scripts/`, `.husky/`, `AGENTS.md` or `.agents/instructions/`: run the V5 drift sweep after the four verifiers, report-only (Phase 3). It greps the doc surface for prose that describes the OLD behaviour and counts the `Docs-Checked:` trailers the change used.
- DO: archive the session directory only after all four verifiers pass. On REJECT it stays in place so the run can be debugged or resumed.
- DO: route every change to `AGENTS.md`, a section under `.agents/instructions/`, the ROUTER or a `triggers:` list through mode `instructions`: place each sentence with `references/instructions-doctrine.md` §2, close with `bun run instructions:check`. NEVER paste section prose into `AGENTS.md`, and NEVER add a ROUTER row without the ADR that decides it (`--accept-router ADR-NNNN`, ADR-0013).
- WHEN a trigger misses or over-fires: fix the section's `triggers:` and add the prompts to `cli/lib/fixtures/instruction-router-eval.json`; NEVER relabel a prompt to hide a miss.

**Read full SKILL.md when**: writing the plan artifact, batching Code-phase tasks, resuming an interrupted session, running mode `instructions`, or reading the ALLOWED/FORBIDDEN path tables themselves.

---

## Mode routing

The first token of `$ARGUMENTS` that names a mode below IS the mode; anything else runs the default pipeline.

| Mode | Trigger phrases | Reference | Output |
|---|---|---|---|
| (default) | evolve framework, new fixture API, refactor cli, boilerplate evolution, sync AI context | this file, Phase 0 to Phase 4 | the framework change, verified |
| `instructions` | edit `AGENTS.md`, add a rule, where does this rule go, router row, tune the triggers, new instruction section | `references/instructions-doctrine.md` | the edited instruction files, `instructions:check` green |

## Mode `instructions`

The one sanctioned path for changing what the agent is told on every session or per request kind. It is the default pipeline cut to the size of a text change: the placement table is the plan, the edit is the code, `instructions:check` is the verifier.

1. **Place.** For each sentence, walk `references/instructions-doctrine.md` §2 and write one line: sentence -> file -> the question that decided it. A sentence that lands in a skill or in an `<aspect>-context` skill leaves this mode for that skill's own flow.
2. **Router row?** A new, changed or removed ROUTER row is a decision: record the ADR (`agentic-qa-core/references/adr-doctrine.md`; `Accepted` when the owner already approved the change), make the edit, run `bun run instructions:check --accept-router ADR-NNNN`, cite the fingerprint it prints in that ADR. Without the ADR the gate stays red; that is the lock working.
3. **Edit.** L0 takes binding sentences only (a critical rule's full text goes in `agent-critical-rules.md` first, the L0 line stays a verbatim fragment of it). A `triggers:` or `paths:` change adds the prompts that motivated it, both languages when the trigger is bilingual, to `cli/lib/fixtures/instruction-router-eval.json`, labelled with what a careful reader of the ROUTER would load.
4. **New section?** Ship it complete: frontmatter, its ROUTER row (step 2), at least three labelled prompts that expect its `id`, a row in the `## Sections` table of `.agents/instructions/README.md`.
5. **Verify.** `bun run instructions:check` (budget, router, frontmatter, rules, binding, the router lock, the eval, completeness), then `bun run docs:check` when a skill, script or doc path moved, then the Phase 3 verifiers as usual (`skills:check` already includes `instructions:check`). A red gate is reported with its output, never worked around.
6. **Measure (optional).** `bun run instructions:audit` reports how often routed sections are actually read, from local transcripts; quote its overall number in the PR when the change is about routing.

---

## Inputs

Canonical reading order for any AI starting cold on a framework-development workflow. Read in order; stop earlier when the change is small enough that later inputs add no signal.

1. `kata-manifest.json` — Component + ATC registry (source of truth per Critical Rule #12). Establishes what already exists before any new fixture API, Page, Api, Steps module, or ATC ID is proposed.
2. `.agents/skills/test-automation/references/kata-architecture.md` + `.agents/skills/test-automation/references/typescript-patterns.md` — KATA layer flow (TestContext → ApiBase / UiBase → YourApi / YourPage → TestFixture), ATC identity rules, fixture-selection contract, import-alias conventions.
3. `tests/components/` — current Api / Page / Steps shape; required reading when touching any L2 / L3 surface or adding a fixture consumed by these components.
4. `cli/install.ts` — installer flow; required reading when evolving the installer, adding install steps, or modifying boilerplate scaffold behavior.
5. `scripts/sync-openapi.ts` + `api/schemas/` — OpenAPI-derived TypeScript types pipeline; required reading when touching the API contract pipeline, schema generation, or any consumer of generated facades.
6. `package.json` + `bun.lock` — dep landscape; required reading before bumping Playwright / Bun / TypeScript / fixture-runtime versions or adding/removing scripts.

---

## Subagent Dispatch Strategy

> **Orchestration & Session contracts**: this skill follows `agentic-qa-core/references/orchestration-doctrine.md` (mandatory subagent dispatch — main thread is command center) AND `agentic-qa-core/references/session-management.md` (Phase 0 resume check, plan-first persistence at `.session/<skill-slug>/<scope>/`, archive on completion). Phase 0 (resume check) and Phase 1 (plan write) are NOT optional.

This skill is compliant with the doctrine in `AGENTS.md` §3 (Orchestration Mode) and the session contract in `.agents/skills/agentic-qa-core/references/session-management.md`. Every dispatch follows the 7-component briefing format defined in `.agents/skills/agentic-qa-core/references/briefing-template.md`, and the pattern selected per phase matches the decision guide in `.agents/skills/agentic-qa-core/references/dispatch-patterns.md`. The four phases — Plan, Code, Verify, Archive — mirror the shape of `/test-automation` (Plan → Code → Review) extended with an inline Archive step. Phase 0 stays inline because the path self-check + session resume check are short orchestrator decisions that do not benefit from a fresh-context subagent.

**Session scope**: `<change-name>` (kebab-case, user-provided at session start). Session state lives at `.session/framework-development/<change-name>/{plan.md, progress.md}` per `agentic-qa-core/references/session-management.md` §9.

| Phase                                              | Pattern              | Subagent role                                                                                                                                                  |
|----------------------------------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Phase 0 — Path self-check + session resume check   | inline               | orchestrator only; no subagent. Lists target paths against `references/kata-invariants.md` §10; aborts on FORBIDDEN. Also checks `.session/framework-development/<change-name>/` for prior plan/progress and offers resume per `agentic-qa-core/references/session-management.md` §4 |
| Phase 1 — Plan (`plan.md`)                         | Single               | one Plan subagent writes `.session/framework-development/<change-name>/plan.md` per `agentic-qa-core/references/session-management.md` §6 schema; collapses prior explore + propose + spec + design + tasks into one artifact |
| Phase 2 — Code (per task batch)                    | Sequential           | one Code subagent per task batch from the plan; orchestrator appends to `progress.md` per `agentic-qa-core/references/session-management.md` §7 schema; on verification failure: STOP, no auto-fix |
| Phase 3 — Verify — `bun run test`                  | Parallel (sub-stage) | one Verifier subagent runs the test suite                                                                                                                       |
| Phase 3 — Verify — `bun run types:check`           | Parallel (sub-stage) | one Verifier subagent runs typecheck                                                                                                                            |
| Phase 3 — Verify — `bun run lint:check`            | Parallel (sub-stage) | one Verifier subagent runs ESLint                                                                                                                               |
| Phase 3 — Verify — `bun run skills:check`          | Parallel (sub-stage) | one Verifier subagent runs the skill-registry lint (framework changes can affect `.agents/skills/`, `AGENTS.md`, `cli/install.ts`)                              |
| Phase 3 — Aggregation + accept/reject decision     | inline               | orchestrator reads the 4 Verifier reports and decides; on any non-zero exit, presents retry / skip / abort                                                       |
| Phase 3 — V5 drift sweep (path-scoped)             | Single (report-only) | only when the change touches `cli/`, `scripts/`, `.husky/`, `AGENTS.md` or `.agents/instructions/`: one subagent hunts the doc surface for sentences that describe the old behaviour; never gates ACCEPT |
| Phase 4 — Archive (move plan + progress)           | inline               | orchestrator only; moves `.session/framework-development/<change-name>/` to `.session/.archive/<YYYY-MM-DD>-framework-development-<change-name>/` (two-file dir preserved per `agentic-qa-core/references/session-management.md` §8); references in commit |

- **Plan artifact location**: `.session/framework-development/<change-name>/plan.md`. The `.session/` tree is gitignored — the plan is local, not committed. Recovery on mid-run crash: the file persists; the orchestrator reads it back on the next session via Phase 0 resume check (see `agentic-qa-core/references/session-management.md` §4).
- **Path guardrails injected per dispatch**: every Plan and Code subagent briefing MUST include the line `KATA invariants and ALLOWED/FORBIDDEN paths: .agents/skills/framework-development/references/kata-invariants.md (read §10 before touching any file).` Do NOT inline the path tables — the reference is authoritative.
- **On any subagent failure**: STOP, return the failing report, do NOT auto-rerun. The orchestrator decides retry / skip / abort. See `.agents/skills/agentic-qa-core/references/orchestration-doctrine.md`.
- **Strict TDD flag** is set in Phase 1's `plan.md` under §"Strict TDD flag". Default OFF. Flipped ON only when the user explicitly opted in. Code phase reads it from the plan; no separate cache needed.

---

## Fleet seam (optional)

Phase 2 Code is sequential per task batch by default, and a change that fits one plan stays that way. A **wave** — several persistent worker sessions taking one task batch each, a conductor integrating them — is for a plan whose batches are genuinely independent (different files, no shared public API in flight). Offer it; never enter it silently.

- **Topology: same checkout with file ownership per worker.** Each worker's brief lists the exact files it owns and commits with explicit paths (never `git add -A`), so two workers never stage each other's work. When two batches must touch the same module, they do not run in the same wave: serialize them, or give each worker its own worktree.
- The conductor writes `launch.txt` in `.session/framework-development/<change-name>/` — one self-contained line per worker — **always**, whether or not any orchestration transport exists on the machine. Launching, supervising and closing those sessions is `orca-orchestration/SKILL.md` (`[ORCHESTRATION_TOOL]`): supervised launch is the native path, and `launch.txt` is the payload for the human-paste fallback when nothing can launch it.
- **Phase 0 and Phase 3 stay with the conductor.** The path self-check runs once, over the union of every worker's paths, before the first launch; the four Phase 3 verifiers run once, on the integrated tree, after the last worker reports. A per-worker green gate is not a wave gate.
- **Read before every edit.** A worker's neighbour may have changed a shared file since the brief was written; Critical Rule #15 (no global discards) binds twice as hard when sessions share a tree.
- **Silence rule**: the absence of an orchestration transport is never named to the user and never appears in the preflight gate or the plan.

---

## Readiness Preflight Gate (MANDATORY — runs before Phase 0)

> Full doctrine: `agentic-qa-core/references/preflight-gate.md`. Runs FIRST, before the path self-check and resume check. Two laws: (1) **args-as-answers** — the change name and touched paths are provided args; ask only the gaps. (2) **probe, don't assume**. Surface gaps + REDs as ONE `AskUserQuestion` checklist; self-fix with approval + explanation; STOP on any blocking RED. This skill evolves the framework itself — it does NOT hit a live env, Jira, DB, or API — so its gate is a **dev-toolchain readiness** check that pairs with the Phase 0 path self-check. **Generic baseline** (the two laws, secret/restart handling, output contract) is inherited from the reference §3.1 — not repeated here; the env/creds half of the baseline is N/A for meta-work. Below is only this skill's **specific capability delta**.

| Capability | Need | Why here |
|---|---|---|
| Dev toolchain | REQUIRED | Phase 3 Verify runs `bun run test` / `bun run types:check` / `bun run lint:check` / `bun run skills:check`. All four must resolve at t=0. `bun install` if a dep is missing. |
| `kata-manifest.json` clean | REQUIRED | Source of truth (Critical Rule #12). Framework changes can invalidate it — `bun run kata:manifest:check` clean, `bun run kata:manifest` to regenerate. |
| Playwright browsers | SCOPE — touching fixtures / KATA bases / tests | Verify of a fixture or base-class change runs the suite, which needs chromium (`bun run pw:install`). |
| `/github-actions-docs` + `/playwright-best-practices` | OPTIONAL | Injected per dispatch when the change touches CI YAML or fixtures/tests (already noted in the briefing skeleton). |

Active env, test-user creds, OpenAPI / API token, DBHub, issue-tracker, TMS and `resend` are **N/A** — framework evolution is meta-work on this repo. After the gate clears (all REQUIRED GREEN), continue to Phase 0 below.

---

## Phase 0 — Path self-check + session resume check (mandatory, runs first)

Before invoking any subagent, the orchestrator MUST (a) list the files / directories the change will touch and verify each one against the ALLOWED / FORBIDDEN tables in `references/kata-invariants.md` §10, and (b) run the session resume check per `agentic-qa-core/references/session-management.md` §4. Skipping Phase 0 is the most common way framework changes leak into ticket-owned surface area OR lose mid-run state on interruption.

1. Read `references/kata-invariants.md` §10 (ALLOWED + FORBIDDEN paths).
2. Ask the user (or infer from the request): "Which paths will this change touch?"
3. For each path, look it up in §10 ALLOWED → proceed. Or §10 FORBIDDEN → abort and redirect to the skill named in the row.
4. If a path matches neither table, ASK the user explicitly — never assume.
5. If a single change spans both ALLOWED and FORBIDDEN paths (e.g. "refactor `tests/components/ui/UiBase.ts` AND update the e2e tests that consume it"), split the work: framework-development handles the base-class change; `/test-automation` handles the test-spec migration in a follow-up.
6. **Session resume check** (per `agentic-qa-core/references/session-management.md` §4): check `.session/framework-development/<change-name>/progress.md`. If it exists, read `plan.md` + the tail of `progress.md`, surface the last completed phase + next planned phase + any blocking notes, and offer **resume / restart / abort**. On `restart`, archive the current directory to `.session/.archive/<YYYY-MM-DD>-framework-development-<change-name>-aborted/` before proceeding.

Phase 0 is one short inline decision — it does NOT write a file. If the change is approved, the decision is captured later in Phase 1's `plan.md` §Investigation.

---

## Native Phase Orchestration

After Phase 0 passes, run the four-phase pipeline in dependency order. Each subagent dispatch follows the 7-component briefing format in `agentic-qa-core/references/briefing-template.md`. Briefing skeleton for Plan and Code phases (fill the `<...>` slots):

```
Goal: <one-sentence outcome scoped to this phase>

Context docs:
  - .agents/skills/framework-development/references/kata-invariants.md
  - .session/framework-development/<change-name>/plan.md   (Code phase only)
  - .session/framework-development/<change-name>/progress.md   (Code phase, batches > 1; orchestrator-written, read-only for subagents)
  - <relevant ALLOWED-path files the phase will read or touch>

Project Standards (auto-resolved):
  <compact-rule blocks pulled from .agents/skills/REGISTRY.md per skill-resolver protocol>

Skills to load: <none by default; orchestrator injects /playwright-best-practices if fixtures/tests, /github-actions-docs if CI YAML>

Exact instructions:
  1. Read kata-invariants.md fully. Verify §10 ALLOWED for every touched path. FORBIDDEN → STOP.
  2. <phase-specific step — e.g. "write the plan", "implement task batch N">
  3. Save the artifact at the engram topic_key framework/<change-name>/<phase>.
  4. Return the executive summary inline.

Report format:
  - status: ready | blocked | failed
  - artifact: <absolute path or engram topic_key>
  - next_recommended: <phase or "stop">
  - risks: [<one-liner per risk>]
  - skill_resolution: injected | fallback-inline

Rules:
  - ALLOWED paths only (kata-invariants.md §10). FORBIDDEN → abort.
  - Do NOT modify generated artifacts (api/openapi-types.ts, kata-manifest.json, reports/).
  - If strict TDD is ON (read from plan §"Strict TDD flag"), every production-code task is preceded by a failing test in the same batch.
  - Decisions: agentic-qa-core/references/decision-protocol.md before any question. A technical call inside the approved plan is decided and reported as DECIDED with the option it beat; escalate to the orchestrator only the four §5 kinds (product behaviour, a new security posture, an irreversible or outward action, what the owner reserved). Never widen the scope beyond the plan.
```

Phase order (each phase gates the next):

```
Phase 0 (inline) -> Phase 1 Plan (Single) -> Phase 2 Code (Sequential per batch) -> Phase 3 Verify (Parallel 4-way) -> Phase 4 Archive (inline)
```

### Phase 1 — Plan

Dispatch: **Single**. The Plan subagent writes one consolidated artifact at `.session/framework-development/<change-name>/plan.md` covering: Goal, Investigation, Approach options, Chosen approach, Invariants touched, Public API delta, Task breakdown, Strict TDD flag, Risks, Verification checklist. One file, ten sections — not five separate documents. The seven base sections from `agentic-qa-core/references/session-management.md` §6 are mandatory; framework-development extends them with three skill-specific sections (Invariants touched, Public API delta, Strict TDD flag).

Present the plan to the user. Wait for approval before Phase 2.

When the change IS a skill, the plan's Task breakdown follows `../agentic-qa-core/references/skill-scaffold.md` §2 for that kind, and the Verification checklist includes its §5 Definition of Done.

**ADR seeding (framework architecture).** When the chosen approach reshapes the framework's test architecture — KATA layers, fixture APIs, the test runner, the isolation/parallelization model, or the OpenAPI/type pipeline — and the decision passes the two-gate test (architectural AND hard to reverse per `agentic-qa-core/references/adr-doctrine.md` §1), record a `.context/ADR/ADR-NNNN-<slug>.md` after the plan is approved and before Phase 2 coding. Framework evolution is meta-work: its decisions bind every test session that follows, so historicize them rather than leaving them in a one-off `plan.md` that gets archived. The plan's "Invariants touched" / "Public API delta" sections are the prime ADR candidates. The human already approved the plan, so the ADR is `Accepted` from the start, its `Deciders` line naming that approval; never ask the human to accept it again (`agentic-qa-core/references/adr-doctrine.md` step 4 and A4). `Proposed` is only for a part of the decision still open, and the ADR says what. Template + lifecycle: `.context/ADR/README.md`.

### Phase 2 — Code

Dispatch: **Sequential** — one subagent per task batch. The orchestrator decides batching from the plan's task list; rule of thumb is 1 batch per 3-5 closely-coupled tasks, or 1 batch per task when the task touches a load-bearing file such as `ApiBase.ts` / `UiBase.ts` / `TestContext.ts`.

Each subagent:
1. Reads `plan.md` and applies the tasks in its batch in plan order.
2. Runs the per-task verification command listed in the plan.
3. Returns a one-line summary per task to the orchestrator.
4. On verification failure: STOP, report, do not auto-fix.

The orchestrator never reads diffs from the Code subagent — only the summary. If the user wants to see actual changes, the orchestrator runs `git diff` inline after the batch returns. After each batch returns, the orchestrator appends a phase entry to `.session/framework-development/<change-name>/progress.md` per `agentic-qa-core/references/session-management.md` §7 (subagents never write to `progress.md` directly — that is an orchestrator-only file).

### Phase 3 — Verify

Dispatch: **Parallel** — four Verifier subagents in the same `<function_calls>` block:

| Verifier | Command                | Captures             |
|----------|------------------------|----------------------|
| V1       | `bun run test`         | exit code, summary   |
| V2       | `bun run types:check`  | exit code, summary   |
| V3       | `bun run lint:check`   | exit code, summary   |
| V4       | `bun run skills:check` | exit code, ERROR/WARN/INFO counts |

`skills:check` is included because framework changes routinely touch `.agents/skills/framework-development/`, `agentic-qa-core/references/`, `AGENTS.md`, and `cli/install.ts` — every one of those surfaces is read by `scripts/lint-skills.ts` and gated by the named checks it declares (tier coherence, anti-leak, stale-path, duplicate-tier, etc.). The other three commands never see this surface; adding the fourth verifier costs one parallel slot and prevents an entire failure class.

After all four return, the orchestrator inline-aggregates:

- All four `exitCode == 0` → ACCEPT. Proceed to Phase 4.
- Any `exitCode != 0` → REJECT. Present failing verifier(s) to the user. Options: retry the failing Phase 2 batch / skip-and-document / abort. Do NOT auto-fix.

### Docs follow-through (closing step of Phase 3)

Two triggers, either one is enough: the change adds, renames or retires a skill, a `package.json` script or a doc path; or it changes a BEHAVIOUR some page describes in prose (what a gate checks, what the installer asks or offers, which files a contract covers, how a rule is applied). The same PR patches every doc that names it or describes it: `.agents/instructions/agent-context-map.md` (task map), `.agents/instructions/agent-skills-and-mcps.md` (skill router), `README.md`, `INSTALLER.md`, `CONTEXT.md`, the `docs/core/` pages, the decks under `packages/decks/` and the Pages home under `packages/pages-home/`. The last two are the surface every measured drift missed. `bun run docs:check` (inside `repo:check`, and on every push) fails when a repo skill is missing from the §5 router or a doc quotes a `bun run` script `package.json` does not declare; the wording around each fact, and any page that describes the old behaviour, is read and fixed by hand. Human pages point to `.agents/skills/REGISTRY.md` for the skill list and never enumerate it (Critical Rule #17). A downstream project's own docs are `test-framework-adaptation` Phase 9.3, never this skill.

**Declared couplings (ADR-0016).** A code region a page describes carries `LINT.IfChange(<label>)` / `LINT.ThenChange(<pages>)` comment lines. When the change touches one, every page it names changes in the same push, or a commit carries `Docs-Checked: <label> <reason>` because the documented behaviour still holds. Pre-push (`scripts/lint-doc-contracts.ts --push`) and CI block otherwise; the commit hook only warns. In Claude Code and Codex the edit hook prints the `DOCS:` line the moment the region is edited. When this change finds a drift no marker caught, add the marker in the same PR: that is how coverage grows where drift happens.

**V5 drift sweep (report-only, path-scoped).** Runs only when the change touches `cli/`, `scripts/`, `.husky/`, `AGENTS.md` or `.agents/instructions/`, after the four verifiers. One subagent, briefed with the diff (`git diff <merge-base>..HEAD`) and a one-paragraph summary of the behaviour that changed:

1. Extract the changed behaviour's terms (flags, file names, commands, rule names, the old wording the diff removed).
2. Grep the doc surface: `README.md`, `INSTALLER.md`, `CONTEXT.md`, `AGENTS.md`, `.agents/instructions/**`, `.agents/skills/**`, `docs/**`, `packages/decks/**`, `packages/pages-home/**`.
3. Read every hit in context and report each sentence that is now wrong or silently incomplete, as `file:line` + the sentence + what changed. A hit the PR already updated is not a finding.
4. Count the `Docs-Checked:` trailers in the range (`git log --format=%B <merge-base>..HEAD`) and list each label with its reason.

Report-only: it never gates ACCEPT. The orchestrator fixes each finding or dismisses it with a reason, in the same PR. It is the one step that finds a coupling nobody declared.

### Phase 4 — Archive

Dispatch: **inline** — no subagent. The orchestrator performs the archive flow from `agentic-qa-core/references/session-management.md` §8:

1. Verifies the Verification checklist in `plan.md` passes (all four Phase 3 verifiers returned exit 0).
2. Moves the entire working directory: `mv .session/framework-development/<change-name>/ .session/.archive/<YYYY-MM-DD>-framework-development-<change-name>/`. Both `plan.md` and `progress.md` are preserved side by side (no concatenation) so future resume-replay stays possible.
3. Calls Engram `mem_session_summary` with the session template per `agentic-qa-core/references/session-management.md` §11. The summary MUST include the archive path so `mem_search "session framework-development <change-name>"` resolves back to the artifacts.
4. Surfaces the archive path so `/git-flow-master` can include it in the commit message body.

Archive is a "close-the-loop" step, not "ship-the-code". Code is shipped by `/git-flow-master` based on the diff that Phase 2 produced and Phase 3 verified. On Phase 3 REJECT, archive does NOT run — the working directory stays in place so the user can debug, resume, or abort.

---

## Anti-patterns — NEVER do these

- **F1.** NEVER use `/framework-development` for per-ticket test writing — that surface is owned by `/test-automation` (Plan → Code → Review on KATA + Playwright + TypeScript). Framework-development governs the architectural surface only.
- **F2.** NEVER collapse KATA layers (TestContext / Base / Domain / Fixture) under the pretext of simplification. The layers are framework architecture, not speculative abstraction. Critical Rule #12-adjacent: simplicity-first does NOT apply to KATA.
- **F3.** NEVER edit per-ticket tests from a framework-development session: the specs and the per-module Page / Api / Steps components in `tests/components/{module}/` are owned by per-ticket work via `/test-automation`. The KATA bases (`TestContext.ts`, `ApiBase.ts`, `UiBase.ts`) and the fixture files in `tests/components/` ARE this skill's surface (`references/kata-invariants.md` §10.1). If a base-class refactor forces a consumer migration, split the work: framework-development changes the base; `/test-automation` migrates the specs in a follow-up.
- **F4.** NEVER skip the Plan → Code → Verify → Archive pipeline for non-trivial framework changes. The pipeline IS the gate — bypassing it for "quick" refactors of `ApiBase.ts`, `UiBase.ts`, `TestContext.ts`, fixtures, installer, or OpenAPI pipeline reliably produces undetected regressions.
- **F5.** NEVER bump major versions of Playwright / Bun / TypeScript without a regression run on a representative E2E suite. Lockstep upgrades hide breaking changes in fixture lifecycle, locator engines, or type-emit behavior.
- **F6.** NEVER add a new fixture API without updating `tests/components/TestFixture.ts` (or the matching `ApiFixture.ts` / `UiFixture.ts`) AND `kata-manifest.json` AND citing at least one existing test that consumes it. Orphan fixtures rot — and `kata-manifest.json` is the anti-duplication gate (Critical Rule #12).
- **F7.** NEVER refactor `cli/install.ts` without testing the full install flow on a clean clone. The installer is the only surface where a bug ships silently to every new user — verification on the developer's already-installed repo proves nothing.
- **F8.** NEVER introduce a hard-to-reverse test-framework architectural decision (KATA-layer reshape, new fixture API, test-runner swap, isolation/parallelization model) without recording it as an ADR in `.context/ADR/`. Framework evolution binds every later test session — a decision left only in an archived `plan.md` gets re-litigated or silently violated. Write it before Phase 2, `Accepted` and citing the plan approval (`Proposed` only while a question is still open). ADRs are append-only: supersede, never rewrite. See `agentic-qa-core/references/adr-doctrine.md`.

---

## Session close contract

**Session-footer contract (mandatory at close).** The final phase is not done until the two chat-facing blocks from `../agentic-qa-core/references/session-footer-contract.md` are printed: (1) consolidated screenshot list — repo-relative paths, verified on disk, bug annotations first — plus in-flow surfacing of every capture's path the instant it lands; (2) Session Footer listing skills/MCPs/CLIs actually used + testing levels touched, with explicit "none" entries for expected-but-untouched levels. Framing for this skill: meta. Multi-subagent sessions: each stage report carries the five footer fields (`skills_loaded`, `mcps_used`, `clis_used`, `testing_levels_touched`, `screenshots_captured`); the orchestrator compiles the footer ONCE at close. Chat only — never in a Jira comment or ATR body. Lessons noticed during the session are PROPOSED to `.session/<skill-slug>/<scope>/refinements.md` and never applied to a live skill, per `../agentic-qa-core/references/skill-refinement-protocol.md`; the footer's `Refinements proposed:` line counts them.

---

## References

- `references/kata-invariants.md` — INVARIANT vs EXTENSIBLE rules for the 4 KATA layers, fixture selection, ATC identity, DRY scope, import aliases, public-method contract, extension points, evolution checklist, out-of-scope surfaces, and §10 ALLOWED / FORBIDDEN path tables. Required reading before any Plan or Code subagent that touches `tests/components/`, `api/schemas/`, or fixtures.
- `../agentic-qa-core/references/skill-composition-strategy.md` — T1/T2/T3/T4 tier model, category vocabulary, validation rules. The §4 anti-leak contract is informational here: framework-development does not chain SDD by default; §4 governs users who manually install SDD and explicitly request the SDD ceremony.
- `../agentic-qa-core/references/briefing-template.md` — 7-component briefing examples per pattern.
- `../agentic-qa-core/references/dispatch-patterns.md` — Single / Sequential / Parallel / Background decision guide.
- `../agentic-qa-core/references/orchestration-doctrine.md` — failure protocol, ASK-on-error rule, no auto-fix.
- `../agentic-qa-core/references/session-management.md` — Phase 0 resume contract, `plan.md` / `progress.md` schemas, archive policy, scope-naming, Engram coupling. This skill is one of the producers of `session/...` topic keys.