SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsframework-development

framework-development

Testing & quality

View repository

Updated 10-16 04:26

About this skill

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.