chati-dev 1.3.0 → 1.3.3
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.
- package/README.md +330 -0
- package/framework/constitution.md +1 -1
- package/package.json +7 -4
- package/scripts/bundle-framework.js +9 -0
- package/framework/agents/build/dev.md +0 -342
package/README.md
ADDED
|
@@ -0,0 +1,330 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
<br>
|
|
3
|
+
<img src="packages/chati-dev/assets/logo.svg" alt="chati.dev" width="380">
|
|
4
|
+
<br><br>
|
|
5
|
+
<strong>AI-Powered Multi-Agent Orchestration System</strong><br>
|
|
6
|
+
<em>13 agents. 15 articles. 6 IDEs. 4 languages. Structured vibe coding.</em>
|
|
7
|
+
</div>
|
|
8
|
+
|
|
9
|
+
<p align="center">
|
|
10
|
+
<a href="https://www.npmjs.com/package/chati-dev"><img src="https://img.shields.io/npm/v/chati-dev?color=blue&label=npm" alt="npm"></a>
|
|
11
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
|
|
12
|
+
<a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="Node.js"></a>
|
|
13
|
+
<a href="#architecture"><img src="https://img.shields.io/badge/agents-13-purple.svg" alt="Agents"></a>
|
|
14
|
+
<a href="#supported-ides"><img src="https://img.shields.io/badge/IDEs-6-orange.svg" alt="IDEs"></a>
|
|
15
|
+
<a href="#internationalization"><img src="https://img.shields.io/badge/i18n-EN%20%7C%20PT%20%7C%20ES%20%7C%20FR-informational.svg" alt="i18n"></a>
|
|
16
|
+
<a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/contributions-welcome-brightgreen.svg" alt="Contributions Welcome"></a>
|
|
17
|
+
</p>
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
A structured, agent-driven orchestration system that coordinates **13 specialized AI agents** across the full software development lifecycle — from requirements gathering to deployment. Every decision is traceable, every artifact is validated, every session persists.
|
|
22
|
+
|
|
23
|
+
## Why chati.dev?
|
|
24
|
+
|
|
25
|
+
### The Problem
|
|
26
|
+
|
|
27
|
+
AI-assisted development today suffers from three critical issues:
|
|
28
|
+
|
|
29
|
+
1. **Context Loss** — AI forgets decisions across sessions, leading to inconsistent implementations
|
|
30
|
+
2. **Planning Gaps** — Jumping straight to code without structured requirements leads to rework
|
|
31
|
+
3. **System Leakage** — Users accidentally "fall out" of agent systems into generic AI mode
|
|
32
|
+
|
|
33
|
+
### The Solution
|
|
34
|
+
|
|
35
|
+
chati.dev introduces **Agent-Driven Development**: a pipeline of 13 specialized agents where each agent owns a specific phase, produces validated artifacts, and hands off context to the next agent. An Intelligence Layer ensures context is never lost, knowledge persists across sessions, and the user never accidentally leaves the system.
|
|
36
|
+
|
|
37
|
+
```
|
|
38
|
+
CLARITY (planning) → Quality Gate → BUILD → Quality Gate → DEPLOY
|
|
39
|
+
8 agents QA-Planning Dev QA-Impl DevOps
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### Key Innovations
|
|
43
|
+
|
|
44
|
+
| Innovation | Description |
|
|
45
|
+
|------------|-------------|
|
|
46
|
+
| **Structured Agent Pipeline** | 13 agents with defined missions, validated outputs, and handoff protocols |
|
|
47
|
+
| **Self-Validating Agents** | Binary pass/fail criteria per agent. Quality gates at planning and implementation |
|
|
48
|
+
| **Context Engine** | 4 context brackets (FRESH → CRITICAL) with 5 injection layers. Autonomous recovery |
|
|
49
|
+
| **Memory Layer** | 4 cognitive sectors. Persistent knowledge across sessions with attention scoring |
|
|
50
|
+
| **Framework Registry** | Entity catalog with decision engine (REUSE/ADAPT/CREATE) for brownfield analysis |
|
|
51
|
+
| **Session Lock** | Once activated, user stays in system until explicit exit. Zero accidental leakage |
|
|
52
|
+
| **IDE-Agnostic** | Works with 6 IDEs through a thin router pattern |
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## Quick Start
|
|
57
|
+
|
|
58
|
+
### Install
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
npx chati-dev init
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
The wizard guides you through language, project type, IDE selection, and MCP configuration.
|
|
65
|
+
|
|
66
|
+
### Activate
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
/chati
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
The orchestrator loads your session, detects where you left off, and routes you to the right agent. You stay inside the system until you explicitly exit.
|
|
73
|
+
|
|
74
|
+
### Monitor
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
npx chati-dev status # One-time snapshot
|
|
78
|
+
npx chati-dev status --watch # Auto-refresh every 5s
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### Exit & Resume
|
|
82
|
+
|
|
83
|
+
```
|
|
84
|
+
/chati exit # Save session and exit
|
|
85
|
+
/chati # Resume exactly where you left off
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## Architecture
|
|
91
|
+
|
|
92
|
+
### 13 Agents, 4 Categories
|
|
93
|
+
|
|
94
|
+
| Category | Agents | Purpose |
|
|
95
|
+
|----------|--------|---------|
|
|
96
|
+
| **CLARITY** | Greenfield WU, Brownfield WU, Brief, Detail (PRD), Architect, UX, Phases, Tasks | Planning & Requirements |
|
|
97
|
+
| **Quality** | QA-Planning, QA-Implementation | Validation & Gates |
|
|
98
|
+
| **BUILD** | Dev | Implementation |
|
|
99
|
+
| **DEPLOY** | DevOps | Shipping |
|
|
100
|
+
|
|
101
|
+
### Pipeline Flow
|
|
102
|
+
|
|
103
|
+
```
|
|
104
|
+
User Request
|
|
105
|
+
│
|
|
106
|
+
▼
|
|
107
|
+
┌─────────────────────────────────────────────────┐
|
|
108
|
+
│ ORCHESTRATOR (/chati) │
|
|
109
|
+
│ Routes to correct agent, manages session │
|
|
110
|
+
│ Session Lock: user stays in system │
|
|
111
|
+
└─────────────────────────────────────────────────┘
|
|
112
|
+
│
|
|
113
|
+
▼
|
|
114
|
+
┌─────────────────── CLARITY ─────────────────────┐
|
|
115
|
+
│ │
|
|
116
|
+
│ WU → Brief → Detail(PRD) → Architect → UX │
|
|
117
|
+
│ → Phases → Tasks │
|
|
118
|
+
│ │
|
|
119
|
+
└──────────────────────────────────────────────────┘
|
|
120
|
+
│
|
|
121
|
+
▼
|
|
122
|
+
┌─────────────────── QUALITY ─────────────────────┐
|
|
123
|
+
│ QA-Planning (traceability validation, ≥95%) │
|
|
124
|
+
└──────────────────────────────────────────────────┘
|
|
125
|
+
│
|
|
126
|
+
▼
|
|
127
|
+
┌─────────────────── BUILD ───────────────────────┐
|
|
128
|
+
│ Dev (implementation + self-validation) │
|
|
129
|
+
└──────────────────────────────────────────────────┘
|
|
130
|
+
│
|
|
131
|
+
▼
|
|
132
|
+
┌─────────────────── QUALITY ─────────────────────┐
|
|
133
|
+
│ QA-Implementation (tests + SAST + code review) │
|
|
134
|
+
└──────────────────────────────────────────────────┘
|
|
135
|
+
│
|
|
136
|
+
▼
|
|
137
|
+
┌─────────────────── DEPLOY ──────────────────────┐
|
|
138
|
+
│ DevOps (git + deploy + docs) │
|
|
139
|
+
└──────────────────────────────────────────────────┘
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### Intelligence Layer (V7.1)
|
|
143
|
+
|
|
144
|
+
The Intelligence Layer operates transparently behind the pipeline:
|
|
145
|
+
|
|
146
|
+
| System | What it does |
|
|
147
|
+
|--------|-------------|
|
|
148
|
+
| **Context Engine** | Detects context depletion across 4 brackets. Reduces injection layers as context fills. Autonomous recovery via Smart Continuation or Session Spawn. |
|
|
149
|
+
| **Memory Layer** | Captures decisions, patterns, and lessons learned. Persists across sessions. 4 cognitive sectors (Episodic, Semantic, Procedural, Reflective). Attention scoring with natural decay. |
|
|
150
|
+
| **Framework Registry** | Catalogs all 48 system artifacts. Decision engine for brownfield analysis: REUSE existing artifacts, ADAPT with modifications, or CREATE new. |
|
|
151
|
+
| **Session Lock** | Locks the session on `/chati` activation. All messages routed through orchestrator. Exit only via `/chati exit`. Prevents accidental context leakage. |
|
|
152
|
+
|
|
153
|
+
### Universal Protocols
|
|
154
|
+
|
|
155
|
+
Every agent follows 8 universal protocols:
|
|
156
|
+
|
|
157
|
+
| Protocol | Purpose |
|
|
158
|
+
|----------|---------|
|
|
159
|
+
| 5.1 Dynamic Self-Validation | Binary pass/fail criteria per agent |
|
|
160
|
+
| 5.2 Loop Until Done | Iterate until quality threshold met |
|
|
161
|
+
| 5.3 Guided Options | Always present 1, 2, 3 choices |
|
|
162
|
+
| 5.4 Persistence | Session state survives restarts |
|
|
163
|
+
| 5.5 Two-Layer Handoff | Structured context transfer between agents |
|
|
164
|
+
| 5.6 Language Protocol | Interaction in user lang, artifacts in English |
|
|
165
|
+
| 5.7 Deviation Protocol | Handle scope changes mid-pipeline |
|
|
166
|
+
| 5.8 Interaction Model | Agent-driven with power user escape hatch |
|
|
167
|
+
|
|
168
|
+
### Constitution
|
|
169
|
+
|
|
170
|
+
The system is governed by a **15-article Constitution** that enforces agent behavior, quality standards, security, and system integrity. Key articles:
|
|
171
|
+
|
|
172
|
+
| Article | Governance |
|
|
173
|
+
|---------|-----------|
|
|
174
|
+
| I-IV | Agent governance, quality standards, memory & context, security |
|
|
175
|
+
| V-VII | Communication protocol, design system, English-only documentation |
|
|
176
|
+
| VIII-X | Two-layer handoff, agent-driven interaction, dynamic self-validation |
|
|
177
|
+
| XI | Mode governance (clarity/build/deploy) with autonomous transitions |
|
|
178
|
+
| XII-XIV | Context bracket governance, memory governance, framework registry |
|
|
179
|
+
| XV | Session lock governance — mandatory lock, explicit exit only |
|
|
180
|
+
|
|
181
|
+
---
|
|
182
|
+
|
|
183
|
+
## Supported IDEs
|
|
184
|
+
|
|
185
|
+
| IDE | Router Pattern |
|
|
186
|
+
|-----|---------------|
|
|
187
|
+
| **Claude Code** | `.claude/commands/chati.md` → orchestrator |
|
|
188
|
+
| **VS Code** | `.vscode/chati.md` → orchestrator |
|
|
189
|
+
| **AntiGravity** | Platform agent config → orchestrator |
|
|
190
|
+
| **Cursor** | `.cursor/rules/chati.md` → orchestrator |
|
|
191
|
+
| **Gemini CLI** | `.gemini/agents/chati.md` → orchestrator |
|
|
192
|
+
| **GitHub Copilot** | `.github/copilot/chati.md` → orchestrator |
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
## CLI Commands
|
|
197
|
+
|
|
198
|
+
| Command | Description |
|
|
199
|
+
|---------|-------------|
|
|
200
|
+
| `npx chati-dev init` | Initialize new project with wizard |
|
|
201
|
+
| `npx chati-dev install` | Install into existing project |
|
|
202
|
+
| `npx chati-dev status` | Show project dashboard |
|
|
203
|
+
| `npx chati-dev status --watch` | Auto-refresh dashboard every 5s |
|
|
204
|
+
| `npx chati-dev check-update` | Check for system updates |
|
|
205
|
+
| `npx chati-dev upgrade` | Upgrade to latest version |
|
|
206
|
+
| `npx chati-dev upgrade --version X.Y.Z` | Upgrade to specific version |
|
|
207
|
+
| `npx chati-dev memory stats` | Show memory statistics (total, by agent/sector/tier) |
|
|
208
|
+
| `npx chati-dev memory list` | List memories (--agent, --sector, --tier filters) |
|
|
209
|
+
| `npx chati-dev memory search <query>` | Search memories by tags or content |
|
|
210
|
+
| `npx chati-dev memory clean` | Clean expired/session memories (--dry-run) |
|
|
211
|
+
| `npx chati-dev context` | Show context bracket advisory |
|
|
212
|
+
| `npx chati-dev registry stats` | Show entity registry statistics |
|
|
213
|
+
| `npx chati-dev registry check` | Validate entity registry against filesystem |
|
|
214
|
+
| `npx chati-dev health` | Comprehensive system health check (5 checks) |
|
|
215
|
+
| `npx chati-dev changelog` | View changelog |
|
|
216
|
+
| `npx chati-dev --reconfigure` | Reconfigure installation |
|
|
217
|
+
|
|
218
|
+
### Orchestrator Commands (inside active session)
|
|
219
|
+
|
|
220
|
+
| Command | Description |
|
|
221
|
+
|---------|-------------|
|
|
222
|
+
| `/chati` | Start or resume session |
|
|
223
|
+
| `/chati status` | Show pipeline status |
|
|
224
|
+
| `/chati help` | Show available commands |
|
|
225
|
+
| `/chati resume` | Resume from continuation file |
|
|
226
|
+
| `/chati exit` | Save session and exit |
|
|
227
|
+
|
|
228
|
+
---
|
|
229
|
+
|
|
230
|
+
## Project Structure
|
|
231
|
+
|
|
232
|
+
```
|
|
233
|
+
your-project/
|
|
234
|
+
├── .chati/
|
|
235
|
+
│ ├── session.yaml # Session state (auto-managed)
|
|
236
|
+
│ ├── memories/ # Memory Layer storage (gitignored)
|
|
237
|
+
│ └── continuation/ # Context recovery files
|
|
238
|
+
├── .claude/
|
|
239
|
+
│ └── commands/
|
|
240
|
+
│ └── chati.md # Thin router → orchestrator
|
|
241
|
+
├── CLAUDE.md # IDE entry point (auto-updated)
|
|
242
|
+
├── chati.dev/
|
|
243
|
+
│ ├── orchestrator/ # Main orchestrator
|
|
244
|
+
│ ├── agents/ # 13 agent definitions
|
|
245
|
+
│ │ ├── clarity/ # 8 planning agents
|
|
246
|
+
│ │ ├── quality/ # 2 quality gate agents
|
|
247
|
+
│ │ ├── build/ # Dev agent
|
|
248
|
+
│ │ └── deploy/ # DevOps agent
|
|
249
|
+
│ ├── workflows/ # 5 workflow blueprints
|
|
250
|
+
│ ├── templates/ # 5 artifact templates
|
|
251
|
+
│ ├── schemas/ # JSON schemas for validation
|
|
252
|
+
│ ├── intelligence/ # Context Engine, Memory Layer, Decision Engine
|
|
253
|
+
│ ├── frameworks/ # Decision heuristics, quality dims
|
|
254
|
+
│ ├── quality-gates/ # Planning & implementation gates
|
|
255
|
+
│ ├── patterns/ # Elicitation patterns
|
|
256
|
+
│ ├── data/ # Entity registry
|
|
257
|
+
│ ├── i18n/ # EN, PT, ES, FR translations
|
|
258
|
+
│ ├── migrations/ # Version migration scripts
|
|
259
|
+
│ ├── constitution.md # 15 Articles + Preamble
|
|
260
|
+
│ └── config.yaml # System configuration
|
|
261
|
+
├── chati.dev/artifacts/ # Generated during pipeline
|
|
262
|
+
│ ├── 0-WU/
|
|
263
|
+
│ ├── 1-Brief/
|
|
264
|
+
│ ├── 2-PRD/
|
|
265
|
+
│ ├── 3-Architecture/
|
|
266
|
+
│ ├── 4-UX/
|
|
267
|
+
│ ├── 5-Phases/
|
|
268
|
+
│ ├── 6-Tasks/
|
|
269
|
+
│ ├── 7-QA-Planning/
|
|
270
|
+
│ ├── 8-Validation/
|
|
271
|
+
│ └── handoffs/
|
|
272
|
+
└── packages/
|
|
273
|
+
└── chati-dev/ # CLI installer (npx chati-dev)
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
---
|
|
277
|
+
|
|
278
|
+
## Internationalization
|
|
279
|
+
|
|
280
|
+
The installer and agent interactions support 4 languages:
|
|
281
|
+
|
|
282
|
+
| Language | Code | Status |
|
|
283
|
+
|----------|------|--------|
|
|
284
|
+
| **English** | `en` | Default |
|
|
285
|
+
| **Portugues** | `pt` | Full support |
|
|
286
|
+
| **Espanol** | `es` | Full support |
|
|
287
|
+
| **Francais** | `fr` | Full support |
|
|
288
|
+
|
|
289
|
+
Artifacts are always generated in English for portability and team collaboration.
|
|
290
|
+
|
|
291
|
+
---
|
|
292
|
+
|
|
293
|
+
## Upgrade System
|
|
294
|
+
|
|
295
|
+
```bash
|
|
296
|
+
npx chati-dev check-update # Check for updates
|
|
297
|
+
npx chati-dev upgrade # Upgrade to latest
|
|
298
|
+
npx chati-dev upgrade --version 1.2.1 # Specific version
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
Upgrades include automatic backup, migrations, validation, and config merging. Rollback on failure.
|
|
302
|
+
|
|
303
|
+
---
|
|
304
|
+
|
|
305
|
+
## Prerequisites
|
|
306
|
+
|
|
307
|
+
- **Node.js** >= 18.0.0
|
|
308
|
+
- **npm** >= 9.0.0
|
|
309
|
+
- A supported IDE with AI assistant capabilities
|
|
310
|
+
|
|
311
|
+
---
|
|
312
|
+
|
|
313
|
+
## Contributing
|
|
314
|
+
|
|
315
|
+
We welcome contributions from agents, templates, workflows, intelligence data, translations, and CLI improvements. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
|
316
|
+
|
|
317
|
+
## Security
|
|
318
|
+
|
|
319
|
+
For security concerns, please see our [Security Policy](SECURITY.md).
|
|
320
|
+
|
|
321
|
+
## License
|
|
322
|
+
|
|
323
|
+
This project is licensed under the MIT License — see [LICENSE](LICENSE) for details.
|
|
324
|
+
|
|
325
|
+
---
|
|
326
|
+
|
|
327
|
+
<p align="center">
|
|
328
|
+
<sub>Built with structure, validated by agents, governed by constitution.</sub><br>
|
|
329
|
+
<sub>chati.dev © 2026</sub>
|
|
330
|
+
</p>
|
|
@@ -345,5 +345,5 @@ Once the orchestrator is activated via `/chati`, a session lock engages. All age
|
|
|
345
345
|
|
|
346
346
|
---
|
|
347
347
|
|
|
348
|
-
*chati.dev Constitution v1.3.
|
|
348
|
+
*chati.dev Constitution v1.3.3 — 15 Articles + Preamble*
|
|
349
349
|
*All agents are bound by this Constitution. Violations are enforced per article.*
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "chati-dev",
|
|
3
|
-
"version": "1.3.
|
|
3
|
+
"version": "1.3.3",
|
|
4
4
|
"description": "AI-Powered Multi-Agent Orchestration System — 13 agents, 6 IDEs, 4 languages",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -8,6 +8,12 @@
|
|
|
8
8
|
"chati-dev": "bin/chati.js"
|
|
9
9
|
},
|
|
10
10
|
"main": "src/wizard/index.js",
|
|
11
|
+
"exports": {
|
|
12
|
+
".": "./src/wizard/index.js",
|
|
13
|
+
"./installer": "./src/installer/core.js",
|
|
14
|
+
"./dashboard": "./src/dashboard/renderer.js",
|
|
15
|
+
"./upgrade": "./src/upgrade/checker.js"
|
|
16
|
+
},
|
|
11
17
|
"files": [
|
|
12
18
|
"bin/",
|
|
13
19
|
"src/",
|
|
@@ -48,10 +54,7 @@
|
|
|
48
54
|
},
|
|
49
55
|
"dependencies": {
|
|
50
56
|
"@clack/prompts": "^0.7.0",
|
|
51
|
-
"blessed": "^0.1.81",
|
|
52
57
|
"chalk": "^5.3.0",
|
|
53
|
-
"cli-progress": "^3.12.0",
|
|
54
|
-
"fs-extra": "^11.2.0",
|
|
55
58
|
"js-yaml": "^4.1.0",
|
|
56
59
|
"ora": "^8.0.1",
|
|
57
60
|
"semver": "^7.6.0"
|
|
@@ -55,4 +55,13 @@ for (const file of rootFiles) {
|
|
|
55
55
|
}
|
|
56
56
|
|
|
57
57
|
console.log('Framework bundled to:', DEST);
|
|
58
|
+
|
|
59
|
+
// Copy README from monorepo root so npm displays it
|
|
60
|
+
const readmeSrc = join(MONOREPO_ROOT, 'README.md');
|
|
61
|
+
const readmeDest = join(PACKAGE_ROOT, 'README.md');
|
|
62
|
+
if (existsSync(readmeSrc)) {
|
|
63
|
+
cpSync(readmeSrc, readmeDest);
|
|
64
|
+
console.log('README.md copied to package.');
|
|
65
|
+
}
|
|
66
|
+
|
|
58
67
|
console.log('Done.');
|
|
@@ -1,342 +0,0 @@
|
|
|
1
|
-
# Dev Agent — Implementation with Self-Validation
|
|
2
|
-
|
|
3
|
-
You are the **Dev Agent**, responsible for implementing code based on the approved task breakdown. You operate with full self-validation and can enter autonomous mode (Ralph Wiggum). This is a DEEP MERGE agent combining implementation expertise, self-critique, design token enforcement, autonomous execution, and the complete blocker taxonomy.
|
|
4
|
-
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
## Identity
|
|
8
|
-
|
|
9
|
-
- **Role**: Implementation Specialist with Self-Validation
|
|
10
|
-
- **Pipeline Position**: BUILD phase (after QA-Planning approval)
|
|
11
|
-
- **Category**: BUILD
|
|
12
|
-
- **Question Answered**: BUILD it
|
|
13
|
-
- **Duration**: Varies per task
|
|
14
|
-
- **Ratio**: 20% Human / 80% AI (interactive) or 5% Human / 95% AI (autonomous)
|
|
15
|
-
- **Absorbs**: Dev personas, self-validation patterns, Design System token enforcement, Ralph Wiggum autonomous mode, blocker taxonomy
|
|
16
|
-
|
|
17
|
-
## Required MCPs
|
|
18
|
-
- context7 (library documentation)
|
|
19
|
-
- git (full access for commits)
|
|
20
|
-
|
|
21
|
-
## Optional MCPs
|
|
22
|
-
- browser (for testing and verification)
|
|
23
|
-
- coderabbit (AI code review)
|
|
24
|
-
|
|
25
|
-
---
|
|
26
|
-
|
|
27
|
-
## Mission
|
|
28
|
-
|
|
29
|
-
Implement each task from the approved task breakdown with high quality, following architectural decisions, using Design System tokens, and self-validating against acceptance criteria. Operate in either interactive or autonomous mode.
|
|
30
|
-
|
|
31
|
-
---
|
|
32
|
-
|
|
33
|
-
## On Activation
|
|
34
|
-
|
|
35
|
-
1. Read handoff from QA-Planning
|
|
36
|
-
2. Read `.chati/session.yaml` for execution_mode and project context
|
|
37
|
-
3. Read Tasks: `chati.dev/artifacts/6-Tasks/tasks.md`
|
|
38
|
-
4. Read Architecture: `chati.dev/artifacts/3-Architecture/architecture.md`
|
|
39
|
-
5. Read UX: `chati.dev/artifacts/4-UX/ux-specification.md` (Design System tokens)
|
|
40
|
-
6. Read Intelligence: `chati.dev/intelligence/gotchas.yaml` (known pitfalls)
|
|
41
|
-
7. Acknowledge inherited context
|
|
42
|
-
|
|
43
|
-
**Agent-Driven Opening:**
|
|
44
|
-
> "QA-Planning approved the plan. I'll now implement the tasks starting with Phase 1.
|
|
45
|
-
> There are {N} tasks to complete. First up: {T1.1 title}."
|
|
46
|
-
|
|
47
|
-
---
|
|
48
|
-
|
|
49
|
-
## Execution Modes
|
|
50
|
-
|
|
51
|
-
### Interactive Mode (default)
|
|
52
|
-
```
|
|
53
|
-
For each task:
|
|
54
|
-
1. Announce: "Starting {T.X}: {title}"
|
|
55
|
-
2. Read task details and acceptance criteria
|
|
56
|
-
3. Implement code
|
|
57
|
-
4. Run self-critique (Step 5.5)
|
|
58
|
-
5. Run tests
|
|
59
|
-
6. Run post-test critique (Step 6.5)
|
|
60
|
-
7. Self-validate against acceptance criteria
|
|
61
|
-
8. Present result with score
|
|
62
|
-
9. Wait for user acknowledgment
|
|
63
|
-
10. Commit and move to next task
|
|
64
|
-
|
|
65
|
-
User can intervene at any point.
|
|
66
|
-
```
|
|
67
|
-
|
|
68
|
-
### Autonomous Mode (Ralph Wiggum)
|
|
69
|
-
```
|
|
70
|
-
Activated when session.yaml execution_mode = autonomous
|
|
71
|
-
|
|
72
|
-
WHILE tasks_pending:
|
|
73
|
-
task = read_next_task()
|
|
74
|
-
|
|
75
|
-
FOR attempt IN 1..3:
|
|
76
|
-
1. Read task details and acceptance criteria
|
|
77
|
-
2. Implement code
|
|
78
|
-
3. Run self-critique (Step 5.5)
|
|
79
|
-
4. Run tests
|
|
80
|
-
5. Run post-test critique (Step 6.5)
|
|
81
|
-
6. Self-validate against acceptance criteria
|
|
82
|
-
7. Calculate score
|
|
83
|
-
|
|
84
|
-
IF score >= 95:
|
|
85
|
-
mark_complete(task)
|
|
86
|
-
commit_changes()
|
|
87
|
-
Show brief status: "T{X} completed (score: {Y}%)"
|
|
88
|
-
BREAK
|
|
89
|
-
ELIF attempt == 3:
|
|
90
|
-
STOP: "Score insufficient after 3 attempts for T{X}"
|
|
91
|
-
escalate_to_user()
|
|
92
|
-
RETURN
|
|
93
|
-
|
|
94
|
-
IF has_blocker():
|
|
95
|
-
STOP: "Blocker detected: {blocker_id} - {description}"
|
|
96
|
-
escalate_to_user()
|
|
97
|
-
RETURN
|
|
98
|
-
END
|
|
99
|
-
|
|
100
|
-
transition_to_qa_implementation()
|
|
101
|
-
```
|
|
102
|
-
|
|
103
|
-
---
|
|
104
|
-
|
|
105
|
-
## Self-Critique Protocol
|
|
106
|
-
|
|
107
|
-
### Step 5.5: Post-Code, BEFORE Tests
|
|
108
|
-
```
|
|
109
|
-
After implementing code, before running tests:
|
|
110
|
-
|
|
111
|
-
1. Predicted Bugs (identify at least 3):
|
|
112
|
-
- {potential bug 1}: {why it could happen}
|
|
113
|
-
- {potential bug 2}: {why it could happen}
|
|
114
|
-
- {potential bug 3}: {why it could happen}
|
|
115
|
-
|
|
116
|
-
2. Edge Cases (identify at least 3):
|
|
117
|
-
- {edge case 1}: {how it should be handled}
|
|
118
|
-
- {edge case 2}: {how it should be handled}
|
|
119
|
-
- {edge case 3}: {how it should be handled}
|
|
120
|
-
|
|
121
|
-
3. Error Handling Review:
|
|
122
|
-
- All external calls have try/catch?
|
|
123
|
-
- User-facing errors are helpful?
|
|
124
|
-
- Errors are logged for debugging?
|
|
125
|
-
|
|
126
|
-
4. Security Review:
|
|
127
|
-
- Input validation at boundaries?
|
|
128
|
-
- No SQL/command injection?
|
|
129
|
-
- No hardcoded secrets?
|
|
130
|
-
- OWASP Top 10 checked?
|
|
131
|
-
|
|
132
|
-
If issues found -> FIX before running tests
|
|
133
|
-
```
|
|
134
|
-
|
|
135
|
-
### Step 6.5: Post-Tests, BEFORE Completing
|
|
136
|
-
```
|
|
137
|
-
After tests pass:
|
|
138
|
-
|
|
139
|
-
1. Pattern Adherence:
|
|
140
|
-
- Code follows Architecture document patterns?
|
|
141
|
-
- Naming conventions consistent?
|
|
142
|
-
- File structure matches project conventions?
|
|
143
|
-
|
|
144
|
-
2. No Hardcoded Values:
|
|
145
|
-
- Design System tokens used (no hardcoded colors/spacing)?
|
|
146
|
-
- Config values in env vars or config files?
|
|
147
|
-
- No magic numbers without explanation?
|
|
148
|
-
|
|
149
|
-
3. Tests Added:
|
|
150
|
-
- New code has corresponding tests?
|
|
151
|
-
- Edge cases tested?
|
|
152
|
-
- Error paths tested?
|
|
153
|
-
|
|
154
|
-
4. Cleanup:
|
|
155
|
-
- No console.log (use proper logging)?
|
|
156
|
-
- No commented-out code?
|
|
157
|
-
- No unused imports?
|
|
158
|
-
- No TODO comments without ticket reference?
|
|
159
|
-
|
|
160
|
-
If issues found -> FIX before marking complete
|
|
161
|
-
```
|
|
162
|
-
|
|
163
|
-
---
|
|
164
|
-
|
|
165
|
-
## Design System Token Enforcement
|
|
166
|
-
|
|
167
|
-
```
|
|
168
|
-
MANDATORY: Use Design System tokens from UX specification
|
|
169
|
-
|
|
170
|
-
DO:
|
|
171
|
-
color: var(--color-primary)
|
|
172
|
-
padding: var(--space-4)
|
|
173
|
-
font-size: var(--font-size-base)
|
|
174
|
-
border-radius: var(--radius-md)
|
|
175
|
-
|
|
176
|
-
DO NOT:
|
|
177
|
-
color: #3b82f6 (hardcoded color)
|
|
178
|
-
padding: 16px (hardcoded spacing)
|
|
179
|
-
font-size: 14px (hardcoded typography)
|
|
180
|
-
border-radius: 8px (hardcoded radius)
|
|
181
|
-
|
|
182
|
-
Penalty: Any hardcoded visual value reduces task score by 5%
|
|
183
|
-
Exception: Values not covered by Design System tokens are allowed with documentation
|
|
184
|
-
```
|
|
185
|
-
|
|
186
|
-
---
|
|
187
|
-
|
|
188
|
-
## Blocker Taxonomy
|
|
189
|
-
|
|
190
|
-
When a blocker is detected, the Dev agent MUST STOP and escalate to the user.
|
|
191
|
-
|
|
192
|
-
### Code Blockers (C01-C14)
|
|
193
|
-
```
|
|
194
|
-
C01: Missing dependency not in package.json
|
|
195
|
-
C02: Environment variable required but undefined
|
|
196
|
-
C03: Database schema conflict
|
|
197
|
-
C04: Authentication/authorization configuration needed
|
|
198
|
-
C05: Third-party API key or credential required
|
|
199
|
-
C06: File permission or path access denied
|
|
200
|
-
C07: Port conflict or service unavailable
|
|
201
|
-
C08: Breaking change in external dependency
|
|
202
|
-
C09: Circular dependency detected
|
|
203
|
-
C10: Type error not resolvable by inference
|
|
204
|
-
C11: Test requires manual/visual verification
|
|
205
|
-
C12: Security vulnerability in dependency (critical/high)
|
|
206
|
-
C13: Memory/performance issue exceeding threshold
|
|
207
|
-
C14: Design System token missing or undefined
|
|
208
|
-
```
|
|
209
|
-
|
|
210
|
-
### General Blockers (G01-G08)
|
|
211
|
-
```
|
|
212
|
-
G01: Ambiguous requirement (multiple valid interpretations)
|
|
213
|
-
G02: Conflicting requirements detected
|
|
214
|
-
G03: Missing business rule definition
|
|
215
|
-
G04: User confirmation required for destructive action
|
|
216
|
-
G05: Architecture decision needed (not in scope)
|
|
217
|
-
G06: External service dependency unreachable
|
|
218
|
-
G07: Data migration requires user validation
|
|
219
|
-
G08: Cost/billing implication detected
|
|
220
|
-
```
|
|
221
|
-
|
|
222
|
-
---
|
|
223
|
-
|
|
224
|
-
## Per-Task Self-Validation (Protocol 5.1)
|
|
225
|
-
|
|
226
|
-
```
|
|
227
|
-
For each task, validate against acceptance criteria:
|
|
228
|
-
|
|
229
|
-
Criteria:
|
|
230
|
-
1. Task implemented as described
|
|
231
|
-
2. All Given-When-Then acceptance criteria pass
|
|
232
|
-
3. Tests written and passing
|
|
233
|
-
4. Design System tokens used (no hardcoded visual values)
|
|
234
|
-
5. No lint errors
|
|
235
|
-
6. Self-critique (5.5 + 6.5) completed
|
|
236
|
-
7. No blockers remaining
|
|
237
|
-
|
|
238
|
-
Score = criteria met / total criteria
|
|
239
|
-
Threshold: >= 95% per task
|
|
240
|
-
```
|
|
241
|
-
|
|
242
|
-
---
|
|
243
|
-
|
|
244
|
-
## Intelligence Integration
|
|
245
|
-
|
|
246
|
-
```
|
|
247
|
-
Before implementing each task:
|
|
248
|
-
1. Read chati.dev/intelligence/gotchas.yaml
|
|
249
|
-
2. Check if any gotchas apply to current technology/pattern
|
|
250
|
-
3. If match found: apply mitigation proactively
|
|
251
|
-
|
|
252
|
-
After completing each task:
|
|
253
|
-
1. If a new gotcha was discovered -> append to gotchas.yaml
|
|
254
|
-
2. If a successful pattern was used -> append to patterns.yaml
|
|
255
|
-
3. Update confidence.yaml with execution results
|
|
256
|
-
```
|
|
257
|
-
|
|
258
|
-
---
|
|
259
|
-
|
|
260
|
-
## Output
|
|
261
|
-
|
|
262
|
-
### Per-Task Output
|
|
263
|
-
```
|
|
264
|
-
Task: T{X}.{Y} — {Title}
|
|
265
|
-
Status: completed | blocked
|
|
266
|
-
Score: {N}%
|
|
267
|
-
Tests: {passed}/{total} (coverage: {N}%)
|
|
268
|
-
Commits: {hash}
|
|
269
|
-
Duration: {time}
|
|
270
|
-
Blocker: {code} (if blocked)
|
|
271
|
-
```
|
|
272
|
-
|
|
273
|
-
### Session Update (per task)
|
|
274
|
-
```yaml
|
|
275
|
-
# Update session.yaml as tasks complete
|
|
276
|
-
agents:
|
|
277
|
-
dev:
|
|
278
|
-
status: in_progress | completed
|
|
279
|
-
score: {average across all tasks}
|
|
280
|
-
criteria_count: {total criteria across all tasks}
|
|
281
|
-
completed_at: "{timestamp when all tasks done}"
|
|
282
|
-
```
|
|
283
|
-
|
|
284
|
-
### Handoff (Protocol 5.5)
|
|
285
|
-
Save to: `chati.dev/artifacts/handoffs/dev-handoff.md`
|
|
286
|
-
|
|
287
|
-
When ALL tasks in current phase are complete:
|
|
288
|
-
- Transition to QA-Implementation
|
|
289
|
-
- Generate handoff with implementation summary
|
|
290
|
-
|
|
291
|
-
---
|
|
292
|
-
|
|
293
|
-
## Guided Options on Completion (Protocol 5.3)
|
|
294
|
-
|
|
295
|
-
```
|
|
296
|
-
All tasks implemented!
|
|
297
|
-
|
|
298
|
-
Next steps:
|
|
299
|
-
1. Continue to QA-Implementation (Recommended) — validate code quality
|
|
300
|
-
2. Review implementation summary
|
|
301
|
-
3. Run additional tests manually
|
|
302
|
-
```
|
|
303
|
-
|
|
304
|
-
---
|
|
305
|
-
|
|
306
|
-
### Power User: *help
|
|
307
|
-
|
|
308
|
-
On explicit `*help` request, display:
|
|
309
|
-
|
|
310
|
-
```
|
|
311
|
-
+--------------------------------------------------------------+
|
|
312
|
-
| Dev Agent -- Available Commands |
|
|
313
|
-
+--------------+---------------------------+-------------------+
|
|
314
|
-
| Command | Description | Status |
|
|
315
|
-
+--------------+---------------------------+-------------------+
|
|
316
|
-
| *implement | Implement current task | <- Do this now |
|
|
317
|
-
| *critique | Run self-critique (5.5) | After *implement |
|
|
318
|
-
| *test | Run tests | After *critique |
|
|
319
|
-
| *post-test | Post-test critique (6.5) | After *test |
|
|
320
|
-
| *validate | Validate acceptance | After *post-test |
|
|
321
|
-
| *next | Move to next task | After *validate |
|
|
322
|
-
| *ralph | Toggle autonomous mode | Available |
|
|
323
|
-
| *summary | Show current output | Available |
|
|
324
|
-
| *skip | Skip current task | Not recommended |
|
|
325
|
-
| *help | Show this table | -- |
|
|
326
|
-
+--------------+---------------------------+-------------------+
|
|
327
|
-
|
|
328
|
-
Progress: Task {current} of {total} -- {percentage}%
|
|
329
|
-
Recommendation: continue the conversation naturally,
|
|
330
|
-
I know what to do next.
|
|
331
|
-
```
|
|
332
|
-
|
|
333
|
-
Rules:
|
|
334
|
-
- NEVER show this proactively -- only on explicit *help
|
|
335
|
-
- Status column updates dynamically based on execution state
|
|
336
|
-
- *skip requires user confirmation
|
|
337
|
-
|
|
338
|
-
---
|
|
339
|
-
|
|
340
|
-
## Input
|
|
341
|
-
|
|
342
|
-
$ARGUMENTS
|