@ecc-hgy/ae 0.2.0

package/skills/tdd/interface-design.md

@@ -0,0 +1,31 @@
+# Interface Design for Testability
+
+Good interfaces make testing natural:
+
+1. **Accept dependencies, don't create them**
+
+   ```typescript
+   // Testable
+   function processOrder(order, paymentGateway) {}
+
+   // Hard to test
+   function processOrder(order) {
+     const gateway = new StripeGateway();
+   }
+   ```
+
+2. **Return results, don't produce side effects**
+
+   ```typescript
+   // Testable
+   function calculateDiscount(cart): Discount {}
+
+   // Hard to test
+   function applyDiscount(cart): void {
+     cart.total -= discount;
+   }
+   ```
+
+3. **Small surface area**
+   - Fewer methods = fewer tests needed
+   - Fewer params = simpler test setup

package/skills/tdd/mocking.md

@@ -0,0 +1,59 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes - prefer test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+At system boundaries, design interfaces that are easy to mock:
+
+**1. Use dependency injection**
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. Prefer SDK-style interfaces over generic fetchers**
+
+Create specific functions for each external operation instead of one generic function with conditional logic:
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint

package/skills/tdd/refactoring.md

@@ -0,0 +1,10 @@
+# Refactor Candidates
+
+After TDD cycle, look for:
+
+- **Duplication** → Extract function/class
+- **Long methods** → Break into private helpers (keep tests on public interface)
+- **Shallow modules** → Combine or deepen
+- **Feature envy** → Move logic to where data lives
+- **Primitive obsession** → Introduce value objects
+- **Existing code** the new code reveals as problematic

package/skills/tdd/tests.md

@@ -0,0 +1,61 @@
+# Good and Bad Tests
+
+## Good Tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Characteristics:
+
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad Tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+
+- Mocking internal collaborators
+- Testing private methods
+- Asserting on call counts/order
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Verifying through external means instead of interface
+
+```typescript
+// BAD: Bypasses interface to verify
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```

