test-design
/test-design
Designs test cases for User Stories on the configured tracker — Azure DevOps or Jira Cloud: analyze a story's acceptance criteria into test conditions, map them to test case titles, create the test artifacts (ADO Test Cases with structured steps, or the Jira issue type the user chooses — Jira has no native Test Case type) and link them to the parent story, behind ONE consolidated approval. Use this skill whenever the user wants to: - Analyze a user story and identify test conditions - Map AC scenarios to test case titles using a naming convention - Create test cases in ADO with proper steps, o
- Author
- mhmdelgazzar ↗
- Repository
- agentex ↗
- Licence
- MIT
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 7
- Scripts
- 4
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 4 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/create-cases.js, scripts/create-cases.test.js, scripts/testplan.js, scripts/testplan.test.js
What it does and when to use it
Designs test cases for User Stories on the configured tracker — Azure DevOps or Jira Cloud: analyze a story's acceptance criteria into test conditions, map them to test case titles, create the test artifacts (ADO Test Cases with structured steps, or the Jira issue type the user chooses — Jira has no native Test Case type) and link them to the parent story, behind ONE consolidated approval. Use this skill whenever the user wants to: - Analyze a user story and identify test conditions - Map AC scenarios to test case titles using a naming convention - Create test cases in ADO with proper steps, o
Original author description
Designs test cases for User Stories on the configured tracker — Azure DevOps or Jira Cloud: analyze a story's acceptance criteria into test conditions, map them to test case titles, create the test artifacts (ADO Test Cases with structured steps, or the Jira issue type the user chooses — Jira has no native Test Case type) and link them to the parent story, behind ONE consolidated approval. Use this skill whenever the user wants to: - Analyze a user story and identify test conditions - Map AC scenarios to test case titles using a naming convention - Create test cases in ADO with proper steps, o
How it works
- Role
- Configuration (never hardcode)
- Project conventions file
- On Jira — the artifact question comes first (Q11)
- Step 1 — Fetch the User Story
- Step 2 — Identify Test Conditions
- Step 3 — Determine the Feature
- Step 4 — Title Convention
- Step 5 — Test Case Steps
- Step 6 — Validate, one screen, ONE approval
SKILL.md preview
---
name: test-design
description: >
Designs test cases for User Stories on the configured tracker — Azure DevOps or Jira Cloud:
analyze a story's acceptance criteria into test conditions, map them to test case titles,
create the test artifacts (ADO Test Cases with structured steps, or the Jira issue type the
user chooses — Jira has no native Test Case type) and link them to the parent story, behind
ONE consolidated approval. Use this skill whenever the user wants to:
- Analyze a user story and identify test conditions
- Map AC scenarios to test case titles using a naming convention
- Create test cases in ADO with proper steps, or design test cases for a Jira story
- Review whether a story's ACs are fully covered by test cases
Trigger on phrases like: "create test cases for story", "design tests for", "design test
cases for a Jira story", "what test cases do I need", "analyze story for testing", "map ACs
to test conditions", or any time a user story ID or Jira issue key is mentioned alongside
test design/coverage work.
---
# Test Design — Azure DevOps or Jira
## Role
You turn a User Story's acceptance criteria into structured test artifacts on the configured
tracker (Azure DevOps test cases, or the Jira issue type the user chooses), linked back to
the story. You never write to the board without the single consolidated approval described
below.
End-to-end methodology for designing, creating, and linking test cases to User Stories on
the **configured tracker**. This file is the **workflow** (how to analyze ACs, what test
cases to derive, the one approval gate). The mechanics live in the bundled scripts — never
run `az` or `acli`, and never compose REST calls for board operations:
- **`${CLAUDE_PLUGIN_ROOT}/skills/test-design/scripts/create-cases.js`** — the story read and
the test-case creation/linking (dry run by default, `--execute` behind the one approval;
the script builds the Steps XML from structured steps on ADO, or ADF step lists on Jira,
and picks the configured provider itself). Read
**`${CLAUDE_PLUGIN_ROOT}/skills/test-design/references/test-case-mechanics.md`** for the
spec shape, XML doctrine, and failure paths before the first spec of a session.
- **`${CLAUDE_PLUGIN_ROOT}/references/tracker/ado-boards.md`** — shared ADO boards knowledge:
field reference names, relation directions, the Test-Case no-delete constraint.
- **`${CLAUDE_PLUGIN_ROOT}/references/tracker/jira-boards.md`** — the Jira twin: field ids,
ADF, link semantics, known limitations (no test plans/runs, no Tested-By).
- **`${CLAUDE_PLUGIN_ROOT}/skills/test-design/scripts/testplan.js`** — test-plan mechanics
(list-suites / list-cases / find-case / create-case / fail), a separate concern with the
same conventions; the bug-report-azure skill invokes it cross-skill. **ADO only**: on a
Jira-configured project it refuses upfront (exit 2, `testPlans:false` — Jira has no
test-plan/run APIs).
## Configuration (never hardcode)
Org/site, project, and assignee resolve from `config/project.json` — the `azure` block on
ADO (legacy `AZURE_*` keys in `.env` as fallback) or the `jira` block on Jira — the scripts
read them themselves, and the credentials (`AZURE_PAT`, or `JIRA_EMAIL` + `JIRA_API_TOKEN`,
in `.env`) never leave them: Authorization header only, never printed or on a command line.
Never bake an organization, site, project, team, or email into anything. Anything genuinely
missing joins the ONE bundled question round below.
## Project conventions file
Everything that varies per project lives in the **consumer project**, not in this skill:
persona, feature map, standard setup steps, project-specific condition categories, and
the languages text checks must cover.
- Look for **`./.agentex/test-template.md`** in the current project and read it before
designing anything.
- If it doesn't exist, offer to scaffold it: create the `./.agentex/` folder if needed and
copy `${CLAUDE_PLUGIN_ROOT}/skills/test-design/templates/test-template.md` there, then ask
the user to fill in (or dictate) the values before proceeding. (A consumer-file write with
its own consent — it happens before any board work and is outside the board-write gate.)
- If a needed convention is missing from the file, that question joins the one bundled round
— do not guess.
## On Jira — the artifact question comes first (Q11)
Jira has no native Test Case type and no Tested-By link. On a Jira-configured project,
**before any spec is built**: inform the user of exactly that, and ask **what to create** —
in the ONE bundled round, never silently substituted. The options are the **project's real
issue types** (the dry run surfaces them: a spec without `artifactType` blocks with
`missing-artifact-type` carrying the live list, sub-task types marked), plus **"document
only / skip creation"** (deliver the conditions table and titled cases as text, zero board
writes). The chosen type goes into the spec as `artifactType` — the script never defaults
it, and validates it against the real types.
The choice can be **pinned** in `./.agentex/test-template.md` under a `## Jira` section
(e.g. `artifactType: Task`, `linkType: Relates`) — a consumer-owned convention, so later
runs skip the ask. A pinned value still shows on the consolidated screen.
Mechanical deltas the script owns (details in
`${CLAUDE_PLUGIN_ROOT}/references/tracker/jira-boards.md`):
- Steps render as an **ADF ordered list** (action → expected) in the artifact's
description — same structured `{type, text, expected}` spec steps, no XML.
- **Linking is a separate write**: no Tested-By exists, so the artifact links back to the
story via the configured/chosen issue link type (`jira.bugLinkType`, spec `linkType`, or
the bundled ask — `Relates` recommended). The plan shows create + link as two intents per
case; a sub-task artifact type instead rides `fields.parent` inside the create (no link
intent).
- The assignee email resolves to an accountId at validation time (shown on the screen);
unresolvable/ambiguous blocks — never assigned blind.
- No server-side `validateOnly` exists on Jira — the createmeta field cache carries
pre-gate validation, and the plan says `validateOnly: 'unsupported-on-jira'` so the
consolidated screen is honest about what was proven.
- Coverage check closes the loop as on ADO: map every AC to a created artifact from the
ledger and re-read the story (free read) to show the links landed.
## Step 1 — Fetch the User Story
```bash
node ${CLAUDE_PLUGIN_ROOT}/skills/test-design/scripts/create-cases.js story --id <STORY_ID>
```
Read the description + acceptance criteria from the JSON (HTML — extract any design link,
e.g. Figma, and translation tables from the tags yourself).
## Step 2 — Identify Test Conditions
Group the ACs into **test conditions**. Each test condition maps to ONE test case.
### Generic condition categories
| AC Content | Test Condition → Test Case Title |
|---|---|
| UI structure, layout, icons, design reference | `user checks the page UI` |
| All text labels, titles, subtitles (every supported language) | `user checks the page text` |
| Button click with action/navigation result | `user checks the [button name] functionality` |
| Valid input values accepted | `user checks valid input` |
| Invalid input (empty, special chars, wrong type, spaces) | `user checks invalid input` |
| Dropdown / selection logic | `user checks [dropdown name] selection` |
| Error / validation messages | `user checks the [feature] error message` |
| Counter/summary values | typically included in the UI check |
The conventions file may add project-specific categories (e.g. a helper panel, a read-only
info section) — treat each as its own test case whenever the story includes that element.
### Rules for identifying conditions
1. **One test case per condition** — never merge two conditions into one test case.
2. **Text is always separate from UI** — even a one-scenario story gets its own text test case.
3. **Each button gets its own test case** — e.g. Next and Back are separate.
4. **No inputs in the story? No input test cases** — only create what the AC specifies.
5. **Out-of-scope items** — if the AC says "handled separately" / "out of scope", do NOT
create a test case for it.
6. **Conventions-file categories** — always a separate test case when the story includes that
element.
The mapped conditions table (with a "covers" column) is presented **on the consolidated
screen** (Step 6) — not as its own confirmation round.
## Step 3 — Determine the Feature
Each title includes the feature the story belongs to. A feature can be a step in a flow
(e.g. `Step5`) but not always — it can also be any feature name (e.g. `Login`). Read the
feature map from the conventions file; if the story isn't in the map, infer from the
story's context — or add the question to the one bundled round.
## Step 4 — Title Convention
```
<Persona> || <Feature> || [test condition]
```
- **Persona** comes from the conventions file (e.g. `SME User`).
- Feature comes from the feature map (a flow step like `Step5`, or a feature name — not the story ID).
- Test condition is lowercase, no punctuation at the end, no quotes around it.
Examples (with persona "SME User"): `SME User || Step5 || user checks the page UI`,
`SME User || Login || user checks the page UI`
## Step 5 — Test Case Steps
Every test case = the standard setup ActionSteps (from the conventions file, adjusted to the
prerequisites of the story's step) followed by ValidateSteps for the condition:
- **page UI** — open the story's design link (include it as an ActionStep so testers know the
reference); verify stepper/header/content/buttons/side panels/spacing against the design.
- **page text** — one validate step per label per supported language (from conventions).
- **[button] functionality** — default state, click, expected outcome (navigation or error, in
every supported language), and that the user stays/moves as expected.
- **valid input** — per field: enter a valid value → accepted.
- **invalid input** — per field: empty, special characters, unsupported type, leading/trailing
spaces → error shown.
- **Conventions-file categories** — per the checks the conventions file defines for them.
You write step *content* as structured JSON (`{type, text, expected}` — see the mechanics
reference); the script owns the XML, IDs, and escaping.
## Step 6 — Validate, one screen, ONE approval
**Bundled input round (only if needed):** anything genuinely unresolvable — a feature not in
the map, a persona missing because the conventions file is incomplete, no assignee anywhere —
is asked in ONE AskUserQuestion **before** validation, never as a series of asks. When the
conventions file + config answer everything, the approval is the only interaction.
1. Build the spec (`storyId`, `assignee`, `cases` with structured steps), write it to
`.agentex/scratch/cases.json` — intermediate files go **only** in `.agentex/scratch/`
(create the folder if it is missing; it is gitignored agent scratch), never anywhere else
in the project — and dry-run:
```bash
node …/create-cases.js --spec ".agentex/scratch/cases.json" [--allow-duplicate]
```
Exit 2 = blocked: surface the reasons (duplicate Test Case IDs, bad steps, stale-cache
options with a `--refresh-fields` offer), correct for the run, re-run — a failure-path
round, not a second gate.
2. Render **the consolidated screen**: the conditions table (with its "covers" column and
"is anything missing?" framed as part of this one screen), the titled cases with a
per-case step summary, the duplicate-check results, and **the exact write plan** (one
atomic create per case — Tested By inline on ADO; on Jira the chosen artifact type with
its create + link intents — routes listed) — plus the explicit statement
that **nothing has been written yet**. Additions/removals edit the spec and re-run the
dry run; the corrected screen still ends in exactly one approval.
3. **One approval** → re-run with `--execute`. Anything else → stop, zero writes.
## Step 7 — Report from the ledger
Every intended case done (ID + URL) or not-done (reason), straight from the script's ledger.
On ADO, linking happened inside each create (`TestedBy-Reverse` → story), so there is no
separate link step to verify or forget; on Jira the story link is its own ledgered write —
report its state per case. A partial failure is a **failure** — name exactly which cases
now exist; no retry, no cleanup (ADO Test Cases can't be deleted via the API, and Jira's
only delete is permanent and never offered — portal cleanup is the user's call).
## Step 8 — Coverage Check
Map every AC scenario to a created test case **from the ledger**, re-read the story
(`story --id <id>` — a free read) to show the Tested By links landed, and show the table.
Flag anything uncovered and ask whether to add a test case for it (a new spec → a new gate).
## Common Mistakes to Avoid
- ❌ Creating a test case for something the AC marks "handled separately" / out of scope
- ❌ Merging text and UI into one test case
- ❌ Creating input test cases when the story has no input fields
- ❌ Skipping non-primary-language text checks when the project is multilingual
- ❌ Using a feature that doesn't match the feature map
- ❌ Asking the condition-table question and the approval as two separate rounds — they are
ONE screen, one approval
- ❌ Running `az` or composing REST calls for board operations — the scripts own transport
and auth (and the old XML/quoting/link-direction mistakes died with them)
Files in this package (7)
- SKILL.md 13 KB
- references/test-case-mechanics.md 6 KB
- scripts/create-cases.js 34 KB
- scripts/create-cases.test.js 34 KB
- scripts/testplan.js 16 KB
- scripts/testplan.test.js 20 KB
- templates/test-template.md 2 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · mhmdelgazzar/agentex | 100 | MIT |
| bdfinst/agentic-dev-team | 100 | MIT |
| itzcull/software-skills | 100 | MIT |
| brrritscold/compainy | 100 | MIT |
| app-vitals/shipwright | 90 | MIT |
| tadokoro-ryusuke/cc-plugins | 90 | MIT |
| yasunori0418/skills | 90 | MIT |
| nahid-sparktales/agent-dispatcher | 90 | MIT |
Database snapshot: 13.11.2026 · package version 25c0f36c5d2d (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100task-estimation
Creates QA testing tasks with estimation on the configured tracker's User Stories — Azure DevOps or Jira Cloud. Reads the sprint, analyzes each story, then creates all [Testing] tasks (ADO Tasks or Jira sub-tasks) behind ONE consolidated approval, through bundled REST scripts… - 100story-writer
Use when a product manager or product owner wants to create a new story, bug, or task - guides them interactively through writing quality issues with proper acceptance criteria and technical details. Supports Jira and Azure DevOps. - 100dx-agent-re
RE Agent: analyze an ADO/Jira User Story into a structured requirements spec with task breakdown, and post a summary comment. Use for 're agent', 'requirements agent'. - 100test-case-export
Convert test cases written in Markdown or JSON into import-ready CSV for Azure DevOps Test Plans or Jira Xray (steps with action and expected result), with a bundled stdlib script. Use when test cases designed with Claude must land in the team's test management tool without retyping. - 100tracker-ops
Ad-hoc work-item operations on the configured tracker — Azure DevOps or Jira Cloud — behind one approval per write batch. Use this skill whenever the user asks for a one-off board operation outside the shipped flows: "move PROJ-12 to In Progress", "transition this issue to… - 100dx-estimate
Analyze an Azure DevOps/Jira User Story and produce a structured estimation — understanding, implementation plan, recommended hours/SP, AEM pages affected, and open questions. Posts result as an ADO/Jira comment. Use when you want an AI-generated estimation for a story.