aw-ecc 1.4.31 → 1.4.47

package/skills/using-aw-skills/SKILL.md

@@ -1,290 +1,223 @@
 ---
 name: using-aw-skills
-description: Session-start skill-first routing for the AW SDLC surface. Select the smallest correct AW skill stack before any substantive response, then load deeper stage, domain, and org-standard detail on demand.
-trigger: Every session start. Loaded automatically via session-start hook.
+description: Session-start skill-first routing for the AW SDLC surface. Classify, route, read stage skill, then respond. Plan-first is mandatory.
+trigger: Every session start and before every substantive response.
 ---
 
 # Using AW Skills
 
-## Overview
+Router for the AW SDLC. MANDATORY on every non-trivial request and re-applied on every scope shift.
 
-This skill is the thin router for the AW SDLC surface.
-Its job is to:
+## Hard Gate (MUST — in order, before any substantive response)
 
-- choose the smallest correct public route
-- choose the smallest correct AW skill stack
-- stop generic commentary until the stage is clear
-- load deeper references only when they materially change the decision
+1. **Classify.** Answer out loud:
+   - Approved plan exists at `.aw_docs/features/<slug>/`? (if no → likely plan-first)
+   - Bug / alert / unclear failure? (→ `/aw:investigate`)
+   - Change touches any plan-first trigger (see list below)? (→ `/aw:plan`, no exceptions)
+   - Crosses >1 file AND >1 concern? (→ `/aw:plan`)
+   - Qualifies as mechanical per whitelist below? (→ `/aw:build` allowed)
+2. **Select route** via decision tree.
+3. **Read the stage skill** (`<route>/SKILL.md`). Naming it is not reading it.
+4. **Follow the skill's artifacts and contract** — not general-knowledge answers.
+5. **Then respond.**
 
-Keep this file small.
-Stage behavior belongs in stage skills.
-Long examples, checklists, and loading guidance belong in shared references.
+## Route Decision Tree
 
