agents-templated 2.2.10 → 2.2.11

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,74 @@ 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
 
@@ -323,15 +338,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 +372,7 @@ Your AI will follow the enterprise patterns automatically!
 
 ---
 
-## 📚 Available Presets
+## Available Presets
 
 | Preset | Tech Stack | Best For |
 |--------|-----------|----------|
@@ -375,7 +390,7 @@ Each preset includes:
 
 ---
 
-## 🔧 Programmatic API
+## Programmatic API
 
 Use agents-templated in your build scripts or automation:
 
@@ -399,7 +414,7 @@ await agentsTemplated.install('./my-project', {
 
 ---
 
-## 📝 Usage Examples
+## Usage Examples
 
 ### Frontend Development
 ```
@@ -424,7 +439,7 @@ await agentsTemplated.install('./my-project', {
 
 ---
 
-## 🤝 Contributing
+## Contributing
 
 When contributing to this template:
 1. Maintain technology-agnostic patterns
@@ -437,13 +452,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,70 @@
+# 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`
+  - `scaffold.md`
+  - `fix.md`
+  - `refactor.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`
+  - `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 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/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,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/agents/commands/audit.md

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

package/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/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/agents/commands/docs.md

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

package/agents/commands/fix.md

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

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