sebastiendegodez/skraft

Use when reviewing DISTILL artefacts (Gherkin scenarios, test plans, implementation plans) for quality, completeness, and alignment. Contains the gate definitions and scoring rubric for the acceptance-designer-reviewer lenses.

Use when deciding WHETHER a candidate architectural choice deserves an architecture decision record, before any record is drafted: a story enters DESIGN with a list of candidate choices, a reviewer flags ADR inflation, or someone asks "should I write an ADR for X?", "how many ADRs does this story need?", "is this ADR-worthy?", "this feels like too many ADRs", "disambiguate baseline from decision". Runs a baseline-vs-decision gate over each candidate and returns ELIGIBLE or NOT ELIGIBLE with the baseline, convention or architecture test that already covers it. Do NOT use when the decision is already settled and the user asks for the record to be written, when the request is about the ADR template, status transitions, superseding or lifecycle, or when the question is which pattern to adopt — those belong to architecture-decisions and architecture-patterns.

Use when reviewing a phase artifact — a discovery brief, a plan, a design, an acceptance specification, or a slice reported as delivered — and the review has to end in a defensible pass-or-block verdict rather than a list of remarks. Covers judging whether the artifact covers everything that fed into it, whether it matches the business intent, whether it holds together internally, and what it puts at risk downstream, then weighing those into a single call. Not for routine code review of an ordinary change.

Use when documenting architecture decisions as ADRs, evaluating trade-offs between alternatives, or managing the lifecycle of existing decisions. Covers ADR template, status transitions, consequence analysis, and quality criteria.

Use when selecting architecture patterns for a new feature, performing Event Modeling, defining bounded contexts, choosing DDD tactical patterns, evaluating pattern fitness, or understanding how patterns compose. Covers Event Modeling methodology, DDD strategic design, DDD tactical patterns, Clean Architecture, CQRS, and Event Sourcing.

Use when reviewing DESIGN artefacts (event models, ADRs, component diagrams, context maps, interface contracts) for quality, DDD compliance, and architectural correctness. Contains gate definitions and scoring rubric for the solution-architect-reviewer lenses.

Use when writing, reviewing, or structuring BDD scenarios in Gherkin format. Covers Given/When/Then conventions, scenario outline patterns, background usage, tag strategies, and domain language alignment. Load before any Gherkin authoring.

Use to reverse-engineer an existing/brownfield codebase into structured, confidence-scored characterization artifacts (tech stack, feature inventory, dependency & integration map, existing API contracts, test-coverage traceability, tech debt & risks). Use before composing a PRD, or standalone to understand a legacy system with no docs. Activate on 'characterize this codebase', 'what does this system do', 'map the architecture', 'find existing contracts', 'assess tech debt', 'reverse-engineer this legacy system'.

Use to discover or reconstruct a service's API contract and produce characterization (golden-master) tests that lock in its CURRENT behavior — including existing bugs — as a safety net before refactoring a brownfield service. Delegates stack detection and Microcks wiring to contract-testing-roster and mocking-strategy-roster; adds nothing new to the toolchain, only the characterization intent. Activate on 'characterize this API', 'lock in current behavior', 'build a contract-based safety net'.

Use when laying out or extending a .NET / ASP.NET Core solution — which project a class belongs in, which project may reference which, and how an endpoint reaches a use case.

Use when laying out or extending a Java / Spring Boot service built with Maven — which module a class belongs in, which module may depend on which, and how an endpoint reaches a use case.

Use when laying out a Python service packaged with pyproject.toml (FastAPI or another web framework), or adding a feature, endpoint, use case, aggregate or repository to one — which package a module belongs in, which package may import which, and how an endpoint reaches a use case. Not for configuration, dependency or tooling changes.

Use when laying out or extending a React / TypeScript front end — which folder a screen, component, hook, use case or API call belongs in, which folder may import which, and how a component reaches the API. Not for build, dependency, environment-variable or tooling configuration.

Use when it is unclear where a test belongs and what it is allowed to talk to — which test project and layer it goes in, whether it gets a real database, an in-memory fake, or no double at all, and whether a value object or a constructor is worth a test of its own. Also use when covering an adapter that calls an external API, a database or the file system, and when layer dependencies must be enforced by the build instead of by review.

Use to compose a structured 17-section PRD at docs/prds/<name>.md from brownfield characterization artifacts produced by characterize-brownfield. Maps as-is features, constraints, integrations, coverage and tech debt into PRD sections with FR/NFR IDs and full traceability. Activate on 'write the PRD', 'compose PRD from characterization', 'produce a PRD for this system'.

Use when authoring OpenAPI/AsyncAPI contracts, generating Microcks samples, setting up Testcontainers mocks, verifying provider contracts, or bridging API contracts across DESIGN → DISTILL → DELIVER phases.

