pi-dev-team 0.2.0

package/skills/domain-driven-design/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: domain-driven-design
+description: Model software around the business domain. Use when designing bounded contexts, defining aggregates and value objects, mapping context relationships, or working with complex business logic. Apply before implementation to prevent model drift.
+role: worker
+user-invocable: true
+---
+
+# Domain-Driven Design (DDD)
+
+## Overview
+
+Model software around the business domain. Collaborate with domain experts to build a shared understanding expressed in code through ubiquitous language, bounded contexts, and tactical patterns.
+
+## Strategic Patterns
+
+### Ubiquitous Language
+
+- Code, documentation, and communication all use the same domain terminology
+- If the domain expert calls it an "enrollment," the code calls it `Enrollment`, not `Registration`
+- Language inconsistencies signal a modeling problem
+
+### Bounded Contexts
+
+- Each context owns its own domain model with clear boundaries
+- The same real-world concept may have different representations in different contexts
+- A `Customer` in Billing is not the same model as a `Customer` in Shipping
+
+### Context Mapping
+
+Define explicit relationships between bounded contexts:
+
+| Pattern | When to Use |
+| --- | --- |
+| **Shared Kernel** | Two contexts co-own a small, stable subset of the model |
+| **Anti-Corruption Layer** | Protect your model from a messy or legacy external model |
+| **Customer/Supplier** | Upstream context serves downstream; downstream can negotiate |
+| **Conformist** | Downstream adopts upstream's model as-is (no negotiation power) |
+| **Open Host Service** | Context exposes a well-defined protocol for many consumers |
+| **Published Language** | Shared interchange format (e.g., industry standard schemas) |
+| **Separate Ways** | No integration at all — the cheaper, more honest choice when the cost of integrating two contexts outweighs the benefit |
+
+### Distillation — Find the Core Domain
+
+Not all of the model is equally valuable. Spend your best modeling effort where it earns the most.
+
+- **Core Domain** — the part that makes the business worth doing; your competitive advantage. Assign your strongest people here; invest in supple design.
+- **Generic Subdomains** — necessary but undifferentiated (auth, notifications, currency conversion). Buy, adopt, or build plainly — do not gold-plate.
+- **Supporting Subdomains** — business-specific but not differentiating. Build simply.
+- **Domain Vision Statement** — a short paragraph naming the Core Domain and why it matters. Write it early; it directs investment and prioritization.
+
+Misallocation is the smell: elaborate custom code in a generic subdomain, or an anemic, neglected Core.
+
+## Tactical Patterns
+
+### Aggregates
+
+- Cluster of entities and value objects with a single **aggregate root**
+- All external access goes through the root
+- Enforce consistency boundaries: one transaction = one aggregate
+- Keep aggregates small; reference other aggregates by ID, not by object
+
+### Entities
+
+- Defined by identity, not attributes
+- Two entities with the same attributes but different IDs are different objects
+- Track lifecycle and state changes
+
+### Value Objects
+
+- Defined by attributes, not identity
+- Immutable; equality by value comparison
+- Use for: money, addresses, date ranges, measurements
+
+### Domain Events
+
+- Record that something meaningful happened in the domain
+- Named in past tense: `OrderPlaced`, `PaymentReceived`, `EnrollmentCompleted`
+- Enable cross-context communication and eventual consistency
+- Carry enough data for consumers to act without calling back
+
+### Domain Services
+
+- Operations that don't naturally belong to a single entity or value object
+- Stateless; coordinate across multiple aggregates
+- Example: `TransferFundsService` operating across two `Account` aggregates
+
+### Repositories
+
+- Domain-level abstraction for aggregate persistence
+- Interface defined in the domain/application layer (a port)
+- Implementation lives in the infrastructure/adapter layer
+- One repository per aggregate root
+
+### Factories
+
+- Encapsulate complex creation of an aggregate or value object so the result is **valid and whole** the moment it exists
+- Move construction invariants out of clients and out of overloaded constructors
+- A factory belongs to the domain layer; it produces domain objects, it does not persist them
+- Use when a constructor would have to know too much, or when creation enforces a non-trivial invariant
+- Skip for objects that are valid by simple construction — a factory is overhead there
+
+### Specifications
+
+- Encapsulate a business rule as a first-class predicate object (`OverdueInvoiceSpecification`, `EligibleForDiscountSpecification`)
+- Three uses: **validation** (does this object satisfy the rule?), **selection** (query for objects that match), **construction-to-order** (build an object that satisfies the rule)
+- The tool for **making an implicit concept explicit**: when the same multi-clause boolean appears in several places, that duplicated predicate is a named domain rule wearing a disguise — give it a name and a type
+- Compose specifications (and / or / not) rather than copying the condition
+
+## Making Implicit Concepts Explicit
+
+When a constraint, process, or policy is buried in conditionals and scattered across methods, the model is hiding a concept the domain expert already has a word for. Surface it:
+
+| Hidden as | Surface it as |
+| --- | --- |
+| A repeated multi-clause `if` | A **Specification** or **Policy** object |
+| A constraint enforced ad hoc in setters | An invariant the **entity/aggregate** guards |
+| A multi-step business process in a service method | A named **domain process** or sequence of **domain events** |
+| A primitive that always travels with rules (`int balanceCents`) | A **Value Object** (`Money`) that owns those rules |
+
+## Supple Design
+
+The craft of refactoring toward deeper insight — design that is safe to change because it reveals intent and contains side effects. Apply to the Core Domain especially.
+
+- **Intention-Revealing Interfaces** — name classes and methods for *what* they accomplish, not how; a caller should not need to read the implementation. Boolean flag parameters that switch behavior are a smell.
+- **Side-Effect-Free Functions** — push computation into functions that return results without changing state; keep state changes in a small, obvious set of command methods (command-query separation). Value Objects should expose only side-effect-free operations.
+- **Assertions** — state post-conditions and invariants explicitly (in code or tests) so behavior is guaranteed, not inferred from reading the body.
+- **Conceptual Contours** — factor the model along the domain's own seams so that what changes together lives together; a single conceptual change should touch one place.
+- **Standalone Classes** — drive down dependencies so a class can be understood and tested in isolation; low coupling is the goal, not just clean layering.
+- **Closure of Operations** — where it fits, define operations whose argument and result are the same type (`Money.add(Money) → Money`); they compose without dragging in other concepts.
+
+## Knowledge Crunching & Model-Driven Design
+
+- The model is not designed up front and frozen — it emerges from **continuous collaboration with domain experts**, distilling messy reality into sharp abstractions.
+- **Bind the model to the implementation.** If the code drifts from the model the team talks about, the model is fiction. The same terms, the same relationships, in conversation and in code.
+- Expect **breakthroughs**: periodic refactorings where a better abstraction suddenly clarifies a whole area. Leave room for them; they are the payoff of crunching, not a failure of earlier design.
+
+## When to Apply
+
+| Situation | Approach |
+| --- | --- |
+| Complex, evolving business logic | Full tactical DDD (aggregates, events, services) |
+| Simple CRUD with minimal logic | Skip tactical patterns; use DDD strategically (bounded contexts, ubiquitous language) |
+| Legacy integration | Anti-Corruption Layer to protect new model |
+| Multiple teams / services | Context mapping is essential |
+
+## Steps
+
+### 1. Establish Ubiquitous Language
+
+- Identify domain terms from requirements and stakeholder input
+- Verify code uses the same terms as domain experts
+- Flag language inconsistencies between code, docs, and conversation
+
+### 2. Define Bounded Contexts
+
+- Map each distinct model to its own context with clear boundaries
+- Identify context relationships using context mapping patterns (Shared Kernel, ACL, etc.)
+
+### 3. Distill the Core
+
+- Classify each subdomain as Core, Supporting, or Generic; write a one-paragraph Domain Vision Statement for the Core
+- Direct the strongest modeling effort (and supple design) at the Core; keep Generic subdomains plain
+
+### 4. Select Tactical Patterns
+
+- Determine whether the domain complexity warrants aggregates, entities, value objects, factories, specifications, and domain events
+- For simple CRUD, apply strategic DDD only (contexts + language)
+
+### 5. Validate Model
+
+- Confirm aggregates enforce consistency boundaries (one transaction = one aggregate)
+- Confirm cross-context communication uses domain events, not direct references
+- Confirm repositories exist per aggregate root with interfaces in domain/application layer
+- Confirm objects are valid on creation (constructor or factory), and that named business rules are explicit (specifications/policies), not duplicated conditionals
+
+## Output
+
+Report modeling decisions: bounded contexts identified, aggregate boundaries, context map relationships, and any violations of DDD constraints found in existing code. Be concise — use tables for context maps and violation lists; skip concept narration.
+
+## Constraints
+
+- Do not share aggregate instances across bounded contexts; reference by ID only
+- Do not leak domain model internals through API boundaries
+- Do not apply full tactical DDD to simple CRUD domains
+
+## Guidelines
+
+- Start with strategic DDD (contexts, language) before reaching for tactical patterns
+- Not every service needs aggregates; recognize when simpler models suffice
+- Domain events are the primary mechanism for cross-context communication
+- Aggregates define transaction boundaries, not query boundaries (use read models for queries)
+- Validate ubiquitous language continuously; stale language leads to model drift
+- Reserve supple design (intention-revealing interfaces, side-effect-free functions, specifications) for the Core Domain; over-engineering a generic subdomain is its own smell
+- A repeated multi-clause condition is an implicit concept — name it (specification/policy) rather than copying it

