agents-templated 2.2.12 → 2.2.14

package/templates/agents/commands/README.md

@@ -3,7 +3,7 @@
 This directory is the modular source of truth for slash-command execution contracts.
 
 - Global protocol and safety framework: `AGENTS.MD` → `Deterministic Slash Command System Standard`
-- Global response schema: `agents/commands/SCHEMA.md`
+- Global response schema: `.claude/commands/SCHEMA.md`
 - Command contracts:
   - `plan.md`
   - `task.md`
@@ -19,6 +19,7 @@ This directory is the modular source of truth for slash-command execution contra
   - `arch-check.md`
   - `ux-bar.md`
   - `debug-track.md`
+  - `test-data.md`
   - `risk-review.md`
   - `release-ready.md`
   - `learn-loop.md`
@@ -38,10 +39,11 @@ Execution requirements:
 
 ## Publish Inclusion
 
-The npm package includes command contracts from both:
+The npm package scaffolds command contracts into `.claude/commands/`.
 
-- `agents/commands/` (root mirror)
-- `templates/agents/commands/` (scaffold source)
+Template source path in this repository:
+
+- `templates/agents/commands/`
 
 ## Workflow Command Mapping
 
@@ -52,6 +54,7 @@ Use these lifecycle commands as the recommended specialist sequence:
 - `arch-check` -> `plan.md`
 - `ux-bar` -> `plan.md`
 - `debug-track` -> `fix.md`
+- `test-data` -> `test.md`
 - `risk-review` -> `audit.md`
 - `perf` -> `perf.md`
 - `release-ready` -> `release.md`
@@ -62,3 +65,80 @@ The CLI command `agents-templated workflow` prints this lifecycle in order:
 
 Think -> Plan -> Build -> Review -> Test -> Ship -> Reflect
 
+## Non-Overlap Routing Boundaries
+
+The orchestrator preserves explicit ownership boundaries between specialist decision surfaces.
+
+- Backend implementation remains separate from tactical build and compatibility remediation:
+  - `backend-specialist` owns implementation.
+  - `build-error-resolver` owns build/type/lint fixes.
+  - `compatibility-checker` owns external contract compatibility decisions.
+- Review chain remains ordered and non-overlapping:
+  - `code-reviewer` -> `dependency-auditor` -> `doc-updater`
+  - `doc-updater` should not absorb review or dependency decisions.
+
+## Test Data Handoff Routing
+
+The orchestrator routes deterministic data preparation through `test-data-builder` and then hands off to downstream consumers.
+
+- Upstream routes:
+  - `qa-design` and backend/database-oriented phases can route to `test-data-builder`.
+- Downstream consumers:
+  - `qa-specialist(mode=validation)`
+  - `e2e-runner`
+  - `performance-specialist(mode=load)`
+- Handoff metadata is emitted in orchestration output as `handoff_inputs`.
+
+## Deprecated Alias Redirects
+
+Deprecated workflow command aliases are supported as non-breaking redirects with deterministic notices.
+
+| Deprecated | Redirects To |
+|------------|--------------|
+| `quality-gate` | `risk-review` |
+| `perf-scan` | `perf` |
+| `docs-sync` | `docs` |
+
+Alias policy:
+
+- Redirects preserve behavior of the canonical command.
+- CLI prints a deprecation notice on each alias invocation.
+- New automation should use canonical command names only.
+
+## Automatic Orchestration
+
+The CLI command `agents-templated orchestrate "<objective>"` builds an automatic multi-phase handoff plan across specialist tracks.
+
+- Uses static scenario routing first.
+- Falls back to keyword intent matching when no explicit scenario override is provided.
+- Emits deterministic structured output compatible with `SCHEMA.md` in `slash-command-auto` mode.
+- Stops the chain on `blocked` or `failed` state and returns a populated `stop_condition`.
+- Includes scenario-conditioned optional delegation to existing subagents (for example `security-reviewer`, `e2e-runner`, `dependency-auditor`) without making them mandatory.
+
+Example:
+
+`agents-templated orchestrate "build auth api and dashboard" --json`
+
+## Mode-Locked Specialist Invocation
+
+The orchestrator must pass explicit mode values for mode-locked specialists and must never allow self-selection.
+
+Mode-locked specialists:
+
+- `qa-specialist`
+  - Allowed modes: `design`, `validation`
+  - Required invocation examples:
+    - `qa-specialist(mode=design, input=<spec>)`
+    - `qa-specialist(mode=validation, input=<changed_files + scope>)`
+- `performance-specialist`
+  - Allowed modes: `profile`, `load`
+  - Required invocation examples:
+    - `performance-specialist(mode=profile, input=<scope>)`
+    - `performance-specialist(mode=load, input=<scope + thresholds>)`
+
+HALT rules:
+
+- Missing mode -> stop execution and return a clarification request.
+- Unsupported mode -> stop execution and return allowed values.
+- Mode inference from context is forbidden.
+

