Stats
Actions
Tags
From jerry
Generates Gherkin BDD feature files from structured use case flows using Clark's UC2.0-to-Gherkin algorithm. Analyzes test coverage completeness against use case steps.
How this skill is triggered — by the user, by Claude, or both
Slash command
/jerry:test-specThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
> **Version:** 1.0.0 | **Framework:** Jerry Framework | **Constitutional compliance:** P-003 (no recursive subagents), P-020 (user authority), P-022 (no deception)
agents/tspec-analyst.governance.yamlagents/tspec-analyst.mdagents/tspec-generator.governance.yamlagents/tspec-generator.mdcomposition/tspec-analyst.agent.yamlcomposition/tspec-analyst.prompt.mdcomposition/tspec-generator.agent.yamlcomposition/tspec-generator.prompt.mdrules/clark-transformation-rules.mdsamples/sample-test-specification.mdtemplates/bdd-scenario.template.mdtemplates/test-plan.template.mdtests/BEHAVIOR_TESTS.mdVersion: 1.0.0 | Framework: Jerry Framework | Constitutional compliance: P-003 (no recursive subagents), P-020 (user authority), P-022 (no deception) Status: PROPOSED | Author: eng-backend | Date: 2026-03-09
| Section | Purpose |
|---|---|
| Document Audience | Who reads which sections |
| Purpose | What this skill does and key capabilities |
| When to Use | Activation conditions and anti-patterns |
| Available Agents | Agent routing table with decision signals |
| P-003 Agent Topology | ASCII hierarchy diagram (multi-agent required) |
| Invoking an Agent | Three invocation modes |
| Clark Transformation Reference | Domain methodology summary |
| Input Requirements | Use case artifact prerequisites |
| Output Artifacts | Feature file and coverage report formats |
| Integration Points | Cross-skill connections |
| Routing Entry (Priority 14) | Trigger map entry for mandatory-skill-usage.md |
| Constitutional Compliance | Principle-to-agent mapping |
| Quick Reference | Common workflows and agent selection |
| References | File paths and external citations |
| Level | Audience | Sections |
|---|---|---|
| L0 | Stakeholders, project managers | Purpose, When to Use, Quick Reference |
| L1 | Developers, QA engineers using the skill | Available Agents, Invoking an Agent, Clark Transformation Reference, Input Requirements, Output Artifacts |
| L2 | Framework maintainers, reviewers | P-003 Agent Topology, Integration Points, Constitutional Compliance, References |
The /test-spec skill transforms structured use case artifacts produced by /use-case into BDD Gherkin test specifications using Clark's (2018) UC2.0-to-Gherkin deterministic mapping algorithm. It closes the gap between use case specifications and testable acceptance criteria.
Key Capabilities:
Activate this skill when:
NEVER invoke this skill when:
/test-spec agents do not implement Cockburn's writing methodology; they consume use case output, not produce it; use /use-case instead./test-spec produces Gherkin BDD scenarios, not OpenAPI specifications; use /contract-design instead./test-spec produces human-readable BDD specifications, not executable test code; write tests directly or use /eng-team for test implementation guidance./adversary for quality scoring and adversarial critique./use-case to elaborate first.| Agent | Role | Model | Cognitive Mode | Tool Tier | Output Location | Decision Signal |
|---|---|---|---|---|---|---|
tspec-generator | Transforms use case flows into Gherkin BDD scenarios using Clark algorithm | sonnet | systematic | T2 | projects/${JERRY_PROJECT}/test-specs/UC-{DOMAIN}-{NNN}-{slug}.feature.md | "generate", "transform", "create feature file", "map to Gherkin", "BDD from use case", "Clark" |
tspec-analyst | Analyzes test coverage completeness against use case flows using 7 Cs framework | sonnet | convergent | T2 | projects/${JERRY_PROJECT}/test-specs/UC-{DOMAIN}-{NNN}-{slug}-coverage.md | "coverage", "analyze coverage", "coverage gap", "missing scenarios", "completeness check", "7 Cs" |
Default routing: When intent is ambiguous between generation and analysis, route to tspec-generator first. Generation must precede coverage analysis. When the user says "generate and check coverage," invoke tspec-generator first, then tspec-analyst on the output.
Both tspec-generator and tspec-analyst are T2 worker agents. They are invoked independently from MAIN CONTEXT. They do NOT invoke each other. The output of tspec-generator (Feature file on disk) is consumed by tspec-analyst via the filesystem -- not via direct agent-to-agent communication.
MAIN CONTEXT (orchestrator)
|
+-- tspec-generator (T2 worker) -- via Task tool
| Reads: UC artifact (.md with YAML frontmatter)
| docs/schemas/use-case-realization-v1.schema.json
| skills/test-spec/rules/clark-transformation-rules.md
| Writes: Feature file (.feature.md)
| Optional: test plan (-test-plan.md)
|
+-- tspec-analyst (T2 worker) -- via Task tool
Reads: Feature file (.feature.md) -- produced by tspec-generator
UC artifact (.md) -- same source artifact
Writes: Coverage report (-coverage.md)
Workers do NOT invoke each other.
tspec-generator output (Feature file) is consumed by tspec-analyst via filesystem.
Cross-agent data flow is mediated by shared artifact files on disk (P-003 compliant).
Generate BDD scenarios from use case UC-AUTH-001.
Analyze test coverage for the Feature file at
projects/PROJ-021/test-specs/UC-AUTH-001-validate-credentials.feature.md
against the source use case.
Use tspec-generator to transform UC-AUTH-001 from
projects/PROJ-021/use-cases/UC-AUTH-001-validate-credentials.md
into a Gherkin Feature file.
Use tspec-analyst to produce a coverage report for
UC-AUTH-001-validate-credentials.feature.md.
# Invoke tspec-generator via Task tool
task:
agent: skills/test-spec/composition/tspec-generator.agent.yaml
prompt: |
Transform use case at projects/PROJ-021/use-cases/UC-AUTH-001-validate-credentials.md
into a Gherkin Feature file. Output path:
projects/PROJ-021/test-specs/UC-AUTH-001-validate-credentials.feature.md
# Invoke tspec-analyst via Task tool
task:
agent: skills/test-spec/composition/tspec-analyst.agent.yaml
prompt: |
Analyze coverage for:
Feature file: projects/PROJ-021/test-specs/UC-AUTH-001-validate-credentials.feature.md
Source UC: projects/PROJ-021/use-cases/UC-AUTH-001-validate-credentials.md
Output coverage report to:
projects/PROJ-021/test-specs/UC-AUTH-001-validate-credentials-coverage.md
Clark's (2018) UC2.0-to-Gherkin algorithm provides a deterministic mapping from use case structure to Gherkin Feature file structure. Full rules are in skills/test-spec/rules/clark-transformation-rules.md.
| Use Case Element | JSON Path | Gherkin Element | Cardinality | Rule |
|---|---|---|---|---|
| Title | $.title | Feature name | 1:1 | RULE-C2-01 |
| Primary actor | $.primary_actor | "As a" narrative | 1:1 | RULE-C2-01 |
| Preconditions | $.preconditions[*] | Given clauses | 1:N | RULE-C6-01 |
| Trigger | $.trigger | First When clause | 1:1 | RULE-C3-01 |
| Basic flow (actor_action steps) | $.basic_flow[*] type=actor_action | When clauses | 1:N | RULE-ST-01 |
| Basic flow (system_response steps) | $.basic_flow[*] type=system_response | Then clauses | 1:N | RULE-ST-02 |
| Basic flow (validation steps) | $.basic_flow[*] type=validation | Then assertion clauses | 1:N | RULE-ST-03 |
| Success postconditions | $.postconditions.success[*] | Final Then clauses | 1:N | RULE-C3-01 |
| Alternative flows | $.alternative_flows[*] | Additional Scenario (1 each) | 1:1 | RULE-C4-01 |
| Extensions (failure) | $.extensions[*] outcome=failure | Negative test Scenario | 1:1 | RULE-OT-01 |
| Extensions (success) | $.extensions[*] outcome=success | Alternate success Scenario | 1:1 | RULE-OT-02 |
| Extensions (rejoin) | $.extensions[*] outcome=rejoin:{N} | Rejoin Scenario to step N | 1:1 | RULE-OT-03 |
| Criterion | Assessment |
|---|---|
| C1: Coverage | Primary -- mapped_scenarios / total_mappable_flows |
| C2: Correctness | Each scenario traces to correct source elements |
| C3: Clarity | Declarative language; no implementation specifics |
| C4: Consistent Abstraction | Uniform abstraction level across Feature file |
| C5: Consistent Structure | All scenarios follow Given-When-Then |
| C6: Completeness of Detail | All preconditions and postconditions included |
| C7: Conciseness | No duplicates; no redundant steps |
Use case artifact must satisfy ALL of the following (enforced by two-layer validation gate):
| Requirement | Field | Validation Layer |
|---|---|---|
$.work_type = USE_CASE | Discriminator | Agent guardrail (Layer 2) |
$.detail_level >= ESSENTIAL_OUTLINE | detail_level | Agent guardrail (Layer 2) |
$.basic_flow has 3-9 steps | basic_flow | Schema (Layer 1) |
Each $.basic_flow[*] has .type field | basic_flow[*].type | Schema (Layer 1) |
$.extensions non-empty (1+ entries) | extensions | Agent guardrail (Layer 2) |
$.preconditions[*] -- enables Given clauses grounded in system state$.postconditions.success[*] -- enables Then clauses grounded in outcomes$.trigger -- enables first When clause grounded in initiating event$.alternative_flows[*] -- enables alternative scenario generationprojects/${JERRY_PROJECT}/test-specs/UC-{DOMAIN}-{NNN}-{slug}.feature.mdprojects/${JERRY_PROJECT}/use-cases/UC-{DOMAIN}-{NNN}-{slug}.mdPath: projects/${JERRY_PROJECT}/test-specs/UC-{DOMAIN}-{NNN}-{slug}.feature.md
Format: YAML frontmatter + Gherkin Feature content in Markdown sections
Schema: docs/schemas/test-specification-v1.schema.json
Template: skills/test-spec/templates/bdd-scenario.template.md
The .feature.md extension indicates "Gherkin content in a Markdown container with YAML frontmatter." This enables traceability metadata (source_use_case, generated_by, coverage snapshot) that standard .feature files cannot carry.
Path: projects/${JERRY_PROJECT}/test-specs/UC-{DOMAIN}-{NNN}-{slug}-coverage.md
Format: Markdown with L0/L1/L2 sections
Template: skills/test-spec/templates/test-plan.template.md
| Integration | Direction | Mechanism | Pre-Condition |
|---|---|---|---|
/use-case to /test-spec | tspec-generator reads UC artifact produced by uc-author or uc-slicer | Shared artifact file validated against docs/schemas/use-case-realization-v1.schema.json | $.detail_level >= ESSENTIAL_OUTLINE, $.extensions non-empty, $.basic_flow[*].type present |
/test-spec to /worktracker | tspec-analyst may update worktracker with coverage metrics | Bash + uv run jerry items update (H-05 compliant; MUST NOT invoke /worktracker via Task -- P-003) | Feature file exists with traceable scenario IDs |
/test-spec output consumed by implementers | Feature files serve as acceptance criteria for implementation | Human-readable .feature.md files in projects/${JERRY_PROJECT}/test-specs/ | Scenarios verified by tspec-analyst coverage check |
/test-spec parallel to /contract-design | Both are independent consumers of /use-case output | File-mediated -- both read the same UC artifact; neither depends on the other | UC artifact at ESSENTIAL_OUTLINE or FULLY_DESCRIBED |
Per agent-routing-standards.md enhanced 5-column trigger map format. Registration in mandatory-skill-usage.md is complete.
| Detected Keywords | Negative Keywords | Priority | Compound Triggers | Skill |
|---|---|---|---|---|
| test spec, test-spec, test specification, BDD, BDD scenario, Gherkin, feature file, Given When Then, generate tests, Clark transformation, test coverage, test plan, scenario mapping, happy path scenario, error scenario, use case to test | requirements specification, V&V, technical review, use case authoring, write use case, create use case, OpenAPI, contract, API design, adversarial, tournament, transcript, penetration, exploit, code review, documentation, tutorial, unit test, pytest, integration test | 14 | "generate tests from use case" OR "BDD scenario" OR "feature file" OR "test specification" OR "test coverage analysis" OR "use case to test" (phrase match) | /test-spec |
Disambiguation: "test" keyword. "test" alone is excluded from positive keywords -- it is ambiguous between unit tests, adversarial testing, and BDD specification. Compound triggers require qualification ("BDD scenario", "feature file", "test specification") to route to /test-spec.
| Principle | Application |
|---|---|
| P-001 (Truth/Accuracy) | Every generated scenario must trace to a source flow element. tspec-generator does not invent scenarios. |
| P-002 (File Persistence) | All outputs persisted to files: Feature files and coverage reports written to projects/${JERRY_PROJECT}/test-specs/. |
| P-003 (No Recursive Subagents) | tspec-generator and tspec-analyst are T2 worker agents. Neither has Task tool access. Neither invokes the other directly. |
| P-004 (Provenance) | Feature file YAML frontmatter carries source_use_case, generated_by, generated_at for full audit trail. |
| P-020 (User Authority) | tspec-generator does not override user decisions about scenario scope. tspec-analyst does not override user decisions about coverage thresholds. |
| P-022 (No Deception) | tspec-generator explicitly reports unmapped flows. tspec-analyst reports mathematically verifiable coverage percentages with numerator and denominator. |
| Workflow | Agent Sequence | Typical Duration |
|---|---|---|
| Generate BDD specs from UC | tspec-generator (single invocation) | 1-2 minutes |
| Generate + verify coverage | tspec-generator then tspec-analyst | 2-4 minutes |
| Coverage-only check (FF already exists) | tspec-analyst (single invocation) | 1-2 minutes |
| Slice-scoped generation | tspec-generator with slice_id parameter | 1-2 minutes |
| Full pipeline: UC to verified test specs | /use-case (uc-author) -> tspec-generator -> tspec-analyst | 5-10 minutes |
| Signal | Route to |
|---|---|
| "Generate", "create", "transform", "make BDD scenarios" | tspec-generator |
| "Coverage", "analyze", "check completeness", "gaps", "missing" | tspec-analyst |
| Ambiguous intent | tspec-generator first (generation must precede analysis) |
| "Generate and check coverage" | tspec-generator, then tspec-analyst on output |
Before invoking tspec-generator, verify your use case artifact has:
detail_level: ESSENTIAL_OUTLINE or FULLY_DESCRIBEDextensions: array with at least 1 entrybasic_flow: with 3-9 stepstype: field (actor_action, system_response, or validation)| File | Purpose |
|---|---|
skills/test-spec/agents/tspec-generator.md | tspec-generator agent definition |
skills/test-spec/agents/tspec-generator.governance.yaml | tspec-generator governance metadata |
skills/test-spec/agents/tspec-analyst.md | tspec-analyst agent definition |
skills/test-spec/agents/tspec-analyst.governance.yaml | tspec-analyst governance metadata |
skills/test-spec/composition/tspec-generator.agent.yaml | tspec-generator canonical agent YAML (Task invocation) |
skills/test-spec/composition/tspec-generator.prompt.md | tspec-generator system prompt copy |
skills/test-spec/composition/tspec-analyst.agent.yaml | tspec-analyst canonical agent YAML (Task invocation) |
skills/test-spec/composition/tspec-analyst.prompt.md | tspec-analyst system prompt copy |
skills/test-spec/rules/clark-transformation-rules.md | Clark (2018) mapping algorithm as imperative rules |
skills/test-spec/templates/bdd-scenario.template.md | Feature file output template |
skills/test-spec/templates/test-plan.template.md | Test plan output template |
skills/test-spec/tests/BEHAVIOR_TESTS.md | BDD behavior test scenarios for the skill |
skills/test-spec/samples/sample-test-specification.md | Sample Feature file demonstrating the skill output |
docs/schemas/test-specification-v1.schema.json | JSON Schema for Feature file YAML frontmatter |
docs/schemas/use-case-realization-v1.schema.json | JSON Schema for input use case artifacts |
| Clark (2018) | Clark, T. D. (2018). Generating BDD Test Scenarios from Use Case Specifications. ICSTW 2018. |
Skill Version: 1.0.0 | Framework: Jerry Framework | Constitutional compliance: P-003, P-020, P-022 Author: eng-backend | Date: 2026-03-09 | Status: ACTIVE SSOT:
projects/PROJ-021-use-case/orchestration/use-case-skills-20260308-001/implementation/step-10-test-spec-architecture.md
npx claudepluginhub geekatron/jerry --plugin jerryGenerates BDD/Gherkin test cases from acceptance criteria using ISTQB techniques (equivalence partitioning, BVA, decision tables). Supports direct text, PRD files, Jira stories, and OpenAPI contracts.
Guides writing BDD scenarios in Gherkin with acceptance criteria, edge cases, tags, and organization. Use for defining behavior specs, test coverage, and requirements.
Generates Gherkin BDD .feature files from spec acceptance criteria. Automatically invoked by cw-spec to produce behavioral scenarios per demoable unit.