ai-spec-dev 0.31.0 → 0.35.0

package/.claude/commands/add-lesson.md

@@ -0,0 +1,34 @@
+Append a lesson learned to the project constitution's §9 accumulated lessons section.
+
+**Input:** $ARGUMENTS (paste a review finding, bug description, or any lesson to remember)
+
+**Steps:**
+
+1. Read `.ai-spec-constitution.md` in the current directory. If it doesn't exist, check for it in the git root.
+
+2. Check if a `## 9. 积累教训` (or `## 9. Accumulated Lessons`) section exists.
+   - If not, append it at the end of the file.
+
+3. Before appending, **deduplicate**: scan existing lesson entries. If the first 60 characters of the new lesson closely match an existing entry (case-insensitive, ignoring punctuation), do NOT add a duplicate — instead say "Similar lesson already exists: [existing entry]" and stop.
+
+4. Classify the lesson into one of these categories:
+   - `[bug]` — logic error or crash that occurred
+   - `[security]` — auth, injection, exposure issue
+   - `[pattern]` — wrong architectural pattern used
+   - `[perf]` — performance regression
+   - `[convention]` — naming, structure, file organization issue
+   - `[other]` — anything else
+
+5. Append in this exact format:
+```
+- [YYYY-MM-DD] [category] <one-sentence description of what went wrong and how to avoid it>
+```
+
+**Example output:**
+```
+- [2026-04-01] [pattern] Store directly called axios instead of going through the API layer — stores must only call functions from src/api/, never import axios directly.
+```
+
+6. Confirm: "Lesson added to §9. Constitution now has N lessons. Consider running `ai-spec init --consolidate` when lessons exceed 8."
+
+**Important:** Be concise. One sentence per lesson. Focus on the actionable rule, not the incident narrative.

package/.claude/commands/check-layers.md

@@ -0,0 +1,65 @@
+Check generated or modified code for layer architecture violations.
+
+**Input:** $ARGUMENTS (file path or directory to check; leave empty to check recent changes)
+
+**What counts as a layer violation:**
+
+```
+Typical layered architecture:
+
+  routes / controllers
+       ↓  (can call)
+     services
+       ↓  (can call)
+   repositories / DB / ORM
+       ↓  (can call)
+    external APIs / infra
+
+  stores (state management)
+       ↓  (can call)
+     api layer (src/api/)
+       ↓  (can call)
+    HTTP client (axios / fetch)
+```
+
+**Violations to detect:**
+
+1. **Store → HTTP direct**: a Pinia/Vuex/Zustand store imports `axios`, `fetch`, or an HTTP client directly instead of going through `src/api/`
+2. **Route → DB direct**: a route/controller file imports Prisma client, Mongoose models, or raw SQL directly — should go through a service
+3. **Component → Service direct**: a UI component imports a service layer function directly instead of going through a store or composable
+4. **Service → Route import**: a service imports anything from the routes layer (circular)
+5. **Cross-feature direct import**: feature A directly imports internal files from feature B (should go through a shared interface)
+
+**Steps:**
+
+1. Determine which files to check (same logic as `/verify-imports`).
+
+2. For each file, read its imports and the file's own layer (infer from path: `routes/`, `controllers/`, `services/`, `stores/`, `components/`, `api/`, `repositories/`).
+
+3. Check each import against the allowed call directions above.
+
+4. Output:
+
+```
+=== Layer Architecture Report ===
+
+✘  src/stores/cartStore.ts  [layer: store]
+     imports axios directly from 'axios'
+     → Violation: store must not make HTTP calls directly
+     → Fix: move HTTP call to src/api/cart.ts, import that function here
+
+✘  src/views/OrderList.vue  [layer: component]
+     imports orderService from '@/services/orderService'
+     → Violation: component should call store, not service directly
+     → Fix: expose this via src/stores/orderStore.ts action
+
+✔  src/services/userService.ts — no violations
+✔  src/api/user.ts — no violations
+
+─────────────────────────────────
+Total: 4 files  |  ✔ 2 clean  |  ✘ 2 violations
+```
+
+5. If you can't determine the project's layer structure from file paths alone, read the project constitution (`.ai-spec-constitution.md` §1 Architecture Rules) first.
+
+6. If no violations found: "Layer architecture check passed ✔ — no cross-layer violations detected."

package/.claude/commands/installed-deps.md

