@ecc-hgy/ae 0.3.0 → 0.5.0

package/README.md

@@ -3,7 +3,30 @@
 [![npm version](https://img.shields.io/npm/v/@ecc-hgy/ae.svg)](https://www.npmjs.com/package/@ecc-hgy/ae)
 [![license](https://img.shields.io/npm/l/@ecc-hgy/ae.svg)](LICENSE)
 
-Agentic Engineering is a lightweight personal software lifecycle method: SDD records what to build, TDD drives how to prove it works. It is delivered as a zero-dependency npm CLI plus agent skills for Claude Code and Codex.
+Agentic Engineering is a lightweight personal software lifecycle method: SDD records what to build, TDD drives how to prove it works. It is delivered as a zero-dependency npm CLI plus agent skills for multiple AI coding platforms.
+
+## How It Works
+
+```text
+   (one-time)  ─────▶  S0 Bootstrap · ae setup → ae init
+                            │
+   (each request) ──▶  Router · is this request a *need*?
+                            │
+                ┌──── no ────┴──── yes ────┐
+                ▼                           ▼
+           just do it                enter S1 Main Loop
+       (Q&A / quick fix /                   │
+        throwaway script)                   ├─ A. Need:   align → PRD → design → todo → TDD → verify
+                                            └─ B. Accept: accept → debug → fix → reverify → sediment
+                                                          │
+                                                          ▼  (rules proven useful)
+                                                     S2 Evolution
+
+   Legend:  SDD = align→PRD→design→todo   ·   TDD = TDD→verify, fix→reverify
+   State:   spec/ = what to build (persistent) · INDEX.md = need@node · handoff.md = session snapshot
+```
+
+A router (the `using-agentic-engineering` skill) gates each non-trivial request: a *need* enters the SDD+TDD loop, everything else is just done. Questions, quick fixes, and throwaway scripts never pay the ceremony.
 
 ## Quick Start
 
@@ -13,10 +36,11 @@ npx @ecc-hgy/ae setup
 npx @ecc-hgy/ae init "one-line project goal"
 ```
 
-`ae setup` installs reusable method assets:
+`ae setup` installs reusable method assets into the AI coding platforms you select. In interactive terminals it prompts for platforms and preselects detected local platform directories. In scripts or CI, pass platforms explicitly:
 
-- `skills/` -> `.claude/skills/`
-- `skills/` -> `.codex/skills/`
+```bash
+npx @ecc-hgy/ae setup --platform claude,codex
+```
 
 `ae init` creates the platform-neutral project skeleton and renders entry files. Project-specific rules live directly in `AGENTS.md`.
 
@@ -24,6 +48,7 @@ npx @ecc-hgy/ae init "one-line project goal"
 
 ```bash
 ae setup
+ae setup --platform claude,codex,cursor
 ae init "one-line project goal"
 ae --help
 ae --version
@@ -37,16 +62,31 @@ Both commands are idempotent. They create missing files, skip existing files, an
 
 - `AGENTS.md` is the canonical project instructions file.
 - `CLAUDE.md` is a short pointer to `AGENTS.md`; do not maintain a separate copy there.
-- All project-specific rules live in `AGENTS.md` under `## Project-Specific Rules`.
+- `ae init` renders `AGENTS.md` nearly blank (title + goal); add your own rules and sections as the project grows — no imposed format.
 
 ## Platform Scope
 
 Current target platforms:
 
-- Claude Code: skills installed to `.claude/skills/`
-- Codex: skills installed to `.codex/skills/`
-
-Cursor and Trae support is intentionally deferred until their stable local skill/rule loading conventions are confirmed.
+| Platform | ID | Skills directory |
+|----------|----|------------------|
+| Claude Code | `claude` | `.claude/skills/` |
+| Codex | `codex` | `.codex/skills/` |
+| Windsurf | `windsurf` | `.windsurf/skills/` |
+| GitHub Copilot | `github-copilot` | `.github/skills/` |
+| Kilo Code | `kilocode` | `.kilocode/skills/` |
+| Kimi Code | `kimicode` | `.kimi-code/skills/` |
+| CodeBuddy | `codebuddy` | `.codebuddy/skills/` |
+| Qoder | `qoder` | `.qoder/skills/` |
+| Trae | `trae` | `.trae/skills/` |
+| Cursor | `cursor` | `.cursor/skills/` |
+| OpenCode | `opencode` | `.opencode/skills/` |
+| Antigravity | `antigravity` | `.agents/skills/` |
+| Gemini CLI | `gemini` | `.gemini/skills/` |
+| Qwen Code | `qwen` | `.qwen/skills/` |
+| Kiro | `kiro` | `.kiro/skills/` |
+
+The first implementation is project-scoped only. It does not generate platform-specific entry rule files such as `.cursorrules`, `GEMINI.md`, or Copilot instructions.
 
 ## Method Overview
 
@@ -66,6 +106,7 @@ The two hard gates are:
 
 | Skill | Role |
 |-------|------|
+| `using-agentic-engineering` | Router: at the start of a non-trivial change, decides whether it enters the SDD+TDD loop and dispatches to the right node skill. |
 | `brainstorming` | Coarse requirement alignment before writing PRD. |
 | `grill-me` | Fine-grained questioning for interface, field, parameter, or expected-state ambiguity. |
 | `to-prd` | Writes `spec/needs/<need-name>/prd.md`. |
@@ -78,6 +119,7 @@ The two hard gates are:
 | `handoff` | Writes the latest session snapshot to `handoff.md`. |
 | `improve-codebase-architecture` | User-triggered architecture deepening review. |
 | `zoom-out` | User-triggered higher-level codebase map. |
+| `karpathy-guidelines` | Always-on coding discipline during A5/B5: think before coding, simplicity first, surgical changes, goal-driven execution. |
 
 ## Documentation
 
@@ -85,7 +127,7 @@ The two hard gates are:
 - [Spec Framework](docs/spec-framework.md)
 - [S0 Bootstrap](docs/scenarios/s0-bootstrap.md)
 - [S1 Main Loop](docs/scenarios/s1-main-loop.md)
-- [Skill Candidate Design Notes](design/skill-candidates/README.md)
+- [Skill Candidate Design Notes](方案/skill-candidates/README.md)
 
 ## Repository Layout
 
@@ -94,18 +136,23 @@ bin/        npm executable entry
 src/        zero-dependency CLI implementation
 skills/     Selected Agentic Engineering skills
 templates/  Entry file templates
-docs/       User-facing methodology docs
-design/     Design records for this repository
+docs/       Methodology docs (framework, scenarios, spec framework)
+方案/        Design & decision records (issues, roadmap, skill candidates, archive)
 tests/      node:test coverage for CLI behavior
 ```
 
 ## Roadmap
 
-1. Stage 2: npm CLI asset distribution with `init` and `ingest-mother`. Superseded by v0.2.
-2. v0.2: split CLI into `setup` + `init`, remove slash command assets, and move rule sync into `ae init`.
-3. v0.3: remove rules injection; make `AGENTS.md` the single source of truth and `CLAUDE.md` a pointer.
-4. Stage 3: design `ae update` for skill/template upgrades and implement `ae index-rebuild`.
-5. Add CI and Windows path validation before broader distribution.
+Completed:
+
+- v0.2: split CLI into `setup` + `init` and remove slash command assets.
+- v0.3: remove rules injection; make `AGENTS.md` the single source of truth and `CLAUDE.md` a pointer.
+
+Next:
+
+1. Design `ae update` for skill/template upgrades.
+2. Implement `ae index-rebuild`.
+3. Add CI and Windows path validation before broader distribution.
 
 ## Limits
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecc-hgy/ae",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Agentic Engineering is a lightweight personal software lifecycle method: SDD records what to build, TDD drives how to prove it works.",
   "type": "module",
   "bin": {

package/skills/diagnose/SKILL.md

@@ -18,7 +18,7 @@ If B2 has NOT been completed (the expected behavior is still ambiguous), STOP an
 
 ## Exit Contract (hand-off to B4)
 
-After Phase 6, do NOT write the issue file inline - that is B4's job. Instead, hand off a structured summary so B4 can write `spec/needs/<need-name>/issues/<topic>.md` in one pass, using the 7-section format in [assets/issue-7-sections.md](assets/issue-7-sections.md).
+After Phase 6, do NOT write the issue file inline - that is B4's job. Instead, hand off a structured summary so B4 can write `spec/needs/<need-name>/issues/<topic>.md` (`<topic>` is kebab-case) in one pass, using the 7-section format in [assets/issue-7-sections.md](assets/issue-7-sections.md).
 
 Sections this skill is expected to populate:
 

package/skills/karpathy-guidelines/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: karpathy-guidelines
+description: Behavioral guidelines to reduce common LLM coding mistakes. Use when writing, reviewing, or refactoring code to avoid overcomplication, make surgical changes, surface assumptions, and define verifiable success criteria.
+license: MIT
+---
+
+# Karpathy Guidelines
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.