@ecc-hgy/ae 0.5.0 → 0.6.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 huguiyuan
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 huguiyuan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,159 +1,172 @@
-# Agentic Engineering
-
-[![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 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
-
-```bash
-cd /your/project
-npx @ecc-hgy/ae setup
-npx @ecc-hgy/ae init "one-line project goal"
-```
-
-`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:
-
-```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`.
-
-## CLI
-
-```bash
-ae setup
-ae setup --platform claude,codex,cursor
-ae init "one-line project goal"
-ae --help
-ae --version
-```
-
-Both commands are idempotent. They create missing files, skip existing files, and never overwrite existing entry files. There is no `--force` mode.
-
-`ae init` requires `ae setup` to have run first. This keeps asset installation explicit before skeleton creation.
-
-## Single Source Of Truth
-
-- `AGENTS.md` is the canonical project instructions file.
-- `CLAUDE.md` is a short pointer to `AGENTS.md`; do not maintain a separate copy there.
-- `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:
-
-| 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
-
-| Scenario | Purpose | Main output |
-|----------|---------|-------------|
-| S0 Bootstrap | Initialize project structure and entry files | `spec/`, `AGENTS.md`, `CLAUDE.md`, `handoff.md` |
-| S1A Need | Turn an idea into spec, design, tasks, code, and verification | `prd.md`, `design.md`, `todo.md`, tested code |
-| S1B Acceptance | Let user acceptance drive debug, fix, re-verification, and sedimentation | `issues/<topic>.md`, PRD/design/ADR updates |
-| S2 Evolution | Promote repeated working habits into reusable method assets | rule or skill proposals |
-
-The two hard gates are:
-
-- No aligned requirement, no `prd.md`.
-- No aligned expected behavior, no bug fix.
-
-## Skills
-
-| 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`. |
-| `writing-plans` | Writes `spec/needs/<need-name>/design.md`. |
-| `to-issues` | Breaks design into `todo.md` vertical slices. |
-| `tdd` | Drives A5 development and B5 bug fixes by red-green-refactor. |
-| `verification-before-completion` | Requires fresh real-path evidence before completion claims. |
-| `diagnose` | Builds a reproducible feedback loop and identifies root cause. |
-| `review` | Reviews against standards and spec, then routes findings into PRD, design, ADR, or S2 candidates. |
-| `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
-
-- [Framework](docs/framework.md)
-- [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](方案/skill-candidates/README.md)
-
-## Repository Layout
-
-```text
-bin/        npm executable entry
-src/        zero-dependency CLI implementation
-skills/     Selected Agentic Engineering skills
-templates/  Entry file templates
-docs/       Methodology docs (framework, scenarios, spec framework)
-方案/        Design & decision records (issues, roadmap, skill candidates, archive)
-tests/      node:test coverage for CLI behavior
-```
-
-## Roadmap
-
+# Agentic Engineering
+
+[![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 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
+
+```bash
+cd /your/project
+npx @ecc-hgy/ae setup
+npx @ecc-hgy/ae init "one-line project goal"
+```
+
+`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:
+
+```bash
+npx @ecc-hgy/ae setup --platform claude,codex
+```
+
+`ae init` creates the platform-neutral project skeleton and renders entry files. The default maintained roots are `src/`, `tests/`, `docs/`, and `data/`; build tools create `dist/` when needed. Project-specific rules live directly in `AGENTS.md`.
+
+## CLI
+
+```bash
+ae setup
+ae setup --platform claude,codex,cursor
+ae init "one-line project goal"
+ae --help
+ae --version
+```
+
+Both commands are idempotent. They create missing files, skip existing files, and never overwrite existing entry files. There is no `--force` mode.
+
+`ae init` requires `ae setup` to have run first. This keeps asset installation explicit before skeleton creation.
+
+## Single Source Of Truth
+
+- `AGENTS.md` is the canonical project instructions file.
+- `CLAUDE.md` is a short pointer to `AGENTS.md`; do not maintain a separate copy there.
+- `ae init` renders `AGENTS.md` with the title, goal, and one default rule: organize maintained files by responsibility and disclose detail progressively. Add project-specific rules and sections as needed; no section format is imposed.
+
+## Project Structure
+
+- `src/` contains product code, entry points, and scripts. Organize it by durable responsibility rather than mirroring `spec/needs/`; one need may touch several modules and one module may serve several needs.
+- `tests/` contains tests and test fixtures, grouped by capability or scenario.
+- `docs/` contains source documents, guides, and maintained project knowledge.
+- `data/` contains project data and run results. Its internal layout grows with the project's actual needs.
+- `dist/` is reserved for generated build artifacts and is created by the build tool, not by `ae init`.
+
+If an existing project already uses a common source root (`app/`, `apps/`, `lib/`, or `packages/`) or test root (`test/` or `__tests__/`), `ae init` keeps that layout instead of adding a duplicate `src/` or `tests/` root.
+
+## Platform Scope
+
+Current target platforms:
+
+| 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
+
+| Scenario | Purpose | Main output |
+|----------|---------|-------------|
+| S0 Bootstrap | Initialize project structure and entry files | `spec/`, `AGENTS.md`, `CLAUDE.md`, `handoff.md` |
+| S1A Need | Turn an idea into spec, design, tasks, code, and verification | `prd.md`, `design.md`, `todo.md`, tested code |
+| S1B Acceptance | Let user acceptance drive debug, fix, re-verification, and sedimentation | `issues/<topic>.md`, PRD/design/ADR updates |
+| S2 Evolution | Promote repeated working habits into reusable method assets | rule or skill proposals |
+
+The two hard gates are:
+
+- No aligned requirement, no `prd.md`.
+- No aligned expected behavior, no bug fix.
+
+## Skills
+
+| 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`. |
+| `writing-plans` | Writes `spec/needs/<need-name>/design.md`. |
+| `to-issues` | Breaks design into `todo.md` vertical slices. |
+| `tdd` | Drives A5 development and B5 bug fixes by red-green-refactor. |
+| `verification-before-completion` | Requires fresh real-path evidence before completion claims. |
+| `diagnose` | Builds a reproducible feedback loop and identifies root cause. |
+| `review` | Reviews against standards and spec, then routes findings into PRD, design, ADR, or S2 candidates. |
+| `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
+
+- [Framework](docs/framework.md)
+- [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](方案/skill-candidates/README.md)
+
+## Repository Layout
+
+```text
+bin/        npm executable entry
+src/        zero-dependency CLI implementation
+skills/     Selected Agentic Engineering skills
+templates/  Entry file templates
+docs/       Methodology docs (framework, scenarios, spec framework)
+方案/        Design & decision records (issues, roadmap, skill candidates, archive)
+tests/      node:test coverage for CLI behavior
+```
+
+## Roadmap
+
 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
-
-`ae index-rebuild` and `ae update` are referenced by the roadmap but not implemented yet. Publishing to npm still requires `npm login`, scope validation, and `npm publish --access public`.
+- v0.4: add the request router, coding discipline, and progressive spec rules.
+- v0.5: install skills for 15 project-level AI coding platforms.
+- v0.6: use a small-project skeleton with responsibility-based, progressively disclosed structure.
+
+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
+
+`ae index-rebuild` and `ae update` are referenced by the roadmap but not implemented yet. Publishing to npm still requires `npm login`, scope validation, and `npm publish --access public`.

package/bin/ae.js

@@ -1,2 +1,2 @@
-#!/usr/bin/env node
-import('../src/cli.js').then((m) => m.run(process.argv.slice(2)));
+#!/usr/bin/env node
+import('../src/cli.js').then((m) => m.run(process.argv.slice(2)));

package/package.json

@@ -1,43 +1,43 @@
-{
-  "name": "@ecc-hgy/ae",
-  "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": {
-    "ae": "bin/ae.js"
-  },
-  "files": [
-    "bin",
-    "src",
-    "skills",
-    "templates",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "test": "node --test tests/*.test.js"
-  },
-  "keywords": [
-    "claude-code",
-    "agentic",
-    "skills",
-    "tdd",
-    "sdd"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/huguiyuan/agentic-engineering.git"
-  },
-  "homepage": "https://github.com/huguiyuan/agentic-engineering#readme",
-  "bugs": {
-    "url": "https://github.com/huguiyuan/agentic-engineering/issues"
-  },
-  "license": "MIT",
-  "author": "huguiyuan",
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@ecc-hgy/ae",
+  "version": "0.6.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": {
+    "ae": "bin/ae.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.js"
+  },
+  "keywords": [
+    "claude-code",
+    "agentic",
+    "skills",
+    "tdd",
+    "sdd"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/huguiyuan/agentic-engineering.git"
+  },
+  "homepage": "https://github.com/huguiyuan/agentic-engineering#readme",
+  "bugs": {
+    "url": "https://github.com/huguiyuan/agentic-engineering/issues"
+  },
+  "license": "MIT",
+  "author": "huguiyuan",
+  "publishConfig": {
+    "access": "public"
+  }
+}