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 tests/components/ from a framework-development session — those L2/L3 KATA components are per-ticket surface.
• 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, drafted Proposed for the human to accept. 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.
• 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: archive the session directory only after all four verifiers pass. On REJECT it stays in place so the run can be debugged or resumed.

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

---

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.lockb — 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 §"Orchestration Mode (Subagent Strategy)" 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 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).
• Grace period for legacy path: prior versions wrote to .scratch/framework-changes/<change-name>/{plan.md, apply-progress.md}. Phase 0 also checks the legacy path during the grace period — if found, the orchestrator offers to copy state to the new .session/... location before resuming.
• 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.
7. Legacy path check (grace period): also check .scratch/framework-changes/<change-name>/ for prior plan/progress under the old layout. If found, offer to migrate the state to the new .session/... location.

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.
  - On uncertainty, STOP and report — do not improvise on framework surface.

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.

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. Draft Proposed; the human accepts. 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 10 named checks (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.

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