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 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 layer dependencies must be enforced by the build instead of by review.

Use to compose an HVE-format PRD (17 sections, docs/prds/<name>.md) from brownfield characterization artifacts produced by characterize-brownfield. Maps as-is features, constraints, integrations, coverage and tech debt into HVE PRD sections with FR/NFR IDs and full traceability. Activate on 'write the PRD', 'compose PRD from characterization', 'produce an HVE 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 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 reviewing DISCOVER artefacts (triage reports, sprint proposals) for completeness, prioritization quality, and duplicate handling. Contains gate definitions G1-G6 and scoring rubric for the backlog-discoverer-reviewer lenses.

Use when building GitHub search queries, paginating through issue results, filtering by labels/milestones/assignees, or implementing artifact-driven discovery from git history. Covers GitHub search syntax, MCP tool usage patterns, and result ranking.

Use when transforming raw issues or feature requests into well-structured user stories with acceptance criteria. Covers user story format, INVEST criteria, acceptance criteria patterns, story splitting techniques, DoR 8-item gate, and 8 antipatterns to detect.

Use when triaging GitHub issues by assigning labels, priority, effort estimates, or detecting duplicates. Covers triage methodology, label taxonomy, priority frameworks, effort sizing, and sprint proposal construction.

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 (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 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 Stryker reports after the test baseline is green

Use when an approved scenario, Gherkin example, worked example, or expected result has to become working software through outside-in / double-loop TDD -- start from an acceptance or application-boundary test, get a trustworthy RED before implementation, let domain logic emerge only from failing behavior, and drive one walking skeleton or first delivery slice at a time. Also use to decide what belongs in first delivery and what stays out of scope, when checking whether a failing suite proves a missing approved behavior or is false evidence, when replacing fixture-provided or test-provided false greens with production behavior, when wider HTTP/DB/infrastructure tests should wait behind an inner failing behavior, and when splitting RED and GREEN across workers or subagents with inspection between them. Finish with post-GREEN wiring verification, mutation/coverage gates, and never commit on red.

Use when reviewing DISCUSS artefacts (stories, acceptance criteria, sprint plans) for INVEST quality, planning coherence, and DoR compliance. Contains gate definitions G1-G8 and scoring rubric for the backlog-planner-reviewer lenses.

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 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 at the end of the COMMIT phase; 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 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 at pipeline start to detect an upstream HVE backlog/sprint handoff (entry-point skip), and at DISCOVER exit to evaluate the difficulty axis, validate immutable invariants, and persist to state.json

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 when planning sprint content, prioritizing stories within milestones, estimating capacity, or analyzing dependency graphs between stories. Covers MoSCoW prioritization, milestone management, velocity tracking, and dependency resolution for GitHub-based workflows.

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.