AGENTS.md

.claude/skills/framework-core/references/briefing-template.md

.claude/skills/framework-core/references/dispatch-patterns.md

/xray-cli

/acli

• Concurrency cap = 10 subagents for Parallel TC creation. Jira and Xray APIs both rate-limit at ~10 writes/sec sustained; fanning out wider triggers 429 responses. If a module has >100 TCs, batches per subagent must be larger than 10 each (cap is on subagent count, not chunk size).
• Error protocol: On any subagent failure: STOP, report the partial success state (which TCs landed, which failed, with their issue keys / errors), present retry / skip / abort options. Do NOT auto-fix nor auto-rollback. See

  .claude/skills/framework-core/references/orchestration-doctrine.md

  .

1. Check

   CLAUDE.md

   for

   {{TMS_CLI}}

   . Value

   bun xray

   (or any Xray CLI) -> Modality A. Value is unset,

   acli

   -only, or

   {{TMS_CLI}}

   matches

   {{ISSUE_TRACKER_CLI}}

   -> Modality B.
2. If

   CLAUDE.md

   is ambiguous, look for a

   .context/master-test-plan.md

   line such as

   TMS: Xray on Jira

   or

   TMS: Jira native

   .
3. If still ambiguous, list existing issue types in the project via

   [ISSUE_TRACKER_TOOL] List issue types

   . If the project exposes

   Test Plan

   /

   Test Execution

   /

   Test Set

   /

   Pre-Condition

   , it is Modality A. Otherwise Modality B.
4. Only if all three checks fail, ask the user the question above. Do NOT ask by default — autoresolve first.

test-session-memory.md

[TMS_TOOL]

• Modality A concepts + Xray REST/GraphQL/CLI ->

  references/xray-platform.md

• Modality B project setup (Test issue type, Screen Scheme, custom fields) ->

  references/jira-setup.md

• Both modes side-by-side (field mapping, workflow, Description template) ->

  references/jira-test-management.md

1. Open the implementation plan (if any) and list the files it touches.
2. Grep the actual code for

   data-testid=

   , route handlers, API paths, and text formats.
3. Compare the ATP's assumptions against what the code does. If they diverge, correct the TC design and add a Refinement Notes section.

• An API the ATP assumed exists turns out to be SSR/direct DB.
• UI text format in the ATP ("based on N reviews") vs reality ("(N reviews)").
• Hardcoded IDs in the ATP vs variable pattern required in TMS.

1. Does it protect against FUTURE regressions? If the bug was a one-time typo in a stable area, the answer is no. Defer.
2. Are there PRIOR bugs in this area? Yes -> prioritize even with moderate ROI ("it failed once, it can fail again").
3. Is it an APP-level concern or a FEATURE-level concern? XSS / a11y / performance / responsive are APP-level suites, not per-feature TCs. Defer from this scope.

Prerequisite: Load

/acli

skill before executing commands below.

[ISSUE_TRACKER_TOOL] Search Issues:
  project: {{PROJECT_KEY}}
  query: type = Epic AND (summary ~ "regression" OR summary ~ "test repository" OR labels = "test-repository")

{{PROJECT_KEY}} Test Repository

test-repository, regression

[TMS_TOOL] Create Test: type=Manual, steps=...

[ISSUE_TRACKER_TOOL] Update Issue

[TMS_TOOL] Create Test: type=Cucumber, gherkin=<high-quality gherkin>

[ISSUE_TRACKER_TOOL] Update Issue

[ISSUE_TRACKER_TOOL] Create Issue: issueType=Test, description=<steps table>

[ISSUE_TRACKER_TOOL] Create Issue: issueType=Test, description=<gherkin in Description>

references/jira-test-management.md

Dispatch: Use the dispatch defined in §Subagent Dispatch Strategy: Parallel when N > 10 TCs (cap = 10 subagents), inline otherwise. The full briefings for both Modality A (Xray via

/xray-cli

) and Modality B (Jira-native via

/acli

) live in

references/tms-architecture.md

§"Parallel TC creation". The sharding rule, error protocol, and aggregation contract are documented there. The serial flow below is the canonical procedure each subagent runs internally for its assigned chunk.

@{priority} @regression @automation-candidate @{US_ID}
Scenario Outline: Validate <core> <conditional>
  """
  Bugs covered: BUG-1, BUG-2
  Related Story: {US_ID}
  """

  # === PRECONDITIONS (tester / script builds them) ===
  Given <entity> exists with <identifier>
  And <entity> has <quantity> <elements> where <quantity> <condition>

  # === ACTION ===
  When the user navigates to "<route>"
  And the user <main_action>

  # === VALIDATIONS ===
  Then <ui_element> is displayed with format "<expected_format>"
  And <additional_validation>

  # === EQUIVALENT PARTITIONS ===
  Examples: Happy path
    | ... |
  Examples: Edge case
    | ... |

• Variables, never hardcoded data:

  {mentor_id}

  not

  550e8400-...

  . Include a Variables table with how to obtain each.
• Tags always include: priority (

  @critical|@high|@medium|@low

  ), suite (

  @regression

  ,

  @smoke

  if critical path), automation flag (

  @automation-candidate

  ), traceability (

  @{US_ID}

  ).
• Structured comments:

  # === PRECONDITIONS ===

  ,

  # === ACTION ===

  ,

  # === VALIDATIONS ===

  ,

  # === EQUIVALENT PARTITIONS ===

  .
• Docstring with metadata: related story, bugs covered, ROI.

Substrate reference: state and transition names below resolve from

.agents/jira-workflows.json

(manifest at

.agents/jira-required.yaml

work_types.test_case

). Use

{{jira.status.test_case.<slug>}}

and

