npx claudepluginhub geekatron/jerry --plugin jerryThis skill is limited to using the following tools:
> **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.mdCreates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Version: 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