agents-templated 2.2.9 → 2.2.11

package/templates/README.md

@@ -9,48 +9,45 @@
 
 ---
 
-## What is Agents Templated?
+## Why This Package Exists
 
-Agents Templated scaffolds your project with:
+Most starter templates only create files. This package creates operating rules for how teams build, review, test, and ship.
 
-✅ **AI Agent Configurations** – Auto-discovery files for 4 major AI coding assistants  
-✅ **Security-First Patterns** – OWASP Top 10 protection guidelines built-in  
-✅ **Testing Strategy** – 80/15/5 coverage targets (unit/integration/e2e)  
-✅ **Agent-Based Architecture** – Specialized patterns for frontend, backend, database, testing, security  
-✅ **Technology-Agnostic** – Works with React, Django, Go, FastAPI, Next.js, or any stack you choose
+You get:
 
-**Important:** This package does **NOT** install frameworks or libraries. It scaffolds the structure, patterns, and AI configurations—you install your chosen tech stack separately.
+- Multi-agent configuration for Cursor, Copilot, Claude, and generic hosts
+- Deterministic command contracts in `agents/commands/`
+- Security-first and testing-first rule baselines
+- Reusable skills and optional subagents
 
----
+Important: this package does not install your framework. It installs the operating layer around your framework.
 
-## 🚀 Quick Start
+## 30-Second Start
 
-### 1. Run the Interactive Wizard (Recommended)
+### 1. Install setup
 
 ```bash
-# Using npx (no installation needed) - RECOMMENDED
 npx agents-templated@latest wizard
+```
 
-# Or install globally first
-npm install -g agents-templated
-agents-templated wizard
+### 2. Start the command workflow
+
+```bash
+agents-templated workflow
+agents-templated problem-map "daily briefing assistant for founders"
 ```
 
-**Or use a preset for fast setup:**
+### 3. Optional preset bootstrap
 
 ```bash
-# Initialize with a specific preset
 npx agents-templated@latest init --preset=nextjs        # Next.js
 npx agents-templated@latest init --preset=express-api   # Express
 npx agents-templated@latest init --preset=django-react  # Django
 npx agents-templated@latest init --preset=fastapi       # FastAPI
 npx agents-templated@latest init --preset=go-api        # Go
-
-# Or install all components without a preset
-npx agents-templated@latest init --all
 ```
 
-### 2. Install Your Tech Stack
+### 4. Install your tech stack
 
 After initializing, install your chosen framework:
 
