agents-templated 2.2.10 → 2.2.12

package/README.md

@@ -9,67 +9,45 @@
 
 ---
 
-## What is Agents Templated?
-
-Agents Templated scaffolds your project with:
-
-✅ **AI Agent Configurations** – Auto-discovery files for 4 major AI coding assistants  
-✅ **Deterministic Command Contracts** – Structured slash-command protocol in `agents/commands/`  
-✅ **Security-First Patterns** – OWASP Top 10 protection guidelines built-in  
-✅ **Hardening Guidance** – Risk-based hardening/obfuscation and release evidence gates  
-✅ **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
-
-**Important:** This package does **NOT** install frameworks or libraries. It scaffolds the structure, patterns, and AI configurations—you install your chosen tech stack separately.
-
-### What’s New in This Version
-
-- Deterministic slash-command standard in `AGENTS.MD` and modular contracts in `agents/commands/`
-- Implicit natural-language routing support (`slash-command-auto`) for non-technical prompts
-- New workflow/routing/hardening rule set:
-  - `.claude/rules/intent-routing.md`
-  - `.claude/rules/system-workflow.md`
-  - `.claude/rules/hardening.md`
-  - `.claude/rules/lessons-learned.md`
-- New baseline skills:
-  - `.github/skills/feature-delivery/`
-  - `.github/skills/bug-triage/`
-  - `.github/skills/error-patterns/`
-  - `.github/skills/app-hardening/`
-  - `.github/skills/shadcn-ui/`
-- Release and audit contracts now require hardening evidence when risk profile requires it
+## Why This Package Exists
 
----
+Most starter templates only create files. This package creates operating rules for how teams build, review, test, and ship.
+
+You get:
+
+- 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
 
-## 🚀 Quick Start
+Important: this package does not install your framework. It installs the operating layer around your framework.
 
-### 1. Run the Interactive Wizard (Recommended)
+## 30-Second Start
+
+### 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:
 
@@ -91,47 +69,59 @@ 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` |
-| 🧭 **Deterministic Commands** | Slash-command contracts with strict structured outputs |
-| 💬 **Auto Intent Routing** | Non-slash prompts can map to command contracts (`slash-command-auto`) |
-| 🔒 **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 |
+| **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` |
+| **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:
 
@@ -141,7 +131,7 @@ 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
 │
@@ -173,7 +163,7 @@ your-project/
 │   │   └── 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
@@ -192,49 +182,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 |
+| `perf` | Performance Analyst | Optimize performance and guard against regressions |
+| `release-ready` | Release Coordinator | Prepare release artifacts and final checks |
+| `docs` | 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
 
@@ -323,15 +337,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)
 
@@ -357,7 +371,7 @@ Your AI will follow the enterprise patterns automatically!
 
 ---
 
-## 📚 Available Presets
+## Available Presets
 
 | Preset | Tech Stack | Best For |
 |--------|-----------|----------|
@@ -375,7 +389,7 @@ Each preset includes:
 
 ---
 
-## 🔧 Programmatic API
+## Programmatic API
 
 Use agents-templated in your build scripts or automation:
 
@@ -399,7 +413,7 @@ await agentsTemplated.install('./my-project', {
 
 ---
 
-## 📝 Usage Examples
+## Usage Examples
 
 ### Frontend Development
 ```
@@ -424,7 +438,7 @@ await agentsTemplated.install('./my-project', {
 
 ---
 
-## 🤝 Contributing
+## Contributing
 
 When contributing to this template:
 1. Maintain technology-agnostic patterns
@@ -437,13 +451,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/agents/commands/README.md

@@ -0,0 +1,64 @@
+# 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

@@ -0,0 +1,22 @@
+# 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

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

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

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

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