ma-agents 3.6.2 → 3.9.0

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-teach-me-testing/SKILL.md

@@ -3,4 +3,127 @@ name: bmad-teach-me-testing
 description: 'Teach testing progressively through structured sessions. Use when user says "lets learn testing" or "I want to study test practices"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+# Teach Me Testing — TEA Academy
+
+**Goal:** Provide self-paced, multi-session learning that teaches testing fundamentals through advanced practices, scalable to entire teams without requiring instructor time.
+
+**Role:** In addition to your name, communication_style, and persona, you are also a Master Test Architect and Teaching Guide collaborating with learners at all levels. This is a partnership, not a lecture. You bring expertise in TEA methodology, testing principles, and teaching pedagogy, while the learner brings their role context, experience, and learning goals. Work together to build their testing knowledge progressively.
+
+**Meta-Context:** This workflow uses continuable architecture with state persistence across sessions. Users can pause and resume anytime, jump to any session based on experience, and learn at their own pace over 1-2 weeks.
+
+You will continue to operate with your given name, identity, and communication_style, merged with the details of this role description.
+
+## Conventions
+
+- Bare paths (e.g. `instructions.md`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+- Resolve sibling workflow files such as `instructions.md`, `checklist.md`, `steps-c/...`, `steps-e/...`, `steps-v/...`, and templates from `{skill-root}`.
+
+## On Activation
+
+### Step 1: Resolve the Workflow Block
+
+Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
+
+**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
+
+1. `{skill-root}/customize.toml` — defaults
+2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides
+3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides
+
+Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
+
+### Step 2: Execute Prepend Steps
+
+Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.
+
+### Step 3: Load Persistent Facts
+
+Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs resolved from `{project-root}` — expand them and load every matching file in lexical path order as facts. All other entries are facts verbatim.
+
+### Step 4: Load Config
+
+Load config from `{project-root}/_bmad/tea/config.yaml` and resolve:
+
+- `user_name`
+- `project_name`
+- `communication_language`
+- `test_artifacts`
+
+### Step 5: Greet the User
+
+Greet `{user_name}`, speaking in `{communication_language}`.
+
+### Step 6: Execute Append Steps
+
+Execute each entry in `{workflow.activation_steps_append}` in order.
+
+Activation is complete. Begin the workflow below.
+
+## Workflow Architecture
+
+This uses **step-file architecture** for disciplined execution:
+
+### Core Principles
+
+- **Micro-file Design**: Each step is a self-contained instruction file that is part of an overall workflow that must be followed exactly
+- **Just-In-Time Loading**: Only the current step file is in memory — never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **State Tracking**: Document progress in progress file using `stepsCompleted` array and session tracking
+- **Continuable Sessions**: Users can pause after any session and resume later with full context preserved
+- **Tri-Modal Structure**: Separate step folders for Create (steps-c/), Edit (steps-e/), and Validate (steps-v/) modes
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **SAVE STATE**: Update `stepsCompleted` and session tracking in progress file before loading next step
+6. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 💾 **ALWAYS** update progress file after each session completion
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+- ✅ **ALWAYS** communicate in `{communication_language}`
+
+## Initialization Sequence
+
+### 1. Mode Determination
+
+**Check if mode was specified in the command invocation:**
+
+- If user invoked with "create" or "teach" or "learn" or "start" or "resume" or "continue" → Set mode to **create**
+- If user invoked with "validate" or "review" or "-v" or "--validate" → Set mode to **validate**
+- If user invoked with "edit" or "modify" or "-e" or "--edit" → Set mode to **edit**
+
+**If mode is still unclear, ask user:**
+
+"Welcome to TEA Academy! What would you like to do?
+
+**[C]reate** — Start learning sessions (new or continue existing progress)
+**[V]alidate** — Review workflow quality and generate validation report
+**[E]dit** — Modify workflow content or structure
+
+Please select: [C]reate / [V]alidate / [E]dit"
+
+### 2. Route to First Step
+
+**IF mode == create:**
+Load, read the full file, and then execute `{skill-root}/steps-c/step-01-init.md` to begin the teaching workflow.
+
+**IF mode == validate:**
+Prompt for workflow path (if validating the workflow itself): "Which workflow would you like to validate?"
+Then load, read the full file, and then execute `{skill-root}/steps-v/step-v-01-validate.md`.
+
+**IF mode == edit:**
+Prompt for what to edit: "What would you like to edit in the teaching workflow?"
+Then load, read the full file, and then execute `{skill-root}/steps-e/step-e-01-assess-workflow.md`.

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-teach-me-testing/checklist.md

@@ -8,10 +8,11 @@ Use this checklist to validate the teaching workflow meets quality standards.
 
 ## Foundation Quality
 
-- [ ] **workflow.md** exists with proper frontmatter
+- [ ] **SKILL.md** exists with proper frontmatter
+- [ ] **customize.toml** defines activation hooks and persistent facts
 - [ ] Tri-modal routing logic present (Create/Edit/Validate)
 - [ ] Configuration loading references correct module (TEA)
-- [ ] First step path correct (`./steps-c/step-01-init.md`)
+- [ ] First step path correct (`{skill-root}/steps-c/step-01-init.md`)
 - [ ] Folder structure complete (steps-c/, steps-e/, steps-v/, data/, templates/)
 
 ---

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-teach-me-testing/customize.toml

@@ -0,0 +1,40 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for bmad-teach-me-testing. Mirrors the
+# agent customization shape under the [workflow] namespace.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+
+# Steps to run before the standard activation (config load, greet).
+# Overrides append. Use for pre-flight loads, compliance checks, etc.
+
+activation_steps_prepend = []
+
+# Steps to run after greet but before the workflow begins.
+# Overrides append. Use for context-heavy setup that should happen
+# once the user has been acknowledged.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (testing standards, framework conventions, learning objectives).
+# Distinct from the runtime memory sidecar — these are static context
+# loaded on activation. Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "Every test must run deterministically in CI."
+#   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/test-standards.md"
+#     (glob patterns are supported; matching files load in lexical path order as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# Scalar: executed when the workflow reaches its terminal step in any
+# mode (create, validate, edit), after the final outputs are produced.
+# Override wins. Leave empty for no custom post-completion behavior.
+
+on_complete = ""

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-teach-me-testing/instructions.md

@@ -38,6 +38,13 @@ The workflow automatically detects existing progress and resumes where you left
 
 ## Workflow Structure
 
+### Step Entrypoints
+
+- Create / start: `{skill-root}/steps-c/step-01-init.md`
+- Continue existing progress: `{skill-root}/steps-c/step-01b-continue.md`
+- Validate the workflow: `{skill-root}/steps-v/step-v-01-validate.md`
+- Edit the workflow: `{skill-root}/steps-e/step-e-01-assess-workflow.md`
+
 ### 7 Sessions
 
 1. **Quick Start (30 min)** - TEA Lite intro, run automate workflow

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-teach-me-testing/steps-c/step-01-init.md

@@ -2,7 +2,7 @@
 name: 'step-01-init'
 description: 'Initialize TEA Academy - check for existing progress and route to continuation or new assessment'
 
-nextStepFile: './step-02-assess.md'
+nextStepFile: '{skill-root}/steps-c/step-02-assess.md'
 continueFile: './step-01b-continue.md'
 progressFile: '{test_artifacts}/teaching-progress/{user_name}-tea-progress.yaml'
 progressTemplate: '../templates/progress-template.yaml'

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-teach-me-testing/steps-c/step-01b-continue.md

@@ -3,7 +3,7 @@ name: 'step-01b-continue'
 description: 'Resume TEA Academy learning - load progress and display dashboard'
 
 progressFile: '{test_artifacts}/teaching-progress/{user_name}-tea-progress.yaml'
-nextStepFile: './step-03-session-menu.md'
+nextStepFile: '{skill-root}/steps-c/step-03-session-menu.md'
 ---
 
 # Step 1b: Continue TEA Academy

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-teach-me-testing/steps-c/step-02-assess.md

@@ -2,7 +2,7 @@
 name: 'step-02-assess'
 description: 'Gather learner role, experience level, learning goals, and pain points to customize teaching'
 
-nextStepFile: './step-03-session-menu.md'
+nextStepFile: '{skill-root}/steps-c/step-03-session-menu.md'
 progressFile: '{test_artifacts}/teaching-progress/{user_name}-tea-progress.yaml'
 ---
 

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-teach-me-testing/steps-c/step-04-session-01.md

@@ -5,7 +5,7 @@ description: 'Session 1: Quick Start - TEA Lite intro, run automate workflow (30
 progressFile: '{test_artifacts}/teaching-progress/{user_name}-tea-progress.yaml'
 sessionNotesTemplate: '../templates/session-notes-template.md'
 sessionNotesFile: '{test_artifacts}/tea-academy/{user_name}/session-01-notes.md'
-nextStepFile: './step-03-session-menu.md'
+nextStepFile: '{skill-root}/steps-c/step-03-session-menu.md'
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 ---

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-teach-me-testing/steps-c/step-04-session-02.md

@@ -5,7 +5,7 @@ description: 'Session 2: Core Concepts - Risk-based testing, DoD, testing philos
 progressFile: '{test_artifacts}/teaching-progress/{user_name}-tea-progress.yaml'
 sessionNotesTemplate: '../templates/session-notes-template.md'
 sessionNotesFile: '{test_artifacts}/tea-academy/{user_name}/session-02-notes.md'
-nextStepFile: './step-03-session-menu.md'
+nextStepFile: '{skill-root}/steps-c/step-03-session-menu.md'
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 ---

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-teach-me-testing/steps-c/step-04-session-03.md

@@ -5,7 +5,7 @@ description: 'Session 3: Architecture & Patterns - Fixtures, network patterns, f
 progressFile: '{test_artifacts}/teaching-progress/{user_name}-tea-progress.yaml'
 sessionNotesTemplate: '../templates/session-notes-template.md'
 sessionNotesFile: '{test_artifacts}/tea-academy/{user_name}/session-03-notes.md'
-nextStepFile: './step-03-session-menu.md'
+nextStepFile: '{skill-root}/steps-c/step-03-session-menu.md'
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 ---

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-teach-me-testing/steps-c/step-04-session-04.md

@@ -5,7 +5,7 @@ description: 'Session 4: Test Design - Risk assessment, test design workflow (60
 progressFile: '{test_artifacts}/teaching-progress/{user_name}-tea-progress.yaml'
 sessionNotesTemplate: '../templates/session-notes-template.md'
 sessionNotesFile: '{test_artifacts}/tea-academy/{user_name}/session-04-notes.md'
-nextStepFile: './step-03-session-menu.md'
+nextStepFile: '{skill-root}/steps-c/step-03-session-menu.md'
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 ---

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-teach-me-testing/steps-c/step-04-session-05.md

@@ -5,7 +5,7 @@ description: 'Session 5: ATDD & Automate - TDD red-green approach, generate test
 progressFile: '{test_artifacts}/teaching-progress/{user_name}-tea-progress.yaml'
 sessionNotesTemplate: '../templates/session-notes-template.md'
 sessionNotesFile: '{test_artifacts}/tea-academy/{user_name}/session-05-notes.md'
-nextStepFile: './step-03-session-menu.md'
+nextStepFile: '{skill-root}/steps-c/step-03-session-menu.md'
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 ---

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-teach-me-testing/steps-c/step-04-session-06.md

@@ -5,7 +5,7 @@ description: 'Session 6: Quality & Trace - Test review, traceability, quality me
 progressFile: '{test_artifacts}/teaching-progress/{user_name}-tea-progress.yaml'
 sessionNotesTemplate: '../templates/session-notes-template.md'
 sessionNotesFile: '{test_artifacts}/tea-academy/{user_name}/session-06-notes.md'
-nextStepFile: './step-03-session-menu.md'
+nextStepFile: '{skill-root}/steps-c/step-03-session-menu.md'
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 ---

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-teach-me-testing/steps-c/step-04-session-07.md

@@ -5,7 +5,7 @@ description: 'Session 7: Advanced Patterns - Menu-driven knowledge fragment expl
 progressFile: '{test_artifacts}/teaching-progress/{user_name}-tea-progress.yaml'
 sessionNotesTemplate: '../templates/session-notes-template.md'
 sessionNotesFile: '{test_artifacts}/tea-academy/{user_name}/session-07-notes.md'
-nextStepFile: './step-03-session-menu.md'
+nextStepFile: '{skill-root}/steps-c/step-03-session-menu.md'
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 ---

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-teach-me-testing/steps-c/step-05-completion.md

@@ -337,3 +337,11 @@ Workflow ends here. User can run the workflow again to re-take sessions or explo
 - Proceeding to next step (this is final - no next step)
 
 **Master Rule:** Verify completion, generate certificate, celebrate achievement, end workflow. This is the finale.
+
+## On Complete
+
+Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
+
+If the resolver succeeds and returns a non-empty `workflow.on_complete`, execute that value as the final terminal instruction before exiting.
+
+If the resolver fails, returns no output, or resolves an empty value, skip the hook and exit normally.

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-teach-me-testing/steps-e/step-e-01-assess-workflow.md

@@ -2,8 +2,8 @@
 name: 'step-e-01-assess-workflow'
 description: 'Assess what needs to be edited in the teaching workflow'
 
-nextStepFile: './step-e-02-apply-edits.md'
-workflowPath: '../'
+nextStepFile: '{skill-root}/steps-e/step-e-02-apply-edits.md'
+workflowPath: '{skill-root}'
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 ---

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-teach-me-testing/steps-e/step-e-02-apply-edits.md

@@ -2,7 +2,7 @@
 name: 'step-e-02-apply-edits'
 description: 'Apply modifications to the teaching workflow based on edit plan'
 
-workflowPath: '../'
+workflowPath: '{skill-root}'
 ---
 
 # Edit Step 2: Apply Edits
@@ -120,3 +120,11 @@ The teach-me-testing workflow has been updated.
 ✅ Edits applied to approved files only, changes validated, workflow integrity maintained, user informed of modifications.
 
 **Master Rule:** Show changes, get approval, apply edits, validate integrity.
+
+## On Complete
+
+Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
+
+If the resolver succeeds and returns a non-empty `workflow.on_complete`, execute that value as the final terminal instruction before exiting.
+
+If the resolver fails, returns no output, or resolves an empty value, skip the hook and exit normally.

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-teach-me-testing/steps-v/step-v-01-validate.md

@@ -2,8 +2,8 @@
 name: 'step-v-01-validate'
 description: 'Validate teach-me-testing workflow quality against BMAD standards'
 
-workflowPath: '../'
-checklistFile: '../checklist.md'
+workflowPath: '{skill-root}'
+checklistFile: '{skill-root}/checklist.md'
 validationReport: '{test_artifacts}/workflow-validation/teach-me-testing-validation-{date}.md'
 ---
 
@@ -63,7 +63,8 @@ This will validate:
 
 **Check:**
 
-- [ ] workflow.md exists with proper frontmatter
+- [ ] SKILL.md exists with proper frontmatter
+- [ ] customize.toml defines workflow customization surface
 - [ ] Tri-modal routing logic present
 - [ ] Configuration loading correct
 - [ ] First step path correct
@@ -261,3 +262,11 @@ Workflow is usable but could be improved.
 ✅ All validation checks run, comprehensive report generated, issues identified with remediation guidance, overall status determined.
 
 **Master Rule:** Check everything systematically, report findings clearly, provide actionable remediation.
+
+## On Complete
+
+Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
+
+If the resolver succeeds and returns a non-empty `workflow.on_complete`, execute that value as the final terminal instruction before exiting.
+
+If the resolver fails, returns no output, or resolves an empty value, skip the hook and exit normally.

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-atdd/SKILL.md

@@ -3,4 +3,83 @@ name: bmad-testarch-atdd
 description: 'Generate red-phase acceptance test scaffolds using the TDD cycle. Use when the user says "lets write acceptance tests" or "I want to do ATDD"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+# Acceptance Test-Driven Development (ATDD)
+
+**Goal:** Generate red-phase acceptance test scaffolds before implementation using TDD red-green-refactor cycle.
+
+**Role:** You are the Master Test Architect.
+
+You will continue to operate with your given name, identity, and communication_style, merged with the details of this role description.
+
+## Conventions
+
+- Bare paths (e.g. `instructions.md`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+- Resolve sibling workflow files such as `instructions.md`, `checklist.md`, `steps-c/...`, `steps-e/...`, `steps-v/...`, and templates from `{skill-root}`.
+
+## On Activation
+
+### Step 1: Resolve the Workflow Block
+
+Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
+
+**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
+
+1. `{skill-root}/customize.toml` — defaults
+2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides
+3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides
+
+Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
+
+### Step 2: Execute Prepend Steps
+
+Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.
+
+### Step 3: Load Persistent Facts
+
+Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs resolved from `{project-root}` — expand them and load every matching file in lexical path order as facts. All other entries are facts verbatim.
+
+### Step 4: Load Config
+
+Load config from `{project-root}/_bmad/tea/config.yaml` and resolve:
+
+- `user_name`
+- `communication_language`
+
+### Step 5: Greet the User
+
+Greet `{user_name}`, speaking in `{communication_language}`.
+
+### Step 6: Execute Append Steps
+
+Execute each entry in `{workflow.activation_steps_append}` in order.
+
+Activation is complete. Begin the workflow below.
+
+## Workflow Architecture
+
+This workflow uses **tri-modal step-file architecture**:
+
+- **Create mode (steps-c/)**: primary execution flow for new runs and resume continuation
+- **Validate mode (steps-v/)**: validation against checklist
+- **Edit mode (steps-e/)**: revise existing outputs
+
+## Initialization Sequence
+
+### 1. Mode Determination
+
+"Welcome to the workflow. What would you like to do?"
+
+- **[C] Create** — Run the workflow from the beginning
+- **[R] Resume** — Resume an interrupted Create workflow
+- **[V] Validate** — Validate existing outputs
+- **[E] Edit** — Edit existing outputs
+
+### 2. Route to First Step
+
+- **If C:** Load `{skill-root}/steps-c/step-01-preflight-and-context.md`
+- **If R:** Load `{skill-root}/steps-c/step-01b-resume.md` (Create-mode continuation)
+- **If V:** Load `{skill-root}/steps-v/step-01-validate.md`
+- **If E:** Load `{skill-root}/steps-e/step-01-assess.md`

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-atdd/customize.toml

@@ -0,0 +1,40 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for bmad-testarch-atdd. Mirrors the
+# agent customization shape under the [workflow] namespace.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+
+# Steps to run before the standard activation (config load, greet).
+# Overrides append. Use for pre-flight loads, compliance checks, etc.
+
+activation_steps_prepend = []
+
+# Steps to run after greet but before the workflow begins.
+# Overrides append. Use for context-heavy setup that should happen
+# once the user has been acknowledged.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (testing standards, framework conventions, compliance constraints).
+# Distinct from the runtime memory sidecar — these are static context
+# loaded on activation. Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "Every test must run deterministically in CI."
+#   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/test-standards.md"
+#     (glob patterns are supported; matching files load in lexical path order as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# Scalar: executed when the workflow reaches its terminal step in any
+# mode (create, validate, edit), after the final outputs are produced.
+# Override wins. Leave empty for no custom post-completion behavior.
+
+on_complete = ""

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-atdd/instructions.md

@@ -34,11 +34,11 @@ From `workflow.yaml`, resolve:
 ### 2. First Step
 
 Load, read completely, and execute:
-`./steps-c/step-01-preflight-and-context.md`
+`{skill-root}/steps-c/step-01-preflight-and-context.md`
 
 ### 3. Resume Support
 
 If the user selects **Resume** mode, load, read completely, and execute:
-`./steps-c/step-01b-resume.md`
+`{skill-root}/steps-c/step-01b-resume.md`
 
 This checks the output document for progress tracking frontmatter and routes to the next incomplete step.

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-atdd/resources/knowledge/contract-testing.md

@@ -167,7 +167,8 @@ describe('User API Contract', () => {
 ```json
 {
   "scripts": {
-    "test:pact:consumer": "vitest run --config vitest.config.pact.ts",
+    "test:pact:consumer": "./scripts/check-pact-determinism.sh 'npm run test:pact:consumer:run' 3 ./pacts",
+    "test:pact:consumer:run": "vitest run --config vitest.config.pact.ts",
     "publish:pact": ". ./scripts/env-setup.sh && ./scripts/publish-pact.sh"
   }
 }
@@ -1024,7 +1025,7 @@ Before implementing contract testing, verify:
 ## Integration Points
 
 - Used in workflows: `*automate` (integration test generation), `*ci` (contract CI setup)
-- Related fragments: `test-levels-framework.md`, `ci-burn-in.md`, `pact-consumer-framework-setup.md`
+- Related fragments: `test-levels-framework.md`, `ci-burn-in.md`, `pact-consumer-framework-setup.md` (consumer vitest `fileParallelism: false` + `pool: 'forks'` + `singleFork: true`), `pactjs-utils-consumer-helpers.md` (PactV4 one-interaction-per-`it()` rule), `pactjs-utils-provider-verifier.md` (provider vitest `pool: 'forks'` + `singleFork: true` — same rule as consumer), `pact-broker-webhooks.md` (PactFlow → GitHub webhook auth, PAT rotation, staleness monitoring)
 - Tools: Pact.js, Pact Broker (Pactflow or self-hosted), Pact CLI
 
 ---
@@ -1033,18 +1034,34 @@ Before implementing contract testing, verify:
 
 When `tea_use_pactjs_utils` is enabled, the following utilities replace manual boilerplate:
 
-| Manual Pattern (raw Pact.js)                             | Pact.js Utils Equivalent                                                          | Benefit                                                               |
-| -------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| Manual `JsonMap` casting for `.given()` params           | `createProviderState({ name, params })`                                           | Type-safe, auto-conversion of Date/null/nested objects                |
-| Repeated builder callbacks for query/header/body         | `setJsonContent({ query, headers, body })`                                        | Reusable callback for `.withRequest(...)` and `.willRespondWith(...)` |
-| Inline body lambda `(builder) => builder.jsonBody(body)` | `setJsonBody(body)`                                                               | Body-only shorthand for cleaner response builders                     |
-| 30+ lines of `VerifierOptions` assembly                  | `buildVerifierOptions({ provider, port, includeMainAndDeployed, stateHandlers })` | One-call setup, env-aware, flow auto-detection                        |
-| Manual broker URL + selector logic from env vars         | `handlePactBrokerUrlAndSelectors({ ..., options })`                               | Mutates options in-place with broker URL and selectors                |
-| DIY Express middleware for auth injection                | `createRequestFilter({ tokenGenerator })`                                         | Bearer prefix contract prevents double-prefix bugs                    |
-| Manual CI branch/tag extraction                          | `getProviderVersionTags()`                                                        | CI-aware (GitHub Actions, GitLab CI, etc.)                            |
-| Message verifier config assembly                         | `buildMessageVerifierOptions({ provider, messageProviders })`                     | Same one-call pattern for Kafka/async contracts                       |
-| Inline no-op filter `(req, res, next) => next()`         | `noOpRequestFilter`                                                               | Pre-built pass-through for no-auth providers                          |
-
-See the `pactjs-utils-*.md` knowledge fragments for complete examples and anti-patterns.
+| Manual Pattern (raw Pact.js)                             | Pact.js Utils Equivalent                                                          | Benefit                                                                                                    |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Manual `JsonMap` casting for `.given()` params           | `createProviderState({ name, params })`                                           | Type-safe, auto-conversion of Date/null/nested objects                                                     |
+| Repeated builder callbacks for query/header/body         | `setJsonContent({ query, headers, body })`                                        | Reusable callback for `.withRequest(...)` and `.willRespondWith(...)`                                      |
+| Inline body lambda `(builder) => builder.jsonBody(body)` | `setJsonBody(body)`                                                               | Body-only shorthand for cleaner response builders                                                          |
+| 30+ lines of `VerifierOptions` assembly                  | `buildVerifierOptions({ provider, port, includeMainAndDeployed, stateHandlers })` | One-call setup, env-aware, flow auto-detection                                                             |
+| Manual broker URL + selector logic from env vars         | `handlePactBrokerUrlAndSelectors({ ..., options })`                               | Mutates options in-place with broker URL and selectors                                                     |
+| DIY Express middleware for auth injection                | `createRequestFilter({ tokenGenerator })`                                         | Bearer prefix contract prevents double-prefix bugs                                                         |
+| Manual CI branch/tag extraction                          | `getProviderVersionTags()`                                                        | CI-aware (GitHub Actions, GitLab CI, etc.)                                                                 |
+| Message verifier config assembly                         | `buildMessageVerifierOptions({ provider, messageProviders })`                     | Same one-call pattern for Kafka/async contracts                                                            |
+| Inline no-op filter `(req, res, next) => next()`         | `noOpRequestFilter`                                                               | Pre-built pass-through for no-auth providers                                                               |
+| Hand-written matcher helper duplicating a Zod/TS type    | `zodToPactMatchers(ConsumerMovieSchema, example)`                                 | Single source of truth for response shape; consumer-curated scope keeps contracts lean and consumer-driven |
+
+See the `pactjs-utils-*.md` knowledge fragments for complete examples and anti-patterns (`pactjs-utils-zod-to-pact.md` covers the consumer-curated schema pattern).
+
+### PactV4 Determinism & FFI Safety (Mandatory)
+
+Four rules that together prevent both (a) non-deterministic pact generation failures that cause `Cannot change pact content for already published pact` errors at PactFlow publish, and (b) "request was expected but not received" flakes observed on Linux CI once a consumer+provider pair has more than one `.pacttest.ts` file:
+
+1. **Consumer Vitest `fileParallelism: false`** in `vitest.config.pact.ts` — prevents parallel workers from racing on the shared pact JSON. See `pact-consumer-framework-setup.md` Example 2.
+2. **Consumer Vitest `pool: 'forks'` + `poolOptions.forks.singleFork: true`** in `vitest.config.pact.ts` — same config as the provider side (`pactjs-utils-provider-verifier.md` Example 7). Best current understanding: the `@pact-foundation/pact` napi-rs binding is not robust across Vitest worker threads sharing a process; serialization alone (via `fileParallelism: false`) is insufficient on the default threads pool in Vitest v1. Forks + `singleFork: true` runs every pact file in one subprocess with a coherent FFI handle and eliminated a reproducible Linux-CI flake on two repos (`pactjs-utils`, `seon-mcp-server`). Single-file consumer suites have not been observed to flake; this rule is still recommended as a future-proof. See `pact-consumer-framework-setup.md` Example 2.
+3. **One `addInteraction()` per `it()` block** — see `pactjs-utils-consumer-helpers.md` Example 6.
+4. **Determinism gate** runs the consumer suite N times and fails on byte-different pact JSON before publish — see `pact-consumer-framework-setup.md` Example 10 (`scripts/check-pact-determinism.sh`).
+
+Provider suites require the same `pool: 'forks'` + `singleFork: true` combination — see `pactjs-utils-provider-verifier.md` Example 7.
+
+### Webhook Auth & Staleness
+
+When `can-i-deploy` in a consumer repo times out with `There is no verified pact between <consumer> and the version of <provider> currently in <env>` — check the provider's PactFlow webhook. Silent failures from an expired/revoked GitHub PAT are the most common non-code cause of this symptom. See `pact-broker-webhooks.md` for the dedicated-machine-user pattern, classic-PAT-with-`repo`-scope rationale, rotation runbook, and staleness monitoring options.
 
 _Source: Pact consumer/provider sample repos, Murat contract testing blog, Pact official documentation, @seontechnologies/pactjs-utils library_