aw-ecc 1.4.31 → 1.4.47

package/skills/aw-adk/references/template-command.md

@@ -0,0 +1,279 @@
+# Command Template
+
+Copy the scaffold below as your starting point. Replace all `<placeholder>` tokens.
+
+---
+
+## Scaffold
+
+````markdown
+---
+name: <namespace>:<command-slug>
+description: "<1-2 sentences. What workflow this automates and when to use it.>"
+argument-hint: "[target] [--flag]"
+mcp: []
+---
+
+# <Command Display Name>
+
+<1-2 sentence purpose. What end-to-end workflow does this command automate?>
+
+## Protocol
+
+> **AW-PROTOCOL**: This command follows the AW orchestration protocol.
+> All phases execute sequentially. Each phase has defined inputs, outputs,
+> and checkpoints. Failure at any checkpoint triggers the on-failure handler
+> before proceeding.
+
+### Skill Loading Gate
+
+> **BLOCKING**: Before executing ANY phase, resolve and load the following skills.
+> Do not proceed until all skills are confirmed loaded.
+
+| Skill | Purpose | Required |
+|-------|---------|----------|
+| `<namespace>-<skill-1>` | <what it provides> | Yes |
+| `<namespace>-<skill-2>` | <what it provides> | Yes |
+| `<namespace>-<skill-3>` | <what it provides> | No |
+
+```
+Resolve: <skill-1>, <skill-2>
+Confirm: all loaded
+Proceed: Phase 0
+```
+
+## Core Principles
+
+1. **<Principle 1>** — <Why this principle matters for this workflow>
+2. **<Principle 2>** — <Why this principle matters>
+3. **<Principle 3>** — <Why this principle matters>
+
+## Agent Roster
+
+| Agent | Role | Phase(s) | Model |
+|-------|------|----------|-------|
+| `<agent-1>` | <what it does> | <phase numbers> | sonnet |
+| `<agent-2>` | <what it does> | <phase numbers> | sonnet |
+| `<agent-3>` | <what it does> | <phase numbers> | haiku |
+
+## Phase 0: Initialize
+
+**Purpose:** Validate inputs, resolve paths, establish workspace.
+
+1. Parse arguments: `<expected arguments>`
+2. Validate target exists: `<validation command>`
+3. Create workspace directory:
+
+```bash
+mkdir -p <workspace-path>
+```
+
+4. Snapshot current state (for rollback):
+
+```bash
+<snapshot command>
+```
+
+**Output:** Validated inputs, workspace path, snapshot reference
+**Checkpoint:** All inputs valid, workspace exists, snapshot saved
+**On-failure:** Report missing inputs with usage example, exit
+
+---
+
+## Phase 1: <Phase Name>
+
+**Purpose:** <What this phase accomplishes and why it comes first>
+
+**Agent:** `<agent-name>`
+**Input:** <What this phase receives from Phase 0 or prior phase>
+
+### Steps
+
+1. <Step with concrete action>
+2. <Step with concrete action>
+3. <Step with concrete action>
+
+```bash
+# Example command for this phase
+<command>
+```
+
+**Output:** <Specific artifacts this phase produces>
+**Checkpoint:** <Verifiable criteria — how to confirm this phase succeeded>
+**On-failure:** <What to do if the checkpoint fails — retry, skip, escalate>
+
+---
+
+## Phase 2: <Phase Name>
+
+**Purpose:** <What this phase accomplishes>
+
+**Agent:** `<agent-name>`
+**Input:** <Output from Phase 1>
+
+### Steps
+
+1. <Step with concrete action>
+2. <Step with concrete action>
+
+**Output:** <Artifacts produced>
+**Checkpoint:** <Success criteria>
+**On-failure:** <Recovery strategy>
+
+---
+
+## Phase 3: <Phase Name>
+
+**Purpose:** <What this phase accomplishes>
+
+**Agent:** `<agent-name>`
+**Input:** <Output from Phase 2>
+
+### Steps
+
+1. <Step with concrete action>
+2. <Step with concrete action>
+
+**Output:** <Artifacts produced>
+**Checkpoint:** <Success criteria>
+**On-failure:** <Recovery strategy>
+
+---
+
+## Phase N: <Human Checkpoint> (optional)
+
+**Purpose:** Pause for human review before irreversible actions.
+
+**Input:** <Summary of all prior phase outputs>
+
+### Review Prompt
+
+```
+The following changes are ready for <action>:
+
+<summary of changes>
+
+Proceed? [y/n]
+```
+
+**On-approve:** Continue to next phase
+**On-reject:** <What to do — rollback, revise, or exit>
+
+---
+
+## Phase N+1: Deliver
+
+**Purpose:** Produce final deliverables and report results.
+
+### Steps
+
+1. Aggregate outputs from all phases
+2. Generate summary report
+3. Clean up workspace (if applicable)
+
+**Output:** Final deliverables (see table below)
+**Checkpoint:** All required deliverables exist and pass validation
+
+## Compound Learnings
+
+<Patterns discovered across phases that should be captured for future runs.
+This section is populated after the first few executions.>
+
+- <Learning 1 — e.g., "Phase 2 consistently takes 3x longer than Phase 1; consider parallelizing sub-steps">
+- <Learning 2 — e.g., "Agent X produces better output when given Phase 1 output as structured JSON, not prose">
+
+## Output Format
+
+```
+## <Command Name> Results
+
+**Status:** <COMPLETE | PARTIAL | FAILED>
+**Duration:** <time>
+**Phases completed:** <N/M>
+
+### Phase Summary
+| Phase | Status | Key Output |
+|-------|--------|------------|
+| 0: Init | PASS | Workspace at <path> |
+| 1: <name> | PASS | <output summary> |
+| 2: <name> | PASS | <output summary> |
+
+### Deliverables
+<list of produced artifacts with paths>
+
+### Issues
+<any failures, warnings, or items needing follow-up>
+```
+
+## Error Handling
+
+| Error | Phase | Recovery |
+|-------|-------|----------|
+| <error-type-1> | <phase> | <what to do> |
+| <error-type-2> | <phase> | <what to do> |
+| <error-type-3> | Any | <what to do> |
+| Unrecoverable failure | Any | Rollback to Phase 0 snapshot, report error |
+
+## References
+
+- [<skill-name>](../skills/<slug>/SKILL.md) — <what it provides>
+- [<reference-name>](references/<file>.md) — <what it covers>
+````
+
+---
+
+## Section-by-Section Guide
+
+### Frontmatter
+
+- `name` — follows naming convention: `aw:platform-<domain>-<slug>` for platform, `aw:<team>-<sub_team>-<slug>` for teams (or `aw:<team>-<sub_team>-<domain>-<slug>` when domain nesting is used), `aw:<slug>` for stage commands. All hyphens, no colons (except the `aw:` prefix). See [registry-structure.md](registry-structure.md) for the full naming table.
+- `description` — front-load the workflow being automated
+- `argument-hint` — shown in help text; keep it short
+- `mcp` — list of MCP servers this command requires (empty if none)
+
+### Protocol & Skill Loading Gate
+
+The AW-PROTOCOL reference signals that this is a managed pipeline. The skill loading gate is BLOCKING — the command must not execute any phase until all required skills are confirmed loaded. This prevents partial execution with missing context.
+
+### Core Principles
+
+Three to five principles that shape decision-making across all phases. These are not rules (those go in rules/); they are workflow-specific values. Example: "Prefer incremental rollout over big-bang deployment."
+
+### Agent Roster
+
+Declares all agents used across phases upfront. This lets the reader understand the full cast before diving into phases. Include the model tier — it affects cost and capability expectations.
+
+### Phase Structure
+
+Every phase follows the same contract:
+
+- **Purpose** — Why this phase exists (not what it does — the steps cover that)
+- **Agent** — Which agent executes this phase
+- **Input** — Explicit data dependency on prior phases
+- **Steps** — Concrete, numbered actions
+- **Output** — What this phase produces (consumed by later phases)
+- **Checkpoint** — Verifiable success criteria (binary: pass or fail)
+- **On-failure** — Recovery strategy (retry, skip, escalate, rollback)
+
+This structure makes commands debuggable. When Phase 3 fails, you check Phase 3's checkpoint and on-failure handler.
+
+### Human Checkpoints
+
+Insert before irreversible actions (deployments, data migrations, external API calls). The command pauses, presents a summary, and waits for approval. Include a clear on-reject path.
+
+### Compound Learnings
+
+Populated after real executions. This is where operational wisdom accumulates. Review after the first 5-10 runs and update the command based on observed patterns.
+
+### Error Handling Table
+
+Exhaustive mapping of known failure modes to recovery strategies. The "Any" phase row catches unexpected failures with a universal rollback strategy.
+
+## Anti-Patterns
+
+| Pattern | Problem | Fix |
+|---|---|---|
+| No checkpoints between phases | Cascading failures — Phase 3 fails because Phase 1 silently produced bad output | Add checkpoint to every phase |
+| Monolithic single-phase command | Not a command — it's a script. Commands orchestrate multiple agents through phases | Break into 3+ phases or make it a skill |
+| No skill loading gate | Agents execute without required context, producing shallow output | Add BLOCKING gate with required skills |
+| Phase depends on implicit state | Breaks when phases are re-run or reordered | Make all inputs explicit in the Input field |