@@ -0,0 +1,35 @@
+List all installed packages in the current project as a dependency whitelist for code generation.
+
+**Steps:**
+
+1. Read `package.json` from the current directory (or git root if not found here).
+
+2. Collect all keys from `dependencies` and `devDependencies`.
+
+3. Also detect non-Node language markers:
+   - `go.mod` present → Go project, list module dependencies from go.mod
+   - `Cargo.toml` present → Rust project, list [dependencies] from Cargo.toml
+   - `requirements.txt` / `pyproject.toml` present → Python project, list packages
+
+4. Output in this format:
+
+```
+=== Installed Packages — ONLY use these in generated code ===
+
+Runtime dependencies:
+  express, prisma, @prisma/client, jsonwebtoken, redis, zod, ...
+
+Dev dependencies:
+  typescript, jest, @types/express, ts-node, ...
+
+⚠  Hard rules for code generation:
+  1. NEVER import a package not listed above — implement the equivalent using what IS installed
+  2. If you need HTTP client → use: [detected: axios / fetch / got / ky — pick from list]
+  3. If you need validation → use: [detected: zod / joi / yup / class-validator — pick from list]
+  4. If you need date handling → use: [detected: dayjs / date-fns / moment — pick from list]
+  5. If a capability needs a missing package → say so explicitly, do NOT silently add an import
+```
+
+5. After the list, highlight any commonly confused alternatives detected (e.g., if both `axios` and native `fetch` patterns exist in the codebase, flag this ambiguity).
+
+This manifest should be treated as ground truth for the entire coding session — copy it into your context when asking Claude to generate code.

package/.claude/commands/recall-lessons.md

