aw-ecc 1.4.32 → 1.4.48

package/skills/aw-adk/references/type-classifier.md

@@ -0,0 +1,98 @@
+# CASRE Type Classifier
+
+Decision tree for classifying user requests into the correct artifact type. Use this before any ADK work to prevent misclassification.
+
+## Decision Tree
+
+```
+What does the user want?
+│
+├── "I want to define a standard/constraint/rule"
+│   └── RULE — An enforceable constraint with WRONG/RIGHT examples
+│
+├── "I want to test/validate an existing artifact"
+│   └── EVAL — Scenarios that verify an artifact works correctly
+│
+├── "I want a multi-step workflow that orchestrates agents"
+│   └── COMMAND — A pipeline with phases, agent assignments, checkpoints
+│
+├── "I want a persona that makes decisions and uses tools"
+│   └── AGENT — Has identity, judgment, model tier, and skills
+│
+├── "I want reusable knowledge, patterns, or checklists"
+│   └── SKILL — Static knowledge loaded on demand
+│
+└── Ambiguous?
+    → Ask: "Does this involve multiple phases with different agents,
+       or is it a single body of knowledge?"
+    → Ask: "Does this enforce a standard, or teach a practice?"
+```
+
+## Quick Classifier Table
+
+| Signal | Type | Reasoning |
+|---|---|---|
+| "best practices for X" | Skill | Static knowledge, reference material |
+| "review checklist for X" | Skill | Checklist = static knowledge |
+| "pipeline from spec to deploy" | Command | Multi-phase workflow |
+| "automate the ship process" | Command | Orchestration of agents |
+| "expert in database optimization" | Agent | Persona with judgment |
+| "reviewer that checks security" | Agent | Decision-making persona |
+| "no hardcoded secrets allowed" | Rule | Enforceable constraint |
+| "all PRs must have tests" | Rule | Standard with severity |
+| "verify my agent works correctly" | Eval | Testing existing artifact |
+| "add test cases for this skill" | Eval | Validation scenarios |
+
+## Common Misclassifications
+
+These are the most frequent mistakes. Catch them before scaffolding:
+
+### "Create a command for X best practices"
+**Wrong:** Command. **Right:** Skill.
+**Why:** "Best practices" is static knowledge, not a multi-phase workflow. Commands orchestrate agents through pipeline phases.
+
+### "Create a command that reviews X"
+**Usually wrong:** Command. **Usually right:** Skill (review checklist).
+**Exception:** If it's a multi-phase pipeline (analyze → review → report → remediate), then it IS a command.
+**Ask:** "Is this a review checklist, or a multi-phase review pipeline?"
+
+### "Create a command that acts as an X expert"
+**Wrong:** Command. **Right:** Agent.
+**Why:** "Acts as" = persona. Commands don't have identity. Agents do.
+
+### "Create a rule for how to write good code"
+**Wrong:** Rule. **Right:** Skill.
+**Why:** Rules enforce specific constraints ("no bare any"). Skills teach practices ("how to write good code").
+
+### "Create an agent that contains all MongoDB patterns"
+**Wrong:** Agent. **Right:** Skill.
+**Why:** A static body of knowledge is a skill. An agent has judgment and decision-making ability. The agent *loads* the skill.
+
+## When to Redirect
+
+If you classify and the user disagrees, don't argue. But explain your reasoning:
+
+```
+I'd suggest making this a skill rather than a command because:
+- It's a body of knowledge (MongoDB patterns), not a multi-step workflow
+- Skills are loaded on demand by agents — an agent can use this skill
+- Commands orchestrate agents through phases, which isn't needed here
+
+But if you prefer a command, I can scaffold one. What would you like?
+```
+
+## Type Relationship
+
+Understanding how types relate helps classify correctly:
+
+```
+Commands orchestrate → Agents
+Agents load → Skills
+Rules constrain → All types
+Evals validate → All types
+```
+
+- A command USES agents (assigns them to phases)
+- An agent LOADS skills (references them in frontmatter)
+- A rule CONSTRAINS any artifact (applies as a standard)
+- An eval TESTS any artifact (validates it works)

package/skills/aw-adk/references/writing-good-agents.md