package/skills/aw-adk/references/template-eval.md

@@ -0,0 +1,176 @@
+# Eval Template
+
+Copy the scaffold below as your starting point. Replace all `<placeholder>` tokens.
+
+---
+
+## Scaffold
+
+````markdown
+---
+name: eval-<eval-slug>
+target: <parent-artifact-name>
+category: <functional | structural | behavioral | integration>
+difficulty: <basic | intermediate | advanced>
+---
+
+# Eval: <Eval Display Name>
+
+## Task
+
+<2-4 sentences describing what the model should do when given this eval's prompt.
+Be specific about the scenario, inputs, and expected workflow. This is the "user request"
+that the executor receives.>
+
+### Prompt
+
+```
+<The exact prompt to give the executor. This must be realistic — something a real user
+would actually ask. Include enough context for the executor to act without follow-up questions.>
+```
+
+## Context
+
+| Field | Value |
+|-------|-------|
+| **Namespace** | `<namespace where the parent artifact lives>` |
+| **Domain** | `<domain: backend, frontend, data, infra, etc.>` |
+| **Target artifact** | `<path to the artifact being tested>` |
+| **Target type** | `<command \| agent \| skill \| rule \| eval>` |
+| **Related work** | `<links to related artifacts, PRs, or docs>` |
+
+## Expected Outcomes
+
+The executor's output must satisfy ALL of the following:
+
+- [ ] <Outcome 1 — specific, verifiable assertion about the output>
+- [ ] <Outcome 2 — structural check: "file exists at X", "section Y is present">
+- [ ] <Outcome 3 — content check: "contains at least N items", "references skill Z">
+- [ ] <Outcome 4 — quality check: "examples are concrete, not placeholder">
+- [ ] <Outcome 5 — negative check: "does NOT contain X" or "does NOT skip Y">
+
+### Assertion Quality Criteria
+
+Each assertion above must be:
+- **Verifiable** — A grader can determine pass/fail from the output alone
+- **Discriminating** — A clearly wrong output would fail this assertion
+- **Stable** — Minor formatting changes don't cause false failures
+
+## Grading Criteria
+
+### PASS (all conditions met)
+
+- All expected outcomes checked
+- Output is production-ready (not placeholder/stub content)
+- No critical errors in execution
+
+### PARTIAL (some conditions met)
+
+- <N>+ of <M> expected outcomes met
+- Output has correct structure but thin content
+- OR output has rich content but wrong structure
+
+### FAIL (below threshold)
+
+- Fewer than <N> expected outcomes met
+- Output is structurally wrong (missing required sections, wrong artifact type)
+- OR executor failed to complete the task
+
+## Evaluation Method
+
+**Type:** <deterministic | model-based | hybrid>
+
+### Deterministic Checks
+
+<Checks that can be performed by a script — file existence, section headers,
+frontmatter fields, naming patterns.>
+
+```bash
+# Example: verify file exists and has required sections
+test -f "<expected-path>" || echo "FAIL: file not found"
+grep -q "## Core Mission" "<expected-path>" || echo "FAIL: missing Core Mission"
+```
+
+### Model-Based Checks
+
+<Checks that require judgment — content quality, example relevance, reasoning depth.
+These are evaluated by the grader agent.>
+
+- Does the output explain WHY, not just WHAT?
+- Are examples concrete and domain-specific (not generic foo/bar)?
+- Would a domain expert find the content useful?
+
+## Variants (optional)
+
+<Alternative scenarios that test the same artifact from different angles.>
+
+| Variant | Difference | Tests |
+|---------|------------|-------|
+| `eval-<slug>-minimal` | Minimal input, no context | Handles missing info gracefully |
+| `eval-<slug>-complex` | Multi-step request with constraints | Handles complexity without losing accuracy |
+| `eval-<slug>-adversarial` | Intentionally ambiguous or misleading input | Doesn't hallucinate or guess |
+
+## Baseline Expectations
+
+<What should happen when the executor runs WITHOUT the target artifact loaded.
+This establishes the value-add of the artifact.>
+
+- Without artifact: <expected behavior — generic output, missed requirements, etc.>
+- With artifact: <expected behavior — specific, structured, complete output>
+- **Expected delta:** <quantified improvement, e.g., "+40% pass rate">
+````
+
+---
+
+## Section-by-Section Guide
+
+### Frontmatter
+
+- `name` — Always prefixed with `eval-`. Lives in the colocated `evals/` directory of the parent artifact.
+- `target` — The artifact this eval tests. Must reference an existing artifact.
+- `category` — What aspect is being tested:
+  - `functional` — Does the artifact produce correct output?
+  - `structural` — Does the output have the right shape?
+  - `behavioral` — Does the artifact handle edge cases correctly?
+  - `integration` — Does the artifact work with other artifacts?
+- `difficulty` — Affects grading tolerance. Basic evals expect straightforward success. Advanced evals allow more nuanced partial results.
+
+### Task & Prompt
+
+The prompt is the most critical field. It must be:
+1. **Realistic** — something a real user would type
+2. **Self-contained** — the executor shouldn't need to ask follow-up questions
+3. **Unambiguous** — one clear correct interpretation
+
+Bad prompts produce unreliable evals. If the eval flakes, the prompt is usually the problem.
+
+### Expected Outcomes
+
+Four or more assertions, each independently verifiable. Mix structural checks (file exists, section present) with content checks (examples are concrete, references are valid) and at least one negative check (does NOT contain placeholder text).
+
+Weak assertions that pass for both good and bad output provide false confidence. Each assertion should discriminate: a clearly wrong output must fail it.
+
+### Grading Criteria
+
+Three tiers with clear thresholds. PASS/PARTIAL/FAIL must be unambiguous — the grader should not need judgment to classify a result into a tier. Use specific counts ("4+ of 5 outcomes") rather than vague language ("most outcomes").
+
+### Evaluation Method
+
+Three options:
+- **Deterministic** — Script-based checks only. Fast, reliable, but can't assess quality.
+- **Model-based** — Grader agent evaluates. Can assess quality, but slower and potentially inconsistent.
+- **Hybrid** — Deterministic for structure, model-based for content. Best of both worlds. Recommended default.
+
+### Baseline Expectations
+
+The with/without comparison is how you measure the artifact's value-add. Without a baseline, you can't distinguish "the artifact helped" from "the model would have done this anyway." Always specify expected delta.
+
+## Anti-Patterns
+
+| Pattern | Problem | Fix |
+|---|---|---|
+| Assertions that always pass | False confidence — bad output also passes | Test assertions against a known-bad output |
+| Ambiguous prompt | Eval flakes — different runs interpret differently | Make prompt self-contained with concrete details |
+| No negative assertions | Doesn't catch hallucination or extra content | Add "does NOT contain" checks |
+| No baseline expectation | Can't measure artifact value-add | Specify without-artifact behavior |
+| Only structural checks | Correct shape with garbage content passes | Add content quality assertions |

