add-coder 0.1.14 โ†’ 0.1.15

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 (3) hide show
  1. package/README.en.md +218 -0
  2. package/README.md +15 -1
  3. package/package.json +1 -1
package/README.en.md ADDED
@@ -0,0 +1,218 @@
1
+ # add-coder
2
+
3
+ > ๐ŸŒ [๐Ÿ€„ไธญๆ–‡](./README.md) | English
4
+
5
+ **AI Governance, Implemented** โ€” The complete scaffolding from [codein2027](https://github.com/xiaomingming92/codein2027) for rapidly building the ADD programming paradigm. Built on the core principle of **Audit as Infrastructure**, it shatters the black-box programming process and cross-session amnesia, evolving the programming paradigm into an auditable, traceable, and convergent new era. [NPM](https://www.npmjs.com/package/add-coder) ยท [GitHub](https://github.com/xiaomingming92/add-coder)
6
+
7
+
8
+ > ๐Ÿงญ **Getting hands-on?** See [GUIDE.md](https://github.com/xiaomingming92/add-coder/blob/main/GUIDE.md) โ€” trigger word quick reference, requirements-to-Plan, and full workflow walkthrough.
9
+
10
+ ```bash
11
+ npx add-coder init
12
+ ```
13
+
14
+ ---
15
+
16
+ ## Not a Template Tool โ€” An Architectural Difference
17
+
18
+ There are already plenty of AI coding templates, hook adapters, and MCP scaffolds. What fundamentally sets add-coder apart is not "what files it generates," but a **paradigm shift at the architectural level**:
19
+
20
+ ### โ‘  Audit Is Infrastructure, Not After-the-Fact Logging
21
+
22
+ Traditional AI development: Chat โ†’ Generate code โ†’ Dig through chat history afterward to find "who changed what"
23
+
24
+ | Traditional Model | add-coder |
25
+ |-------------------|-----------|
26
+ | Logs are append-only text files | Audit is a **structured data table** (DevOperation + AuditLog), supporting multi-dimensional queries by plan/step/agent/tool |
27
+ | Auditing relies on developer discipline | The **MCP audit toolchain** automatically records every operation; system gateways enforce checks |
28
+ | No traceability | Audit events are naturally linked: Plan โ†’ Spec โ†’ Task โ†’ Step โ†’ Tool Call, forming a complete evidence chain |
29
+
30
+ ### โ‘ก Gateway-Driven, Not Free-Form Conversation
31
+
32
+ Traditional AI coding is "you say, I do" โ€” quality depends entirely on the LLM's state that day. add-coder embeds **dual quality gateways** into the architecture:
33
+
34
+ ```
35
+ DPS (Design-Process Symmetry) โ€” Design / Implementation / Docs / Audit, each weighted 25%, < 85% BLOCKED
36
+ RAHS (Runtime Architecture Health Score) โ€” Runtime architecture health, < 90% BLOCKED
37
+ ```
38
+
39
+ These are not "suggestions" โ€” they are **architectural blocks**. A Step cannot advance without passing its gateway.
40
+
41
+ ### โ‘ข Cross-Session Memory, Not Per-Session Amnesia
42
+
43
+ The fatal flaw of AI conversations: architectural decisions from last session, bugs fixed, agreements reached โ€” all forgotten in the next conversation. add-coder solves this at the architecture level:
44
+
45
+ - **Handoff Documents** โ€” Automatically generated structured handoff at the end of each session, auto-loaded by the next session
46
+ - **Plan Index** โ€” All Plans are centrally indexed via `index.md`, supporting fuzzy-match quick lookup
47
+ - **DevLog Timeline** โ€” Every operation is written to the `{YYYY-MM}/{DD}/` timeline, enabling full historical state traceability
48
+
49
+ ### โ‘ฃ Policy-Update-Loop: Self-Evolving Governance (the scaffold itself does not include this architectural capability; a DEMO repo will be provided next to better illustrate the Policy-Update-Loop and Report system)
50
+
51
+ Not a static template, but a **closed-loop adaptive system**:
52
+
53
+ ```
54
+ Execute โ†’ Audit โ†’ Boundary Report โ†’ Rule Adjustment โ†’ Next Execution
55
+ ```
56
+
57
+ Runtime-generated Reports feed back into governance rules, enabling continuous evolution of governance strategies.
58
+
59
+ ### โ‘ค Multi-IDE Hooks as the Governance Layer
60
+
61
+ Hooks are not "notification push" โ€” they are the **IDE runtime interception layer**:
62
+
63
+ | Hook Type | Function |
64
+ |-----------|----------|
65
+ | PreToolUse | Validates whitelist before tool invocation, injects context, DPS condition checks |
66
+ | PostToolUse | Automatic audit logging, Plan sync detection, format guarding |
67
+ | PreCompact | Forces retention of critical document paths during cross-session context compression |
68
+ | PromptSubmit | Injects ADD vocabulary triggers, ensuring zero-latency LLM response to commands like "acceptance" and "gateway" |
69
+
70
+ Each IDE (Claude/Qoder/VS Code) has its own hook implementation, but the **governance logic is unified** โ€” the architecture is consistent, only the adapter layer differs.
71
+
72
+ ---
73
+
74
+ ## Quick Start
75
+
76
+ ```bash
77
+ npx add-coder init
78
+ ```
79
+
80
+ The first `init` auto-detects your IDE and interactively guides you through database selection (PostgreSQL / SQLite / self-managed), container runtime (podman / docker / self-managed), Prisma initialization, and ADD template deployment.
81
+
82
+ ```bash
83
+ npx add-coder init
84
+ # โ†’ Choose IDE (Qoder / Claude / VS Code)
85
+ # โ†’ Choose database (PostgreSQL / SQLite / self-managed)
86
+ # โ†’ Choose container (podman / docker / self-managed)
87
+ # โ†’ prisma init + add.prisma copied
88
+ # โ†’ prisma db push (adds new tables only, no data deletion)
89
+ # โ†’ prisma generate
90
+ # โ†’ ADD governance model ready โœ“
91
+ ```
92
+
93
+ > **Env file priority**: `.env.development.local` > `.env.development` > `.env.local` > `.env`
94
+
95
+ ## Commands
96
+
97
+ | Command | Description |
98
+ |---------|-------------|
99
+ | `init` | Initialize ADD templates, supports `--adapter claude\|qoder\|vscode\|auto` |
100
+ | `sync` | Incrementally sync missing files |
101
+ | `status` | Check template integrity |
102
+
103
+ ### init Internal Flow
104
+
105
+ | Step | Action | Description |
106
+ |------|--------|-------------|
107
+ | โ‘  | Detect IDE | Scan for `.qoder/` `.claude/` `.vscode/` existence, or specify via `--adapter` |
108
+ | โ‘ก | Load config | Interactive Q&A > `add-coder.config.ts` > auto-detect > defaults |
109
+ | โ‘ข | DB deployment | `db-ensure.sh` starts container/PG connection + `injectPrisma()` Caijue layer (Prisma init โ†’ AddUser model copy โ†’ db push โ†’ generate) |
110
+ | โ‘ฃ | Render templates | 55 core template files (skills/agents/templates/plans/specs/scriptsโ€ฆ) |
111
+ | โ‘ค | Deploy adapters | Copy core content to `.add/` `.qoder/` `.claude/` directories, supplement IDE-specific hooks/mcp |
112
+ | โ‘ฅ | Write files | Four modes: interactive / yes / force / dry-run; `.sh` scripts auto `chmod` |
113
+ | โ‘ฆ | Output summary | Created / skipped / overwritten stats + next-step hints |
114
+
115
+ ### init Options
116
+
117
+ | Option | Description |
118
+ |--------|-------------|
119
+ | `--adapter <type>` | Target IDE: claude / qoder / vscode / auto (default) |
120
+ | `--config <path>` | Specify config file |
121
+ | `--yes` | Skip interactions, create new files only |
122
+ | `--force` | Overwrite existing files |
123
+ | `--dry-run` | Preview mode, no writes |
124
+
125
+ ## Generated Content
126
+
127
+ | Directory | Content |
128
+ |-----------|---------|
129
+ | `.add/` | ADD shared core (skills, agents, docs, scripts, rules, etc.) |
130
+ | `.claude/` | Claude Code adapter (hooks, settings.json) |
131
+ | `.qoder/` | Qoder adapter (hooks, settings.json, mcp.json) |
132
+ | `.vscode/` | VS Code adapter (settings.json, tasks.json) |
133
+
134
+ ## MCP Audit Toolchain
135
+
136
+ `init` automatically deploys the MCP server (`mcp-server.ts`) into the project, loaded by the IDE via `mcp.json`. The following audit and governance tools are provided:
137
+
138
+ | Tool | Purpose | Trigger Scenario |
139
+ |------|---------|-----------------|
140
+ | `record_dev_operation` | Record development operation audits (before/after/reason) | Every file change, config modification |
141
+ | `query_audit_logs` | Query audit records by planKeyword / targetId | Cross-session context recovery, iteration evidence verification |
142
+ | `get_project_context` | Get ADD workflow status snapshot | Fresh conversation start |
143
+ | `get_db_schema` | Get Prisma schema info | Database-related operations |
144
+ | `check_dps` | DPS gateway (Design/Implementation/Docs/Audit, each 25%) | End of Step 0 |
145
+ | `check_rahs` | RAHS gateway (runtime architecture health) | Step 4/8 |
146
+ | `check_add_route_status` | add-route file existence check | Before Step 3 |
147
+ | `check_spec_sync` | Spec doc checkbox status vs. code consistency | After Spec execution |
148
+ | `find_related_docs` | Search related architecture/spec documents | Context understanding |
149
+
150
+ > Full tool list: [MCP Toolchain Specification](https://github.com/xiaomingming92/codein2027/blob/main/docs/ๅคง็”ฐ็ฒพๅ‡†่€•ๆ’ญๆ™บ่ƒฝๅ†ณ็ญ–็ณป็ปŸ/knowledge/02-่ง„่Œƒ/%E3%80%8A%E5%BC%80%E5%8F%91%E6%93%8D%E4%BD%9C%E5%AE%A1%E8%AE%A1%E5%AD%98%E6%A1%A3%E8%A7%84%E8%8C%83%E3%80%8B.md).
151
+
152
+ ## Architecture Overview
153
+
154
+ ```
155
+ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
156
+ โ”‚ ADD Paradigmโ”‚
157
+ โ”‚ Step 0-9 โ”‚
158
+ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜
159
+ โ”‚ Gateway-driven
160
+ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
161
+ โ–ผ โ–ผ โ–ผ
162
+ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
163
+ โ”‚DPS Gatewayโ”‚ โ”‚RAHS Gate โ”‚ โ”‚Complianceโ”‚
164
+ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”˜
165
+ โ”‚ โ”‚ โ”‚
166
+ โ–ผ โ–ผ โ–ผ
167
+ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
168
+ โ”‚ Audit Infrastructure Layer โ”‚
169
+ โ”‚ DevOperation / AuditLog Tables โ”‚
170
+ โ”‚ MCP Audit Toolchain โ”‚
171
+ โ”‚ Handoff / DevLog Timeline Docs โ”‚
172
+ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
173
+ โ”‚
174
+ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
175
+ โ–ผ โ–ผ โ–ผ
176
+ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
177
+ โ”‚ Claude โ”‚ โ”‚ Qoder โ”‚ โ”‚ VS Code โ”‚
178
+ โ”‚ Hooks โ”‚ โ”‚ Hooks โ”‚ โ”‚ Config โ”‚
179
+ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
180
+ โ”‚
181
+ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
182
+ โ–ผ
183
+ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
184
+ โ”‚ Caijuehub Rule Engine โ”‚
185
+ โ”‚ TOML-Driven Policy System โ”‚
186
+ โ”‚ Detect / Adapt / Prisma / Write โ€” โ”‚
187
+ โ”‚ Fully Configurable โ”‚
188
+ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
189
+ ```
190
+
191
+ ## Prerequisites
192
+
193
+ - Node.js >= 20
194
+ - Prisma ^7.0 (auto-detected during `init`, guided installation if missing)
195
+ - PostgreSQL / SQLite (MCP toolchain depends on DevOperation + AuditLog tables)
196
+
197
+ > **Recommended**: Run PostgreSQL via Podman/Docker, reference config:
198
+ > ```yaml
199
+ > postgres:
200
+ > image: docker.io/postgres:16-alpine
201
+ > ports: ["127.0.0.1:5433:5432"]
202
+ > environment:
203
+ > POSTGRES_DB: mydb
204
+ > POSTGRES_USER: admin
205
+ > POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
206
+ > ```
207
+ > Mount data volume to `~/data/your_project/postgres/` to avoid data loss on container removal.
208
+
209
+ > ๐Ÿ“ฆ [Changelog](./CHANGELOG.md)
210
+
211
+ ---
212
+
213
+ ## ๐ŸŽฌ Coming Soon
214
+
215
+ | Plan | Description |
216
+ |------|-------------|
217
+ | Demo Repo | A full example repository showcasing end-to-end closed-loop practice of Policy-Update-Loop and the Report system |
218
+ | MCP Restructure | MCP toolchain architecture upgrade, improving audit and gateway tool extensibility and standalone deployment capability |
package/README.md CHANGED
@@ -1,7 +1,10 @@
1
1
  # add-coder
2
2
 
3
+ > ๐ŸŒ ๐Ÿ€„ไธญๆ–‡ | [English](./README.en.md)
4
+
3
5
  **AI ไปฃ็ ๆฒป็†็š„่ฝๅœฐๆ–นๆกˆ** โ€” [codein2027](https://github.com/xiaomingming92/codein2027) ๅฟซ้€Ÿๆž„ๅปบ ADD ็ผ–็จ‹่Œƒๅผ็š„ๅฎŒๆ•ด่„šๆ‰‹ๆžถใ€‚ไปฅใ€Œๅฎก่ฎกๅณๅŸบ็ก€่ฎพๆ–ฝใ€ไธบๆ ธๅฟƒ๏ผŒๅฝปๅบ•ๆ‰“็ ด็ผ–็จ‹่ฟ‡็จ‹้ป‘็›’ไธŽ่ทจ่ฝฎๅคฑๅฟ†๏ผŒ่ฎฉ็ผ–็จ‹่Œƒๅผ่ฟ›ๅŒ–ไธบๅฏๅฎก่ฎกใ€ๅฏ่ฟฝๆบฏใ€ๅฏๆ”ถๆ•›็š„ๆ–ฐๆ—ถไปฃใ€‚ [NPM](https://www.npmjs.com/package/add-coder) ยท [GitHub](https://github.com/xiaomingming92/add-coder)
4
6
 
7
+
5
8
  > ๐Ÿงญ **ไปŽ้›ถไธŠๆ‰‹ๅฎžๆ“๏ผŸ** ่ฏทๅ‚่ง [GUIDE.md](https://github.com/xiaomingming92/add-coder/blob/main/GUIDE.md) โ€” ๅŒ…ๅซ่งฆๅ‘่ฏ้€ŸๆŸฅใ€้œ€ๆฑ‚่ฝฌ Planใ€ๅฎŒๆ•ด้“พ่ทฏๆผ”็ปƒใ€‚
6
9
 
7
10
  ```bash
@@ -43,7 +46,7 @@ AI ๅฏน่ฏ็š„่‡ดๅ‘ฝ็ผบ้™ท๏ผšไธŠๆฌก่ฎจ่ฎบ็š„ๆžถๆž„ๅ†ณ็ญ–ใ€ๅทฒไฟฎๅค็š„ Bugใ€่พพ
43
46
  - **Plan ็ดขๅผ•** โ€” ๆ‰€ๆœ‰ Plan ้€š่ฟ‡ `index.md` ้›†ไธญ็ดขๅผ•๏ผŒๆ”ฏๆŒๆจก็ณŠๅŒน้…ๅฟซ้€Ÿๅฎšไฝ
44
47
  - **DevLog ๆ—ถๅบ่ฎฐๅฝ•** โ€” ๆฏไธ€ๆญฅๆ“ไฝœๅ†™ๅ…ฅ `{YYYY-MM}/{DD}/` ๆ—ถ้—ด่ฝด๏ผŒๅฏๅ›žๆบฏไปปๆ„ๅŽ†ๅฒ็Šถๆ€
45
48
 
46
- ### โ‘ฃ Policy-Update-Loop๏ผšๆฒป็†่‡ชๆˆ‘่ฟ›ๅŒ–
49
+ ### โ‘ฃ Policy-Update-Loop๏ผšๆฒป็†่‡ชๆˆ‘่ฟ›ๅŒ–(่„šๆ‰‹ๆžถไธๅŒ…ๅซๆญคๆžถๆž„่ƒฝๅŠ›,ๆŽฅไธ‹ๆฅไผš็ป™ๅˆฐDEMOไป“ๅบ“่ฎฉๅคงๅฎถๆ›ดๅฅฝ็†่งฃPolicy-Update-Loopๅ’ŒReportไฝ“็ณป)
47
50
 
48
51
  ไธๆ˜ฏ้™ๆ€ๆจกๆฟ๏ผŒ่€Œๆ˜ฏ**้—ญ็Žฏ่‡ช้€‚ๅบ”็ณป็ปŸ**๏ผš
49
52
 
@@ -201,3 +204,14 @@ npx add-coder init
201
204
  > POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
202
205
  > ```
203
206
  > ๆ•ฐๆฎๅทๅปบ่ฎฎๆŒ‚่ฝฝๅˆฐ `~/data/your_project/postgres/`๏ผŒ้ฟๅ…ๅฎนๅ™จ้”€ๆฏไธขๅคฑๆ•ฐๆฎใ€‚
207
+
208
+ > ๐Ÿ“ฆ [ๆ›ดๆ–ฐๆ—ฅๅฟ— (CHANGELOG)](./CHANGELOG.md)
209
+
210
+ ---
211
+
212
+ ## ๐ŸŽฌ ้ข„ๅ‘Š
213
+
214
+ | ่ฎกๅˆ’ | ่ฏดๆ˜Ž |
215
+ |------|------|
216
+ | Demo ไป“ๅบ“ๆผ”็คบ | ๆไพ›ๅฎŒๆ•ด็คบไพ‹ไป“ๅบ“๏ผŒๅฑ•็คบ Policy-Update-Loop ไธŽ Report ไฝ“็ณป็š„็ซฏๅˆฐ็ซฏ้—ญ็Žฏๅฎž่ทต |
217
+ | MCP ่ƒฝๅŠ›้‡ๆž„ | MCP ๅทฅๅ…ท้“พๆžถๆž„ๅ‡็บง๏ผŒๆๅ‡ๅฎก่ฎกไธŽ้—จ็ฆๅทฅๅ…ท็š„ๅฏๆ‰ฉๅฑ•ๆ€งๅ’Œ็‹ฌ็ซ‹้ƒจ็ฝฒ่ƒฝๅŠ› |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "add-coder",
3
- "version": "0.1.14",
3
+ "version": "0.1.15",
4
4
  "private": false,
5
5
  "description": "[codein2027](https://github.com/xiaomingming92/codein2027) ๅฟซ้€Ÿๆž„ๅปบ ADD ็ผ–็จ‹่Œƒๅผ็š„ๅฎŒๆ•ด่„šๆ‰‹ๆžถโ€”โ€”AI ไปฃ็ ๆฒป็†็š„่ฝๅœฐๆ–นๆกˆใ€‚ไปฅใ€Œๅฎก่ฎกๅณๅŸบ็ก€่ฎพๆ–ฝใ€ไธบๆ ธๅฟƒ๏ผŒๅฝปๅบ•ๆ‰“็ ด็ผ–็จ‹่ฟ‡็จ‹้ป‘็›’ไธŽ่ทจ่ฝฎๅคฑๅฟ†๏ผŒ่ฎฉ็ผ–็จ‹่Œƒๅผ่ฟ›ๅŒ–ไธบๅฏๅฎก่ฎกใ€ๅฏ่ฟฝๆบฏใ€ๅฏๆ”ถๆ•›็š„ๆ–ฐๆ—ถไปฃใ€‚npx ๅณ็”จ๏ผŒไบบไบบๅฏไฝ“้ชŒใ€‚",
6
6
  "type": "module",