@ecc-hgy/ae 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +108 -0
  3. package/bin/ae.js +2 -0
  4. package/package.json +43 -0
  5. package/skills/brainstorming/SKILL.md +133 -0
  6. package/skills/diagnose/SKILL.md +146 -0
  7. package/skills/diagnose/assets/issue-7-sections.md +35 -0
  8. package/skills/diagnose/scripts/hitl-loop.template.sh +41 -0
  9. package/skills/grill-me/SKILL.md +10 -0
  10. package/skills/handoff/SKILL.md +19 -0
  11. package/skills/improve-codebase-architecture/DEEPENING.md +37 -0
  12. package/skills/improve-codebase-architecture/HTML-REPORT.md +123 -0
  13. package/skills/improve-codebase-architecture/INTERFACE-DESIGN.md +44 -0
  14. package/skills/improve-codebase-architecture/LANGUAGE.md +53 -0
  15. package/skills/improve-codebase-architecture/SKILL.md +101 -0
  16. package/skills/review/SKILL.md +119 -0
  17. package/skills/tdd/SKILL.md +157 -0
  18. package/skills/tdd/deep-modules.md +33 -0
  19. package/skills/tdd/interface-design.md +31 -0
  20. package/skills/tdd/mocking.md +59 -0
  21. package/skills/tdd/refactoring.md +10 -0
  22. package/skills/tdd/tests.md +61 -0
  23. package/skills/to-issues/SKILL.md +79 -0
  24. package/skills/to-issues/todo-template.md +25 -0
  25. package/skills/to-prd/SKILL.md +108 -0
  26. package/skills/verification-before-completion/SKILL.md +153 -0
  27. package/skills/writing-plans/SKILL.md +115 -0
  28. package/skills/zoom-out/SKILL.md +7 -0
  29. package/src/cli.js +62 -0
  30. package/src/commands/init.js +190 -0
  31. package/src/commands/setup.js +111 -0
  32. package/src/skeleton.js +209 -0
  33. package/src/utils/copy.js +100 -0
  34. package/src/utils/paths.js +60 -0
  35. package/src/utils/report.js +31 -0
  36. package/templates/ae-rules.md +17 -0
  37. package/templates/entries/AGENTS.md +21 -0
  38. package/templates/entries/CLAUDE.md +21 -0
  39. package/templates/entries/README.md +18 -0
  40. package/templates/entries/handoff.md +1 -0
  41. package/templates/entries/spec/INDEX.md +15 -0
  42. package/templates/entries/spec/README.md +19 -0
