framework-development

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.