@@ -72,44 +69,58 @@ pip install sqlalchemy alembic                # SQLAlchemy
 npm install mongoose                          # Mongoose (MongoDB)
 ```
 
-### 3. Start Coding with AI
+### 5. Run the specialist sequence
+
+Start with a product objective, then move through specialist commands:
+
+```bash
+agents-templated workflow
+agents-templated problem-map "daily briefing assistant for founders"
+agents-templated scope-shape "scope the first release"
+agents-templated risk-review "audit branch changes before merge"
+agents-templated release-ready "prepare release checklist"
+```
+
+### 6. Start Coding with AI
 
 Your AI assistant will auto-load the configurations and follow enterprise patterns automatically!
 
 ---
 
-## ✨ Key Features
+## Key Features
 
 | Feature | Description |
 |---------|-------------|
-| 🚀 **Quick Start Presets** | 5 popular tech stack presets (Next.js, Express, Django, FastAPI, Go) |
-| 🧙 **Interactive Wizard** | Guided setup with personalized recommendations |
-| 🤖 **AI Agents Supported** | Cursor, GitHub Copilot, Claude, and generic agents via `AGENTS.MD` |
-| 🔒 **Security-First** | OWASP Top 10 protection patterns built-in |
-| 🧪 **Testing Strategy** | 80/15/5 coverage targets (unit/integration/e2e) |
-| ✅ **Project Validation** | `validate` and `doctor` commands for health checks |
-| 🔄 **Template Updates** | Keep your templates in sync with `update` command |
-| 🎯 **Technology-Agnostic** | Works with React, Django, Go, FastAPI, Next.js, or any stack |
-| ♿ **Accessibility** | WCAG 2.1 AA compliance patterns included |
+| **Quick Start Presets** | 5 popular tech stack presets (Next.js, Express, Django, FastAPI, Go) |
+| **Interactive Wizard** | Guided setup with personalized recommendations |
+| **Deterministic Commands** | Slash-command contracts with strict structured outputs |
+| **Intent-Routing Ready** | Command schema supports `slash-command-auto` mode for agent-side routing policies |
+| **Security-First** | OWASP Top 10 protection patterns built-in |
+| **Hardening Workflow** | Risk-based hardening rules plus verification/release gates |
+| **Testing Strategy** | 80/15/5 coverage targets (unit/integration/e2e) |
+| **Project Validation** | `validate` and `doctor` commands for health checks |
+| **Template Updates** | Keep your templates in sync with `update` command |
+| **Technology-Agnostic** | Works with React, Django, Go, FastAPI, Next.js, or any stack |
+| **Accessibility** | WCAG 2.1 AA compliance patterns included |
 
 ---
 
-## 🤖 AI Agent Support
+## AI Agent Support
 
 Agents Templated automatically configures compatible wrappers for major AI coding assistants:
 
 | AI Agent | Config File | Auto-Discovery |
 |----------|-------------|----------------|
-| **Cursor** | `.cursorrules` | ✅ Auto-loads in Cursor IDE |
-| **GitHub Copilot** | `.github/copilot-instructions.md` | ✅ Auto-loads in VS Code |
-| **Claude** | `CLAUDE.md` | ✅ Compatible |
-| **Generic agents** | `AGENTS.MD` | ✅ Compatible |
+| **Cursor** | `.cursorrules` | Auto-loads in Cursor IDE |
+| **GitHub Copilot** | `.github/copilot-instructions.md` | Auto-loads in VS Code |
+| **Claude** | `CLAUDE.md` | Compatible |
+| **Generic agents** | `AGENTS.MD` | Compatible |
 
 **Single source of truth:** `CLAUDE.md` drives generated tool-compatible instruction files.
 
 ---
 
-## 📦 What Gets Installed
+## What Gets Installed
 
 When you run `agents-templated init`, you get:
 
@@ -119,14 +130,17 @@ your-project/
 │   └── source/
 │       └── core.md               # Canonical instruction source of truth
 │
-├── agent-docs/                      # 📚 Comprehensive documentation
+├── agent-docs/                      # Comprehensive documentation
 │   ├── ARCHITECTURE.md             # Project architecture & tech stack
 │   └── README.md                   # Human-readable setup guide
 │
 ├── .github/
 │   ├── skills/
 │   │   ├── find-skills/           # Skill discovery helper
+│   │   ├── feature-delivery/      # Scoped feature delivery workflow
+│   │   ├── bug-triage/            # Reproduction-first defect workflow
 │   │   ├── error-patterns/         # Persistent error-debugging memory workflow
+│   │   ├── app-hardening/         # Hardening and release-evidence workflow
 │   │   ├── ui-ux-pro-max/         # Advanced UI/UX design implementation skill
 │   │   ├── shadcn-ui/             # shadcn/ui setup and component patterns
 │   │   ├── README.md              # Guide for creating custom skills
@@ -141,9 +155,14 @@ your-project/
 │   │   ├── frontend.md
 │   │   ├── database.md
 │   │   ├── style.md
+│   │   ├── workflows.md
+│   │   ├── intent-routing.md
+│   │   ├── system-workflow.md
+│   │   ├── hardening.md
 │   │   └── lessons-learned.md
+│   └── agents/                     # Optional subagents
 │
-├── agents/                          # 🤖 Deterministic command contracts
+├── agents/                          # Deterministic command contracts
 │   └── commands/
 │   │   ├── SCHEMA.md              # Global slash-command response schema
 │   │   ├── plan.md                # /plan contract
@@ -162,49 +181,73 @@ your-project/
 
 ---
 
-## 📋 Command Reference
+## Command Reference
 
 ### Setup Commands
 
 ```bash
-# 🧙 Interactive wizard (recommended for beginners)
+# Interactive wizard (recommended for beginners)
 agents-templated wizard
 
-# 🚀 Quick start with presets
+# Quick start with presets
 agents-templated init --preset=nextjs         # Next.js full-stack
 agents-templated init --preset=express-api    # Express.js API
 agents-templated init --preset=django-react   # Django + React
 agents-templated init --preset=fastapi        # FastAPI
 agents-templated init --preset=go-api         # Go API
 
