citadel-ai 1.4.0 โ†’ 1.4.1

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 (2) hide show
  1. package/README.md +127 -84
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,39 +1,98 @@
1
1
  # ๐Ÿฐ CITADEL
2
2
 
3
- **Command Intelligence Tower for Architected Development with Enforced Layers**
3
+ **Tu vibecodes. Ta dรฉmo marche. Mais est-ce que ton projet repose sur du sable ?**
4
4
 
5
- > A governance framework for AI-assisted building. 42 agents. Phased context. Maker โ‰  Checker. You describe, they build โ€” with structure.
5
+ CITADEL helps serious vibe coders build with structure, memory, and review โ€” so their MVP doesn't collapse under hidden mistakes.
6
6
 
7
7
  [![npm version](https://img.shields.io/npm/v/citadel-ai.svg)](https://www.npmjs.com/package/citadel-ai)
8
8
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
9
9
 
10
+ ```bash
11
+ npx citadel-ai init
12
+ ```
13
+
14
+ Works with **Claude Code** ยท **Cursor** ยท **Antigravity** ยท **Windsurf**
15
+
10
16
  ---
11
17
 
12
- ## What is CITADEL?
18
+ ## Is this for you?
13
19
 
14
- CITADEL is not "42 AI agents that build your app." It's a **governance framework** that turns your AI IDE into a structured engineering team โ€” with roles, rules, gates, and separation of duties.
20
+ ### CITADEL is for
15
21
 
16
- It installs into your project and works with **any AI IDE**: Claude Code, Cursor, Antigravity, Windsurf.
22
+ - Solo founders building their first MVP with AI
23
+ - Operators and PMs who vibecode internal tools
24
+ - Growth builders shipping fast without a dedicated dev team
25
+ - Non-traditional developers who want guardrails, not gatekeeping
17
26
 
18
- ```bash
19
- npx citadel-ai init
20
- ```
27
+ ### CITADEL is not for
28
+
29
+ - People looking for one-shot prompts
30
+ - Senior engineers who already have strong architecture discipline
31
+ - Teams that need a production-grade CI/CD platform
32
+ - Complete beginners who have never built anything with AI
33
+
34
+ ---
35
+
36
+ ## The problem
37
+
38
+ When you vibecode without structure:
39
+
40
+ - The AI skips architecture โ€” it generates code that works today and breaks tomorrow
41
+ - Nobody reviews โ€” the builder validates their own work (and misses their own mistakes)
42
+ - Context gets lost โ€” the AI forgets what was decided 3 messages ago
43
+ - No standards โ€” spaghetti code, magic numbers, business logic everywhere
44
+ - Security is an afterthought โ€” auth, encryption, compliance happen "later" (never)
45
+
46
+ You end up with a prototype that demos well and crumbles under real use.
47
+
48
+ ---
49
+
50
+ ## What CITADEL does
51
+
52
+ CITADEL installs a governance layer into your AI IDE. It doesn't replace your AI โ€” it makes it work like a disciplined team instead of a solo improviser.
21
53
 
22
- Open your IDE. Start talking. The AI already knows the rules.
54
+ **Forces strategic thinking first.** Before any code, a virtual C-Suite asks questions about your product, architecture, security, data, and growth. You answer. Then specs get drafted. Not the other way around.
23
55
 
24
- ### What CITADEL actually is
56
+ **Separates building from reviewing.** The agent that writes code is never the one that reviews it. Like any serious engineering org.
25
57
 
26
- - An **OS for AI-assisted building** โ€” rules, phases, gates injected into your IDE
27
- - **42 agent personas** with distinct roles, philosophies, and immutable rules
28
- - An **orchestrator** that routes work based on the current phase
29
- - **Phased context loading** โ€” only the relevant team is loaded, not all 42 agents
30
- - **Persistent memory** โ€” decisions, errors, and state survive across sessions
58
+ **Enforces safety checks before shipping.** 5 mandatory gates from inception to deployment. Security has veto power โ€” no exceptions.
31
59
 
32
- ### What CITADEL is not (yet)
60
+ **Keeps project memory across sessions.** Decisions, errors, architecture choices โ€” all persisted locally. The AI doesn't start from scratch every time.
33
61
 
34
- - Not a fully autonomous AI swarm
35
- - Not a replacement for a real dev team when you need to scale
36
- - Not a polished SaaS product โ€” it's an open-source framework in active development
62
+ **Loads only what's needed.** Instead of dumping 42 agent profiles into context (and burning your token quota), CITADEL loads only the team relevant to the current phase. 88% less tokens.
63
+
64
+ ---
65
+
66
+ ## Without CITADEL / With CITADEL
67
+
68
+ | | Without | With CITADEL |
69
+ |--|---------|-------------|
70
+ | Start | "Build me an app" โ†’ AI dives into code | C-Suite asks: who is this for? what data? what security? |
71
+ | Architecture | Whatever the AI decides in the moment | Explicit ADR, reviewed by a dedicated architecture agent |
72
+ | Code quality | Hope for the best | Standards enforced: 200 lines/file, typed errors, no magic numbers |
73
+ | Review | You read it yourself (and miss things) | Independent checker agents with different perspective |
74
+ | Security | "We'll add auth later" | Security review at every gate. Veto power on deployment |
75
+ | Next session | AI forgot everything | Memory persists decisions, errors, and project context |
76
+ | Token usage | Full context every message (~14K tokens) | Phased loading (~1,800 tokens per phase) |
77
+
78
+ ---
79
+
80
+ ## How it works โ€” 5 steps
81
+
82
+ ### Step 1: Clarify what you're building
83
+ The C-Suite (product, architecture, security, data, growth) asks questions before anything gets drafted.
84
+
85
+ ### Step 2: Lock the strategy
86
+ PRD, architecture decisions, security requirements, data model โ€” all written to `.citadel/specs/` after your answers.
87
+
88
+ ### Step 3: Build with role separation
89
+ Specialized maker agents build per domain (backend, frontend, mobile, API, auth, data). Each one follows strict code standards.
90
+
91
+ ### Step 4: Review before shipping
92
+ Independent checker agents validate code quality, tests, performance, security, accessibility. Builder โ‰  reviewer โ€” always.
93
+
94
+ ### Step 5: Ship with memory
95
+ Decisions, errors, and context persist in `.citadel/memory/`. Next session picks up where you left off.
37
96
 
38
97
  ---
39
98
 
@@ -44,38 +103,34 @@ cd my-project
44
103
  npx citadel-ai init
45
104
  ```
46
105
 
47
- After init, CITADEL creates:
106
+ This creates:
48
107
 
49
108
  ```
50
109
  your-project/
51
- โ”œโ”€โ”€ CLAUDE.md โ† Rules for Claude Code (auto-loaded)
52
- โ”œโ”€โ”€ GEMINI.md โ† Rules for Antigravity (auto-loaded)
53
- โ”œโ”€โ”€ .cursorrules โ† Rules for Cursor (auto-loaded)
54
- โ”œโ”€โ”€ .windsurfrules โ† Rules for Windsurf (auto-loaded)
55
- โ”œโ”€โ”€ .claude/commands/ โ† Slash commands (/citadel-help, etc.)
56
- โ”œโ”€โ”€ .cursor/commands/ โ† Slash commands
57
- โ”œโ”€โ”€ .antigravity/rules.md โ† Antigravity backup rules
110
+ โ”œโ”€โ”€ CLAUDE.md โ† Auto-loaded by Claude Code
111
+ โ”œโ”€โ”€ GEMINI.md โ† Auto-loaded by Antigravity
112
+ โ”œโ”€โ”€ .cursorrules โ† Auto-loaded by Cursor
113
+ โ”œโ”€โ”€ .windsurfrules โ† Auto-loaded by Windsurf
114
+ โ”œโ”€โ”€ .claude/commands/ โ† /citadel-help, /citadel-build, /citadel-review...
115
+ โ”œโ”€โ”€ .cursor/commands/
58
116
  โ”œโ”€โ”€ .citadel/
59
- โ”‚ โ”œโ”€โ”€ agents/ โ† 42 full agent persona files (.md)
60
- โ”‚ โ”œโ”€โ”€ teams/ โ† 10 team files (phased loading for IDE)
61
- โ”‚ โ”‚ โ”œโ”€โ”€ c-suite.md โ† Loaded at Inception
62
- โ”‚ โ”‚ โ”œโ”€โ”€ cto-makers.md โ† Loaded at Build
63
- โ”‚ โ”‚ โ”œโ”€โ”€ cto-checkers.md โ† Loaded at Review
64
- โ”‚ โ”‚ โ””โ”€โ”€ ...
65
- โ”‚ โ”œโ”€โ”€ specs/ โ† PRD, ADR, Security, Data Model, Growth
66
- โ”‚ โ”œโ”€โ”€ memory/ โ† Session state, decisions, errors (gitignored)
67
- โ”‚ โ””โ”€โ”€ gates/ โ† Gate progress tracking (gitignored)
68
- โ””โ”€โ”€ .gitignore โ† Updated automatically
117
+ โ”‚ โ”œโ”€โ”€ agents/ โ† 42 full agent personas (reference)
118
+ โ”‚ โ”œโ”€โ”€ teams/ โ† 10 team files (phased loading by IDE)
119
+ โ”‚ โ”œโ”€โ”€ specs/ โ† PRD, ADR, Security, Data Model, Growth
120
+ โ”‚ โ”œโ”€โ”€ memory/ โ† Persistent state (gitignored)
121
+ โ”‚ โ””โ”€โ”€ gates/ โ† Gate tracking (gitignored)
69
122
  ```
70
123
 
71
- | IDE | Rules file | How to start |
72
- |-----|-----------|--------------|
73
- | Claude Code | `CLAUDE.md` + `/citadel-help` | Slash commands |
74
- | Cursor | `.cursorrules` + `/citadel-help` | Slash commands |
75
- | Antigravity | `GEMINI.md` | Just start chatting |
76
- | Windsurf | `.windsurfrules` | Just start chatting |
124
+ Everything is installed. The IDE reads only what's contextual.
125
+
126
+ | IDE | How to start |
127
+ |-----|-------------|
128
+ | Claude Code | `/citadel-help` |
129
+ | Cursor | `/citadel-help` |
130
+ | Antigravity | Just start chatting |
131
+ | Windsurf | Just start chatting |
77
132
 
78
- For the interactive CLI (optional):
133
+ Optional CLI (needs API key):
79
134
  ```bash
80
135
  export ANTHROPIC_API_KEY=sk-ant-... # or OPENAI_API_KEY
81
136
  npx citadel-ai run
@@ -83,59 +138,47 @@ npx citadel-ai run
83
138
 
84
139
  ---
85
140
 
86
- ## The Core Idea
87
-
88
- Most AI coding tools are one brain doing everything. CITADEL is an **organization**.
89
-
90
- ### 1. Organization > Single Agent
141
+ ## Why it's different
91
142
 
92
- | Layer | Agents | Role |
93
- |-------|--------|------|
94
- | Command | โšก ATLAS | Orchestrates, routes, explains |
95
- | C-Suite | ๐Ÿ—๏ธ LINUS (CTO), ๐ŸŽฏ MARTY (CPO), ๐Ÿ“ˆ SEAN (CGO), ๐Ÿ›ก๏ธ BRUCE (CISO), ๐Ÿ—„๏ธ MONICA (CDO) | Strategic decisions |
96
- | Makers (20) | UNCLE BOB, DAN, STEIPETE, KELSEY, JONY, FILIPPO, CODD, KARPATHY, HARRISON, ALEX, GRACE, CHARITY, RICH... | Build |
97
- | Checkers (16) | GUIDO, KENT, BRENDAN, JAKOB, CHARLIE, AARON, ALEYDA, DATE, DEMING, FLYWAY, TRAIL... | Validate |
143
+ Most AI frameworks give you **more agents**. CITADEL gives you **more discipline**.
98
144
 
99
- Each agent has a name, inspiration (Linus Torvalds, Kent Beck, Bruce Schneier...), philosophy, voice, and immutable rules. Full personas in `.citadel/agents/`.
145
+ - **Organization > single brain.** 42 agents with distinct roles, rules, and personalities โ€” but loaded per phase, not all at once.
146
+ - **Governance > speed.** Questions before specs. Review before ship. Security veto before deploy.
147
+ - **Memory > amnesia.** Project decisions, architecture choices, and past errors persist locally across sessions.
148
+ - **Efficiency > brute force.** Phased context loading means ~1,800 tokens per phase instead of ~14,000.
100
149
 
101
- ### 2. Governance Before Speed
150
+ ---
102
151
 
103
- - **Questions before specs** โ€” C-Suite asks questions BEFORE drafting anything
104
- - **5 mandatory gates** โ€” Inception โ†’ Pre-Design โ†’ Pre-Build โ†’ Pre-Ship โ†’ Post-Deploy
105
- - **Chinese Wall** โ€” Maker โ‰  Checker. The builder never reviews their own work
106
- - **CISO veto** โ€” BRUCE can block any deployment. No override possible
107
- - **Code standards in agent DNA** โ€” TS strict, 200 lines/file, 30 lines/function, 80% test coverage, anti-patterns auto-rejected
152
+ ## The 42 agents
108
153
 
109
- ### 3. Phased Context Loading
154
+ Each agent has a full persona: name, inspiration, philosophy, voice, immutable rules, and system prompt. All stored in `.citadel/agents/`.
110
155
 
111
- The IDE doesn't load all 42 agents at once. It loads only the team needed for the current phase:
156
+ **Strategic (C-Suite):** ATLAS (Orchestrator) ยท LINUS (CTO) ยท MARTY (CPO) ยท SEAN (CGO) ยท BRUCE (CISO) ยท MONICA (CDO)
112
157
 
113
- | Phase | File loaded | Tokens |
114
- |-------|------------|--------|
115
- | Inception | `c-suite.md` | ~460 |
116
- | Build (backend) | `cto-makers.md` | ~680 |
117
- | Review (code) | `cto-checkers.md` | ~340 |
118
- | Security audit | `ciso-all.md` | ~740 |
158
+ **Builders (Makers):** UNCLE BOB ยท DAN ยท STEIPETE ยท KELSEY ยท JONY ยท TERESA ยท STRUNK ยท DJ PATIL ยท CYRUS ยท CHAMATH ยท FILIPPO ยท MOXIE ยท MAX ยท CODD ยท KARPATHY ยท HARRISON ยท ALEX ยท GRACE ยท CHARITY ยท RICH
119
159
 
120
- Rules file (`GEMINI.md` etc.): ~1,200 tokens โ€” loaded every message.
160
+ **Validators (Checkers):** GUIDO ยท KENT ยท BRENDAN ยท JAKOB ยท RAZOR ยท LISA ยท NATE ยท ALEYDA ยท PEEP ยท CHARLIE ยท WINDOW ยท DATE ยท DEMING ยท FLYWAY ยท AARON ยท TRAIL
121
161
 
122
- **Result: ~1,600โ€“1,900 tokens per phase** instead of ~14,000 if everything was loaded. 88% reduction.
162
+ `npx citadel-ai agents` lists them all with roles and teams.
123
163
 
124
164
  ---
125
165
 
126
- ## The 42 Agents
127
-
128
- **CTO Team:** โš™๏ธ UNCLE BOB (Backend) ยท ๐ŸŽจ DAN (Frontend) ยท ๐Ÿ“ฑ STEIPETE (Mobile) ยท ๐Ÿš€ KELSEY (DevOps) ยท ๐Ÿ“ก GRACE (API Design) ยท ๐Ÿ”ญ CHARITY (Observability)
166
+ ## Known limitations
129
167
 
130
- **CPO Team:** โœ๏ธ JONY (UX) ยท ๐Ÿ“Š TERESA (Analyst) ยท ๐Ÿ“ STRUNK (Spec Writer) ยท ๐Ÿ“š RICH (Documentation)
168
+ - **Early stage.** This is v1, actively developed. Expect rough edges.
169
+ - **Not autonomous.** CITADEL structures AI work โ€” it doesn't run unsupervised.
170
+ - **Not a replacement for a real team.** Great for MVPs and internal tools. For scaling to production, you still need real developers and a CTO.
171
+ - **IDE-dependent.** The phased loading relies on how your IDE reads context files. Behavior varies.
131
172
 
132
- **CGO Team:** ๐Ÿ“‰ DJ PATIL (Analytics) ยท ๐Ÿ”Ž CYRUS (SEO) ยท ๐Ÿงฌ CHAMATH (Growth)
133
-
134
- **CISO Team:** ๐Ÿ” FILIPPO (Auth) ยท ๐Ÿ”’ MOXIE (Encryption) ยท ๐Ÿ“‹ MAX (Compliance)
173
+ ---
135
174
 
136
- **CDO Team:** ๐Ÿ›๏ธ CODD (Data Architect) ยท ๐Ÿค– KARPATHY (ML/AI) ยท ๐Ÿง  HARRISON (Agentic AI) ยท ๐Ÿ”Œ ALEX (MCP)
175
+ ## Roadmap
137
176
 
138
- **Checkers:** ๐Ÿ” GUIDO ยท ๐Ÿงช KENT ยท โšก BRENDAN ยท ๐Ÿ‘๏ธ JAKOB ยท ๐Ÿ“ RAZOR ยท โœ… LISA ยท โœ”๏ธ NATE ยท ๐Ÿ•ท๏ธ ALEYDA ยท ๐ŸŽฏ PEEP ยท โš”๏ธ CHARLIE ยท ๐Ÿ”ฌ WINDOW ยท ๐Ÿง DATE ยท ๐Ÿ… DEMING ยท ๐Ÿ”„ FLYWAY ยท โ™ฟ AARON ยท ๐Ÿ“œ TRAIL
177
+ - [ ] Onboarding wizard (guided first 10 minutes)
178
+ - [ ] Demo video (60-second Loom)
179
+ - [ ] More IDE-specific optimizations
180
+ - [ ] Plugin system for custom agents
181
+ - [ ] Non-code use cases (growth teams, marketing, ops)
139
182
 
140
183
  ---
141
184
 
@@ -144,10 +187,10 @@ Rules file (`GEMINI.md` etc.): ~1,200 tokens โ€” loaded every message.
144
187
  | Command | Description |
145
188
  |---------|-------------|
146
189
  | `npx citadel-ai init` | Install CITADEL in your project |
147
- | `npx citadel-ai run` | Interactive CLI (needs API key in env) |
190
+ | `npx citadel-ai run` | Interactive CLI (needs API key) |
148
191
  | `npx citadel-ai agents` | List all 42 agents |
149
- | `npx citadel-ai status` | Show current phase & gate |
150
- | `npx citadel-ai help` | Show all commands |
192
+ | `npx citadel-ai status` | Current phase & gate |
193
+ | `npx citadel-ai help` | All commands |
151
194
 
152
195
  ---
153
196
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "citadel-ai",
3
- "version": "1.4.0",
3
+ "version": "1.4.1",
4
4
  "description": "Enterprise AI dev framework. 42 agents. C-suite governance. Chinese walls. Persistent memory. You talk, they build.",
5
5
  "keywords": [
6
6
  "ai",
@@ -55,4 +55,4 @@
55
55
  "engines": {
56
56
  "node": ">=18.0.0"
57
57
  }
58
- }
58
+ }