@@ -0,0 +1,227 @@
+# Writing Good Agents
+
+An agent is an autonomous AI persona with identity, tools, and judgment. Unlike skills (passive knowledge) or rules (enforced constraints), agents reason independently, make decisions, and produce artifacts.
+
+## Before / After: Identity
+
+### Bad — thin identity
+
+```yaml
+identity:
+  role: "A code reviewer"
+```
+
+The agent has no personality, no memory model, no domain grounding. It will produce generic reviews indistinguishable from a raw LLM prompt.
+
+### Good — four-field identity
+
+```yaml
+identity:
+  role: >
+    Senior backend engineer specializing in NestJS microservices
+    with 8+ years of production experience in multi-tenant SaaS platforms.
+  personality: >
+    Thorough but pragmatic. Flags critical issues firmly, treats style
+    preferences as suggestions. Explains *why* something matters, not
+    just *what* is wrong. Never condescending.
+  memory: >
+    Retains context about the current PR's changed files, related test
+    coverage, and the service's recent incident history when available.
+  experience: >
+    Has debugged N+1 query issues, auth bypass vulnerabilities, and
+    race conditions in event-driven architectures. Knows the difference
+    between a real bug and a nitpick.
+```
+
+Why this works: The four fields constrain behavior across multiple axes. The agent knows *what* it is, *how* it communicates, *what* it remembers, and *what* patterns it recognizes from "experience."
+
+## Before / After: Mission
+
+### Bad — vague mission
+
+```yaml
+mission: "Review code and find issues"
+```
+
+No domain scope, no outcome definition, no boundary.
+
+### Good — concrete mission with domain, outcomes, scope
+
+```yaml
+mission:
+  domain: "Backend NestJS services in the payments domain"
+  outcomes:
+    - "Identify security vulnerabilities (auth bypass, injection, data leakage)"
+    - "Flag performance issues (N+1 queries, missing indexes, unbounded loops)"
+    - "Verify multi-tenancy scoping (locationId from auth context, not client)"
+    - "Ensure error handling follows platform patterns (no empty catch, structured responses)"
+  scope:
+    includes:
+      - "Changed files in the current PR"
+      - "Test files corresponding to changed source files"
+    excludes:
+      - "Generated files (*.generated.ts, migrations)"
+      - "Third-party library code"
+      - "Style/formatting issues (handled by linter)"
+```
+
+## Before / After: Communication Style
+
+### Bad — no communication guidance
+
+The agent dumps findings in an unstructured wall of text with no severity indicators.
+
+### Good — structured output contract
+
+```yaml
+communication:
+  format: |
+    ## Review Summary
+    **Risk Level:** CRITICAL | HIGH | MEDIUM | LOW
+
+    ### Findings
+    For each finding:
+    - **Severity:** CRITICAL / HIGH / MEDIUM / LOW
+    - **File:** path/to/file.ts:lineNumber
+    - **Issue:** One-sentence description
+    - **Why:** Why this matters (security risk, data loss, performance)
+    - **Fix:** Concrete code suggestion
+
+    ### Verdict
+    BLOCK (has CRITICAL) | APPROVE WITH COMMENTS | APPROVE
+  rules:
+    - "CRITICAL findings must include BLOCK verdict"
+    - "Never say 'looks good' without evidence of what was checked"
+    - "Maximum 10 findings per review — prioritize by severity"
+```
+
+## Anti-Pattern Catalog
+
+### 1. God-Agent (Does Everything)
+
+**Symptom:** One agent handles code review, testing, deployment, documentation, and security analysis.
+
+**Fix:** Split by responsibility. Each agent should have one clear mission. A code reviewer does not deploy. A security reviewer does not write docs.
+
+**Test:** If your agent's mission has more than 4 outcomes spanning unrelated domains, it's a god-agent.
+
+### 2. Tool Hoarding
+
+**Symptom:** Agent has 15 tools listed, uses 3 regularly.
+
+**Fix:** Give agents only the tools they need for their mission. Extra tools waste context window and invite off-task behavior.
+
+**Guideline:** 3-6 tools is typical. If an agent needs more than 8, it's probably a god-agent in disguise.
+
+### 3. Missing Communication Style
+
+**Symptom:** Agent produces output in unpredictable formats. Sometimes bullet lists, sometimes prose, sometimes JSON.
+
+**Fix:** Define an explicit output contract. Specify the structure, severity labels, and verdict format. The consuming command or human needs to parse the output reliably.
+
+### 4. No Measurable Metrics
+
+**Symptom:** Agent mission says "improve code quality" with no way to verify.
+
+**Fix:** Define observable outcomes:
+- "Flag all uses of bare `any` type" (countable)
+- "Identify missing test files for new source files" (binary per file)
+- "Detect N+1 query patterns in repository methods" (specific pattern)
+
+### 5. Generic Rules Without BLOCK/NEVER
+
+**Symptom:** Agent instructions say "be careful with security" without specifying what triggers a block.
+
+**Fix:** Use explicit behavioral boundaries:
+
+```yaml
+rules:
+  BLOCK:
+    - "Hardcoded secrets (API keys, passwords, tokens)"
+    - "Missing auth guard on new endpoints"
+    - "locationId from client input instead of auth context"
+  NEVER:
+    - "Never approve a PR with failing tests"
+    - "Never suggest disabling TypeScript strict mode"
+  PREFER:
+    - "Prefer suggesting fixes over just flagging issues"
+```
+
+### 6. No Error Handling Guidance
+
+**Symptom:** Agent crashes or produces garbage when it encounters unexpected input (empty diff, binary files, massive files).
+
+**Fix:** Define edge case behavior:
+
+```yaml
+edge_cases:
+  empty_diff: "Report 'No changes to review' and exit"
+  binary_files: "Skip with note: 'Binary file skipped: {path}'"
+  file_over_1000_lines: "Review only changed hunks, note that full file review was skipped"
+```
+
+## Scope Boundaries
+
+### Agent vs Skill vs Command
+
+| Dimension | Agent | Skill | Command |
+|-----------|-------|-------|---------|
+| **Has identity** | Yes | No | No |
+| **Makes decisions** | Yes | No | Orchestrates decisions |
+| **Loaded by** | Command or user | Agent or command | User directly |
+| **Produces** | Findings, artifacts, verdicts | Nothing (passive reference) | End-to-end outcome |
+| **Example** | Security reviewer | NestJS auth patterns | `/review-pr` |
+
+### Decision Guide
+
+- **Need autonomous judgment?** → Agent
+- **Need reusable knowledge?** → Skill
+- **Need a multi-step pipeline?** → Command (which uses agents)
+- **Need an enforceable constraint?** → Rule
+
+## Squad Assignment (1-9)
+
+Squads group agents by domain for efficient coordination:
+
+| Squad | Domain | Example Agents |
+|-------|--------|----------------|
+| 1 | Planning & Architecture | planner, architect |
+| 2 | Implementation | coder, refactorer |
+| 3 | Testing | tdd-guide, e2e-runner |
+| 4 | Review & Quality | code-reviewer, security-reviewer |
+| 5 | DevOps & Infrastructure | deployer, build-resolver |
+| 6 | Documentation | doc-updater |
+| 7 | Data & Analytics | data-reviewer |
+| 8 | Frontend | ui-reviewer, a11y-checker |
+| 9 | Coordination | command coordinators |
+
+**Rules:**
+- Agents in the same squad share domain context and can hand off seamlessly.
+- Cross-squad communication goes through the coordinator (squad 9).
+- An agent belongs to exactly one squad.
+
+## Model Tier Selection
+
+| Tier | Model | Use For | Cost Signal |
+|------|-------|---------|-------------|
+| **Coordinator** | Opus | Orchestration, judgment calls, architectural decisions, conflict resolution | High |
+| **Worker** | Sonnet | Code generation, implementation, detailed review, refactoring | Medium |
+| **Checker** | Haiku | Checklists, linting-style checks, simple validations, formatting | Low |
+
+**Guidelines:**
+- Coordinators (Opus) make judgment calls and resolve ambiguity. They do not write code.
+- Workers (Sonnet) do the heavy lifting. Most agents are workers.
+- Checkers (Haiku) handle mechanical tasks. Use when the task is deterministic and the instructions are clear enough for the smallest model.
+- If a Haiku-tier agent produces inconsistent results, promote to Sonnet. If Sonnet can't handle the judgment, promote to Opus.
+
+## Agent Quality Checklist
+
+- [ ] Four-field identity (role, personality, memory, experience)
+- [ ] Concrete mission with domain, outcomes, and scope boundaries
+- [ ] 3-6 tools (no hoarding)
+- [ ] Explicit output contract with structure and severity levels
+- [ ] BLOCK/NEVER/PREFER behavioral rules
+- [ ] Edge case handling defined
+- [ ] Model tier justified (not defaulting to Opus for everything)
+- [ ] Squad assignment documented
+- [ ] Tested with representative inputs including edge cases