-# 🔧 Manual component selection
+# Manual component selection
 agents-templated init --all                   # All components
 agents-templated init --docs                  # Documentation only
 agents-templated init --rules                 # Agent rules only
 agents-templated init --skills                # Skills only
+agents-templated init --commands              # Command contracts only
 
-# ⚠️ Force overwrite existing files
+# Force overwrite existing files
 agents-templated init --all --force
 ```
 
 ### Maintenance Commands
 
 ```bash
-# ✅ Validate your project setup
+# Validate your project setup
 agents-templated validate                     # Quick validation
 agents-templated doctor                       # Comprehensive health check
 
-# 🔄 Update templates to latest version
+# Update templates to latest version
 agents-templated update                       # Apply updates with backup
 agents-templated update --check-only          # Check without installing
 
-# 📚 List available components and presets
+# List available components and presets
 agents-templated list
+
+# Lifecycle workflow and specialist commands
+agents-templated workflow
 ```
 
+### Workflow Commands
+
+These commands provide deterministic specialist guidance aligned to the sprint lifecycle:
+
+| Command | Specialist | Primary Outcome |
+|---------|------------|-----------------|
+| `problem-map` | Problem Strategist | Clarify user pain and define the actual problem |
+| `scope-shape` | Scope Director | Challenge scope and set high-leverage direction |
+| `arch-check` | Architecture Reviewer | Lock architecture and edge-case coverage |
+| `ux-bar` | Design Quality Lead | Raise UX quality before implementation |
+| `debug-track` | Root-Cause Investigator | Reproduce and isolate root cause |
+| `risk-review` | Release Risk Reviewer | Surface production-risk issues before merge |
+| `quality-gate` | Quality Gatekeeper | Validate behavior and regression safety |
+| `perf-scan` | Performance Analyst | Capture performance baseline and deltas |
+| `release-ready` | Release Coordinator | Prepare release artifacts and final checks |
+| `docs-sync` | Documentation Engineer | Sync docs with shipped behavior |
+| `learn-loop` | Iteration Lead | Capture lessons and next-cycle actions |
+
+Each command maps to deterministic contract files in `agents/commands/` and uses the schema in `agents/commands/SCHEMA.md`.
+
 ---
 
-## 🎯 After Installation: Next Steps
+## After Installation: Next Steps
 
 ### 1. Install Your Tech Stack
 
@@ -293,15 +336,15 @@ Your AI will follow the enterprise patterns automatically!
 
 ---
 
-## 🏗️ Core Principles
+## Core Principles
 
 ### Security-First Development
 
-✅ Validate all inputs at application boundaries with schema validation  
-✅ Authenticate and authorize every protected endpoint  
-✅ Rate limit public endpoints to prevent abuse  
-✅ Sanitize outputs to prevent injection attacks  
-✅ Never expose sensitive data in error messages or logs
+- Validate all inputs at application boundaries with schema validation  
+- Authenticate and authorize every protected endpoint  
+- Rate limit public endpoints to prevent abuse  
+- Sanitize outputs to prevent injection attacks  
+- Never expose sensitive data in error messages or logs
 
 **Reference**: [.claude/rules/security.md](.claude/rules/security.md)
 
@@ -327,7 +370,7 @@ Your AI will follow the enterprise patterns automatically!
 
 ---
 
-## 📚 Available Presets
+## Available Presets
 
 | Preset | Tech Stack | Best For |
 |--------|-----------|----------|
@@ -345,7 +388,7 @@ Each preset includes:
 
 ---
 
-## 🔧 Programmatic API
+## Programmatic API
 
 Use agents-templated in your build scripts or automation:
 
@@ -369,7 +412,7 @@ await agentsTemplated.install('./my-project', {
 
 ---
 
-## 📝 Usage Examples
+## Usage Examples
 
 ### Frontend Development
 ```
