agents-templated 2.2.11 → 2.2.13

package/templates/agents/commands/README.md

@@ -7,9 +7,7 @@ This directory is the modular source of truth for slash-command execution contra
 - Command contracts:
   - `plan.md`
   - `task.md`
-  - `scaffold.md`
   - `fix.md`
-  - `refactor.md`
   - `audit.md`
   - `perf.md`
   - `test.md`
@@ -21,11 +19,9 @@ 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`
-  - `quality-gate.md`
-  - `perf-scan.md`
   - `release-ready.md`
-  - `docs-sync.md`
   - `learn-loop.md`
 
 Execution requirements:
@@ -57,14 +53,91 @@ 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`
-- `quality-gate` -> `test.md`
-- `perf-scan` -> `perf.md`
+- `perf` -> `perf.md`
 - `release-ready` -> `release.md`
-- `docs-sync` -> `docs.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
 
+## 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/arch-check.md

@@ -1,33 +1,58 @@
-# /arch-check
-
-## A. Intent
-Validate architecture decisions, dependency boundaries, and failure handling before coding.
-
-## B. When to Use
-Use after scope lock and before implementation starts.
-
-## C. Required Inputs
-- Scoped feature set
-- Existing system boundaries
-- Non-functional requirements
-
-## D. Deterministic Execution Flow
-1. Map data and control flow.
-2. Identify component boundaries.
-3. Enumerate failure modes.
-4. Define testing and validation checkpoints.
-5. Emit architecture decision set.
-
-## E. Structured Output Template
-- `architecture_summary`
-- `boundaries[]`
-- `data_flow`
-- `failure_modes[]`
-- `validation_plan[]`
-
-## F. Stop Conditions
-- Critical dependency unclear.
-- Failure modes not covered.
-
-## G. Safety Constraints
-- Include security and testing gates for each critical path.
+# /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/templates/agents/commands/audit.md

@@ -1,38 +1,58 @@
-# /audit
-
-## A. Intent
-Run structured engineering audit across security, correctness, and maintainability.
-
-## B. When to Use
-Use before high-impact merges, releases, and external reviews.
-
-## C. Required Inputs
-- Audit scope
-- Risk profile
-- Compliance baseline
-- Hardening profile requirement (if applicable)
-
-## D. Deterministic Execution Flow
-1. Resolve audit scope.
-2. Run static checks.
-3. Run security checks.
-4. Run dependency/config checks.
-5. Verify hardening evidence when hardening-required profile applies.
-6. Classify findings by severity.
-7. Emit audit report.
-
-## E. Structured Output Template
-- `scope`
-- `checks_executed[]`
-- `findings[]`
-- `severity_summary`
-- `remediation_plan[]`
-- `hardening_evidence_status`
-
-## F. Stop Conditions
-- Inaccessible scope.
-- Unavailable tooling.
-
-## G. Safety Constraints
-- Classify secret leaks and auth bypass as critical.
-- Classify missing hardening verification evidence as release-blocking when hardening is required.
+# /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/templates/agents/commands/debug-track.md

@@ -1,33 +1,58 @@
-# /debug-track
-
-## A. Intent
-Produce a root-cause-first defect investigation path with bounded fixes.
-
-## B. When to Use
-Use for bugs, regressions, and unexpected runtime behavior.
-
-## C. Required Inputs
-- Defect symptom
-- Reproduction context
-- Expected behavior
-
-## D. Deterministic Execution Flow
-1. Reproduce defect consistently.
-2. Trace data and execution path.
-3. Confirm root cause with evidence.
-4. Propose minimal patch.
-5. Validate fix and regression safety.
-
-## E. Structured Output Template
-- `reproduction_steps[]`
-- `root_cause`
-- `affected_surface[]`
-- `patch_plan`
-- `regression_checks[]`
-
-## F. Stop Conditions
-- Defect not reproducible.
-- Root cause remains unverified.
-
-## G. Safety Constraints
-- Do not patch symptoms without root-cause evidence.
+# /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/templates/agents/commands/docs.md

@@ -1,34 +1,58 @@
-# /docs
-
-## A. Intent
-Generate or update documentation aligned to implemented behavior.
-
-## B. When to Use
-Use when code, APIs, operations, or workflows change.
-
-## C. Required Inputs
-- Documentation scope
-- Source changes
-- Target audience
-
-## D. Deterministic Execution Flow
-1. Resolve source-of-truth artifacts.
-2. Extract behavior and API deltas.
-3. Map deltas to sections.
-4. Apply concise updates.
-5. Validate examples/commands.
-6. Emit docs change report.
-
-## E. Structured Output Template
-- `scope`
-- `sources[]`
-- `sections_updated[]`
-- `example_validation`
-- `follow_up_actions[]`
-
-## F. Stop Conditions
-- Missing source artifacts.
-- Unresolved ambiguity.
-
-## G. Safety Constraints
-- Do not publish secrets, tokens, or credentials.
+# /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/templates/agents/commands/fix.md

@@ -1,34 +1,58 @@
-# /fix
-
-## A. Intent
-Apply the smallest safe change that resolves a verified defect.
-
-## B. When to Use
-Use for bugs with reproducible evidence.
-
-## C. Required Inputs
-- Defect description
-- Reproduction evidence
-- Target scope
-
-## D. Deterministic Execution Flow
-1. Validate defect evidence.
-2. Reproduce failure.
-3. Locate root cause.
-4. Generate minimal patch.
-5. Execute targeted validation.
-6. Emit fix report.
-
-## E. Structured Output Template
-- `defect_id`
-- `root_cause`
-- `patch_summary`
-- `files_changed[]`
-- `validation_results[]`
-
-## F. Stop Conditions
-- Non-reproducible failure.
-- Root cause unresolved.
-
-## G. Safety Constraints
-- Do not broaden scope beyond defect boundary.
+# /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