package/skills/aw-adk/references/template-rule.md

@@ -0,0 +1,119 @@
+# Rule Template
+
+Copy the scaffold below as your starting point. Replace all `<placeholder>` tokens. Rules are intentionally shorter than other artifact types — a rule that needs 1000 words to explain is probably a skill.
+
+---
+
+## Scaffold
+
+````markdown
+---
+id: <domain>/<rule-slug>
+severity: <MUST | SHOULD | MAY>
+domains: [<domain-1>, <domain-2>]
+paths: ["<glob-pattern-1>", "<glob-pattern-2>"]
+---
+
+# <Rule Title>
+
+## Rule
+
+<requirement-statement> [<MUST|SHOULD|MAY>]
+
+**Why:** <1-2 sentences explaining the consequence of violating this rule. What breaks, degrades, or becomes vulnerable? This is the most important part — a model that understands "why" handles edge cases better than one following a directive.>
+
+## WRONG
+
+<Real violation — not a toy example. Show code or config that a developer would actually write.>
+
+```<language>
+// <Brief comment explaining what's wrong>
+<violating code>
+```
+
+**Impact:** <What happens if this ships — runtime error, security vulnerability, data corruption, etc.>
+
+## RIGHT
+
+<Verified fix — the correct way to write the same code. Must compile/run.>
+
+```<language>
+// <Brief comment explaining why this is correct>
+<correct code>
+```
+
+## Exceptions
+
+<When this rule does NOT apply. Be specific — vague exceptions become loopholes.>
+
+- <Exception 1>: <specific condition and why the rule doesn't apply>
+- <Exception 2>: <specific condition>
+
+If no exceptions exist, write: "No exceptions. This rule applies universally."
+
+## Enforcement
+
+- **Automated:** <How this can be caught automatically — linter rule, CI check, grep pattern>
+- **Manual:** <What a reviewer should look for during code review>
+
+## Severity Justification
+
+**<MUST|SHOULD|MAY>** because <reason tied to impact>:
+
+- **MUST** — Violation causes correctness failures, security vulnerabilities, or data loss
+- **SHOULD** — Violation degrades quality, maintainability, or developer experience
+- **MAY** — Violation is suboptimal but acceptable in some contexts
+
+## References
+
+- [<skill-name>](../skills/<slug>/SKILL.md) — <deeper guidance on the practice>
+- [<external-doc>](<url>) — <authoritative source>
+````
+
+---
+
+## Section-by-Section Guide
+
+### Frontmatter
+
+- `id` — Unique identifier in `<domain>/<slug>` format. Used in rule-manifest.json and AGENTS.md references.
+- `severity` — One of MUST (violation = defect), SHOULD (violation = code smell), MAY (recommendation).
+- `domains` — Which platform domains this applies to. Use `["universal"]` for cross-cutting rules.
+- `paths` — Glob patterns for files this rule applies to. Enables automated scoping.
+
+### Rule Statement
+
+One sentence. Active voice. Ends with the severity tag in brackets. The model reads this as the primary constraint.
+
+**Good:** `All database queries must be scoped by locationId from auth context. [MUST]`
+**Bad:** `It is recommended that queries should generally include location scoping when possible. [SHOULD]`
+
+### Why
+
+The single most important section. Models follow rules more reliably when they understand consequences. "Because the style guide says so" is not a reason. "Because unscoped queries return data from other tenants, creating a data leak" is.
+
+### WRONG / RIGHT Examples
+
+Real code, not pseudocode. The WRONG example should be something a developer would plausibly write — not a strawman. The RIGHT example must be a direct fix of the WRONG example, not a different scenario.
+
+### Exceptions
+
+Explicit exceptions prevent false positives and reduce rule fatigue. If a rule has no exceptions, say so explicitly — ambiguity about exceptions leads to inconsistent enforcement.
+
+### Enforcement
+
+Split into automated (CI/linter) and manual (code review). Every rule should have at least one enforcement path. Rules that can only be enforced manually are expensive — prioritize automatable rules.
+
+### Severity Justification
+
+Explains why this severity level was chosen, not what the levels mean. "MUST because unscoped queries create cross-tenant data leaks in production" connects the severity to the specific consequence.
+
+## Anti-Patterns
+
+| Pattern | Problem | Fix |
+|---|---|---|
+| No "Why" section | Model follows rule mechanically, fails on edge cases | Add consequence-driven explanation |
+| Pseudocode examples | Developer can't map to real code | Use real language, real patterns |
+| WRONG example is a strawman | Nobody would write that; rule feels patronizing | Use a plausible violation from real code |
+| Vague exceptions | "Sometimes this doesn't apply" — when? | List specific conditions or write "No exceptions" |
+| MUST severity without justification | Everything feels critical; severity loses meaning | Justify with specific impact |