package/templates/agents/commands/SCHEMA.md

@@ -15,8 +15,28 @@ All slash command responses MUST include the following top-level fields:
 - `stop_condition`
 - `next_action`
 
+Optional orchestration fields:
+- `artifacts.scenario`
+- `artifacts.scenario_reason`
+- `artifacts.phases[]`
+- `artifacts.phases[].optional_subagents[]`
+- `artifacts.phases[].invocation_mode`
+- `artifacts.phases[].handoff_inputs[]`
+- `artifacts.deprecation_notices[]`
+- `execution_log[].orchestration_phase`
+- `execution_log[].routed_subagent`
+- `execution_log[].routed_track`
+- `execution_log[].routed_skills`
+- `execution_log[].optional_subagents[]`
+- `execution_log[].invocation_mode`
+- `execution_log[].handoff_inputs[]`
+
 Constraints:
 - `mode` MUST be one of: `slash-command`, `slash-command-auto`.
 - `status` MUST be one of: `completed`, `blocked`, `failed`.
 - If a field value is unknown, set it to `null`.
-- Unknown or malformed slash commands MUST return structured error output and stop.
+- Unknown or malformed slash commands MUST return structured error output and stop.
+- In `slash-command-auto` mode, orchestration chains MUST stop on first `blocked` or `failed` phase and return a non-null `stop_condition`.
+- Optional subagent delegation MUST remain non-required and scenario-conditioned.
+- For `qa-specialist` and `performance-specialist`, orchestrator invocation MUST include an explicit mode.
+- Missing or unsupported mode for mode-locked specialists MUST return `status=blocked` with a non-null `stop_condition`.

package/templates/agents/commands/test-data.md

@@ -0,0 +1,56 @@
+# /test-data
+
+## A. Intent
+Produce deterministic fixtures, seeds, and mocks for downstream validation, e2e, and load phases.
+
+## B. When to Use
+- Use when QA design or backend/database changes require repeatable datasets.
+- Use before `qa-specialist(mode=validation)`, `e2e-runner`, or `performance-specialist(mode=load)`.
+
+## C. Context Assumptions
+- Acceptance criteria and target test flows are defined.
+- Data shape constraints are known.
+- Generated data can be reset safely.
+
+## D. Required Inputs
+| Input | Type | Example |
+|---------------------|------------|----------------------------------|
+| `consumer_targets` | string[] | ["qa-validation", "e2e", "perf-load"] |
+| `dataset_scope` | string | "orders with edge-case payment states" |
+| `data_constraints` | string[] | ["no PII", "stable IDs", "seed-controlled randomness"] |
+
+## E. Pre-Execution Guards <- fail fast, check ALL before running
+- [ ] dataset scope is explicit and bounded
+- [ ] production secrets and real PII are excluded
+- [ ] setup/reset path is defined and reversible
+
+## F. Execution Flow
+1. Confirm required consumer targets and edge cases.
+2. Build deterministic fixtures/seeds/mocks.
+3. Package setup/reset instructions.
+4. Validate data reproducibility and cleanup safety.
+5. Emit test-data handoff report.
+
+## G. Output Schema
+
+```json
+{
+  "data_package_id": "string",
+  "assets": ["array", "of", "strings"],
+  "setup_steps": ["array", "of", "strings"],
+  "reset_steps": ["array", "of", "strings"],
+  "handoff_targets": ["array", "of", "strings"]
+}
+```
+
+## H. Output Target
+- Default delivery: stdout
+- Override flag: --output=<target>
+
+## I. Stop Conditions <- abort with error message, never emit partial output
+- dataset constraints are ambiguous or contradictory
+- setup/reset cannot be executed safely
+
+## J. Safety Constraints
+- Hard block: never use production credentials or real PII
+- Warn only: warn when synthetic distributions are approximate

