agents-templated 2.2.11 → 2.2.12

package/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/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

package/agents/commands/pr.md

@@ -1,35 +1,58 @@
-# /pr
-
-## A. Intent
-Prepare a deterministic pull request payload with implementation evidence.
-
-## B. When to Use
-Use after validated changes are ready for review.
-
-## C. Required Inputs
-- Change summary
-- Linked issues/tasks
-- Validation evidence
-
-## D. Deterministic Execution Flow
-1. Collect changed files.
-2. Summarize intent and impact.
-3. Attach validation evidence.
-4. Classify risk and rollout impact.
-5. Build reviewer checklist.
-6. Emit PR package.
-
-## E. Structured Output Template
-- `title`
-- `summary`
-- `files_changed[]`
-- `validation_evidence[]`
-- `risk_assessment`
-- `review_checklist[]`
-
-## F. Stop Conditions
-- Missing validation evidence.
-- Open critical findings.
-
-## G. Safety Constraints
-- Block PR package when critical issues remain unresolved.
+# /pr
+
+## A. Intent
+Prepare a deterministic pull request package with implementation and validation evidence.
+
+## B. When to Use
+- Use after code changes and validation are complete and review package is needed.
+- Do not use when critical findings are still unresolved.
+
+## C. Context Assumptions
+- Change set exists.
+- Validation evidence is available.
+- Linked issue/task context is known.
+
+## D. Required Inputs
+| Input | Type | Example |
+|---------------------|------------|----------------------------------|
+| `change_summary` | string | "add retry policy to webhook worker" |
+| `linked_items` | string[] | ["ISSUE-18", "TASK-42"] |
+| `validation_evidence` | artifact | test report, benchmark output, screenshot |
+
+## E. Pre-Execution Guards <- fail fast, check ALL before running
+- [ ] change summary is complete
+- [ ] linked items are resolvable
+- [ ] validation evidence is present
+
+## F. Execution Flow
+1. Collect changed files and linked references.
+2. Summarize intent, impact, and scope.
+3. Attach validation and risk evidence.
+4. Decision point ->
+   - condition A -> critical blocker open -> abort PR package
+   - condition B ->  no blocker -> continue.
+5. Build reviewer checklist and rollout notes.
+6. Emit PR payload.
+
+## G. Output Schema
+
+```json
+{
+  "title": "string",
+  "files_changed": ["array","of","strings"],
+  "risk_assessment": "low | medium | high",
+  "blockers": "string | null"
+}
+```
+
+## H. Output Target
+- Default delivery: stdout
+- Override flag: --output=<target>
+
+## I. Stop Conditions <- abort with error message, never emit partial output
+- validation evidence missing for critical changes
+- open critical findings remain unresolved
+
+## J. Safety Constraints
+- Hard block: hard block if critical issues remain
+- Warn only: warn when non-critical follow-up items are deferred

package/agents/commands/problem-map.md

@@ -1,33 +1,58 @@
-# /problem-map
-
-## A. Intent
-Define the actual user problem and measurable pain signals before solutioning.
-
-## B. When to Use
-Use at the start of an initiative when the request is a feature idea rather than a validated problem.
-
-## C. Required Inputs
-- Problem statement
-- Current user pain examples
-- Target user segment
-
-## D. Deterministic Execution Flow
-1. Extract user outcomes and friction points.
-2. Separate symptoms from root pain.
-3. Identify constraints and non-goals.
-4. Propose a focused problem frame.
-5. Emit acceptance signals for success.
-
-## E. Structured Output Template
-- `problem_frame`
-- `pain_signals[]`
-- `root_causes[]`
-- `target_user_segment`
-- `success_signals[]`
-
-## F. Stop Conditions
-- Missing target user segment.
-- No concrete pain evidence provided.
-
-## G. Safety Constraints
-- Do not lock implementation details in this stage.
+# /problem-map
+
+## A. Intent
+Frame the real user problem and guarantee a clear problem statement before planning.
+
+## B. When to Use
+- Use at the start of a feature cycle when pain points are unclear or broad.
+- Do not use for implementation details or code-level debugging.
+
+## C. Context Assumptions
+- User objective is available.
+- Stakeholder context can be collected.
+- Outcome can be stated as a measurable problem.
+
+## D. Required Inputs
+| Input | Type | Example |
+|---------------------|------------|----------------------------------|
+| `user_problem` | string | "onboarding drop-off at step 2" |
+| `signals` | string[] | ["support tickets", "analytics"] |
+| `evidence_artifact` | artifact | funnel screenshot, issue links |
+
+## E. Pre-Execution Guards <- fail fast, check ALL before running
+- [ ] problem statement is concrete
+- [ ] signals support the stated pain
+- [ ] scope remains problem-focused
+
+## F. Execution Flow
+1. Collect user pain signals and context.
+2. Synthesize candidate problem statements.
+3. Validate statement against evidence.
+4. Decision point ->
+   - condition A -> weak evidence -> request stronger signals
+   - condition B ->  strong evidence -> continue.
+5. Produce framed problem and success criteria.
+6. Emit problem map package.
+
+## G. Output Schema
+
+```json
+{
+  "problem_id": "string",
+  "core_pains": ["array","of","strings"],
+  "urgency": "low | medium | high",
+  "unknowns": "string | null"
+}
+```
+
+## H. Output Target
+- Default delivery: stdout
+- Override flag: --output=<target>
+
+## I. Stop Conditions <- abort with error message, never emit partial output
+- problem statement remains vague
+- evidence contradicts proposed framing
+
+## J. Safety Constraints
+- Hard block: hard block on fabricated assumptions presented as facts
+- Warn only: warn when evidence quality is limited