package/skills/aw-adk/references/template-skill.md

@@ -0,0 +1,123 @@
+# Skill Template
+
+Copy the scaffold below as your starting point. Replace all `<placeholder>` tokens.
+
+---
+
+## Scaffold
+
+````markdown
+---
+name: <namespace>-<skill-slug>
+description: "<1-2 sentences. State primary capability first, then 'Use when <trigger scenario>'.>"
+trigger: when the user <trigger condition>
+---
+
+# <Skill Display Name>
+
+<1-2 sentence purpose statement. What does this skill teach, and why does it matter?>
+
+## When to Use
+
+- <Trigger scenario 1 — specific user intent or request pattern>
+- <Trigger scenario 2 — a different angle or adjacent need>
+- <Trigger scenario 3 — an edge case that should still match>
+
+## Quick Start
+
+<Minimal example showing the skill in action. This is the "show, don't tell" section.
+Give a concrete, copy-pasteable example — not a description of what to do.>
+
+```bash
+# Example: a concrete invocation or code snippet
+<command or code>
+```
+
+## Detailed Guide
+
+### <Topic 1>
+
+<Step-by-step instructions with concrete actions. Each step should be:
+1. Numbered
+2. Actionable (starts with a verb)
+3. Specific (includes file paths, commands, or code)>
+
+### <Topic 2>
+
+<More guidance. Add as many topic sections as needed, but each should
+earn its place — if a section doesn't change behavior, remove it.>
+
+### <Topic 3 — Common Pitfalls>
+
+<What goes wrong and how to fix it. Real failure modes, not hypothetical ones.>
+
+## Checklist
+
+- [ ] <Check item 1> — <pass/fail criteria: what to look for and what "done" means>
+- [ ] <Check item 2> — <pass/fail criteria>
+- [ ] <Check item 3> — <pass/fail criteria>
+
+## Output Format
+
+<Show the exact structure of what this skill produces. If it produces a file,
+show the file. If it produces a checklist, show the checklist. Be concrete.>
+
+```
+<output structure>
+```
+
+## References
+
+- [<reference-name>](references/<file>.md) — <what it covers>
+- [<external-link>](<url>) — <why it's relevant>
+````
+
+---
+
+## Section-by-Section Guide
+
+### Frontmatter
+
+The three fields (`name`, `description`, `trigger`) control discoverability. The description is what the model reads to decide whether to load this skill. Front-load the capability; put the trigger scenario second.
+
+**Good:** `"MongoDB query optimization patterns for Mongoose and native driver. Use when debugging slow queries, reviewing aggregation pipelines, or designing indexes."`
+
+**Bad:** `"This skill helps with MongoDB."` (too vague, no trigger signals)
+
+### Purpose Statement
+
+One to two sentences below the H1. This is the first thing a reader sees. It should answer: "Why does this skill exist?" and "What outcome does it produce?"
+
+### When to Use
+
+Three or more trigger scenarios. These help the model (and human readers) decide if this skill matches their situation. Be specific about user intent, not about the skill's internal mechanics.
+
+### Quick Start
+
+The most important section for adoption. A developer should be able to copy-paste this and get a working result. If your Quick Start requires reading the Detailed Guide first, it's too complex.
+
+### Detailed Guide
+
+Progressive disclosure. Only readers who need depth will reach here. Organize by task or topic, not by internal architecture. Each subsection should be independently useful.
+
+### Checklist
+
+Actionable verification items. Each item must have clear pass/fail criteria — "looks good" is not a criterion. These are used by graders and reviewers to validate the skill was applied correctly.
+
+### Output Format
+
+Show, don't describe. If the skill produces JSON, show JSON. If it produces a markdown report, show the markdown. The model uses this section to format its output correctly.
+
+### References
+
+Link to deeper material. Reference files for detailed patterns, external docs for vendor APIs. Keep the skill itself lean; push depth into references.
+
+## Anti-Patterns
+
+| Pattern | Problem | Fix |
+|---|---|---|
+| 5000+ word SKILL.md | Model wastes context loading it | Split into SKILL.md (overview) + references/ (depth) |
+| No Quick Start | Low adoption — readers leave before learning | Add a copy-pasteable example |
+| Vague trigger description | Model loads the skill for wrong requests | Add 3+ specific trigger scenarios |
+| Checklist without criteria | Unverifiable — "did I do this?" has no answer | Add pass/fail criteria to every item |
+| Generic examples | Model produces generic output | Use real domain examples, not `foo`/`bar` |