package/agents/commands/README.md

@@ -1,64 +0,0 @@
-# Deterministic Slash Command Contracts
-
-This directory is the modular source of truth for slash-command execution contracts.
-
-- Global protocol and safety framework: `AGENTS.MD` → `Deterministic Slash Command System Standard`
-- Global response schema: `agents/commands/SCHEMA.md`
-- Command contracts:
-  - `plan.md`
-  - `task.md`
-  - `fix.md`
-  - `audit.md`
-  - `perf.md`
-  - `test.md`
-  - `pr.md`
-  - `release.md`
-  - `docs.md`
-  - `problem-map.md`
-  - `scope-shape.md`
-  - `arch-check.md`
-  - `ux-bar.md`
-  - `debug-track.md`
-  - `risk-review.md`
-  - `release-ready.md`
-  - `learn-loop.md`
-
-Execution requirements:
-- Parse slash commands deterministically.
-- Return structured output only.
-- No conversational fallback in slash mode.
-- Enforce destructive confirmation token: `CONFIRM-DESTRUCTIVE:<target>`.
-- Enforce unique command purpose for each primary workflow command.
-
-## Command Integrity Guards
-
-- Primary workflow commands must have unique purpose identifiers.
-- Duplicate command purpose definitions fail CLI startup validation.
-- Deprecated aliases are not part of the active command surface.
-
-## Publish Inclusion
-
-The npm package includes command contracts from both:
-
-- `agents/commands/` (root mirror)
-- `templates/agents/commands/` (scaffold source)
-
-## Workflow Command Mapping
-
-Use these lifecycle commands as the recommended specialist sequence:
-
-- `problem-map` -> `plan.md`
-- `scope-shape` -> `plan.md`
-- `arch-check` -> `plan.md`
-- `ux-bar` -> `plan.md`
-- `debug-track` -> `fix.md`
-- `risk-review` -> `audit.md`
-- `perf` -> `perf.md`
-- `release-ready` -> `release.md`
-- `docs` -> `docs.md`
-- `learn-loop` -> `task.md`
-
-The CLI command `agents-templated workflow` prints this lifecycle in order:
-
-Think -> Plan -> Build -> Review -> Test -> Ship -> Reflect
-

package/agents/commands/SCHEMA.md

@@ -1,22 +0,0 @@
-# Slash Command Output Schema
-
-All slash command responses MUST include the following top-level fields:
-
-- `command`
-- `execution_id`
-- `mode`
-- `status`
-- `inputs`
-- `prechecks`
-- `execution_log`
-- `artifacts`
-- `risks`
-- `safety_checks`
-- `stop_condition`
-- `next_action`
-
-Constraints:
-- `mode` MUST be one of: `slash-command`, `slash-command-auto`.
-- `status` MUST be one of: `completed`, `blocked`, `failed`.
-- If a field value is unknown, set it to `null`.
-- Unknown or malformed slash commands MUST return structured error output and stop.