Use when the contract-testing-roster resolved a .NET stack for a provider-side contract test. Always provides the baseline WebApplicationFactory + HttpClient integration test recipe; when the Microcks opt-in is enabled, additionally provides the MicrocksContainer + TestEndpointAsync(OPEN_API_SCHEMA) layer that replays the published contract against the running service and validates response codes, headers, and ProblemDetails shape. Emits test wiring only; the business TDD cycle stays with the software-engineer lead.

Use when the contract-testing-roster resolved a Python stack for a provider-side contract test. Always provides the baseline FastAPI TestClient integration test through the app factory; when the Microcks opt-in is enabled, additionally boots the service on a real port with uvicorn and has a MicrocksContainer (unofficial microcks-testcontainers binding, pinned) replay the published contract against it (OPEN_API_SCHEMA runner). Emits test wiring only; the business TDD cycle stays with the software-engineer lead.

Use when an agent must produce a provider-side contract test for THIS service's API and needs to know the stack adapter and whether the optional Microcks verification layer is enabled. Resolves the stack and reads the Microcks opt-in (off by default), then points to the concrete contract-testing-<stack> adapter. Loaded by the contract-testing-worker. A baseline in-process integration test is always produced; Microcks contract verification is an additive opt-in.

Use when a change looks finished and is about to be committed, or a phase has just turned green — the self-check the software-engineer runs before claiming the work is done. Not a review contract. The reviewer verifies artifacts independently.

Use when publishing already-prepared Markdown to a GitHub PR conversation or issue comment, updating that comment, or reconciling an interrupted publication. Covers MCP-first publication with host gh fallback when MCP capability is unavailable. Not for finding issues, authoring Markdown, generating reports or judging their content.

Use to refactor or restructure existing code IN PLACE when the change is likely to break things in ways that are hard to predict up front — drive the Mikado Method loop: attempt the change naively, capture what breaks as prerequisite graph nodes, revert, and implement bottom-up from the leaves, always keeping the codebase green. Loaded internally by brownfield-refactorer when the human chooses in-place restructuring over Strangler Fig.

Use when the mocking-strategy-roster resolved (inprocess, .NET) — the override mocking strategy that replaces a downstream dependency with an in-process test double (FakeItEasy, NSubstitute, or Moq) instead of a Microcks container. Provides the concrete double registration swapped into the WebApplicationFactory DI. Emits mock wiring only; the business TDD cycle stays with the software-engineer lead.

Use when the mocking-strategy-roster resolved (inprocess, Python) — the override mocking strategy that replaces a downstream dependency with an in-process double (respx for httpx, responses for requests, or a hand-written fake passed to the app factory) instead of a Microcks container. Emits mock wiring only; the business TDD cycle stays with the software-engineer lead.

Use when the mocking-strategy-roster resolved (inprocess, TypeScript) — the override mocking strategy that replaces a downstream HTTP API with an in-process double (MSW answering at the network layer, or a hand-written gateway handed to the feature) in a Vitest integration test, instead of a Microcks container. Emits mock wiring only; the business TDD cycle stays with the software-engineer lead.

Use when the mocking-strategy-roster resolved (microcks, .NET) — the default mocking strategy for a .NET integration test. Provides the concrete Microcks Testcontainers wiring and the WebApplicationFactory scaffold that points the system-under-test's typed HttpClient at the mock URL. Emits mock wiring only; the business TDD cycle stays with the software-engineer lead.

Use when the mocking-strategy-roster resolved (microcks, Python) — the default mocking strategy for a Python integration test. Provides the MicrocksContainer wiring (unofficial microcks-testcontainers binding, pinned) of a Microcks container seeded from the downstream dependency's contract and the pytest fixture that points the system-under-test's HTTP client at the mock URL through the app factory. Emits mock wiring only; the business TDD cycle stays with the software-engineer lead.

Use when the mocking-strategy-roster resolved (microcks, TypeScript) — the default mocking strategy that serves a downstream HTTP API from its OpenAPI contract in a Microcks container (@microcks/microcks-testcontainers) for a Vitest gateway integration test. Emits mock wiring only; the business TDD cycle stays with the software-engineer lead.

Use when an agent must mock a downstream HTTP/event dependency for an integration test and needs to know WHICH mocking strategy and stack adapter to use. Resolves the mocking strategy (Microcks by default, overridable to an in-process library) and the stack, then points to the concrete mocking-<strategy>-<stack> adapter. Loaded by the mock-integration-worker. No agent hardcodes a mocking approach — it resolves it here.

Use when entering COMMIT & VERIFY phase, killing surviving mutants, verifying test quality via mutation score, or analyzing supported Stryker.NET, Node TAP StrykerJS, TypeScript StrykerJS with the Vitest runner or Python cosmic-ray results after the test baseline is green