package/skills/improve-codebase-architecture/HTML-REPORT.md ADDED
@@ -0,0 +1,123 @@
1
+ # HTML Report Format
2
+
3
+ The architectural review is rendered as a single self-contained HTML file in the OS temp directory. Tailwind and Mermaid both come from CDNs. Mermaid handles graph-shaped diagrams reliably; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two — don't lean on Mermaid for everything, it'll start to look generic.
4
+
5
+ ## Scaffold
6
+
7
+ ```html
8
+ <!doctype html>
9
+ <html lang="en">
10
+ <head>
11
+ <meta charset="utf-8" />
12
+ <title>Architecture review — {{repo name}}</title>
13
+ <script src="https://cdn.tailwindcss.com"></script>
14
+ <script type="module">
15
+ import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
16
+ mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
17
+ </script>
18
+ <style>
19
+ /* small custom layer for things Tailwind doesn't cover cleanly:
20
+ dashed seam lines, hand-drawn-feeling arrow heads, etc. */
21
+ .seam { stroke-dasharray: 4 4; }
22
+ .leak { stroke: #dc2626; }
23
+ .deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
24
+ </style>
25
+ </head>
26
+ <body class="bg-stone-50 text-slate-900 font-sans">
27
+ <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
28
+ <header>...</header>
29
+ <section id="candidates" class="space-y-10">...</section>
30
+ <section id="top-recommendation">...</section>
31
+ </main>
32
+ </body>
33
+ </html>
34
+ ```
35
+
36
+ ## Header
37
+
38
+ Repo name, date, and a compact legend: solid box = module, dashed line = seam, red arrow = leakage, thick dark box = deep module. No introduction paragraph — straight into the candidates.
39
+
40
+ ## Candidate card
41
+
42
+ The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms ([LANGUAGE.md](LANGUAGE.md)) without ceremony.
43
+
44
+ Each candidate is one `<article>`:
45
+
46
+ - **Title** — short, names the deepening (e.g. "Collapse the Order intake pipeline").
47
+ - **Badge row** — recommendation strength (`Strong` = emerald, `Worth exploring` = amber, `Speculative` = slate), plus a tag for the dependency category (`in-process`, `local-substitutable`, `ports & adapters`, `mock`).
48
+ - **Files** — monospaced list, `font-mono text-sm`.
49
+ - **Before / After diagram** — the centrepiece. Two columns, side by side. See patterns below.
50
+ - **Problem** — one sentence. What hurts.
51
+ - **Solution** — one sentence. What changes.
52
+ - **Wins** — bullets, ≤6 words each. e.g. "Tests hit one interface", "Pricing logic stops leaking", "Delete 4 shallow wrappers".
53
+ - **ADR callout** (if applicable) — one line in an amber-tinted box.
54
+
55
+ No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram.
56
+
57
+ ## Diagram patterns
58
+
59
+ Pick the pattern that fits the candidate. Mix them. Don't make every diagram look the same — variety is part of the point.
60
+
61
+ ### Mermaid graph (the workhorse for dependencies / call flow)
62
+
63
+ Use a Mermaid `flowchart` or `graph` when the point is "X calls Y calls Z, and look at the mess." Wrap it in a Tailwind-styled card so it doesn't feel parachuted in. Style with classDef to colour leakage edges red and the deep module dark. Sequence diagrams work well for "before: 6 round-trips; after: 1."
64
+
65
+ ```html
66
+ <div class="rounded-lg border border-slate-200 bg-white p-4">
67
+ <pre class="mermaid">
68
+ flowchart LR
69
+ A[OrderHandler] --> B[OrderValidator]
70
+ B --> C[OrderRepo]
71
+ C -.leak.-> D[PricingClient]
72
+ classDef leak stroke:#dc2626,stroke-width:2px;
73
+ class C,D leak
74
+ </pre>
75
+ </div>
76
+ ```
77
+
78
+ ### Hand-built boxes-and-arrows (when Mermaid's layout fights you)
79
+
80
+ Modules as `<div>`s with borders and labels. Arrows as inline SVG `<line>` or `<path>` elements positioned absolutely over a relative container. Reach for this when you want the "after" diagram to feel like one thick-bordered deep module with greyed-out internals — Mermaid won't render that with the right weight.
81
+
82
+ ### Cross-section (good for layered shallowness)
83
+
84
+ Stack horizontal bands (`h-12 border-l-4`) to show layers a call passes through. Before: 6 thin layers each doing nothing. After: 1 thick band labelled with the consolidated responsibility.
85
+
86
+ ### Mass diagram (good for "interface as wide as implementation")
87
+
88
+ Two rectangles per module — one for interface surface area, one for implementation. Before: interface rectangle is nearly as tall as the implementation rectangle (shallow). After: interface rectangle is short, implementation rectangle is tall (deep).
89
+
90
+ ### Call-graph collapse
91
+
92
+ Before: a tree of function calls rendered as nested boxes. After: the same tree collapsed into one box, with the now-internal calls shown faded inside it.
93
+
94
+ ## Style guidance
95
+
96
+ - Lean editorial, not corporate-dashboard. Generous whitespace. Serif optional for headings (`font-serif` works well with stone/slate).
97
+ - Colour sparingly: one accent (emerald or indigo) plus red for leakage and amber for warnings.
98
+ - Keep diagrams ~320px tall so before/after sits comfortably side by side without scrolling.
99
+ - Use `text-xs uppercase tracking-wider` for module labels inside diagrams — they should read as schematic, not as UI.
100
+ - The only scripts are the Tailwind CDN and the Mermaid ESM import. The report is otherwise static — no app code, no interactivity beyond Mermaid's own rendering.
101
+
102
+ ## Top recommendation section
103
+
104
+ One larger card. Candidate name, one sentence on why, anchor link to its card. That's it.
105
+
106
+ ## Tone
107
+
108
+ Plain English, concise — but the architectural nouns and verbs come straight from [LANGUAGE.md](LANGUAGE.md). Concision is not an excuse to drift.
109
+
110
+ **Use exactly:** module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.
111
+
112
+ **Never substitute:** component, service, unit (for module) · API, signature (for interface) · boundary (for seam) · layer, wrapper (for module, when you mean module).
113
+
114
+ **Phrasings that fit the style:**
115
+
116
+ - "Order intake module is shallow — interface nearly matches the implementation."
117
+ - "Pricing leaks across the seam."
118
+ - "Deepen: one interface, one place to test."
119
+ - "Two adapters justify the seam: HTTP in prod, in-memory in tests."
120
+
121
+ **Wins bullets** name the gain in glossary terms: *"locality: bugs concentrate in one module"*, *"leverage: one interface, N call sites"*, *"interface shrinks; implementation absorbs the wrappers"*. Don't write *"easier to maintain"* or *"cleaner code"* — those terms aren't in the glossary and don't earn their place.
122
+
123
+ No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in [LANGUAGE.md](LANGUAGE.md), reach for one that is before inventing a new one.
package/skills/improve-codebase-architecture/INTERFACE-DESIGN.md ADDED
@@ -0,0 +1,44 @@
1
+ # Interface Design
2
+
3
+ When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best.
4
+
5
+ Uses the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**, **leverage**.
6
+
7
+ ## Process
8
+
9
+ ### 1. Frame the problem space
10
+
11
+ Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
12
+
13
+ - The constraints any new interface would need to satisfy
14
+ - The dependencies it would rely on, and which category they fall into (see [DEEPENING.md](DEEPENING.md))
15
+ - A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete
16
+
17
+ Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel.
18
+
19
+ ### 2. Spawn sub-agents
20
+
21
+ Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module.
22
+
23
+ Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:
24
+
25
+ - Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point."
26
+ - Agent 2: "Maximise flexibility — support many use cases and extension."
27
+ - Agent 3: "Optimise for the most common caller — make the default case trivial."
28
+ - Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies."
29
+
30
+ Include both [LANGUAGE.md](LANGUAGE.md) vocabulary and `spec/INDEX.md` + relevant `spec/needs/*/{prd,design}.md` vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language.
31
+
32
+ Each sub-agent outputs:
33
+
34
+ 1. Interface (types, methods, params — plus invariants, ordering, error modes)
35
+ 2. Usage example showing how callers use it
36
+ 3. What the implementation hides behind the seam
37
+ 4. Dependency strategy and adapters (see [DEEPENING.md](DEEPENING.md))
38
+ 5. Trade-offs — where leverage is high, where it's thin
39
+
40
+ ### 3. Present and compare
41
+
42
+ Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by **depth** (leverage at the interface), **locality** (where change concentrates), and **seam placement**.
43
+
44
+ After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not a menu.
package/skills/improve-codebase-architecture/LANGUAGE.md ADDED
@@ -0,0 +1,53 @@
1
+ # Language
2
+
3
+ Shared vocabulary for every suggestion this skill makes. Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.
4
+
5
+ ## Terms
6
+
7
+ **Module**
8
+ Anything with an interface and an implementation. Deliberately scale-agnostic — applies equally to a function, class, package, or tier-spanning slice.
9
+ _Avoid_: unit, component, service.
10
+
11
+ **Interface**
12
+ Everything a caller must know to use the module correctly. Includes the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics.
13
+ _Avoid_: API, signature (too narrow — those refer only to the type-level surface).
14
+
15
+ **Implementation**
16
+ What's inside a module — its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise.
17
+
18
+ **Depth**
19
+ Leverage at the interface — the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface. A module is **shallow** when the interface is nearly as complex as the implementation.
20
+
21
+ **Seam** _(from Michael Feathers)_
22
+ A place where you can alter behaviour without editing in that place. The *location* at which a module's interface lives. Choosing where to put the seam is its own design decision, distinct from what goes behind it.
23
+ _Avoid_: boundary (overloaded with DDD's bounded context).
24
+
25
+ **Adapter**
26
+ A concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside).
27
+
28
+ **Leverage**
29
+ What callers get from depth. More capability per unit of interface they have to learn. One implementation pays back across N call sites and M tests.
30
+
31
+ **Locality**
32
+ What maintainers get from depth. Change, bugs, knowledge, and verification concentrate at one place rather than spreading across callers. Fix once, fixed everywhere.
33
+
34
+ ## Principles
35
+
36
+ - **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface.
37
+ - **The deletion test.** Imagine deleting the module. If complexity vanishes, the module wasn't hiding anything (it was a pass-through). If complexity reappears across N callers, the module was earning its keep.
38
+ - **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape.
39
+ - **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it.
40
+
41
+ ## Relationships
42
+
43
+ - A **Module** has exactly one **Interface** (the surface it presents to callers and tests).
44
+ - **Depth** is a property of a **Module**, measured against its **Interface**.
45
+ - A **Seam** is where a **Module**'s **Interface** lives.
46
+ - An **Adapter** sits at a **Seam** and satisfies the **Interface**.
47
+ - **Depth** produces **Leverage** for callers and **Locality** for maintainers.
48
+
49
+ ## Rejected framings
50
+
51
+ - **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead.
52
+ - **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know.
53
+ - **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**.
package/skills/improve-codebase-architecture/SKILL.md ADDED
@@ -0,0 +1,101 @@
1
+ ---
2
+ name: improve-codebase-architecture
3
+ description: Find architectural deepening opportunities, informed by `spec/INDEX.md` vocabulary and `spec/ADR/` decisions. User-triggered ONLY: use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.
4
+ ---
5
+
6
+ # Improve Codebase Architecture
7
+
8
+ Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
9
+
10
+ ## Trigger model
11
+
12
+ This skill is **user-triggered only**. It is NOT attached to any S1 node. Three legitimate trigger points:
13
+
14
+ 1. **Post-B-loop** — a bug in B3 diagnose revealed structural coupling; B7 review noted "architectural change needed" but did NOT invoke this skill; the user now opts in.
15
+ 2. **Pre-A3** — before writing `design.md` for a complex new need, the user wants a deep look at the area to be touched.
16
+ 3. **Standalone** — periodic, user-driven architecture review.
17
+
18
+ Do NOT invoke this skill from inside another skill. Other skills MAY recommend it; only the user calls it.
19
+
20
+ ## Glossary
21
+
22
+ Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary." Full definitions in [LANGUAGE.md](LANGUAGE.md).
23
+
24
+ - **Module** — anything with an interface and an implementation (function, class, package, slice).
25
+ - **Interface** — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature.
26
+ - **Implementation** — the code inside.
27
+ - **Depth** — leverage at the interface: a lot of behaviour behind a small interface. **Deep** = high leverage. **Shallow** = interface nearly as complex as the implementation.
28
+ - **Seam** — where an interface lives; a place behaviour can be altered without editing in place. (Use this, not "boundary.")
29
+ - **Adapter** — a concrete thing satisfying an interface at a seam.
30
+ - **Leverage** — what callers get from depth.
31
+ - **Locality** — what maintainers get from depth: change, bugs, knowledge concentrated in one place.
32
+
33
+ Key principles (see [LANGUAGE.md](LANGUAGE.md) for the full list):
34
+
35
+ - **Deletion test**: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
36
+ - **The interface is the test surface.**
37
+ - **One adapter = hypothetical seam. Two adapters = real seam.**
38
+
39
+ This skill is _informed_ by the project's domain model. Read `spec/INDEX.md` for the vocabulary of needs and ADRs; read `spec/needs/*/prd.md` and `spec/needs/*/design.md` for the domain language and the names of seams that matter; read `spec/ADR/*.md` to find decisions the skill should not re-litigate. Treat ADRs with `status: accepted` as binding.
40
+
41
+ ## Process
42
+
43
+ ### 1. Explore
44
+
45
+ Read `spec/INDEX.md` (vocabulary + need landscape), the relevant `spec/needs/*/prd.md` and `spec/needs/*/design.md` files for the area being touched, and any `spec/ADR/*.md` with `status: accepted` that constrains the area.
46
+
47
+ Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
48
+
49
+ - Where does understanding one concept require bouncing between many small modules?
50
+ - Where are modules **shallow** — interface nearly as complex as the implementation?
51
+ - Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
52
+ - Where do tightly-coupled modules leak across their seams?
53
+ - Which parts of the codebase are untested, or hard to test through their current interface?
54
+
55
+ Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
56
+
57
+ Classify dependencies using [DEEPENING.md](DEEPENING.md) before recommending a direction. The dependency category determines whether the proposed seam is in-process, local-substitutable, ports-and-adapters, or mock-backed.
58
+
59
+ ### 2. Present candidates as an HTML report
60
+
61
+ Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `<tmpdir>/architecture-review-<timestamp>.html` so each run gets a fresh file. Open it for the user — `xdg-open <path>` on Linux, `open <path>` on macOS, `start <path>` on Windows — and tell them the absolute path.
62
+
63
+ The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals — use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.
64
+
65
+ Use [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance.
66
+
67
+ For each candidate, the same template as before, but rendered as a card:
68
+
69
+ - **Files** — which files/modules are involved
70
+ - **Problem** — why the current architecture is causing friction
71
+ - **Solution** — plain English description of what would change
72
+ - **Benefits** — explained in terms of locality and leverage, and how tests would improve
73
+ - **Before / After diagram** — side-by-side, custom-drawn, illustrating the shallowness and the deepening
74
+ - **Recommendation strength** — one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge
75
+
76
+ End the report with a **Top recommendation** section: which candidate you'd tackle first and why.
77
+
78
+ **Use `spec/INDEX.md` + need-level `prd.md`/`design.md` vocabulary for the domain, and [LANGUAGE.md](LANGUAGE.md) vocabulary for the architecture.** If `spec/INDEX.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
79
+
80
+ **ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: _"contradicts ADR-0007 in `spec/ADR/` — but worth reopening because..."_). Don't list every theoretical refactor an ADR forbids.
81
+
82
+ Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"
83
+
84
+ ### 3. Grilling loop
85
+
86
+ Once the user picks a candidate, drop into a grilling conversation. Walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
87
+
88
+ Side effects happen inline as decisions crystallize:
89
+
90
+ - **Naming a deepened module after a concept not in `spec/INDEX.md`?** Add the term to the relevant `spec/needs/<need-name>/design.md` (or, if it spans needs, propose a new ADR). Do NOT create or modify a `CONTEXT.md` file — this project does not use that path.
91
+ - **Sharpening a fuzzy term during the conversation?** Patch the relevant `design.md` or ADR right there.
92
+ - **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as `spec/ADR/NNNN-architecture-<topic>.md` with `status: proposed` so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer — skip ephemeral reasons ("not worth it right now") and self-evident ones.
93
+ - **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md).
94
+ - **User accepts the candidate and asks you to apply it?** Stop here. Do NOT modify code from this skill. Bounce back to S1: open a new need (A1) for the refactor, or patch an existing `design.md` (A3). This skill is REVIEW-only.
95
+
96
+ ## Boundaries
97
+
98
+ - Do not attach this skill to A/B nodes. B7 may recommend it; only the user invokes it.
99
+ - Do not modify application code from this skill.
100
+ - Do not create `CONTEXT.md` or `docs/adr/`.
101
+ - Keep architecture vocabulary in [LANGUAGE.md](LANGUAGE.md); keep report shape in [HTML-REPORT.md](HTML-REPORT.md); keep dependency strategy in [DEEPENING.md](DEEPENING.md); use [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md) only after the user chooses a candidate.
package/skills/review/SKILL.md ADDED
@@ -0,0 +1,119 @@
1
+ ---
2
+ name: review
3
+ description: Two-axis review (Standards / Spec) of the changes for a need that is about to close, followed by sedimentation routing - review findings flow into prd.md / design.md / spec/ADR/ / S2 candidates per `spec-framework.md`. Used at S1 node B7.
4
+ ---
5
+
6
+ # Review
7
+
8
+ Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
9
+
10
+ - **Standards** - does the code conform to this repo's documented coding standards?
11
+ - **Spec** - does the code faithfully implement the originating need?
12
+
13
+ Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
14
+
15
+ ## Entry (S1 node B7)
16
+
17
+ Invoke this skill when a need is about to close - typically after B6 user re-verification passes. Inputs:
18
+
19
+ - The owning need: `spec/needs/<need-name>/` (must contain `prd.md`, `design.md`, `todo.md`, and at least one `issues/*.md` if this close was preceded by a B-loop)
20
+ - The fixed point: the git commit at which work on this need started (merge-base with `main`, or the user's specified SHA)
21
+ - `spec/INDEX.md` (to confirm the need-name and to update afterward)
22
+
23
+ ## Process
24
+
25
+ ### 1. Pin the fixed point
26
+
27
+ Whatever the user said is the fixed point - a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. Don't be opinionated; pass it through. If they didn't specify one, ask: "Review against what - a branch, a commit, or `main`?" Don't proceed until you have it.
28
+
29
+ Capture the diff command once: `git diff <fixed-point>...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log <fixed-point>..HEAD --oneline`.
30
+
31
+ ### 2. Identify the spec source
32
+
33
+ The spec is fixed by the need-name (resolved from the user's input, the active branch, or `spec/INDEX.md`'s `当前节点` column). Read these files in order:
34
+
35
+ 1. `spec/needs/<need-name>/prd.md` - WHAT and WHY (acceptance criteria)
36
+ 2. `spec/needs/<need-name>/design.md` - HOW (decisions and trade-offs)
37
+ 3. `spec/needs/<need-name>/todo.md` - execution checklist (rolling)
38
+ 4. `spec/needs/<need-name>/issues/*.md` - any B-loop issue files for this close
39
+
40
+ Do NOT search `docs/`, `specs/`, `.scratch/`, or commit-message issue references - the contract is: this project always uses `spec/needs/<need-name>/`. If `<need-name>` cannot be determined, STOP and ask the user.
41
+
42
+ ### 3. Identify the standards sources
43
+
44
+ Anything in the repo that documents how code should be written. For this project's spec layout, the canonical sources are:
45
+
46
+ - `AGENTS.md`, `CLAUDE.md` (entry rules + R1 - mirrored content)
47
+ - `spec/README.md` (project map; rarely contains rules but read for context)
48
+ - `spec/INDEX.md` (need + ADR index; the `当前节点` and `related-needs` columns reveal cross-need coupling)
49
+ - `spec/ADR/*.md` (architectural decisions are standards; treat `status: accepted` as binding)
50
+ - `CONTRIBUTING.md` (if present at repo root)
51
+ - `.editorconfig`, `eslint.config.*`, `biome.json`, `prettier.config.*`, `tsconfig.json`, `ruff.toml`, etc. (machine-enforced - note them but don't re-check what tooling already checks)
52
+ - Any `STYLE.md`, `STANDARDS.md`, `STYLEGUIDE.md` at the repo root or under `spec/`
53
+
54
+ Do NOT look under `docs/adr/`, `CONTEXT.md`, or `CONTEXT-MAP.md` - this project uses `spec/ADR/` and the INDEX/README split instead.
55
+
56
+ Collect the list of files. The **Standards** sub-agent will read them.
57
+
58
+ ### 4. Spawn both sub-agents in parallel
59
+
60
+ Send a single message with two `Agent` tool calls. Use the `general-purpose` subagent for both.
61
+
62
+ **Standards sub-agent prompt** - include:
63
+
64
+ - The full diff command and commit list.
65
+ - The list of standards-source files you found in step 3.
66
+ - The brief: "Read the standards docs. Then read the diff. Report - per file/hunk where relevant - every place the diff violates a documented standard. Cite the standard (file + the rule). Distinguish hard violations from judgement calls. Skip anything tooling enforces. Under 400 words."
67
+
68
+ **Spec sub-agent prompt** - include:
69
+
70
+ - The diff command and commit list.
71
+ - The path or fetched contents of the spec.
72
+ - The brief: "Read the spec. Then read the diff. Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words."
73
+
74
+ If the spec is missing, skip the Spec sub-agent and note this in the final report.
75
+
76
+ ### 5. Aggregate
77
+
78
+ Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings - the two axes are deliberately separate so the user can see them independently.
79
+
80
+ End with a one-line summary: total findings per axis, and the worst single issue (if any) flagged.
81
+
82
+ ### 6. Sediment (sedimentation routing)
83
+
84
+ This step is what makes review a B7 skill and not a generic PR review. After Aggregate, walk through every finding from BOTH axes and route each one of four ways. Show the user a routing plan; only execute after approval.
85
+
86
+ | Finding type | Routing target | What to write |
87
+ |---|---|---|
88
+ | **Business rule** (spec said WHAT was wrong, or B-loop surfaced an unstated rule) | `spec/needs/<need-name>/prd.md` | Patch the relevant section; bump `last-aligned: <today>`; keep `status: active` |
89
+ | **Local technical decision** (affects ONLY this need) | `spec/needs/<need-name>/design.md` | Patch the relevant section; bump `last-aligned`; keep `status: active` |
90
+ | **Cross-need decision** (affects 2+ needs, or a project-wide invariant) | New `spec/ADR/NNNN-<title>.md` | New ADR with `status: proposed` (NOT accepted - user decides in a separate pass). In affected `design.md` files, add a reference and prune the local version of the decision. |
91
+ | **Reusable method / pattern** (not project-specific knowledge) | Handoff proposal (NOT this skill) | Add a single line under "S2 candidates" in `handoff.md` (or surface it for the next `handoff` skill run). Do NOT create a skill file here - promotion is user-confirmed at S2. |
92
+
93
+ After routing:
94
+
95
+ 1. Update `spec/INDEX.md`:
96
+ - Set every `issues/*.md` referenced in this close to "已验收"
97
+ - If any `prd.md` / `design.md` was patched, leave `status: active` and refresh `last-aligned`
98
+ - If a new ADR was created, add a row under `## ADR` with `status: proposed`
99
+ - If unsure, run `/ae-index-rebuild`
100
+ 2. Print a one-block summary to the user:
101
+ - Findings routed to prd / design / ADR / S2-candidates with counts
102
+ - Files modified (path list)
103
+ - Suggested next action: close the need (mark all relevant files appropriately) or open a fresh A1 alignment for the new ADR proposals
104
+
105
+ ## Boundaries
106
+
107
+ - This skill READS the diff and need files, WRITES patches to `prd.md` / `design.md`, NEW files in `spec/ADR/`, and ONE INDEX update.
108
+ - It does NOT close or archive `prd.md` / `design.md` - `archived` is reserved for need-level lifecycle, not B7.
109
+ - It does NOT promote rules into reusable skills - S2 promotion is user-confirmed in a separate pass.
110
+ - It does NOT invoke `improve-codebase-architecture` directly - that skill is user-triggered; B7 findings can list it as a suggested follow-up but do not call it.
111
+
112
+ ## Why two axes
113
+
114
+ A change can pass one axis and fail the other:
115
+
116
+ - Code that follows every standard but implements the wrong thing -> **Standards pass, Spec fail.**
117
+ - Code that does exactly what the issue asked but breaks the project's conventions -> **Spec pass, Standards fail.**
118
+
119
+ Reporting them separately stops one axis from masking the other.
package/skills/tdd/SKILL.md ADDED
@@ -0,0 +1,157 @@
1
+ ---
2
+ name: tdd
3
+ description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
4
+ ---
5
+
6
+ # Test-Driven Development
7
+
8
+ ## Inputs (S1 nodes A5 / B5)
9
+
10
+ This skill operates on a single need. Read the following before starting any cycle:
11
+
12
+ - `spec/needs/<need-name>/design.md` - the HOW (modules, interfaces, key trade-offs); test names and the public interfaces under test SHOULD match its vocabulary
13
+ - `spec/needs/<need-name>/todo.md` - the rolling task list produced by A4 `to-issues`; pick the next unchecked `## 实施` item, top-down
14
+ - `spec/INDEX.md` - domain vocabulary; cross-need ADRs at `spec/ADR/`
15
+
16
+ ## Hard Constraints
17
+
18
+ - **No scope smuggling.** Do NOT implement anything not present in `design.md`. If the current `todo.md` item requires behavior the design did not anticipate, STOP, go back to A3 (`writing-plans`) to patch `design.md`, then resume here.
19
+ - **One slice at a time.** Pick a single `- [ ]` item from `## 实施`, complete the full red -> green -> refactor cycle for it, mark it `- [x]`, then move to the next. Do not batch.
20
+ - **End-to-end verification is A6's job, not A5's.** This skill's exit criterion is "all `## 实施` items checked + tests green at the slice seam". Real-user-path verification happens in A6 `verification-before-completion`.
21
+
22
+ ## Two Modes
23
+
24
+ | Mode | When | Output |
25
+ |------|------|--------|
26
+ | **A5 (development)** | Driven by `todo.md` after a fresh need passes A4 | Roll `todo.md` forward; mark items `- [x]` as each cycle completes |
27
+ | **B5 (fix)** | Driven by an existing `spec/needs/<need-name>/issues/<topic>.md` after B3 diagnose | Apply the fix per the root cause; `todo.md` is NOT touched (it was already fully checked when the bug surfaced). Append progress notes to the issue file's `## bug` section instead. |
28
+
29
+ ## Philosophy
30
+
31
+ **Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
32
+
33
+ **Good tests** are integration-style: they exercise real code paths through public APIs. They describe _what_ the system does, not _how_ it does it. A good test reads like a specification - "user can checkout with valid cart" tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure.
34
+
35
+ **Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior.
36
+
37
+ See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
38
+
39
+ ## Anti-Pattern: Horizontal Slices
40
+
41
+ **DO NOT write all tests first, then all implementation.** This is "horizontal slicing" - treating RED as "write all tests" and GREEN as "write all code."
42
+
43
+ This produces **crap tests**:
44
+
45
+ - Tests written in bulk test _imagined_ behavior, not _actual_ behavior
46
+ - You end up testing the _shape_ of things (data structures, function signatures) rather than user-facing behavior
47
+ - Tests become insensitive to real changes - they pass when behavior breaks, fail when behavior is fine
48
+ - You outrun your headlights, committing to test structure before understanding the implementation
49
+
50
+ **Correct approach**: Vertical slices via tracer bullets. One test -> one implementation -> repeat. Each test responds to what you learned from the previous cycle. Because you just wrote the code, you know exactly what behavior matters and how to verify it.
51
+
52
+ ```
53
+ WRONG (horizontal):
54
+ RED: test1, test2, test3, test4, test5
55
+ GREEN: impl1, impl2, impl3, impl4, impl5
56
+
57
+ RIGHT (vertical):
58
+ RED->GREEN: test1->impl1
59
+ RED->GREEN: test2->impl2
60
+ RED->GREEN: test3->impl3
61
+ ...
62
+ ```
63
+
64
+ ## Workflow
65
+
66
+ ### 1. Planning
67
+
68
+ When exploring the codebase, use vocabulary from `spec/INDEX.md` and the current need's `design.md` so that test names and interface vocabulary match the project's language. Respect ADRs under `spec/ADR/`.
69
+
70
+ Before writing any code for the current slice:
71
+
72
+ - [ ] Read the `## 实施` item being implemented; confirm it traces to a section in `design.md`
73
+ - [ ] Confirm with user (or re-read `design.md`) what interface changes the slice requires
74
+ - [ ] Confirm which behaviors to test (prioritize per slice acceptance criteria)
75
+ - [ ] Identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation)
76
+ - [ ] Design interfaces for [testability](interface-design.md)
77
+ - [ ] List the behaviors to test (not implementation steps)
78
+ - [ ] If `design.md` needs amendment (new behavior surfaced), STOP and go back to A3
79
+
80
+ Ask: "What should the public interface look like? Which behaviors are most important to test?"
81
+
82
+ **You can't test everything.** Confirm with the user exactly which behaviors matter most. Focus testing effort on critical paths and complex logic, not every possible edge case.
83
+
84
+ ### 2. Tracer Bullet
85
+
86
+ Write ONE test that confirms ONE thing about the system:
87
+
88
+ ```
89
+ RED: Write test for first behavior -> test fails
90
+ GREEN: Write minimal code to pass -> test passes
91
+ ```
92
+
93
+ This is your tracer bullet - proves the path works end-to-end.
94
+
95
+ ### 3. Incremental Loop
96
+
97
+ For each remaining behavior:
98
+
99
+ ```
100
+ RED: Write next test -> fails
101
+ GREEN: Minimal code to pass -> passes
102
+ ```
103
+
104
+ Rules:
105
+
106
+ - One test at a time
107
+ - Only enough code to pass current test
108
+ - Don't anticipate future tests
109
+ - Keep tests focused on observable behavior
110
+
111
+ ### 4. Refactor
112
+
113
+ After all tests pass, look for [refactor candidates](refactoring.md):
114
+
115
+ - [ ] Extract duplication
116
+ - [ ] Deepen modules (move complexity behind simple interfaces)
117
+ - [ ] Apply SOLID principles where natural
118
+ - [ ] Consider what new code reveals about existing code
119
+ - [ ] Run tests after each refactor step
120
+
121
+ **Never refactor while RED.** Get to GREEN first.
122
+
123
+ ## Checklist Per Cycle
124
+
125
+ ```
126
+ [ ] Test describes behavior, not implementation
127
+ [ ] Test uses public interface only
128
+ [ ] Test would survive internal refactor
129
+ [ ] Code is minimal for this test
130
+ [ ] No speculative features added
131
+ ```
132
+
133
+ ## After Each Slice (A5)
134
+
135
+ 1. Tick the corresponding `- [ ]` -> `- [x]` in `spec/needs/<need-name>/todo.md`
136
+ 2. Update `spec/INDEX.md`:
137
+ - Bump the `todo` column counter (e.g. `2/8` -> `3/8`)
138
+ - If all `## 实施` items are now checked, set `当前节点` to `A6 verify` (per `spec-framework.md` INDEX rules)
139
+ - If unsure, run `/ae-index-rebuild`
140
+ 3. Commit. Suggested message: `feat(<need-name>): T<n> <title>`.
141
+
142
+ ## After All Slices Checked (A5 only)
143
+
144
+ Hand off to A6 `verification-before-completion` for end-to-end verification on the real user path. This skill's job ends when `todo.md` is fully checked AND slice-level tests are green.
145
+
146
+ ## After Fix Lands (B5 only)
147
+
148
+ 1. Do NOT modify `todo.md` (it was fully checked before the bug surfaced).
149
+ 2. Append a short progress note under the issue file's `## bug` section (the 7-section format produced at B4). Quote the failing test name and the root-cause one-liner.
150
+ 3. Commit. Suggested message: `fix(<need-name>): <root cause summary>`.
151
+ 4. Hand off to B6 user re-verification.
152
+
153
+ ## Boundaries
154
+
155
+ - This skill writes code and tests, plus updates `todo.md` (A5) or the issue file's `## bug` section (B5).
156
+ - It does NOT write `prd.md`, `design.md`, or new ADRs. Scope changes go back through A3.
157
+ - It does NOT perform end-to-end / user-path verification - that is A6.
package/skills/tdd/deep-modules.md ADDED
@@ -0,0 +1,33 @@
1
+ # Deep Modules
2
+
3
+ From "A Philosophy of Software Design":
4
+
5
+ **Deep module** = small interface + lots of implementation
6
+
7
+ ```
8
+ ┌─────────────────────┐
9
+ │ Small Interface │ ← Few methods, simple params
10
+ ├─────────────────────┤
11
+ │ │
12
+ │ │
13
+ │ Deep Implementation│ ← Complex logic hidden
14
+ │ │
15
+ │ │
16
+ └─────────────────────┘
17
+ ```
18
+
19
+ **Shallow module** = large interface + little implementation (avoid)
20
+
21
+ ```
22
+ ┌─────────────────────────────────┐
23
+ │ Large Interface │ ← Many methods, complex params
24
+ ├─────────────────────────────────┤
25
+ │ Thin Implementation │ ← Just passes through
26
+ └─────────────────────────────────┘
27
+ ```
28
+
29
+ When designing interfaces, ask:
30
+
31
+ - Can I reduce the number of methods?
32
+ - Can I simplify the parameters?
33
+ - Can I hide more complexity inside?