{{jira.transition.test_case.<slug>}}

in skill code; the substrate maps the slug to the literal Jira name. See

references/tms-conventions.md

§5 for the full state machine.

Draft --start_design--> In Design --ready_to_run--> Ready --+-- for_manual                  --> Manual    (terminal manual)
                                                            +-- automation_review_from_ready --> In Review
                                                                                                  |
                                                                                                  +-- approve_to_automate --> Candidate (feeds test-automation)

back_from_<state>

back_from_ready

{US_ID or TS_ID}: TC#: Validate <CORE> <CONDITIONAL>

• CORE

  : verb + object — the behavior itself (

  successful login

  ,

  authentication error

  ,

  order creation

  ).

• CONDITIONAL

  : the distinguishing condition (

  with valid credentials

  ,

  when password is incorrect

  ,

  when exceeding 5 failed attempts

  ).
• In code (KATA):

  @atc('{US_ID}-TC#')

  decorator and

  Should <behavior> when <condition>

  in

  test()

  blocks.

"Login test"

"Login - error"

"TC1: Test form"

• Scope (required, one+):

  regression

  (almost always),

  smoke

  (critical path only — aim for 10-20% of suite),

  e2e

  ,

  integration

  ,

  functional

  .
• Status (applied as it moves):

  automation-candidate

  ,

  manual-only

  ,

  automated

  .

  automation-candidate

  and

  manual-only

  are mutually exclusive; remove

  automation-candidate

  once it becomes

  automated

  .
• Priority (optional):

  critical

  ,

  high

  ,

  medium

  ,

  low

  .

references/tms-conventions.md

• ROI divisors matter: Effort and Dependencies go in the denominator. A "critical flow" with Effort=5 and Dependencies=5 has low ROI by design — that is correct, not a bug in the formula.
• Prior-bug rule overrides ROI thresholds: a scenario tied to a closed bug enters regression even at ROI 1.5-3.0. Source:

  test-prioritization.md

  +

  atc-definition-strategy.md

  — both agree.
• Cross-cutting is not a TC: "Mobile responsive", "XSS prevention", "Performance" are never TCs on their own. They are validated inside other TCs or in an app-level suite.
• Linking order is not optional: create ATP and ATR BEFORE the first TC. If you create TCs first, you get orphaned references and

  fix-traceability

  is the only way out.
• Xray requires two calls: one

  [TMS_TOOL] Create Test

  (registers in Xray), then one

  [ISSUE_TRACKER_TOOL] Update Issue

  to paste the full Description. Skipping the second call leaves a TC with no readable documentation in Jira.
• Never hardcode UUIDs or emails in Gherkin. Always use

  {variable}

  with a Variables table and a query showing how to obtain the real value at runtime.
• One (precondition, action) = one TC. Multiple expected results all belong to the same TC. Splitting assertions into separate TCs is the single most-diagnosed anti-pattern in reviews.
• Bug-driven TCs default to Candidate. A closed bug is empirical evidence that the area regresses. Start at "automate" unless automation is technically impossible.
• Source-code validation is mandatory: the ATP was written before code. Grep for

  data-testid=

  , routes, text formats. Log discrepancies in a Refinement Notes section on the TC.
• Most candidates should be Deferred. If a module produces 80 scenarios and 60 end up in regression, re-apply Phase 0 more harshly. Target: a few well-chosen TCs per story (1-3 simple, 3-5 complex).
• Test Plan / Test Set ID (Xray) vs User Story ID (native Jira): the TC prefix depends on stack. In Xray with a Test Set, prefix is the TS ID. In native Jira, prefix is the US ID. Both work — pick one per project and stay consistent.

• Creating ATP/ATR/TC for a story or checking links -> read

  references/tms-architecture.md

  (entity model, required fields, linking sequence, completeness criteria).
• Naming a TC, filling fields, picking labels, or choosing Gherkin vs Traditional -> read

  references/tms-conventions.md

  (naming formulas, label taxonomy, workflow state machine, ROI table).
• Working in Jira native or Jira+Xray mode, creating tests via the right tool, or producing the full Description template -> read

  references/jira-test-management.md

  (mode comparison, Xray issue types, Description template, local cache template, CI/CD sync).
• Fixing broken traceability (TC not linked to US/ATP/ATR, name wrong) -> use the procedure in the Linking Order section above, backed by

  references/tms-architecture.md

  §Traceability Rules.
• Deciding if a bug deserves a regression TC -> apply Phase 0 question 2 (prior bug = prioritize), then ROI; bug-driven scope defaults to Candidate.
• TMS operations -> load

  /xray-cli

  skill for concrete CLI syntax. Issue-tracker operations resolve via

  [ISSUE_TRACKER_TOOL]

  per CLAUDE.md Tool Resolution.

Prerequisite: Load

/acli

skill before executing commands below.

[ISSUE_TRACKER_TOOL] Search Issues:
  project: {{PROJECT_KEY}}
  query: type = Epic AND labels = "test-repository"

Prerequisite: Load

/xray-cli

and

/acli

skills before executing commands below.

undefined

Prerequisite: Load

/acli

skill before executing commands below.

undefined

Prerequisite: Load

/acli

skill before executing commands below.

[ISSUE_TRACKER_TOOL] Transition Issue:
  issue: {TEST_KEY}
  transition: {{jira.transition.test_case.start_design}}   # Draft -> In Design
  # later: {{jira.transition.test_case.ready_to_run}}              # In Design -> Ready
  # later: {{jira.transition.test_case.automation_review_from_ready}}  # Ready -> In Review
  # later: {{jira.transition.test_case.approve_to_automate}}      # In Review -> Candidate
  # OR:    {{jira.transition.test_case.for_manual}}               # Ready -> Manual