package/agents/commands/arch-check.md

@@ -1,58 +0,0 @@
-# /arch-check
-
-## A. Intent
-Validate architecture readiness and implementation constraints before build begins.
-
-## B. When to Use
-- Use after scope lock and before implementation starts.
-- Do not use for post-release retrospectives.
-
-## C. Context Assumptions
-- Scope is frozen for current increment.
-- Architecture options are documented.
-- Test strategy can be defined.
-
-## D. Required Inputs
-| Input | Type | Example |
-|---------------------|------------|----------------------------------|
-| `architecture_goal` | string | "multi-tenant API isolation" |
-| `design_options` | string[] | ["shared schema", "schema-per-tenant"] |
-| `design_artifact` | artifact | ADR doc, sequence diagram |
-
-## E. Pre-Execution Guards <- fail fast, check ALL before running
-- [ ] design options are comparable
-- [ ] key edge cases are identified
-- [ ] test strategy exists for selected design
-
-## F. Execution Flow
-1. Review architecture options and constraints.
-2. Evaluate edge cases and failure modes.
-3. Validate selected option against requirements.
-4. Decision point ->
-   - condition A -> critical gap found -> block readiness
-   - condition B ->  no critical gaps -> continue.
-5. Build architecture decision and test implications.
-6. Emit architecture readiness report.
-
-## G. Output Schema
-
-```json
-{
-  "architecture_id": "string",
-  "decisions": ["array","of","strings"],
-  "risk_level": "low | medium | high",
-  "blocker": "string | null"
-}
-```
-
-## H. Output Target
-- Default delivery: stdout
-- Override flag: --output=<target>
-
-## I. Stop Conditions <- abort with error message, never emit partial output
-- selected architecture lacks testable validation path
-- critical edge case has no mitigation
-
-## J. Safety Constraints
-- Hard block: hard block on architecture with unresolved critical failure modes
-- Warn only: warn when non-critical tradeoffs are accepted

package/agents/commands/audit.md

@@ -1,58 +0,0 @@
-# /audit
-
-## A. Intent
-Produce a deterministic risk and compliance audit with prioritized findings.
-
-## B. When to Use
-- Use before release or for targeted quality/security reviews.
-- Do not use as a substitute for implementation planning.
-
-## C. Context Assumptions
-- Audit scope is defined.
-- Relevant artifacts are available.
-- Severity rubric is agreed.
-
-## D. Required Inputs
-| Input | Type | Example |
-|---------------------|------------|----------------------------------|
-| `audit_scope` | string | "authentication flows" |
-| `checklist` | string[] | ["security", "tests", "rollback"] |
-| `evidence_set` | artifact | PR diff, logs, reports |
-
-## E. Pre-Execution Guards <- fail fast, check ALL before running
-- [ ] scope is explicit
-- [ ] evidence artifacts are accessible
-- [ ] severity model is available
-
-## F. Execution Flow
-1. Collect scoped evidence and standards.
-2. Evaluate checks against evidence.
-3. Classify findings by severity.
-4. Decision point ->
-   - condition A -> critical unresolved finding -> block recommendation
-   - condition B ->  no critical blocker -> continue.
-5. Assemble remediation actions and owners.
-6. Emit audit report.
-
-## G. Output Schema
-
-```json
-{
-  "audit_id": "string",
-  "findings": ["array","of","strings"],
-  "severity": "low | medium | high",
-  "blocker": "string | null"
-}
-```
-
-## H. Output Target
-- Default delivery: stdout
-- Override flag: --output=<target>
-
-## I. Stop Conditions <- abort with error message, never emit partial output
-- scope cannot be determined
-- critical evidence is missing
-
-## J. Safety Constraints
-- Hard block: hard block when critical finding lacks mitigation
-- Warn only: warn when medium findings are deferred

package/agents/commands/debug-track.md

