agents-templated 2.2.11 → 2.2.12

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

package/templates/agents/commands/learn-loop.md

@@ -1,33 +1,58 @@
-# /learn-loop
-
-## A. Intent
-Capture delivery lessons and convert them into concrete next-cycle actions.
-
-## B. When to Use
-Use after release or milestone completion.
-
-## C. Required Inputs
-- Completed work summary
-- Incident/defect outcomes
-- Team or process observations
-
-## D. Deterministic Execution Flow
-1. Summarize wins and misses.
-2. Identify repeated friction points.
-3. Propose concrete process and tooling actions.
-4. Assign ownership and priority.
-5. Emit next-cycle action list.
-
-## E. Structured Output Template
-- `wins[]`
-- `misses[]`
-- `root_process_issues[]`
-- `next_actions[]`
-- `owner_map`
-
-## F. Stop Conditions
-- No actionable next steps.
-- Lessons are not tied to observable outcomes.
-
-## G. Safety Constraints
-- Avoid vague retrospectives without owned follow-through actions.
+# /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

package/templates/agents/commands/perf.md

@@ -1,34 +1,58 @@
-# /perf
-
-## A. Intent
-Evaluate and optimize performance using measurable baselines.
-
-## B. When to Use
-Use when latency, throughput, memory, or build-time regressions are reported.
-
-## C. Required Inputs
-- Target metrics
-- Baseline environment
-- Optimization scope
-
-## D. Deterministic Execution Flow
-1. Capture baseline metrics.
-2. Identify bottlenecks.
-3. Apply one optimization unit.
-4. Re-measure metrics.
-5. Compare against baseline.
-6. Emit performance report.
-
-## E. Structured Output Template
-- `baseline_metrics`
-- `optimization_units[]`
-- `post_metrics`
-- `regression_check`
-- `recommendation`
-
-## F. Stop Conditions
-- Missing baseline metrics.
-- Non-reproducible benchmark.
-
-## G. Safety Constraints
-- Do not trade security controls for performance.
+# /perf
+
+## A. Intent
+Define and execute deterministic performance optimization workflow against known baselines.
+
+## B. When to Use
+- Use when improving latency, throughput, or resource efficiency.
+- Do not use for one-off smoke checks; use /perf-scan for quick regression comparison.
+
+## C. Context Assumptions
+- Baseline metrics exist or can be captured.
+- Performance target is defined.
+- Measurement method is repeatable.
+
+## D. Required Inputs
+| Input | Type | Example |
+|---------------------|------------|----------------------------------|
+| `performance_goal` | string | "p95 latency under 200ms" |
+| `baseline_metrics` | string[] | ["p95=260ms", "cpu=70%"] |
+| `benchmark_artifact` | artifact | profiling report or benchmark output |
+
+## E. Pre-Execution Guards <- fail fast, check ALL before running
+- [ ] goal is measurable
+- [ ] baseline metric set is present
+- [ ] benchmark method is consistent
+
+## F. Execution Flow
+1. Capture or validate baseline metrics.
+2. Apply targeted optimization changes.
+3. Measure post-change metrics.
+4. Decision point ->
+   - condition A -> target unmet -> iterate optimization
+   - condition B ->  target met -> continue.
+5. Summarize gains, tradeoffs, and risks.
+6. Emit performance optimization report.
+
+## G. Output Schema
+
+```json
+{
+  "perf_run_id": "string",
+  "metrics": ["array","of","strings"],
+  "impact": "low | medium | high",
+  "regression": "string | null"
+}
+```
+
+## H. Output Target
+- Default delivery: stdout
+- Override flag: --output=<target>
+
+## I. Stop Conditions <- abort with error message, never emit partial output
+- baseline cannot be measured reliably
+- measurement method is non-deterministic
+
+## J. Safety Constraints
+- Hard block: do not trade correctness/security for performance gains
+- Warn only: warn when gains are within noise threshold

package/templates/agents/commands/plan.md

@@ -1,34 +1,58 @@
-# /plan
-
-## A. Intent
-Generate an executable implementation plan with ordered steps and risk controls.
-
-## B. When to Use
-Use for non-trivial work requiring sequencing, dependencies, and checkpoints.
-
-## C. Required Inputs
-- Objective
-- Scope boundaries
-- Constraints
-
-## D. Deterministic Execution Flow
-1. Parse objective and constraints.
-2. Extract atomic work units.
-3. Compute dependency order.
-4. Attach validation checkpoints.
-5. Attach risk and rollback notes.
-6. Emit plan artifacts.
-
-## E. Structured Output Template
-- `plan_summary`
-- `work_units[]`
-- `dependency_graph`
-- `validation_checkpoints[]`
-- `risk_register[]`
-
-## F. Stop Conditions
-- Missing objective or scope.
-- Contradictory constraints.
-
-## G. Safety Constraints
-- Include security and testing gates for code-changing units.
+# /plan
+
+## A. Intent
+Build a deterministic implementation plan with scoped phases and acceptance checks.
+
+## B. When to Use
+- Use when a feature or change request is approved for planning before coding starts.
+- Do not use for post-incident debugging; use /debug-track instead.
+
+## C. Context Assumptions
+- Problem statement and objective are available.
+- Primary stakeholders and delivery window are known.
+- Scope boundaries can be explicitly defined.
+
+## D. Required Inputs
+| Input | Type | Example |
+|---------------------|------------|----------------------------------|
+| `objective` | string | "Ship onboarding v2" |
+| `constraints` | string[] | ["2-week deadline", "no schema rewrite"] |
+| `references` | artifact | PRD link, issue URL, screenshot |
+
+## E. Pre-Execution Guards <- fail fast, check ALL before running
+- [ ] objective is non-empty and testable
+- [ ] constraints are explicit and non-contradictory
+- [ ] required references are accessible
+
+## F. Execution Flow
+1. Collect requirements and constraints.
+2. Split work into ordered phases and milestones.
+3. Attach measurable acceptance criteria per phase.
+4. Decision point ->
+   - condition A -> phase risk > threshold -> add mitigation gate
+   - condition B ->  otherwise -> continue with baseline plan.
+5. Assemble plan artifacts and dependency map.
+6. Emit final plan package.
+
+## G. Output Schema
+
+```json
+{
+  "plan_id": "string",
+  "phases": ["array","of","strings"],
+  "risk_level": "low | medium | high",
+  "notes": "string | null"
+}
+```
+
+## H. Output Target
+- Default delivery: stdout
+- Override flag: --output=<target>
+
+## I. Stop Conditions <- abort with error message, never emit partial output
+- any guard in section E fails
+- acceptance criteria cannot be made measurable
+
+## J. Safety Constraints
+- Hard block: no hidden scope expansion beyond declared boundaries
+- Warn only: allow proceed with warning when estimate confidence is low