-This means the file should optimize for one thing first:
-
-- make the right next skill obvious
-
-## When to Use
-
-- at session start
-- before any substantive response
-- whenever the request might map to planning, building, investigating, testing, reviewing, deploying, or shipping work
-- whenever the user gives a vague request and the right stage still has to be selected
-
-Do not skip this skill just because the work looks small.
-
-## Skill Discovery
-
-When a task arrives, identify the current delivery phase and load the smallest correct route:
-
-```text
-Task arrives
-    │
-    ├── Vague idea, spec, or task breakdown? ───────→ /aw:plan
-    ├── Approved change to implement? ──────────────→ /aw:build
-    ├── Bug, alert, or unclear runtime failure? ────→ /aw:investigate
-    ├── Need QA proof or regression evidence? ──────→ /aw:test
-    ├── Need findings or readiness decision? ───────→ /aw:review
-    ├── Need one concrete release action? ──────────→ /aw:deploy
-    ├── Need launch or rollout closeout? ───────────→ /aw:ship
-    └── Need one-run end-to-end automation? ───────→ aw-yolo
+```
+FIRST — Is the user asking you to create, improve, fix, score, or audit
+  an agent, skill, command, rule, or eval? These are markdown files that
+  live in .aw/.aw_registry/ and define how AI tools behave.
+  ├── YES → /aw:adk
+  │         The user wants you to write or edit the file itself.
+  │         Example: "Create a command for database migration" means
+  │         write a command markdown file — not perform an actual
+  │         migration. The subject matter inside the artifact doesn't
+  │         change the route.
+  └── NO  → continue ↓
+
+SECOND — Is the user asking to push registry artifacts (.aw_registry/
+  or .aw_rules/) to the remote platform-docs registry?
+  Signals: "push this agent/skill/rule to the registry", "publish my
+  registry changes", "sync to platform-docs", "aw push", "aw push-rules"
+  NOTE: Regular git push, code PRs, and deploys are NOT this route.
+  ├── YES → /aw:publish
+  │         Always dry-run first, then confirm before pushing.
+  └── NO  → continue ↓
+
+Approved plan for this exact work?
+├── NO → Bug/alert/unclear failure?
+│         ├── YES → /aw:investigate
+│         └── NO  → /aw:plan   ← DEFAULT for anything new
+└── YES → Implemented & needs test/review?
+          ├── YES → /aw:test or /aw:review
+          └── NO  → Deploy/release action?
+                    ├── YES → Single release outcome? → /aw:deploy
+                    │         Launch readiness/rollout/rollback? → /aw:ship
+                    └── NO  → /aw:build
 ```
 
-Then load the supporting craft and domain skills that sharpen that route.
-If the work is in a real GHL domain, load `using-platform-skills` next.
-
-## Public Surface
-
-The public surface stays intentionally small.
-The canonical routes are the stages shown in the discovery flow above:
-
-- `/aw:plan`, `/aw:build`, `/aw:test`, `/aw:review`, `/aw:deploy`, `/aw:ship`
-- `/aw:investigate`
-
-Default delivery flow:
-
-- `/aw:plan` -> `/aw:build` -> `/aw:test` -> `/aw:review` -> `/aw:deploy` -> `/aw:ship`
-
-Conditional route:
-
-- `/aw:investigate`
-
-`/aw:investigate` is a first-class route for bugs, alerts, regressions, and unclear root cause.
-It should not be treated as a mandatory phase in every request.
-
-Compatibility entrypoints remain available during migration:
-
-- `/aw:execute` -> `/aw:build`
-- `/aw:verify` -> `/aw:test`, `/aw:review`, or the smallest correct combined verification flow
-
-There is also one explicit internal power workflow:
-
-- `aw-yolo`
-
-`aw-yolo` is for clearly end-to-end requests where the user wants one-run automation.
-It should not become the default route for normal stage-specific work.
-When it is selected, begin at the first unsatisfied stage rather than restarting the lifecycle from the top.
-
-## Core Operating Behaviors
-
-These behaviors apply across every route.
-
-### 1. Surface Assumptions
+## Plan-First Triggers (exhaustive — ANY of these → `/aw:plan`)
 
-Name assumptions that materially change scope, architecture, rollout, or verification.
-If an assumption could change the selected route, say it early.
+- new/modified endpoints, services, schemas, migrations, workers, queues
+- architecture or layer-boundary changes
+- integrations (third-party APIs, external registries, upstream-sourced skills/agents)
+- **router / routing rules / skill orchestration** changes
+- **new/modified skills, agents, commands, rule-manifest entries** (exception: if the user wants to create or edit an agent, skill, command, rule, or eval — the files in `.aw/.aw_registry/` that define AI behavior — that's `/aw:adk`. The gate above catches this before you get here.)
+- **`state.json` / `verification.md` / review-or-build contract** changes
+- **cross-registry propagation** (mirroring into platform-core, GitHub→local, etc.)
+- **model assignment changes across multiple agents**
+- security-sensitive work (auth, tokens, permissions, tenant scoping)
+- public API / interface contract changes
+- config changes that alter runtime behavior or feature flags
 
-### 2. Manage Confusion Actively
+## Mechanical-Change Whitelist (ONLY bypass of plan-first — ALL must hold)
 
-If the request, spec, code, or baseline disagree:
+- single file OR verbatim rename across files
+- no new public contract, schema, state-field, workflow step, or registry entry
+- no behavior change beyond a named bug fix
+- no cross-registry propagation
+- no new agent / skill / command / rule / reference
 
-1. stop
-2. name the contradiction
-3. state the tradeoff or blocking question
-4. do not guess through it
+If ANY condition fails → plan-first. "Just a config tweak" / "just a skill edit" does NOT qualify.
 
-### 3. Push Back With Concrete Tradeoffs
+## Compound-Request Guard
 
-If an approach creates obvious risk, complexity, or rollout danger:
+Per-turn edits that *individually* look mechanical but *cumulatively* form a feature. ANY signal → pause, route to `/aw:plan`, retro-capture under `.aw_docs/features/<slug>/`:
 
-- say so directly
-- name the downside
-- propose the smallest safer alternative
+- second consecutive edit touches a new file or concern
+- any edit adds a field to a state/schema/contract already edited this session
+- any edit mirrors content from an external source
+- user says "also do X" after an initial edit
 
-### 4. Enforce Simplicity
+## Pre-Edit Checklist (before the first `Edit`/`Write`/side-effecting `Bash` of a logical change)
 
-Prefer the smallest route and the smallest supporting skill stack.
-Do not turn a single-stage task into a hidden multi-stage workflow.
+- [ ] classification completed
+- [ ] route selected and named
+- [ ] stage skill read
+- [ ] plan exists when plan-first applies
+- [ ] all 5 mechanical conditions verified when whitelist is claimed
+- [ ] compound-request signals checked against prior turns
 
-### 5. Maintain Scope Discipline
+## Re-Route Mid-Session
 
-Touch only the stage and supporting context required for the current request.
-Do not reopen planning, implementation, or release work without a reason.
+If a follow-up changes the nature of the work (e.g. review session becomes "patch this skill too"), **re-run the Hard Gate for the new scope**. Do not carry old route forward by inertia.
 
-### 6. Verify, Don't Assume
+## Public Surface
 
-Every route must eventually produce evidence, not just confidence.
-Proof belongs in the right stage artifact, not only in narration.
+`/aw:plan` · `/aw:build` (alias: `/aw:execute`) · `/aw:investigate` · `/aw:test` (alias: `/aw:verify`) · `/aw:review` · `/aw:deploy` · `/aw:ship` · `/aw:feature` · `/aw:adk` · `/aw:publish`
+
+Honor explicit `/aw:<command>` the user types; do not reinterpret.
+
+## Public Command Roles
+
+| Command | Role | Primary artifacts |
+|---|---|---|
+| `/aw:plan` | Minimum correct planning | `prd.md`, `design.md`, `spec.md`, `tasks.md`, `state.json` |
+| `/aw:build` | Implement approved work in reversible slices | `execution.md`, `state.json`, code/config |
+| `/aw:investigate` | Reproduce, localize, confirm failure | `investigation.md`, `state.json` |
+| `/aw:test` | Produce fresh QA evidence | `verification.md`, `state.json` |
+| `/aw:review` | Findings, governance, readiness | `verification.md`, `state.json` |
+| `/aw:deploy` | One release outcome for verified work | `release.md`, `state.json` |
+| `/aw:ship` | Launch readiness, rollout safety, rollback, closeout | `release.md`, `state.json`, rollback notes |
+| `/aw:feature` | Guided phase-by-phase SDLC (18 phases) | `state.json`, delegates to stage skills |
+| `/aw:adk` | Author, score, fix, audit any registry artifact (command, agent, skill, rule, eval) | Registry artifacts, evals, `aw link` sync |
+| `/aw:publish` | Push local artifacts to remote registry via PR (dry-run + confirm gate) | PR to platform-docs |
+
+## Intent Routing (quick map)
+
+| Intent signals | Route |
+|---|---|
+| PRD, design, spec, task breakdown, architecture, "build-ready" | `/aw:plan` |
+| "implement", "apply", "fix", "continue" w/ approved scope | `/aw:build` |
+| "reproduce", "why is X failing", alert, incident | `/aw:investigate` |
+| "run tests", "produce evidence", QA proof | `/aw:test` |
+| "review", "is this ready", PR checks, findings, readiness | `/aw:review` |
+| "create PR", "deploy to staging/prod" (single outcome) | `/aw:deploy` |
+| "is this ready to launch", rollout, rollback plan, release closeout | `/aw:ship` |
+| "idea → production", "do the whole flow", "PR AND deploy" | `aw-yolo` (internal, not a public route — user should stage explicitly) |
+| "create an agent/skill/command/rule/eval", "score my skill", "audit all agents", "ADK", "developer kit" | `/aw:adk` |
+| "push this agent/skill/rule to the registry", "publish registry changes", "sync to platform-docs", "aw push" (NOT regular git push or code PRs) | `/aw:publish` |
+
+## Scope Guardrails
+
+- code request ≠ design/product work; design ≠ coding
+- deploy does not reopen planning; review does not silently implement
+- planning request already well-defined does not need a forced PRD
+- do not produce substantive non-routing output before skill selection
+- local repo AW routing is not skipped because a parent workspace has rules
+- every first destructive tool call in a turn re-confirms the route
+
+## Red Flags (stop and re-classify)
+
+| Thought | Reality |
+|---|---|
+| "I can answer quickly first" | Quick answers still need skill context. |
+| "Just exploring a little" | Exploration is work — load the skill first. |
+| "Just a clarifying question" | Clarify after skill selection. |
+| "I know the route" | Knowing ≠ loading. |
+| "User said 'yes do it' — I can skip plan" | Approval for an edit ≠ approval to skip routing. |
+| "It's just a skill/config tweak" | Skills/routers/agents/registries are plan-first. |
+| "Each turn was small" | Compound guard triggers on accumulation. |
+| "Planning now is late" | Retro-plan before the next edit. |
+| "Entered under /aw:review so route is locked" | Scope shift → re-route. |
+| "Just mirroring upstream" | Cross-registry propagation is plan-first. |
 
 ## Always-On Activation
 
 Before any substantive response, this router must select the smallest correct AW skill stack and matching public route.
 
-- explicit user command -> honor that command and load the mapped AW stage skill first
-- clear process need -> load the needed internal process skill first
-- otherwise choose the smallest correct AW primary stage skill and matching public route by intent
+- explicit user command → honor and load the mapped stage skill first
+- clear process need → load the needed internal process skill first
+- otherwise choose the smallest correct AW primary stage skill by intent
 - only after the required AW skills are selected, load deeper domain skills or ask clarifying questions
 
 Do not start with generic implementation, review, or deploy advice before skill selection.
-Do not leave the active skill stack or matching route implicit for non-trivial work.
 
 ## The Rule
 
 If there is even a small chance that an AW process skill, stage skill, or required domain skill applies, load it before responding.
 
-Questions count.
-Clarifying questions count.
-Quick exploration counts.
-
-The AW public command is the user-facing projection of the selected primary stage skill.
-
 ## Skill Priority
 
-When multiple AW skills could apply, use this order:
-
-1. process skills first:
-   - `aw-brainstorm`
-   - `aw-debug`
-   - `aw-prepare`
-   - `aw-yolo`
-2. primary stage skills second:
-   - `aw-plan`
-   - `aw-build`
-   - `aw-investigate`
-   - `aw-test`
-   - `aw-review`
-   - `aw-deploy`
-   - `aw-ship`
-3. domain and cross-cutting skills third
-
-The selected public route should reflect the primary stage skill, not hide it.
-
-## Route Selection
-
-Use one primary route unless the user explicitly asks for end-to-end orchestration.
-
-For route examples, explicit routing priority, and scope guardrails, see [`../../references/route-selection-patterns.md`](../../references/route-selection-patterns.md).
-
-## Failure Modes to Avoid
-
-These patterns look productive, but they create routing drift:
-
-1. answering quickly before selecting a route
-2. treating exploration as exempt from routing
-3. choosing `/aw:investigate` for every bug, even when the fix is already known
-4. treating `aw-yolo` as the default because it feels convenient
-5. reopening planning during `build` without a real blocker
-6. silently implementing during `test` or `review`
-7. loading every domain skill "just in case"
-8. giving a confident answer without evidence or stage artifacts
+1. process skills (`aw-brainstorm`, `aw-debug`, `aw-review`, `aw-prepare`)
+2. primary stage skill (`aw-plan`, `aw-build`, `aw-test`, `aw-review`, `aw-deploy`, `aw-ship`)
+3. domain skills (`platform-services/frontend/data/infra/sdet/review/design/mobile:*`) — delegated to `using-platform-skills`
 
 ## Cross-Cutting Engineering Skills
 
-After the primary stage is selected, load the portable craft skill that best sharpens the work:
-
-- `idea-refine`
-- `context-engineering`
-- `incremental-implementation`
-- `frontend-ui-engineering`
-- `api-and-interface-design`
-- `browser-testing-with-devtools`
-- `code-simplification`
-- `security-and-hardening`
-- `performance-optimization`
-- `git-workflow-and-versioning`
-- `ci-cd-and-automation`
-- `deprecation-and-migration`
-- `documentation-and-adrs`
-
-Load them because they improve the selected stage, not because they create a new public route.
-For domain families, cross-cutting guidance, and org-standard loading, see [`../../references/domain-skill-loading.md`](../../references/domain-skill-loading.md).
-
-## Platform Skill Loading
-
-After the primary AW route is known, use `using-platform-skills` when GHL platform behavior materially affects the stage.
-
-- backend and worker work -> `platform-services:*`
-- frontend and design-system work -> `platform-frontend:*` plus `platform-design:*`
-- data and migrations -> `platform-data:*`
-- infra and deploy paths -> `platform-infra:*`
-- test systems and QA governance -> `platform-sdet:*`
-- review depth and readiness -> `platform-review:*`
-- product context and business behavior -> `platform-product:*`
-
-Use `using-platform-skills` to decide the first supporting platform skills for the selected stage.
-
-## Context Loading
+Load across stages when context applies: `incremental-implementation`, `context-engineering`, `api-and-interface-design`, `git-workflow-and-versioning`, `ci-cd-and-automation`, `deprecation-and-migration`, `documentation-and-adrs`, `frontend-ui-engineering`, `browser-testing-with-devtools`, `idea-refine`, `aw-adk`
 
-Load context in the smallest order that reduces uncertainty without flooding the session.
-Start with repo-local contracts and approved AW artifacts before broad code search or domain docs.
+## Cross-Cutting Deepening Skills
 
-See [`../../references/context-loading-and-intake.md`](../../references/context-loading-and-intake.md).
+| Skill | Load when |
+|---|---|
+| `grill-with-docs` | Inside `/aw:plan` when requirements, domain language, edge cases, or acceptance criteria are fuzzy enough that a guided interview would materially improve the artifact. |
+| `to-prd` | Inside `/aw:plan` for product/full mode or when missing product assumptions must be frozen into `prd.md`; do not require it for already-clear technical plans. |
+| `to-issues` | Inside `/aw:plan` before `tasks.md` when a PRD/spec needs vertical tracer-bullet slices; remote issue publishing requires an explicit user request. |
+| `tdd` | Inside `/aw:build` as a companion to `tdd-workflow` when behavior-test, mocking, or tracer-bullet judgement needs more depth. |
+| `diagnose` | Inside `/aw:investigate` when the failure is unclear, hard to reproduce, performance-related, or vulnerable to speculative patching. |
+| `zoom-out` | Any stage when unfamiliar code needs a higher-level module map before local edits or review. |
+| `improve-codebase-architecture` | Standalone or before planning/building architecture-heavy changes where shallow modules, bad seams, or poor testability are the core concern. |
+| `grill-me` | Product, design, architecture, or decision review when the user explicitly wants to be questioned before committing to a path. |
 
-## Org Standards Always On
+## Internal Helpers (not public routes)
 
-When the selected stage falls inside a resolved baseline profile, the stage must honor:
+`aw:brainstorm` (discovery only) · `aw:finish` (legacy) · `aw:code-review` → alias of `/aw:review` · `aw:tdd` → alias of `/aw:build` · `aw-yolo` (internal power workflow for autonomous end-to-end orchestration — never advertise as public route)
 
-- `defaults/aw-sdlc/baseline-profiles.yml`
-- relevant platform playbooks
-- relevant `.aw_rules`
+## Rules Always Active
 
-Frontend work should still inherit HighRise, accessibility, responsive, and review expectations.
-Release work should still inherit governance, rollback, and evidence expectations.
-See [`../../references/domain-skill-loading.md`](../../references/domain-skill-loading.md).
+Relevant `.aw_rules/` and platform docs remain constraints regardless of route — never a reason to broaden scope.
 
-## Skill Rules
-
-1. Check for an applicable AW route before starting real work.
-2. Use one primary route unless the user explicitly asks for end-to-end orchestration.
-3. Load process skills before stage skills when the process itself changes the right path.
-4. Load domain and craft skills only after the primary route is clear.
-5. Load `using-platform-skills` when a GHL platform family materially changes the work.
-6. When in doubt between diagnosis and implementation, choose `/aw:investigate` only if root cause is still unclear.
-7. When in doubt between a normal route and `aw-yolo`, prefer the normal route.
-
-## Typical Sequences
-
-For a normal feature:
-
-```text
-/aw:plan -> /aw:build -> /aw:test -> /aw:review -> /aw:deploy -> /aw:ship
-```
-
-For a bug with unclear root cause:
-
-```text
-/aw:investigate -> /aw:build -> /aw:test -> /aw:review
-```
-
-For a release-ready change that only needs rollout work:
-
-```text
-/aw:deploy -> /aw:ship
-```
-
-For explicit one-run automation:
-
-```text
-aw-yolo -> [smallest correct internal stage sequence]
-```
+## Harness Activation (one line per harness)
 
-## Verification
+- Claude / hook-capable plugins → global plugin install
+- Cursor native / headless → `~/.cursor/hooks.json`
+- Cursor plugin → `hooks/hooks-cursor.json`
+- Codex → global `~/.codex/` install (launcher fallback)
+- Cursor repo without plugin → `.cursor/rules/aw-sdlc-router.mdc`
 
-Before moving past routing, confirm:
+## References
 
-- [ ] the smallest correct AW skill stack was selected first
-- [ ] the public route matches the actual stage intent
-- [ ] `/aw:investigate` was only chosen when diagnosis is actually required
-- [ ] org-standard playbooks and `.aw_rules` are loaded when the baseline requires them
-- [ ] the task is not being silently broadened into extra stages
-- [ ] `aw-yolo` is used only when the user explicitly asked for end-to-end automation
+- [context-loading-and-intake](../../references/context-loading-and-intake.md)
+- [route-selection-patterns](../../references/route-selection-patterns.md)
+- [domain-skill-loading](../../references/domain-skill-loading.md)

package/skills/using-aw-skills/hooks/session-start.sh

@@ -59,21 +59,10 @@ read_frontmatter_name() {
   ' "$file_path"
 }
 
-extract_skill_excerpt() {
+read_skill_content() {
   local file_path="$1"
   [[ -f "$file_path" ]] || return 0
-
-  awk '
-    NR == 1 && $0 == "---" { in_frontmatter = 1; next }
-    in_frontmatter && $0 == "---" { in_frontmatter = 0; next }
-    in_frontmatter { next }
-    /^[[:space:]]*$/ { next }
-    {
-      print
-      count++
-      if (count >= 4) exit
-    }
-  ' "$file_path"
+  cat "$file_path"
 }
 
 collect_registry_skills() {
@@ -127,7 +116,7 @@ elif [[ -n "$AW_REGISTRY_ROOT" && -f "$AW_REGISTRY_ROOT/platform/core/skills/usi
   ROUTER_SKILL_PATH="$AW_REGISTRY_ROOT/platform/core/skills/using-aw-skills/SKILL.md"
 fi
 
-ROUTER_EXCERPT="$(extract_skill_excerpt "$ROUTER_SKILL_PATH")"
+ROUTER_CONTENT="$(read_skill_content "$ROUTER_SKILL_PATH")"
 REGISTRY_SKILLS=""
 REGISTRY_COMMANDS=""
 if [[ -n "$AW_REGISTRY_ROOT" ]]; then
@@ -135,37 +124,18 @@ if [[ -n "$AW_REGISTRY_ROOT" ]]; then
   REGISTRY_COMMANDS="$(collect_registry_commands "$AW_REGISTRY_ROOT")"
 fi
 
-CONTEXT="# AW Session Context
-
-## First Response Rule
-Before any substantive response, select the smallest correct AW skill stack from the repo-local router.
-Honor an explicit AW command and its mapped stage skill first.
-Otherwise choose the needed process skill, primary stage skill, and matching route by intent, then load deeper domain skills.
-Do not start with generic implementation, review, or deploy advice before skill selection.
+CONTEXT="<EXTREMELY_IMPORTANT>
+You have the AW Agentic Workspace engine.
 
-## Primary Routes
-- /aw:plan -> ideas, specs, task breakdown, architecture direction
-- /aw:build -> approved implementation work
-- /aw:investigate -> bugs, alerts, or unclear runtime failures
-- /aw:test -> QA proof and regression evidence
-- /aw:review -> findings, risk review, and readiness
-- /aw:deploy -> rollout or release execution
-- /aw:ship -> release closeout and final handoff
+# AW Session Context
 
-## Compatibility Routes
-- /aw:execute -> compatibility route; resolve to /aw:build
-- /aw:verify -> compatibility route; resolve to /aw:test or /aw:review
+**Below is the full content of your 'using-aw-skills' skill — your router for all AW workflows. For all other skills, use the Skill tool:**
 
-## Router Source
-Use skills/using-aw-skills/SKILL.md as the repo-local router.
-Load domain, platform, and craft skills only after the smallest correct AW route is selected."
+${ROUTER_CONTENT}
+</EXTREMELY_IMPORTANT>
 
-if [[ -n "$ROUTER_EXCERPT" ]]; then
-  CONTEXT="${CONTEXT}
-
-## Router Excerpt
-${ROUTER_EXCERPT}"
-fi
+IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
+This is not negotiable. This is not optional. You cannot rationalize your way out of this."
 
 if [[ -n "$REGISTRY_SKILLS" ]]; then
   CONTEXT="${CONTEXT}

package/skills/zoom-out/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: zoom-out
+description: Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture.
+disable-model-invocation: true
+---
+
+# Zoom Out
+
+## When To Use
+
+Use this when a file, module, or unfamiliar code area is too local to understand safely without first mapping the surrounding system.
+
+## Workflow
+
+I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary vocabulary.
+
+## Output
+
+Return:
+
+- the main modules involved
+- how they call or depend on each other
+- the domain terms that should be used consistently
+- the safest local entry points for deeper inspection

package/.cursor/rules/common-agents.md

@@ -1,53 +0,0 @@
----
-description: "Agent orchestration: available agents, parallel execution, multi-perspective analysis"
-alwaysApply: true
----
-# Agent Orchestration
-
-## Available Agents
-
-Located in `~/.claude/agents/`:
-
-| Agent | Purpose | When to Use |
-|-------|---------|-------------|
-| planner | Implementation planning | Complex features, refactoring |
-| architect | System design | Architectural decisions |
-| tdd-guide | Test-driven development | New features, bug fixes |
-| code-reviewer | Code review | After writing code |
-| security-reviewer | Security analysis | Before commits |
-| build-error-resolver | Fix build errors | When build fails |
-| e2e-runner | E2E testing | Critical user flows |
-| refactor-cleaner | Dead code cleanup | Code maintenance |
-| doc-updater | Documentation | Updating docs |
-
-## Immediate Agent Usage
-
-No user prompt needed:
-1. Complex feature requests - Use **planner** agent
-2. Code just written/modified - Use **code-reviewer** agent
-3. Bug fix or new feature - Use **tdd-guide** agent
-4. Architectural decision - Use **architect** agent
-
-## Parallel Task Execution
-
-ALWAYS use parallel Task execution for independent operations:
-
-```markdown
-# GOOD: Parallel execution
-Launch 3 agents in parallel:
-1. Agent 1: Security analysis of auth module
-2. Agent 2: Performance review of cache system
-3. Agent 3: Type checking of utilities
-
-# BAD: Sequential when unnecessary
-First agent 1, then agent 2, then agent 3
-```
-
-## Multi-Perspective Analysis
-
-For complex problems, use split role sub-agents:
-- Factual reviewer
-- Senior engineer
-- Security expert
-- Consistency reviewer
-- Redundancy checker