package/skills/exploratory-testing/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: exploratory-testing
+description: Charter-driven exploratory testing — probe a running feature/endpoint with structured heuristics, evaluate charter quality, run adversarial expansion, classify defects, and auto-triage critical findings into an incremental report. Use when the user runs /explore, says "explore this endpoint", "poke at this feature", "find bugs in the running app", or wants hands-off exploratory testing of a live target.
+role: worker
+user-invocable: true
+---
+
+# Exploratory Testing
+
+## Overview
+
+The QA Engineer in charter-driven **"Chaos Specialist"** mode. Given a charter and a running target (endpoint, CLI, feature), it probes with structured heuristics, captures telemetry on every probe, classifies defects, auto-triages critical findings, and writes an incremental report ending with runnable follow-up charters. It is bounded by a **probe budget** so a session always terminates.
+
+Frameworks (charter quality, variable identification, state model, implicit-expectation lenses) live in `knowledge/exploratory-testing-field-guide.md`; this file is the protocol.
+
+## Constraints
+
+- **Probe a running target.** This skill exercises live behavior — it does not read code to reason about bugs (that is `/triage`'s job once a defect is found).
+- **Bounded.** Stop at or before the probe budget (default 15) with a stated reason. Every probe counts.
+- **Incremental.** Append each probe result to the report as it runs — a `/stop` or budget exhaustion must still leave a usable partial report.
+- **Auto-triage critical defects only**, and never fix them — hand off to `/triage`.
+- **Be concise.** Stream one line per probe to chat; the detail lives in the report.
+
+## Parse Arguments
+
+- `--charter '<goal>'` — **required.** Charter format: `Explore [target] with [approach] to discover [concern]`.
+- `--probe-budget <n>` — max probes (default **15**).
+- `--invariants '<expr,...>'` — per-probe invariants to validate; a violation is Critical-immediate.
+- `--no-adversarial` — skip adversarial expansion (on by default).
+- `--force` — proceed past a charter-quality warning without refining.
+- target — the URL/endpoint/command under test (from the charter or an explicit arg).
+
+If `--charter` is absent, do not probe: emit exactly `What should I investigate? Provide a charter: --charter '<goal>'` and stop with no report.
+
+## Steps
+
+### 1. Evaluate charter quality (before any probe)
+
+Check the charter against the anti-patterns in the field guide (§1): too specific (a test case), too broad (infinite scope), missing `with` (no approach), missing `to discover` (no risk hypothesis). On a match, emit a **one-line warning** naming the anti-pattern and prompt: refine the charter, or re-run with `--force`. Do not probe until the charter is acceptable or `--force` is given.
+
+### 2. Reachability pre-flight
+
+Confirm the target responds (a baseline request). If unreachable, write no report and report the target URL plus the connection error. A reachable baseline (the happy path) is **probe 1** and anchors Happy-Path Divergence.
+
+### 3. Plan the probe set (variable identification)
+
+From the field guide (§2), identify what can vary for this target (parameters, values, types, sizes, character sets, combinations). If the charter names an **entity noun** (order, user, account…), include a **CRUD Sweep** (create/read/update/delete + read-after-delete). For permission/role/multi-select fields, include **Goldilocks set-dimension variants** (none / one / some / all / invalid member).
+
+### 4. Probe loop (until budget or `/stop`)
+
+Run heuristics, decrementing the budget per probe. Capture telemetry on **every** probe: probe type, exact input, HTTP status (or exit code), response time, response size, and any captured stderr.
+
+The five heuristics:
+
+| Heuristic | What it does |
+|-----------|--------------|
+| **Goldilocks** | too-small / just-right / too-big for each variable; plus set-dimension variants (none/one/some/all/invalid) for set-valued fields |
+| **Happy-Path Divergence** | start from the confirmed happy path (probe 1), then change one thing at a time and watch for divergence |
+| **Telemetry Deepening** | when a probe is slow / large / noisy, follow it with sharper probes around that variable (perf cliffs, O(n²), truncation) |
+| **Invariant Probing** | if `--invariants` given, assert each after every probe (e.g. balance never negative, count conserved) |
+| **CRUD Sweep** | for entity charters: create → read → update → delete → read-after-delete; watch for orphans, stale reads, double-delete |
+
+**Follow surprises:** when a probe produces an unexpected result, spend the next probes varying that input (field guide §4). **Off-charter temptations** are recorded as follow-up charters (Step 7), not chased now.
+
+### 5. Adversarial expansion (default on; `--no-adversarial` skips)
+
+After the heuristic probes, expand along **3 implicit-expectation lenses** (field guide §5) — pick the 3 most relevant of: authorization bypass, data integrity, timing/ordering, performance-at-scale, crash-resistance — generating **up to 6 angles** total (budget permitting). Label every adversarial probe `adversarial-<lens>` in the report.
+
+### 6. Classify defects + auto-triage
+
+Classify each finding by severity. A **Critical** defect (data corruption, auth bypass, crash, invariant violation) triggers auto-triage:
+
+- Retry the probe **once** to rule out a transient — **except invariant violations**, which are **Critical-immediate** (no retry).
+- If it reproduces (or is invariant-immediate), invoke **`/triage`** with the reproduction. On success, record the returned `triage-record: .dev-team-reports/triage/<slug>.md` path in the report. On triage failure, preserve the reproduction at `tmp/explore-trace-<timestamp>.md` and record that path instead.
+- **No defect → no triage.** Non-critical findings are recorded in the report only.
+
+### 7. Session debrief
+
+When the budget is exhausted or `/stop` is received, stop and state the termination reason (budget reached / charter exhausted / stopped). Finalize the report, ending with a **"Next Exploration"** section: 2–3 runnable follow-up charter strings (off-charter temptations and unfollowed surprises become these).
+
+## Output
+
+Write incrementally to `.dev-team-reports/explore-<YYYYMMDDThhmmss>.md`:
+
+```markdown
+## Exploration — <charter>
+
+**Target**: <url>   **Budget**: <used>/<n>   **Status**: <complete|partial|stopped — reason>
+
+### Probes
+| # | Heuristic | Input | Status | Time | Size | stderr | Finding |
+
+### Defects
+| Severity | Probe # | Summary | Triage |
+(Triage = `.dev-team-reports/triage/<slug>.md` path, or `tmp/explore-trace-<ts>.md` on triage failure)
+
+### Next Exploration
+- `--charter 'Explore … with … to discover …'`
+- `--charter '…'`
+```
+
+The report must contain **≥1 Goldilocks and ≥1 Happy-Path Divergence** entry unless the charter explicitly restricts scope. Write it incrementally so a partial report survives `/stop`.
+
+## Integration
+
+- Invoked by the `/explore` command; runs as the QA Engineer's Chaos Specialist mode.
+- Hands critical defects to `/triage` (which writes `.dev-team-reports/triage/<slug>.md`).
+- Frameworks: `knowledge/exploratory-testing-field-guide.md`. For *test design* (which layer, which double) use `test-design-advisor`; this skill probes running behavior, it does not design a suite.

package/skills/explore/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: explore
+description: >-
+  Charter-driven exploratory testing of a running feature or endpoint. Dispatches
+  the QA Engineer in "Chaos Specialist" mode to probe with structured heuristics
+  (Goldilocks, Happy-Path Divergence, Telemetry Deepening, Invariant Probing,
+  CRUD Sweep), run adversarial expansion, and auto-triage critical defects into an
+  incremental report. Use when the user says "explore this endpoint", "poke at
+  this feature", or wants hands-off exploratory testing of a live target.
+argument-hint: "--charter '<goal>' [target] [--probe-budget <n>] [--invariants '<expr,...>'] [--no-adversarial] [--force]"
+user-invocable: true
+allowed-tools: Read, Grep, Glob, Bash, Write, Skill, Agent
+---
+
+# Explore
+
+Role: worker. This command is a thin entry point: it parses arguments, runs the
+charter-quality + reachability pre-flight, then runs the
+[`exploratory-testing`](../exploratory-testing/SKILL.md) skill as the
+probe loop. It does not probe directly — the skill owns the protocol.
+
+## Worker constraints
+
+1. Probe a **running** target; do not fix anything. Critical defects go to `/triage`.
+2. Stop at or before the probe budget; always leave a usable (possibly partial) report.
+3. **Be concise.** Stream one line per probe to chat; detail lives in the report.
+
+## Parse Arguments
+
+Arguments: $ARGUMENTS
+
+- `--charter '<goal>'` — **required**. `Explore [target] with [approach] to discover [concern]`.
+- `target` — URL/endpoint/command under test (may be implied by the charter).
+- `--probe-budget <n>` — default `15`.
+- `--invariants '<expr,...>'` — per-probe invariants; a violation is Critical-immediate.
+- `--no-adversarial` — skip adversarial expansion (on by default).
+- `--force` — proceed past a charter-quality warning.
+
+If `--charter` is absent, do not probe and do not write a report — emit exactly:
+
+```
+What should I investigate? Provide a charter: --charter '<goal>'
+```
+
+## Steps
+
+1. **Charter quality** — evaluate the charter against the field-guide anti-patterns. On a match, emit a one-line warning and prompt to refine or re-run with `--force`; do not probe until acceptable or forced.
+2. **Reachability** — baseline-request the target. If unreachable, report the URL + error and stop (no report).
+3. **Run the skill** — invoke `exploratory-testing` with the parsed charter, budget, invariants, and flags. It runs the probe loop, adversarial expansion, defect classification, auto-triage, and writes `.dev-team-reports/explore-<YYYYMMDDThhmmss>.md` incrementally — ending with a "Next Exploration" section of 2–3 follow-up charters.
+
+Surface the report path and any triaged defects in chat. On `/stop`, the skill finalizes a partial report.

package/skills/farley-score/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: farley-score
+description: Evaluate test quality using Dave Farley's 8 properties with a weighted Farley Score. Use when reviewing test suites, after writing tests, or when the user says "score my tests", "test quality", "Farley score", or "how good are my tests".
+role: worker
+user-invocable: true
+---
+
+# Farley Score
+
+## Overview
+
+Evaluates test quality using the 8 properties of good tests as described by Andrea Laforgia, based on Dave Farley's testing principles. Produces a quantitative "Farley Score" that teams can track over time.
+
+Attribution: Andrea Laforgia / Dave Farley — properties of good automated tests.
+
+**Locating the tests to score.** Prefer CodeGraph/Repowise over raw
+`Grep`/`Glob` for finding the test files in scope and the production code
+they exercise — grounding "Maintainable" and "Necessary" scores in real
+coupling and call-graph data instead of guessing from test names alone. See
+[`knowledge/codegraph-vs-graphify.md`](../../knowledge/codegraph-vs-graphify.md)
+for tool selection and the fallback contract.
+
+## The 8 Properties
+
+Each property is scored 1-10:
+
+| # | Property | Weight | Description |
+|---|----------|--------|-------------|
+| 1 | **Understandable** | 1.5 | Can a new team member read the test and understand what behavior is verified? Clear names, obvious arrange-act-assert structure, no hidden setup. |
+| 2 | **Maintainable** | 1.5 | Can the test be updated without deep knowledge of the implementation? Minimal coupling to internals, no fragile selectors, uses abstractions (page objects, builders). |
+| 3 | **Repeatable** | 1.2 | Does it produce the same result every time? No time-dependence, no external service calls, no shared mutable state, deterministic data. |
+| 4 | **Atomic** | 1.0 | Does it test exactly one behavior? Single assertion concept (multiple asserts on one object are fine), no test interdependency, independent setup/teardown. |
+| 5 | **Necessary** | 1.0 | Does it verify behavior that matters? Not testing framework code, not duplicating another test, covers a real scenario or edge case. |
+| 6 | **Granular** | 1.0 | Does it fail with a clear, specific message? Pinpoints the failure location, doesn't require debugging to understand what broke. |
+| 7 | **Fast** | 0.8 | Does it run quickly enough for the feedback loop? Unit tests <100ms, integration tests <5s, E2E tests <30s. |
+| 8 | **First** | 1.0 | Was it written before or alongside the implementation (TDD)? Evidence: test commit predates implementation, test names describe behavior not implementation. |
+
+### Scoring anchors — score from evidence, not intuition
+
+Every property score must be justified by a specific line, assertion, or absence you can point to. **A score with no citation is a guess — re-read the test before assigning it.** Use these fixed anchors for every property:
+
+| Band | Meaning | Example |
+|------|---------|---------|
+| 1-2 (Critical) | The property is actively violated | Repeatable scored 2: test calls `Date.now()` with no injected clock |
+| 3-4 (Weak) | A real strength is present, but a violation still dominates | Maintainable scored 4: uses a builder for setup, but an assertion still reaches into a private internal field |
+| 5-6 (Partial) | The property holds in general but has a specific counter-example in this test | Understandable scored 6: AAA structure is clear, but the assertion message is generic (`expect(result).toBeTruthy()`) |
+| 7-8 (Solid) | An affirmative strength is cited, and a specific counter-example — a minor gap, not a violation — keeps it below Exemplary | Granular scored 8: asserts the specific error code, but no message text — a failure still needs the source to interpret why |
+| 9-10 (Exemplary) | No counter-example found AND an affirmative strength cited | Atomic scored 10: exactly one behavior verified, no interdependency with other tests |
+
+**9-10**: no counter-example found AND an affirmative strength cited. **Below 9**: a specific counter-example is required, UNLESS a strength justifies pulling a 1-2 score up into the 3-6 range.
+
+**Property-specific rules that remove the most common ambiguity:**
+
+- **First**: commit history is the primary evidence. When commit history is unavailable (e.g. reviewing a working tree with no VCS access), do not guess a number — fall back to the observable proxy: does the test name describe *behavior* (`should reject invalid email format`) or *mechanism* (`calls validateEmail with a regex`)? Behavior-named tests score 7-8 on this proxy alone (not 9-10 — the proxy is weaker evidence than commit history). If neither commit history nor a readable test name is available, mark the property `Unknown`, drop it from both the numerator and the weight total in the Farley Score formula, and state in the output that it was excluded — never substitute a default (e.g. 5) for missing evidence.
+- **Necessary**: "duplicates another test" must name the specific other test by identifier. Never mark a test not-necessary from a hunch that "something else probably covers this."
+- **Atomic**: multiple assertions on the *same* result object are one behavior, not a violation — do not penalize this pattern (see property description).
+- **Fast**: constructing real, sociable collaborators is not itself a `Fast` defect — score against the stated threshold only, never as grounds to double a collaborator that doesn't meet a blocker (`${CLAUDE_PLUGIN_ROOT}/knowledge/internal-collaborator-doubling.md#the-three-blockers-exhaustive`).
+- **Granular**: a failure surfacing inside a real collaborator's own code, rather than at a mocked boundary, is not itself a `Granular` defect — score the assertion/message clarity, never use it as grounds to double a collaborator that doesn't meet a blocker (`${CLAUDE_PLUGIN_ROOT}/knowledge/internal-collaborator-doubling.md#the-three-blockers-exhaustive`).
+- **Maintainable**: constructing a real collaborator through its public constructor is coupling to its public shape, not "coupling to internals" — never grounds to double a collaborator that doesn't meet a blocker (`${CLAUDE_PLUGIN_ROOT}/knowledge/internal-collaborator-doubling.md#the-three-blockers-exhaustive`).
+
+### Weighting
+
+```
+Farley Score = (sum of property_score × weight) / (sum of weights)
+```
+
+Total weight: 9.0 (or the reduced total when a property is scored `Unknown` per the First rule above — recompute both numerator and denominator without it). Maximum score: 10.0. This produces a 1-10 scale — never multiply by 10 or present it as a percentage.
+
+### Score interpretation
+
+| Range | Rating | Action |
+|-------|--------|--------|
+| 9.0 - 10.0 | Exemplary | Reference test — share as an example |
+| 7.0 - 8.9 | Good | Minor improvements possible |
+| 5.0 - 6.9 | Adequate | Specific improvements recommended |
+| 3.0 - 4.9 | Poor | Significant rework needed |
+| < 3.0 | Critical | Test provides false confidence — fix or delete |
+
+### Suite-level score
+
+Average the per-test scores. Report the distribution (how many Exemplary, Good, etc.).
+
+## Output Format
+
+```markdown
+## Test Quality Report — Farley Score
+
+**Suite**: `path/to/tests/`
+**Tests scored**: 12
+**Suite score**: 7.4 (Good)
+
+### Distribution
+- Exemplary (9+): 2
+- Good (7-8.9): 6
+- Adequate (5-6.9): 3
+- Poor (3-4.9): 1
+
+### Top Issues
+1. **Maintainability** (avg 5.2): 4 tests coupled to implementation details — use behavior-based assertions
+2. **Repeatability** (avg 6.0): 2 tests use `Date.now()` — inject time dependency
+3. **First** (avg 6.5): Test names describe implementation ("calls handleSubmit") not behavior ("submits form data")
+
+### Per-Test Scores (lowest first)
+| Test | Score | Weakest Property | Suggestion |
+|------|-------|-----------------|------------|
+| `should call the API` | 4.2 | Understandable (2) | Rename to describe behavior, not mechanism |
+| `test edge case` | 5.1 | Necessary (3) | Unclear what edge case — specify the condition |
+```
+
+Each row here summarizes one test; the per-property table backing it — every property scored with a citation — is computed the same way as the Worked Example below and must exist even when only this summary row is reported.
+
+## Worked Example
+
+Same test, scored the correct way and an ambiguous way that requires a correction. Use the correct version as the literal template; the incorrect version names the specific defects that made past outputs get redirected.
+
+**Test under review:**
+
+```js
+test('should reject invalid email format', () => {
+  const result = validateEmail('not-an-email');
+  expect(result.isValid).toBe(false);
+  expect(result.error).toBe('INVALID_FORMAT');
+});
+```
+
+### Correct scoring output
+
+```markdown
+| Property | Score | Weight | Citation |
+|----------|-------|--------|----------|
+| Understandable | 9 | 1.5 | Name states the behavior; single arrange-act-assert block, no hidden setup |
+| Maintainable | 8 | 1.5 | Asserts on the public `result` shape, not `validateEmail`'s internals, but the literal `'not-an-email'` input is inlined rather than named — a reader must infer why this string was chosen |
+| Repeatable | 10 | 1.2 | Pure function call — no time, network, or shared state |
+| Atomic | 9 | 1.0 | One behavior (rejecting a bad format); both assertions target the same result object |
+| Necessary | 8 | 1.0 | Real edge case; no other test in the file asserts `INVALID_FORMAT`, but the test doesn't state why this specific malformed string was chosen over other invalid formats |
+| Granular | 8 | 1.0 | Asserts the specific error code, but no message text — a failure still needs the source to interpret why |
+| Fast | 10 | 0.8 | Unit test, no I/O |
+| First | 7 | 1.0 | No commit history available; falling back to the name proxy — behavior-named, so 7-8 per the First rule, not 9-10 |
+
+Farley Score = (9×1.5 + 8×1.5 + 10×1.2 + 9×1.0 + 8×1.0 + 8×1.0 + 10×0.8 + 7×1.0) / 9.0 = 77.5 / 9.0 = **8.6 (Good)**
+
+| Test | Score | Weakest Property | Suggestion |
+|------|-------|-------------------|------------|
+| `should reject invalid email format` | 8.6 | First (7) | Confirm test predates implementation via commit history when available |
+```
+
+### Incorrect / ambiguous scoring output (avoid this)
+
+```markdown
+| Test | Score | Weakest Property | Suggestion |
+|------|-------|-------------------|------------|
+| `should reject invalid email format` | 7 | — | Looks fine overall |
+```
+
+This is exactly the shape that forces a correction, for three concrete reasons:
+
+1. **No per-property breakdown.** For a test scored individually — not summarized in a suite's Per-Test Scores table — a single number with no property scores or citations cannot be audited or reproduced; there is no way to tell if `7` came from the weighted formula or was guessed.
+2. **`Weakest Property` left blank.** The Output Format table requires naming the weakest property so the suggestion is actionable; `—` gives the reader nothing to act on.
+3. **No arithmetic shown.** The correct output's total (77.5 / 9.0 = 8.6) is checkable by re-adding the eight weighted rows; `7` with no visible sum is unverifiable and, per the Scoring anchors rule above, a score with no citation is a guess.
+
+## Integration
+
+- **test-review agent**: Farley Score is computed at orchestrator level (`/test-design` for existing tests, `/build` Step 7 for branch tests) — not invoked directly from test-review.
+- **QA Engineer agent**: Uses Farley Score in quality reports
+- **Mutation testing skill**: Farley Score complements mutation score — high Farley + low mutation = assertions too weak

package/skills/feature-file-validation/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: feature-file-validation
+description: >-
+  Validate Gherkin feature files for structural quality, determinism, and
+  implementation independence, then verify each scenario has matching test
+  automation. Use this skill whenever reviewing test files, feature files, or
+  BDD scenarios — including during /code-review when .feature files or step
+  definition files appear in the changeset. Also use when a user asks to
+  "check my feature files", "validate my Gherkin", "are my scenarios
+  testable", or "do my feature files have tests".
+role: worker
+user-invocable: true
+---
+
+# Feature File Validation
+
+Feature files are the contract between intent and implementation. This skill validates two things: (1) are scenarios well-formed, deterministic, and behavioral? (2) does every scenario have matching test automation?
+
+## When to Run
+
+- During `/code-review` when `.feature` or step definition files are in the changeset
+- When `test-review` encounters feature files
+- When a user explicitly asks to validate feature files or BDD scenarios
+- Before `/build` as a pre-flight check
+
+## Step 1: Find Feature Files
+
+Locate all `.feature` files in scope. If reviewing changed files only, limit to `.feature` files in the changeset plus any referenced by changed step definitions. If none found, report skip and stop.
+
+## Step 2: Validate Feature File Structure
+
+For each feature file, check every category below. Read `references/validation-rules.md` for detailed patterns and examples.
+
+| Category | What to flag | Severity |
+|----------|-------------|----------|
+| **Gherkin syntax** | Missing Given/When/Then, bad Background, empty Examples, orphan steps, blank feature name | warning |
+| **Determinism** | Time-dependent steps, order-dependent scenarios, environment-dependent steps, probabilistic assertions, uncontrolled concurrency | error |
+| **Implementation coupling** | Technology names, code-level details, CSS selectors, performance constraints, data structure specifics in step text | warning |
+| **Scenario quality** | Multiple When steps, vague assertions ("it works"), missing negative/edge cases | warning/suggestion |
+
+## Step 3: Verify Test Automation Coverage
+
+For each scenario, check whether test automation exists using two strategies. A match from either is sufficient. Read `references/validation-rules.md` for framework detection patterns and naming conventions.
+
+- **Strategy A — Step definition matching**: Find step definition files (per framework conventions) whose patterns match the scenario's step text. Covered when all steps have definitions.
+- **Strategy B — Test file naming**: Find test files named after the feature file (e.g., `login.feature` -> `login.test.ts`) that reference the scenario name.
+
+**Graph-assisted lookup.** Prefer CodeGraph/Repowise over raw `Grep`/`Glob` for locating step definition files and matching test files under either strategy — see [`knowledge/codegraph-vs-graphify.md`](../../knowledge/codegraph-vs-graphify.md) for tool selection and the fallback contract.
+
+Report per feature file: total scenarios, covered, uncovered, partially covered.
+
+## Step 4: Output
+
+```json
+{
+  "status": "pass|warn|fail",
+  "issues": [
+    {
+      "severity": "error|warning|suggestion",
+      "confidence": "high|medium|none",
+      "file": "features/login.feature",
+      "line": 12,
+      "message": "Description of the issue",
+      "category": "determinism|implementation-coupling|structure|coverage",
+      "suggestedFix": "How to fix it"
+    }
+  ],
+  "coverage": {
+    "total_scenarios": 0,
+    "covered": 0,
+    "uncovered": 0,
+    "partial": 0
+  },
+  "summary": "One-line summary"
+}
+```
+
+Severity and confidence mappings are in `references/validation-rules.md`.