package/skills/aw-adk/references/writing-good-commands.md

@@ -0,0 +1,258 @@
+# Writing Good Commands
+
+A command is a user-facing pipeline that orchestrates agents, skills, and tools through defined phases to produce an end-to-end outcome. Commands are what users invoke (e.g., `/review-pr`, `/implement-feature`).
+
+## Before / After: Command Structure
+
+### Bad — monolith command
+
+```yaml
+name: review-pr
+phases:
+  - name: "Review"
+    description: "Review the PR and provide feedback"
+    agents: [code-reviewer, security-reviewer, performance-reviewer, test-reviewer, doc-reviewer]
+    steps:
+      - "Load the PR diff"
+      - "Review everything"
+      - "Output findings"
+```
+
+Problems: One phase does everything. No checkpoints. No skill loading. Five agents compete for context with no coordination. No error handling. The user sees nothing until the end.
+
+### Good — phased pipeline with checkpoints
+
+```yaml
+name: review-pr
+phases:
+  - name: "Context"
+    description: "Load PR context and determine review scope"
+    agent: coordinator
+    model: opus
+    steps:
+      - "Fetch PR diff and metadata via gh CLI"
+      - "Classify changed files by domain (backend, frontend, infra, test)"
+      - "Load relevant skills based on file types"
+      - "Determine which review agents are needed"
+    gate: "coordinator confirms scope and agent roster before proceeding"
+
+  - name: "Review"
+    description: "Parallel domain-specific reviews"
+    agents:
+      - code-reviewer (changed backend files)
+      - security-reviewer (auth/input/secret files)
+    model: sonnet
+    execution: parallel
+    steps:
+      - "Each agent reviews its assigned files"
+      - "Each agent produces structured findings with severity"
+
+  - name: "Synthesis"
+    description: "Merge findings and produce verdict"
+    agent: coordinator
+    model: opus
+    steps:
+      - "Collect findings from all reviewers"
+      - "Deduplicate overlapping findings"
+      - "Assign final verdict: BLOCK / APPROVE WITH COMMENTS / APPROVE"
+    checkpoint: "Present findings to user for confirmation before posting"
+
+  - name: "Publish"
+    description: "Post review to GitHub"
+    agent: coordinator
+    steps:
+      - "Format findings as PR review comments"
+      - "Post via gh CLI"
+```
+
+## Phase Design Patterns
+
+### Linear Pipeline
+
+Phases execute sequentially. Output of phase N is input to phase N+1.
+
+```
+Context → Plan → Implement → Test → Review → Commit
+```
+
+**Use when:** Tasks have natural ordering where later phases depend on earlier results.
+
+### Interactive Loop
+
+A phase repeats until a condition is met, with human input between iterations.
+
+```
+Draft → [checkpoint: user reviews] → Revise → [checkpoint] → ... → Approve
+```
+
+**Use when:** Output quality requires human judgment (e.g., PRD drafting, design review).
+
+### Parallel Fan-Out
+
+Multiple agents work simultaneously on independent subtasks, then results merge.
+
+```
+Context → [security-review | code-review | perf-review] → Synthesis
+```
+
+**Use when:** Subtasks are independent and can run concurrently. Always follow with a synthesis phase.
+
+### MCP-Driven
+
+Phases interact with external systems (GitHub, Jenkins, Grafana) via MCP tools.
+
+```
+Fetch PR → Review → Post Comments → Trigger Build → Monitor
+```
+
+**Use when:** The command integrates with external services and needs to react to their responses.
+
+## Anti-Pattern Catalog
+
+### 1. No Checkpoints
+
+**Symptom:** Command runs 10 minutes, produces wrong output, user has no opportunity to correct course.
+
+**Fix:** Add at least 1 human checkpoint. Place it after the most consequential decision (usually after planning or before publishing).
+
+**Rule of thumb:** Minimum 1 checkpoint, maximum 3. More than 3 creates friction. Fewer than 1 creates risk.
+
+### 2. No Skill Loading Gate
+
+**Symptom:** Agents start working without loading relevant skills. They use generic knowledge instead of your team's patterns.
+
+**Fix:** Add a Context phase that classifies the task and loads appropriate skills before agents begin work.
+
+```yaml
+# BAD: agents start cold
+phases:
+  - name: "Review"
+    agents: [code-reviewer]
+
+# GOOD: context phase loads skills first
+phases:
+  - name: "Context"
+    steps:
+      - "Classify changed files by domain"
+      - "Load skills: nestjs-patterns, mongoose-queries (based on file types)"
+  - name: "Review"
+    agents: [code-reviewer]  # now has loaded skills in context
+```
+
+### 3. No Error Handling
+
+**Symptom:** If `gh pr diff` fails (network error, auth issue), the command crashes with no recovery.
+
+**Fix:** Define fallback behavior for each phase:
+
+```yaml
+error_handling:
+  network_failure: "Retry once, then report error to user with diagnostic info"
+  empty_diff: "Report 'No changes found' and exit gracefully"
+  agent_timeout: "Use partial results, note incomplete review in output"
+```
+
+### 4. Silent Execution
+
+**Symptom:** User invokes command and sees nothing for 5 minutes.
+
+**Fix:** Each phase should emit a progress signal:
+
+```yaml
+phases:
+  - name: "Context"
+    on_start: "Fetching PR #{{pr_number}} context..."
+    on_complete: "Scope: {{file_count}} files across {{domains}} domains"
+  - name: "Review"
+    on_start: "Running {{agent_count}} reviewers in parallel..."
+    on_complete: "Found {{finding_count}} findings ({{critical_count}} critical)"
+```
+
+### 5. Too Many Agents
+
+**Symptom:** Command uses 7 agents, each invoked once. Context window is bloated with identity setup for agents that do minimal work.
+
+**Fix:** Follow the agent roster rules below. If an agent does one small task, consider making it a step within another agent's workflow instead.
+
+### 6. No Phase Gates
+
+**Symptom:** Phase 2 proceeds even when Phase 1 produced garbage (e.g., empty plan, failed fetch).
+
+**Fix:** Add gates between phases:
+
+```yaml
+gate: "Plan must contain at least 3 implementation steps and a test strategy"
+```
+
+If the gate fails, the command stops and reports to the user rather than wasting tokens on doomed downstream phases.
+
+## Agent Roster Rules
+
+### Minimize Unique Agents
+
+Every unique agent added to a command costs context window (identity, mission, tools, rules). Use the minimum set.
+
+| Command Complexity | Recommended Agent Count |
+|-------------------|------------------------|
+| Simple (single-domain) | 1-2 |
+| Medium (cross-domain) | 2-3 |
+| Complex (full pipeline) | 3-5 |
+
+### Max 2-3 Uses Per Agent
+
+If an agent is used more than 3 times in a command, it's doing too much. Either:
+- Merge those phases into one agent invocation
+- Split the agent's responsibilities
+
+### Coordinator Is Opus
+
+The coordinating agent (phase routing, synthesis, conflict resolution) should run on Opus. Worker agents run on Sonnet. Checklist agents run on Haiku.
+
+```yaml
+# GOOD: tiered model assignment
+agents:
+  coordinator: { model: opus, uses: [context, synthesis, publish] }
+  code-reviewer: { model: sonnet, uses: [review] }
+  lint-checker: { model: haiku, uses: [formatting-check] }
+```
+
+## Human Checkpoint Guidance
+
+### Minimum: 1 Checkpoint
+
+Every command that produces artifacts visible to others (PR comments, commits, messages) must have at least one checkpoint before publishing.
+
+### Maximum: 3 Checkpoints
+
+More than 3 checkpoints turns an automated command into a manual process. If you need that much human oversight, the command is not well-defined enough.
+
+### Where to Place Checkpoints
+
+| Placement | When |
+|-----------|------|
+| After planning | When the plan determines all downstream work |
+| After review/synthesis | When findings will be published externally |
+| Before destructive actions | Commits, deployments, PR comments |
+
+### Checkpoint Format
+
+```yaml
+checkpoint:
+  display: "Summary of what was done and what will happen next"
+  options:
+    - "proceed" — continue to next phase
+    - "revise" — re-run current phase with feedback
+    - "abort" — stop command, preserve artifacts so far
+```
+
+## Command Quality Checklist
+
+- [ ] Minimum 2 phases (context + execution at minimum)
+- [ ] Skill loading gate in first phase
+- [ ] 1-3 human checkpoints at consequential decision points
+- [ ] Progress signals on every phase (on_start, on_complete)
+- [ ] Error handling with fallbacks for network, empty input, timeouts
+- [ ] Agent count justified (not exceeding 5 for complex commands)
+- [ ] Coordinator on Opus, workers on Sonnet, checkers on Haiku
+- [ ] Gates between phases to prevent garbage propagation
+- [ ] Each agent used 1-3 times (not more)