package/agents/commands/release-ready.md

@@ -1,33 +1,58 @@
-# /release-ready
-
-## A. Intent
-Validate release readiness with checks for quality, risk, and rollback.
-
-## B. When to Use
-Use immediately before opening or merging a release PR.
-
-## C. Required Inputs
-- Change summary
-- Validation evidence
-- Deployment path
-
-## D. Deterministic Execution Flow
-1. Confirm test and quality gate outcomes.
-2. Confirm risk-review status.
-3. Verify migration and deploy prerequisites.
-4. Verify rollback plan.
-5. Emit release readiness decision.
-
-## E. Structured Output Template
-- `release_scope`
-- `checks_passed[]`
-- `blocking_issues[]`
-- `rollback_plan`
-- `ready_status`
-
-## F. Stop Conditions
-- Blocking issue unresolved.
-- Rollback plan absent.
-
-## G. Safety Constraints
-- Do not approve release when required evidence is missing.
+# /release-ready
+
+## A. Intent
+Validate pre-release readiness gates and guarantee deploy prerequisites are satisfied.
+
+## B. When to Use
+- Use after implementation/tests/risk review and before final release decision.
+- Do not use to execute deployment itself.
+
+## C. Context Assumptions
+- Release candidate exists.
+- All required gate outputs are available.
+- Rollout and rollback plans are drafted.
+
+## D. Required Inputs
+| Input | Type | Example |
+|---------------------|------------|----------------------------------|
+| `candidate_version` | string | "v2.4.0-rc1" |
+| `gate_artifacts` | string[] | ["test", "risk-review", "perf-scan"] |
+| `release_artifact` | artifact | release checklist, migration plan |
+
+## E. Pre-Execution Guards <- fail fast, check ALL before running
+- [ ] mandatory gates are present
+- [ ] critical blockers are resolved
+- [ ] rollback steps are executable
+
+## F. Execution Flow
+1. Collect gate evidence for candidate.
+2. Validate checklist completion.
+3. Verify rollout and rollback readiness.
+4. Decision point ->
+   - condition A -> missing mandatory gate -> block readiness
+   - condition B ->  all gates complete -> continue.
+5. Assemble readiness summary and open items.
+6. Emit release-ready report.
+
+## G. Output Schema
+
+```json
+{
+  "readiness_id": "string",
+  "gate_status": ["array","of","strings"],
+  "readiness_risk": "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
+- mandatory gate missing or failed
+- rollback execution path is unverified
+
+## J. Safety Constraints
+- Hard block: hard block when release checklist is incomplete on critical items
+- Warn only: warn when non-critical items are deferred

package/agents/commands/release.md

@@ -1,39 +1,58 @@
-# /release
-
-## A. Intent
-Produce deterministic release readiness decision and rollout contract.
-
-## B. When to Use
-Use when promoting validated changes to release channels.
-
-## C. Required Inputs
-- Version/tag
-- Change manifest
-- Rollback strategy
-- Hardening verification evidence (when required by risk profile)
-
-## D. Deterministic Execution Flow
-1. Validate release prerequisites.
-2. Validate compatibility and migration risks.
-3. Validate security and test gates.
-4. Validate hardening verification evidence when hardening-required profile applies.
-5. Build release notes.
-6. Build rollout and rollback steps.
-7. Emit release contract.
-
-## E. Structured Output Template
-- `version`
-- `release_readiness`
-- `gates[]`
-- `rollout_plan[]`
-- `rollback_plan[]`
-- `release_notes`
-- `hardening_verification`
-
-## F. Stop Conditions
-- Gate failure.
-- Missing rollback strategy.
-
-## G. Safety Constraints
-- Block release when any critical gate fails.
-- Block release when required hardening evidence is missing.
+# /release
+
+## A. Intent
+Generate deterministic release decision package with rollout and rollback readiness.
+
+## B. When to Use
+- Use when deciding whether to ship to production.
+- Do not use before release-ready checks are complete.
+
+## C. Context Assumptions
+- Release candidate is identified.
+- Pre-release checks are completed.
+- Rollback strategy is defined.
+
+## D. Required Inputs
+| Input | Type | Example |
+|---------------------|------------|----------------------------------|
+| `version` | string | "v2.4.0" |
+| `gate_results` | string[] | ["tests-pass", "risk-review-pass"] |
+| `release_artifacts` | artifact | release notes draft, migration plan |
+
+## E. Pre-Execution Guards <- fail fast, check ALL before running
+- [ ] version is valid and unique
+- [ ] required gates are complete
+- [ ] rollback plan exists
+
+## F. Execution Flow
+1. Collect gate outputs and release artifacts.
+2. Validate rollout and rollback prerequisites.
+3. Classify release risk.
+4. Decision point ->
+   - condition A -> high unresolved risk -> block release
+   - condition B ->  acceptable risk -> continue.
+5. Build release decision and communication payload.
+6. Emit release package.
+
+## G. Output Schema
+
+```json
+{
+  "release_id": "string",
+  "gates": ["array","of","strings"],
+  "release_risk": "low | medium | high",
+  "rollback_status": "string | null"
+}
+```
+
+## H. Output Target
+- Default delivery: stdout
+- Override flag: --output=<target>
+
+## I. Stop Conditions <- abort with error message, never emit partial output
+- required gate missing or failed
+- rollback plan is undefined
+
+## J. Safety Constraints
+- Hard block: hard block on unresolved high-severity release risks
+- Warn only: warn when rollout is phased due to uncertainty

package/agents/commands/risk-review.md

@@ -1,33 +1,58 @@
-# /risk-review
-
-## A. Intent
-Identify release risks that may pass CI but fail in production.
-
-## B. When to Use
-Use before merge or release candidate approval.
-
-## C. Required Inputs
-- Proposed changes
-- Test and validation status
-- Deployment context
-
-## D. Deterministic Execution Flow
-1. Inspect behavior deltas.
-2. Rank risks by impact and likelihood.
-3. Validate mitigation or rollback paths.
-4. Identify missing tests.
-5. Emit ship recommendation.
-
-## E. Structured Output Template
-- `risk_findings[]`
-- `severity_summary`
-- `mitigations[]`
-- `rollback_readiness`
-- `release_recommendation`
-
-## F. Stop Conditions
-- High-severity risk has no mitigation.
-- Rollback path is undefined.
-
-## G. Safety Constraints
-- Block release for unresolved high-severity findings.
+# /risk-review
+
+## A. Intent
+Perform deterministic release risk review with mitigation and rollback readiness.
+
+## B. When to Use
+- Use before merge or release approval on non-trivial changes.
+- Do not use as a substitute for running tests.
+
+## C. Context Assumptions
+- Change set is available.
+- Validation evidence exists.
+- Deployment context is known.
+
+## D. Required Inputs
+| Input | Type | Example |
+|---------------------|------------|----------------------------------|
+| `change_set` | string | "payment retry + queue changes" |
+| `validation_status` | string[] | ["unit pass", "integration pass"] |
+| `deployment_artifact` | artifact | rollout plan, env config snapshot |
+
+## E. Pre-Execution Guards <- fail fast, check ALL before running
+- [ ] change set is fully described
+- [ ] validation status is current
+- [ ] rollback path is defined
+
+## F. Execution Flow
+1. Inspect behavior deltas and blast radius.
+2. Rank risks by impact and likelihood.
+3. Validate mitigations and rollback readiness.
+4. Decision point ->
+   - condition A -> high unresolved risk -> block recommendation
+   - condition B ->  acceptable risk -> continue.
+5. Build release risk summary and actions.
+6. Emit risk review report.
+
+## G. Output Schema
+
+```json
+{
+  "review_id": "string",
+  "risks": ["array","of","strings"],
+  "risk_level": "low | medium | high",
+  "recommendation": "string | null"
+}
+```
+
+## H. Output Target
+- Default delivery: stdout
+- Override flag: --output=<target>
+
+## I. Stop Conditions <- abort with error message, never emit partial output
+- high-severity risk has no mitigation
+- rollback readiness is undefined
+
+## J. Safety Constraints
+- Hard block: hard block on unresolved high-severity risks
+- Warn only: warn when medium risks are accepted with owner