@@ -1,58 +0,0 @@
-# /debug-track
-
-## A. Intent
-Run root-cause-first debugging workflow and guarantee evidence-backed defect diagnosis.
-
-## B. When to Use
-- Use when behavior is broken, failing, or regressing in runtime.
-- Do not use to apply speculative patches without diagnosis.
-
-## C. Context Assumptions
-- Defect symptom is captured.
-- A reproduction path is available or can be derived.
-- Runtime context is accessible.
-
-## D. Required Inputs
-| Input | Type | Example |
-|---------------------|------------|----------------------------------|
-| `defect_symptom` | string | "payment retries loop forever" |
-| `repro_steps` | string[] | ["submit order", "disconnect network"] |
-| `runtime_artifact` | artifact | error logs, trace screenshot, failing test |
-
-## E. Pre-Execution Guards <- fail fast, check ALL before running
-- [ ] reproduction path is actionable
-- [ ] evidence can be collected at runtime
-- [ ] investigation scope is bounded
-
-## F. Execution Flow
-1. Reproduce issue and capture trace.
-2. Follow execution and state transitions.
-3. Confirm root cause with evidence.
-4. Decision point ->
-   - condition A -> root cause unverified -> continue investigation
-   - condition B ->  verified -> continue.
-5. Draft minimal patch strategy and checks.
-6. Emit debug investigation report.
-
-## G. Output Schema
-
-```json
-{
-  "debug_id": "string",
-  "evidence": ["array","of","strings"],
-  "certainty": "low | medium | high",
-  "root_cause": "string | null"
-}
-```
-
-## H. Output Target
-- Default delivery: stdout
-- Override flag: --output=<target>
-
-## I. Stop Conditions <- abort with error message, never emit partial output
-- issue cannot be reproduced with available context
-- root cause cannot be evidenced
-
-## J. Safety Constraints
-- Hard block: hard block on symptom-only fixes without diagnosis
-- Warn only: warn when reproduction is intermittent

package/agents/commands/docs.md

@@ -1,58 +0,0 @@
-# /docs
-
-## A. Intent
-Create deterministic documentation outputs aligned with current implementation behavior.
-
-## B. When to Use
-- Use when generating or updating docs as a direct deliverable.
-- Do not use for release decision making.
-
-## C. Context Assumptions
-- Source behavior is known.
-- Target audience is defined.
-- Doc destination is available.
-
-## D. Required Inputs
-| Input | Type | Example |
-|---------------------|------------|----------------------------------|
-| `doc_scope` | string | "API auth endpoints" |
-| `source_refs` | string[] | ["src/auth.ts", "openapi.yaml"] |
-| `doc_artifact` | artifact | existing README path or docs URL |
-
-## E. Pre-Execution Guards <- fail fast, check ALL before running
-- [ ] scope is explicit
-- [ ] source refs are accessible
-- [ ] destination path is writable
-
-## F. Execution Flow
-1. Collect implementation references.
-2. Draft structured documentation content.
-3. Validate examples and references.
-4. Decision point ->
-   - condition A -> mismatch with implementation -> revise doc content
-   - condition B ->  aligned -> continue.
-5. Assemble final documentation package.
-6. Emit documentation output.
-
-## G. Output Schema
-
-```json
-{
-  "doc_id": "string",
-  "updated_sections": ["array","of","strings"],
-  "confidence": "low | medium | high",
-  "gap": "string | null"
-}
-```
-
-## H. Output Target
-- Default delivery: file
-- Override flag: --output=<target>
-
-## I. Stop Conditions <- abort with error message, never emit partial output
-- source references are unavailable
-- critical behavior cannot be documented accurately
-
-## J. Safety Constraints
-- Hard block: hard block on knowingly incorrect implementation claims
-- Warn only: warn when sections remain TODO with owner

package/agents/commands/fix.md