@@ -0,0 +1,40 @@
+Surface relevant accumulated lessons from the project constitution before starting a task.
+
+**Input:** $ARGUMENTS (describe the task you're about to do, e.g. "add a payment API endpoint" or "build a user profile page")
+
+**Steps:**
+
+1. Read `.ai-spec-constitution.md` in the current directory (or git root).
+   - If not found, say "No constitution found. Run `ai-spec init` to generate one." and stop.
+
+2. Find the `## 9. 积累教训` or `## 9. Accumulated Lessons` section.
+   - If not found, say "No accumulated lessons yet (§9 section missing). This is normal for new projects." and stop.
+
+3. Read all lesson entries. For each one, score its relevance to the current task description on a scale:
+   - **High** — directly related (same domain, same layer, same pattern)
+   - **Medium** — adjacent (same tech area but different feature)
+   - **Low** — unrelated
+
+4. Output only High and Medium relevance lessons:
+
+```
+=== Relevant Lessons for: "<task description>" ===
+
+⚠  HIGH relevance — apply these directly:
+  - [2026-03-15] [pattern] ...lesson text...
+  - [2026-03-20] [security] ...lesson text...
+
+💡 MEDIUM relevance — keep in mind:
+  - [2026-02-10] [convention] ...lesson text...
+
+Total lessons in §9: N  |  Shown: M relevant
+```
+
+5. If there are High relevance lessons, add:
+```
+Before writing any code, confirm you've accounted for each ⚠ lesson above.
+```
+
+6. If no lessons are relevant, say: "No directly relevant lessons found. Proceed, and remember to `/add-lesson` after review."
+
+**Purpose:** Prevents repeating past mistakes by making institutional knowledge visible at the start of every task.

package/.claude/commands/scan-singletons.md

@@ -0,0 +1,45 @@
+Scan the current project for all "singleton config files" — files that must never be duplicated and can only be modified in place.
+
+**What to scan for:**
+
+Search the project (excluding node_modules, dist, .git) for files matching these patterns:
+- i18n / locale files: `**/locales/**/*.json`, `**/i18n/**/*.{json,ts,js}`, `**/*.locale.{ts,js}`, `**/lang/**/*.{json,ts,js}`
+- Constants / enums: `**/constants/**/*.{ts,js}`, `**/enums/**/*.{ts,js}`, `**/*constants*.{ts,js}`, `**/*enums*.{ts,js}`
+- Route index files: `**/routes/index.{ts,js}`, `**/router/index.{ts,js}`, `**/routes.{ts,js}`
+- Store index files: `**/stores/index.{ts,js}`, `**/store/index.{ts,js}`
+- Global config: `**/config/index.{ts,js}`, `**/config.{ts,js,json}` (project root level only)
+- Error codes: `**/*error*code*.{ts,js}`, `**/*ErrorCode*.{ts,js}`
+
+**Output format:**
+
+Print a manifest like this:
+
+```
+=== Singleton Config Files — MODIFY ONLY, NEVER RECREATE ===
+
+i18n / Locale:
+  - src/locales/zh-CN.json          ← append new keys here
+  - src/locales/en-US.json          ← append new keys here
+
+Constants / Enums:
+  - src/constants/index.ts          ← add new constants here
+  - src/enums/status.ts             ← add new enum values here
+
+Route Registration:
+  - src/router/index.ts             ← register new routes here
+
+Store Registration:
+  - src/stores/index.ts             ← register new stores here
+
+Error Codes:
+  - src/constants/errorCodes.ts     ← add new error codes here
+
+⚠  Rules:
+  1. When adding translations → append keys to the files above, never create a new locale file
+  2. When adding constants/enums → add values to existing file, never create a parallel file
+  3. When adding a new route → register it in the route index above
+  4. When adding a new store → register it in the store index above
+  5. If a file in the list doesn't exist yet, create it once — then it becomes the singleton
+```
+
+After printing the manifest, ask: "Do you want me to save this manifest to `.ai-spec-constitution.md` §8 for future use?"

package/.claude/commands/verify-imports.md

@@ -0,0 +1,48 @@
+Verify that all import paths in generated or modified files actually exist in the project.
+
+**Input:** $ARGUMENTS (file path, directory path, or leave empty to check all recently modified files)
+
+**Steps:**
+
+1. Determine which files to check:
+   - If a file path is given → check that file only
+   - If a directory is given → check all `.ts` / `.js` / `.tsx` / `.jsx` files in it
+   - If empty → check files modified in the last git commit (`git diff --name-only HEAD~1`)
+
+2. For each file, extract all import statements:
+   - `import ... from '...'`
+   - `require('...')`
+   - `import('...')`
+
+3. Classify each import:
+   - **External package** (no leading `./`, `../`, `@/`, `~/`) → verify it's in `package.json` dependencies
+   - **Alias path** (`@/`, `~/`, `#`) → resolve using `tsconfig.json` `paths` or `vite.config` `alias`, then verify the resolved path exists
+   - **Relative path** (`./`, `../`) → resolve relative to the file, verify the file exists (check `.ts`, `.tsx`, `.js`, `/index.ts` variants)
+
+4. Output:
+
+```
+=== Import Verification Report ===
+
+✔  src/api/user.ts
+     @/utils/request → src/utils/request.ts ✔
+     @/types/user → src/types/user.ts ✔
+
+✘  src/stores/orderStore.ts
+     @/utils/http → NOT FOUND  ← did you mean @/utils/request?
+     ../services/paymentService → NOT FOUND  ← file doesn't exist
+
+✔  src/router/index.ts
+     (all imports verified)
+
+─────────────────────────────────
+Total: 3 files  |  ✔ 2 clean  |  ✘ 1 with broken imports
+```
+
+5. For each broken import, suggest the most likely correct path by:
+   - Searching for files with a similar name in the project
+   - Checking git history for recently renamed files
+
+6. If all imports are clean, say: "All imports verified ✔ — no hallucinated paths found."
+
+**Why this matters:** AI models frequently invent import paths (`@/utils/http` instead of `@/utils/request`) that look plausible but don't exist, causing silent build failures.

package/.claude/settings.local.json

@@ -4,7 +4,21 @@
       "Bash(npm run:*)",
       "Bash(python3 -c \":*)",
       "Bash(grep -E \"^./\\\\w+/|^./\\\\w+\\\\.ts$\")",
-      "Bash(wc -l core/*.ts prompts/*.ts)"
+      "Bash(wc -l core/*.ts prompts/*.ts)",
+      "Bash(npx tsc:*)",
+      "Bash(npm install:*)",
+      "Bash(npx vitest:*)",
+      "Bash(npm test:*)",
+      "Bash(for f:*)",
+      "Bash(do echo:*)",
+      "Read(//Users/hongzhong/Documents/文稿 - hongzhong的MacBook Pro/code/ai-spec-dev-poc/**)",
+      "Bash(done)",
+      "Bash(node dist/cli/index.js dashboard)",
+      "Bash(grep -E \"\\\\.\\(ts|js\\)$\")",
+      "Read(//Users/hongzhong/Documents/文稿 - hongzhong的MacBook Pro/code/**)",
+      "Bash(npx tsx:*)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:raw.githubusercontent.com)"
     ]
   }
 }