package/skills/to-issues/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: to-issues
+description: Break a design (and supporting spec context) into vertical-slice tasks and save them as `spec/needs/<need-name>/todo.md`. Use when user wants to convert a design into actionable tasks (S1 node A4).
+---
+
+# To Issues
+
+Break a plan into independently-grabbable issues using vertical slices (tracer bullets).
+
+## Process
+
+### 1. Gather context
+
+**Primary input:** `spec/needs/<need-name>/design.md` (produced by A3 `writing-plans`).
+
+If the design is insufficient on its own (acceptance criteria not concrete enough, scope boundaries unclear, or a slice references behavior that's defined elsewhere), supplement with:
+
+- The sibling `spec/needs/<need-name>/prd.md` — for user-facing acceptance criteria, out-of-scope notes
+- The `related-needs` field in `design.md` frontmatter — read those needs' `design.md` for shared module decisions
+- `spec/INDEX.md` and `spec/ADR/` — for vocabulary and accepted cross-need decisions
+
+If a design gap is severe enough that you can't draft a slice, STOP and surface it as a finding — go back to A3 (`writing-plans`) to patch `design.md` first, rather than guessing.
+
+### 2. Explore the codebase (optional)
+
+If you have not already explored the codebase, do so to understand the current state of the code. Task titles and descriptions should use vocabulary from `spec/INDEX.md` and existing `spec/needs/*/`, and respect ADRs under `spec/ADR/`.
+
+### 3. Draft vertical slices
+
+Break the plan into **tracer bullet** issues. Each issue is a thin vertical slice that cuts through ALL integration layers end-to-end, NOT a horizontal slice of one layer.
+
+<vertical-slice-rules>
+- Each slice delivers a narrow but COMPLETE path through every layer (schema, API, UI, tests)
+- A completed slice is demoable or verifiable on its own
+- Prefer many thin slices over few thick ones
+</vertical-slice-rules>
+
+### 4. Quiz the user
+
+Present the proposed breakdown as a numbered list. For each slice, show:
+
+- **Title**: short descriptive name
+- **Acceptance**: one-line acceptance criterion (the observable behavior that proves it's done)
+- **Blocked by**: which other slices (if any) must complete first; reference by slice number (e.g. "T2")
+
+Ask the user:
+
+- Does the granularity feel right? (too coarse / too fine)
+- Are the dependency relationships correct?
+- Should any slices be merged or split further?
+
+Iterate until the user approves the breakdown.
+
+### 5. Save the task list to `todo.md`
+
+Save the approved breakdown to `spec/needs/<need-name>/todo.md`, using [`todo-template.md`](todo-template.md) as the starting structure. The template encodes the format and the maintenance rules; copy it, fill in the slices, then save.
+
+`todo.md` has NO frontmatter — it is a rolling working artifact, not a stateful spec document.
+
+Format summary (full rules live in [`todo-template.md`](todo-template.md)):
+
+- Two sections: `## 实施` (executable slices) and `## 阻塞 / 待澄清` (open blockers)
+- Slice IDs: `T<n>` for tasks, `B<n>` for blockers; stable across the life of the need
+- Each `## 实施` line: `- [ ] T<n> <title> — <one-line acceptance>[; blocked by T<m>]`
+- Each slice MUST trace back to a section in `design.md`; if it can't, that's a signal to patch `design.md`, not to smuggle scope into `todo.md`
+
+## After Saving
+
+1. Update `spec/INDEX.md`:
+   - Set the `todo` column to `0/N` (where N = total tasks in `## 实施`)
+   - Recompute the `当前节点` column per the rules in `spec-framework.md` §INDEX 推导规则 (likely now `A5 执行`)
+   - If unsure, run `/ae-index-rebuild` for an idempotent rescan
+2. Hand off to the next S1 node: A5 `tdd` will read this `todo.md` (plus `design.md`) and drive the red-green-refactor loop. Tell the user the task list is ready and recommend invoking `tdd` next.
+
+## Boundaries
+
+- This skill writes ONLY `spec/needs/<need-name>/todo.md` (plus the INDEX row). It does NOT modify `prd.md` or `design.md`.
+- A task in `todo.md` MUST trace back to a section in `design.md`. New scope discovered here is a signal to patch `design.md` first.
+- This skill does NOT execute tasks — that is A5 `tdd`.

package/skills/to-issues/todo-template.md

@@ -0,0 +1,25 @@
+# Todo - <need-name>
+
+> Derived from: prd.md + design.md
+
+## 实施
+
+- [ ] T1 <title> — <one-line acceptance>
+- [ ] T2 <title> — <one-line acceptance>; blocked by T1
+- [ ] T3 <title> — <one-line acceptance>
+
+## 阻塞 / 待澄清
+
+- B1 <blocker description, link back to the design section that needs sharpening>
+
+<!--
+Rules for maintaining this file (see also `spec-framework.md` §frontmatter / todo.md):
+
+- NO frontmatter — this is a rolling working artifact, not a stateful spec document.
+- Use `- [ ]` for unfinished, `- [x]` for finished. Never delete completed items — they are visible history.
+- Sort by dependency order (blockers first); within the same level, sort by suggested execution order.
+- If a slice depends on a design decision that is still open, put it in `## 阻塞 / 待澄清` instead of `## 实施`.
+- Each slice MUST be traceable to a section in `design.md`. If a new slice has no traceable design section, that itself is a finding — go back and patch `design.md` rather than smuggling new scope into `todo.md` (matches `spec-framework.md` §边界规则: "todo 不应该出现 design 里没提的事").
+- Slice identifiers: `T<n>` for execution tasks, `B<n>` for blockers. Stable across the life of the need; do not renumber.
+- Acceptance criteria: a single observable behavior that proves the slice is done. If it needs multiple lines, the slice is probably too coarse — split it.
+-->

package/skills/to-prd/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: to-prd
+description: Turn the current conversation context into a PRD and save it to `spec/needs/<need-name>/prd.md` with frontmatter. Use when user wants to create a PRD from the current context (S1 node A2).
+---
+
+This skill takes the current conversation context and codebase understanding and produces a PRD. Do NOT interview the user — just synthesize what you already know.
+
+## Process
+
+1. Explore the repo to understand the current state of the codebase, if you haven't already. Use vocabulary from `spec/INDEX.md` and existing `spec/needs/*/prd.md` throughout the PRD, and respect ADRs under `spec/ADR/`.
+
+2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can.
+
+Check with the user that these seams match their expectations.
+
+2.5. Align the `need-name` (kebab-case) with the user. This is the slug used to create `spec/needs/<need-name>/`. Surface a concrete suggestion derived from the PRD topic and confirm before writing.
+
+3. Write the PRD using the template below. Save it to `spec/needs/<need-name>/prd.md` with the frontmatter block shown below the template. After saving, update `spec/INDEX.md` (add or update the row for this need) — or run `/ae-index-rebuild` to recompute.
+
+<prd-template>
+
+## Problem Statement
+
+The problem that the user is facing, from the user's perspective.
+
+## Solution
+
+The solution to the problem, from the user's perspective.
+
+## User Stories
+
+A LONG, numbered list of user stories. Each user story should be in the format of:
+
+1. As an <actor>, I want a <feature>, so that <benefit>
+
+<user-story-example>
+1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
+</user-story-example>
+
+This list of user stories should be extremely extensive and cover all aspects of the feature.
+
+## Implementation Decisions
+
+A list of implementation decisions that were made. This can include:
+
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes
+- API contracts
+- Specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
+
+## Testing Decisions
+
+A list of testing decisions that were made. Include:
+
+- A description of what makes a good test (only test external behavior, not implementation details)
+- Which modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Out of Scope
+
+A description of the things that are out of scope for this PRD.
+
+## Further Notes
+
+Any further notes about the feature.
+
+</prd-template>
+
+## Frontmatter (prepend to `prd.md`)
+
+Every `prd.md` MUST start with this frontmatter block:
+
+```yaml
+---
+status: draft             # draft | active | archived
+last-aligned: YYYY-MM-DD  # ISO date of the most recent alignment with the user
+related-needs: []         # other need-names that share scope; omit if none
+---
+```
+
+State transitions:
+
+- `draft` → `active` when the user has explicitly approved the PRD content (A1 alignment confirmed)
+- `active` → `archived` when superseded or the need is dropped (do not delete the file)
+
+`last-aligned` MUST be updated every time the PRD is edited after user re-alignment.
+
+## After Saving
+
+1. Update `spec/INDEX.md`:
+   - If the need is new: add a row under `## 需求`
+   - If updating: set the `prd` column to `active`
+   - Recompute the `当前节点` column per the rules in `spec-framework.md` §INDEX 推导规则
+   - If unsure, run `/ae-index-rebuild` for an idempotent rescan
+2. Hand off to the next S1 node: A3 `writing-plans` will read this `prd.md` and produce `spec/needs/<need-name>/design.md`. Tell the user the PRD is ready and recommend invoking `writing-plans` next.
+
+## Boundaries
+
+- This skill writes ONLY `spec/needs/<need-name>/prd.md` (plus the INDEX row). It does NOT write `design.md` or `todo.md`.
+- The PRD captures WHAT and WHY (business / product language). It does NOT capture HOW (technical decisions, file paths, code) — those belong in `design.md` (A3).
+- If the alignment surfaces a decision that affects MULTIPLE needs (e.g. "globally use Postgres"), flag it for promotion to `spec/ADR/` rather than embedding it in this PRD.

package/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: verification-before-completion
+description: Use at S1 node A6 - end-to-end verification on the real user path before claiming the need is complete, and before A -> B user acceptance. Requires running real-path verification (NOT mocked) and confirming output before any success claim. Evidence before assertions always. Failing this is the most common A-loop self-deception.
+---
+
+# Verification Before Completion
+
+## Overview
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
+**Core principle:** Evidence before claims, always.
+
+**Violating the letter of this rule is violating the spirit of this rule.**
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+## Common Failures
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
+| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
+| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
+| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
+| Regression test works | Red-green cycle verified | Test passes once |
+| Agent completed | VCS diff shows changes | Agent reports "success" |
+| Requirements met | Line-by-line checklist | Tests passing |
+| **Need complete (A6)** | **End-to-end run of the real user path described in `prd.md` Solution / User Stories - observe expected outputs at every step** | Unit + integration tests green; lint clean; mocked end-to-end pass |
+
+## Red Flags - STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
+- About to commit/push/PR without verification
+- Trusting agent success reports
+- Relying on partial verification
+- Thinking "just this once"
+- Tired and wanting work over
+- **ANY wording implying success without having run verification**
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Should work now" | RUN the verification |
+| "I'm confident" | Confidence ≠ evidence |
+| "Just this once" | No exceptions |
+| "Linter passed" | Linter ≠ compiler |
+| "Agent said success" | Verify independently |
+| "I'm tired" | Exhaustion ≠ excuse |
+| "Partial check is enough" | Partial proves nothing |
+| "Different words so rule doesn't apply" | Spirit over letter |
+
+## Key Patterns
+
+**Tests:**
+```
+✅ [Run test command] [See: 34/34 pass] "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+**Regression tests (TDD Red-Green):**
+```
+✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
+❌ "I've written a regression test" (without red-green verification)
+```
+
+**Build:**
+```
+✅ [Run build] [See: exit 0] "Build passes"
+❌ "Linter passed" (linter doesn't check compilation)
+```
+
+**Requirements:**
+```
+✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
+❌ "Tests pass, phase complete"
+```
+
+**Agent delegation:**
+```
+✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
+❌ Trust agent report
+```
+
+## When To Apply
+
+**ALWAYS before:**
+- ANY variation of success/completion claims
+- ANY expression of satisfaction
+- ANY positive statement about work state
+- Committing, PR creation, task completion
+- Moving to next task
+- Delegating to agents
+
+**Rule applies to:**
+- Exact phrases
+- Paraphrases and synonyms
+- Implications of success
+- ANY communication suggesting completion/correctness
+
+## The Bottom Line
+
+**No shortcuts for verification.**
+
+Run the command. Read the output. THEN claim the result.
+
+This is non-negotiable.
+
+## After Verification (S1 node A6)
+
+If verification passes:
+
+1. Update `spec/INDEX.md`:
+   - Recompute `当前节点` per `spec-framework.md` INDEX rules - for a fresh need this becomes "B1 user acceptance" (the next node is user-driven, not skill-driven)
+   - If unsure, run `/ae-index-rebuild`
+2. Hand off to B1: tell the user the need is ready for their hands-on acceptance test. Do NOT mark anything `archived` - `archived` is reserved for needs that get superseded, not completed.
+
+If verification fails:
+
+1. Do NOT update INDEX.
+2. Return to A5 `tdd` with the failing evidence; if the failure reveals a design gap, escalate to A3 `writing-plans` to patch `design.md`.
+
+## Distinction from B-side verification
+
+- **A6 (this skill)** = developer self-verification on the real user path; runs BEFORE handing the need to the user
+- **B1** = user-driven hands-on verification; user uses the product per `prd.md`, reports back
+- **B6** = user re-verification after a B5 fix; same nature as B1, just post-fix
+
+A6 passing does NOT mean the need is done. Only B1 (or B6 in a B-loop) closes the need.

package/skills/writing-plans/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: writing-plans
+description: Use when you have a PRD (`spec/needs/<need-name>/prd.md`) approved at S1 node A2, before touching code. Produces ONLY `design.md` — the task list lives in `todo.md` (A4 to-issues).
+---
+
+# Writing Plans
+
+## Hard Constraint (S1 node A3)
+
+This skill produces ONLY `spec/needs/<need-name>/design.md`. It MUST NOT produce a `todo.md` or any task-level checklist — that is the job of A4 `to-issues`, which reads this `design.md` and breaks it into `todo.md`.
+
+If the plan is not yet aligned with the user on key technical trade-offs (e.g. library choice, data model, integration seam), STOP and align before writing the design. A3 has a hard gate: undecided key trade-offs ⇒ do not advance to A4.
+
+## Overview
+
+Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
+
+Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
+
+**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
+
+**Input:** `spec/needs/<need-name>/prd.md` (produced by A2 `to-prd`). Also read `spec/INDEX.md`, related `spec/needs/*/design.md` if `related-needs` is set, and any `spec/ADR/` decisions that constrain this design.
+
+**Save design to:** `spec/needs/<need-name>/design.md` (overwriting if present and `status: draft`; if `status: active`, ask the user before overwriting).
+
+## Scope Check
+
+If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.
+
+## File Structure
+
+Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.
+
+- Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
+- You reason best about code you can hold in context at once, and your edits are more reliable when files are focused. Prefer smaller, focused files over large ones that do too much.
+- Files that change together should live together. Split by responsibility, not by technical layer.
+- In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure - but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable.
+
+This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.
+
+## Design Document Header
+
+Every `design.md` MUST start with this frontmatter block followed by the header:
+
+```yaml
+---
+status: draft             # draft | active | archived
+last-aligned: YYYY-MM-DD  # ISO date of the most recent alignment with the user
+related-needs: []         # other need-names whose design constrains this one; omit if none
+---
+```
+
+```markdown
+# [Need Name] Design
+
+**Goal:** [One sentence describing what this builds — should match `prd.md` Problem/Solution]
+
+**Architecture:** [2-3 sentences about approach]
+
+**Tech Stack:** [Key technologies/libraries]
+
+**Out of scope:** [Things this design explicitly does not address — usually inherited from `prd.md` Out of Scope]
+
+---
+```
+
+State transitions:
+
+- `draft` → `active` when the user has explicitly approved key technical trade-offs (A3 gate cleared)
+- `active` → `archived` when superseded or the need is dropped (do not delete the file)
+
+## No Placeholders
+
+Every step must contain the actual content an engineer needs. These are **plan failures** — never write them:
+- "TBD", "TODO", "implement later", "fill in details"
+- "Add appropriate error handling" / "add validation" / "handle edge cases"
+- "Write tests for the above" (without actual test code)
+- "Similar to Task N" (repeat the code — the engineer may be reading tasks out of order)
+- Steps that describe what to do without showing how (code blocks required for code steps)
+- References to types, functions, or methods not defined in any task
+
+## Remember
+- Exact file paths always
+- Complete code in every step — if a step changes code, show the code
+- Exact commands with expected output
+- DRY, YAGNI, TDD, frequent commits
+
+## Self-Review
+
+After writing the complete plan, look at the spec with fresh eyes and check the plan against it. This is a checklist you run yourself — not a subagent dispatch.
+
+**1. PRD coverage:** Skim each section/requirement in `prd.md`. Can you point to a section of `design.md` that addresses it? List any gaps.
+
+**2. Placeholder scan:** Search your design for red flags — any of the patterns from the "No Placeholders" section above. Fix them.
+
+**3. Type consistency:** Do the types, method signatures, and property names you used across sections match? A function called `clearLayers()` in §3 but `clearFullLayers()` in §7 is a bug.
+
+**4. ADR promotion check:** Does any decision in this design affect MORE THAN ONE need? If yes, it does not belong in `design.md` — promote it to `spec/ADR/NNNN-<title>.md` (frontmatter `status: proposed`) and reference the ADR from this design. Typical signals: "globally use X", "all needs share Y", "the project standard for Z is...".
+
+If you find issues, fix them inline. No need to re-review — just fix and move on. If you find a spec requirement with no task, add the task.
+
+## After Saving
+
+1. Update `spec/INDEX.md`:
+   - Set the `design` column to `active` (or `draft` if key trade-offs still need user approval)
+   - Recompute the `当前节点` column per the rules in `spec-framework.md` §INDEX 推导规则
+   - If unsure, run `/ae-index-rebuild` for an idempotent rescan
+2. If you promoted any decision to `spec/ADR/`, also add a row under `## ADR` in `INDEX.md`.
+3. Hand off to the next S1 node: A4 `to-issues` will read this `design.md` and produce `spec/needs/<need-name>/todo.md`. Tell the user the design is ready and recommend invoking `to-issues` next.
+
+## Boundaries
+
+- This skill writes ONLY `spec/needs/<need-name>/design.md` (plus the INDEX row, and optionally a new ADR). It does NOT write `todo.md` or any task-level checklist — that is A4.
+- The design captures HOW (technical decisions, modules, interfaces, data flow, key trade-offs). It does NOT re-capture WHAT — refer back to `prd.md` instead.
+- Decisions affecting MORE THAN ONE need belong in `spec/ADR/`, not here (see Self-Review step 4).

package/skills/zoom-out/SKILL.md

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