@@ -1,58 +0,0 @@
-# /fix
-
-## A. Intent
-Apply the smallest safe code fix with regression evidence and bounded impact.
-
-## B. When to Use
-- Use after root cause is confirmed and a targeted fix is required.
-- Do not use when defect cause is still speculative.
-
-## C. Context Assumptions
-- Issue is reproducible or sufficiently evidenced.
-- Root cause has been identified.
-- Regression checks are available.
-
-## D. Required Inputs
-| Input | Type | Example |
-|---------------------|------------|----------------------------------|
-| `defect_id` | string | "BUG-142" |
-| `affected_paths` | string[] | ["src/auth.ts", "tests/auth.test.ts"] |
-| `evidence` | artifact | stack trace, failing test output, screenshot |
-
-## E. Pre-Execution Guards <- fail fast, check ALL before running
-- [ ] root cause evidence is present
-- [ ] fix scope is bounded
-- [ ] regression checks are defined
-
-## F. Execution Flow
-1. Read defect evidence and failing paths.
-2. Implement minimal change set.
-3. Run targeted validations.
-4. Decision point ->
-   - condition A -> validation fails -> iterate fix or abort
-   - condition B ->  validation passes -> continue.
-5. Prepare change rationale and impact summary.
-6. Emit fix package with evidence.
-
-## G. Output Schema
-
-```json
-{
-  "fix_id": "string",
-  "changed_files": ["array","of","strings"],
-  "risk": "low | medium | high",
-  "rollback_note": "string | null"
-}
-```
-
-## H. Output Target
-- Default delivery: stdout
-- Override flag: --output=<target>
-
-## I. Stop Conditions <- abort with error message, never emit partial output
-- no verified root-cause evidence
-- regression validation unavailable for critical path
-
-## J. Safety Constraints
-- Hard block: no broad refactor inside fix-only workflow
-- Warn only: warn when temporary workaround is used

package/agents/commands/learn-loop.md

@@ -1,58 +0,0 @@
-# /learn-loop
-
-## A. Intent
-Capture deterministic retrospective outcomes and convert lessons into next-cycle actions.
-
-## B. When to Use
-- Use after delivery milestones, incidents, or release cycles.
-- Do not use for pre-implementation planning.
-
-## C. Context Assumptions
-- Cycle outcome data is available.
-- Owners for follow-up actions can be assigned.
-- Retrospective scope is defined.
-
-## D. Required Inputs
-| Input | Type | Example |
-|---------------------|------------|----------------------------------|
-| `cycle_name` | string | "Sprint 18" |
-| `observations` | string[] | ["test flakiness", "scope churn"] |
-| `evidence_artifact` | artifact | metrics dashboard, incident notes, PR links |
-
-## E. Pre-Execution Guards <- fail fast, check ALL before running
-- [ ] observations are evidence-backed
-- [ ] action owners can be assigned
-- [ ] follow-up window is defined
-
-## F. Execution Flow
-1. Collect outcomes, wins, and misses.
-2. Identify root process issues and patterns.
-3. Prioritize actionable improvements.
-4. Decision point ->
-   - condition A -> no actionable item -> request clearer observations
-   - condition B ->  actionable set ready -> continue.
-5. Map actions to owners and timelines.
-6. Emit learn-loop action report.
-
-## G. Output Schema
-
-```json
-{
-  "loop_id": "string",
-  "actions": ["array","of","strings"],
-  "urgency": "low | medium | high",
-  "blocker": "string | null"
-}
-```
-
-## H. Output Target
-- Default delivery: stdout
-- Override flag: --output=<target>
-
-## I. Stop Conditions <- abort with error message, never emit partial output
-- retrospective inputs are anecdotal without evidence
-- no owner can be assigned to critical actions
-
-## J. Safety Constraints
-- Hard block: hard block on publishing blame-focused output without actionable remediation
-- Warn only: warn when metrics are incomplete but direction is still usable