Use when an approved behaviour (scenario, Gherkin example, worked example, expected result) must become working software, or when a test suite is not trustworthy evidence of it — the suite is green while the real runtime behaviour is wrong or missing because fixtures or tests supply the value, or the suite already fails but that failure may not prove the missing approved outcome. Drives outside-in / double-loop TDD with an acceptance or application-boundary test first, a trustworthy RED before any implementation, domain logic emerging only from failing behaviour, one walking skeleton or delivery slice at a time. Also decides what belongs in first delivery, keeps wider HTTP/DB/infrastructure tests behind an inner failing behaviour, and keeps the RED inspection point when RED and GREEN are split across workers or subagents. Finishes with post-GREEN wiring verification and mutation/coverage gates; never commits on red.

Use when capturing E2E test evidence (screenshots, videos, traces) and storing them in .copilot-tracking/skraft-plans/{projectSlug}/changes/{date}/evidence/{story}/evidence/ for agents to consume. Covers Playwright setup, on-failure capture, trace collection, and evidence manifest generation.

Use when preparing QA forecast or outcome Markdown from approved plans and recorded delivery evidence, including DISTILL forecast handoff, blocked delivery summaries, and checking report data against its sources. Not for running tests, deciding quality gates, or publishing prepared Markdown.

Use when the active repository is a .NET solution (.sln / .csproj present) and the software-engineer must produce falsifiable evidence for the quality gates. Most gates are captured once, after the story's last work commit; the G10 RED capture is taken **at RED**, before any production code, and cannot be reconstructed later. Provides the concrete dotnet / stryker commands and how their outputs map onto the tech-agnostic schema.

Use when producing or verifying the structured evidence log that attests quality gates (tests, build, mutation, commits, RED/GREEN integrity). Tech-agnostic schema. Loaded by software-engineer (writer) at COMMIT phase and by quality-gates-lens (reader) during review.

Use in a JavaScript/Node.js project when running its existing package tests or build scripts, when running StrykerJS mutation gates after a green baseline, or when judging whether a recorded JavaScript test or mutation result is enough to call delivery verified. Owns command resolution from checked-in package scripts, sequential core/boundary StrykerJS 9.6.1 TAP execution and fresh evidence. Not for explaining test code, TypeScript or Vitest packages (quality-gates-typescript), coverage enforcement, or other mutation runners.

Use when the active repository is a Python project (pyproject.toml present) and the software-engineer must produce falsifiable evidence for the quality gates, or run the cosmic-ray mutation gates after a green baseline. Provides the cross-platform scripts (Node, no shell) that run pytest, import-linter, coverage.py and cosmic-ray from the project's virtual environment and map their outputs onto the tech-agnostic schema. The G10 RED capture is taken at RED, before any production code.

Use when the repository holds a TypeScript project tested with Vitest — a React front end or a Node package with vitest in its package.json — and the software-engineer must produce falsifiable evidence for the quality gates, or run the StrykerJS mutation gates after a green baseline. Provides the cross-platform scripts (Node, no shell) that run Vitest, tsc, ESLint and its boundaries rules, v8 coverage and StrykerJS with the Vitest runner, and map their outputs onto the tech-agnostic schema. The G10 RED capture is taken at RED, before any production code.

Use whenever an agent must run a toolchain command (build, test, mutation) and needs the concrete invocation. Resolves build/test/mutation commands from the detected stack via the quality-gates-<tech> adapters so no agent hardcodes dotnet test, dotnet build, or any toolchain command. Loaded by acceptance-designer and software-engineer.

Use before running, verifying, or reporting any quality gate. States the one permanent threshold for mutation score and line coverage, and the enforcement level of every gate. Load when about to invoke a mutation run, when deciding whether a gate blocks or merely warns, when writing or reviewing an evidence record, when a skill or descriptor appears to state a threshold of its own, and whenever a number would otherwise be copied from memory or from an older document. There are no tiers, no advisory level, and no override. Does not choose the toolchain command (resolving-stack-commands), classify survivors (mutation-testing), define the evidence schema (quality-gates-evidence-contract), or set the reviewer lens count (each review-criteria skill owns its own).

Use to REPLACE part of an existing brownfield system incrementally — behind a routing facade, one slice at a time, verified by contract equivalence against a green safety net — rather than restructuring it in place. Loaded internally by brownfield-refactorer when the human chooses replacement over Mikado in-place restructuring.

Use when planning which tests an approved set of examples actually needs before any code is written — where each test enters and what it observes, whether a rule those examples already cover deserves a test of its own, and whether a scenario reads in business terms and ends in an outcome a user could observe.

Use when the tests pass but the test code itself has gone bad — the same setup copied into several tests, names that describe the method instead of the behavior, near-duplicate test methods, or a class grown too large to read. Use it to clean that up without losing a single case of coverage.