@ecc-hgy/ae 0.4.0 → 0.6.0

package/skills/tdd/interface-design.md

@@ -1,31 +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
+# 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

@@ -1,59 +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
+# 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

@@ -1,10 +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
+# 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

@@ -1,61 +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");
-});
-```
+# 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

@@ -1,79 +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/AGENTS.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`.
+---
+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/AGENTS.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

@@ -1,25 +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:
-
-- 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`.
-- 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.
--->
+# 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:
+
+- 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`.
+- 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.
+-->