@@ -394,7 +437,7 @@ await agentsTemplated.install('./my-project', {
 
 ---
 
-## 🤝 Contributing
+## Contributing
 
 When contributing to this template:
 1. Maintain technology-agnostic patterns
@@ -407,13 +450,13 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
 
 ---
 
-## 📖 License
+## License
 
 MIT License - See [LICENSE](LICENSE) for details.
 
 ---
 
-## 🔗 Links
+## Links
 
 - **NPM Package**: https://www.npmjs.com/package/agents-templated
 - **GitHub Repository**: https://github.com/rickandrew2/agents-templated

package/templates/agents/commands/README.md

@@ -16,9 +16,55 @@ This directory is the modular source of truth for slash-command execution contra
   - `pr.md`
   - `release.md`
   - `docs.md`
+  - `problem-map.md`
+  - `scope-shape.md`
+  - `arch-check.md`
+  - `ux-bar.md`
+  - `debug-track.md`
+  - `risk-review.md`
+  - `quality-gate.md`
+  - `perf-scan.md`
+  - `release-ready.md`
+  - `docs-sync.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 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`
+- `quality-gate` -> `test.md`
+- `perf-scan` -> `perf.md`
+- `release-ready` -> `release.md`
+- `docs-sync` -> `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/templates/agents/commands/arch-check.md

@@ -0,0 +1,33 @@
+# /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.

package/templates/agents/commands/debug-track.md

@@ -0,0 +1,33 @@
+# /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.

package/templates/agents/commands/docs-sync.md

@@ -0,0 +1,33 @@
+# /docs-sync
+
+## A. Intent
+Keep documentation aligned with shipped behavior and contract changes.
+
+## B. When to Use
+Use after implementation or release-prep changes.
+
+## C. Required Inputs
+- Code changes summary
+- Updated behavior/contracts
+- Target documentation set
+
+## D. Deterministic Execution Flow
+1. Identify behavior and API changes.
+2. Locate affected docs.
+3. Update docs with minimal accurate edits.
+4. Verify examples and command references.
+5. Emit documentation update summary.
+
+## E. Structured Output Template
+- `docs_updated[]`
+- `behavior_changes[]`
+- `contract_updates[]`
+- `example_checks[]`
+- `remaining_doc_gaps[]`
+
+## F. Stop Conditions
+- Behavior changed with no corresponding doc update.
+- Example commands are unverified.
+
+## G. Safety Constraints
+- Do not publish stale setup or command instructions.

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

@@ -0,0 +1,33 @@
+# /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.

package/templates/agents/commands/perf-scan.md

@@ -0,0 +1,33 @@
+# /perf-scan
+
+## A. Intent
+Measure baseline performance and detect regressions with deterministic thresholds.
+
+## B. When to Use
+Use before and after performance-sensitive changes.
+
+## C. Required Inputs
+- Baseline context
+- Target endpoints or flows
+- Performance thresholds
+
+## D. Deterministic Execution Flow
+1. Capture baseline metrics.
+2. Execute candidate workload.
+3. Compare p95/p99 latency and error rates.
+4. Flag regressions with threshold deltas.
+5. Emit optimization priorities.
+
+## E. Structured Output Template
+- `baseline_metrics`
+- `candidate_metrics`
+- `regressions[]`
+- `threshold_checks[]`
+- `recommendations[]`
+
+## F. Stop Conditions
+- Baseline missing.
+- Thresholds undefined.
+
+## G. Safety Constraints
+- Avoid performance claims without before/after evidence.

package/templates/agents/commands/problem-map.md

@@ -0,0 +1,33 @@
+# /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.

package/templates/agents/commands/quality-gate.md

@@ -0,0 +1,33 @@
+# /quality-gate
+
+## A. Intent
+Enforce quality gates using test signals, behavior checks, and regression controls.
+
+## B. When to Use
+Use before release, and after major bug fixes.
+
+## C. Required Inputs
+- Target build/revision
+- Test scope
+- Critical user flows
+
+## D. Deterministic Execution Flow
+1. Run required test layers.
+2. Validate critical user flows.
+3. Inspect flaky or unstable results.
+4. Define required remediations.
+5. Emit pass/conditional/block outcome.
+
+## E. Structured Output Template
+- `test_results[]`
+- `critical_flow_status[]`
+- `quality_findings[]`
+- `required_fixes[]`
+- `gate_status`
+
+## F. Stop Conditions
+- Critical flow untested.
+- Required tests failed.
+
+## G. Safety Constraints
+- Do not mark pass when critical regressions remain open.

package/templates/agents/commands/release-ready.md

@@ -0,0 +1,33 @@
+# /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.