citadel-ai 1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,91 @@
+# Contributing to CITADEL
+
+First off, thanks for wanting to contribute! CITADEL is built for vibe coders — people who build with AI. You don't need to be a traditional developer to help.
+
+## How to Contribute
+
+### Reporting Bugs
+
+Open an issue with:
+- What you expected to happen
+- What actually happened
+- Steps to reproduce
+- Your Node.js version (`node --version`)
+- Your OS
+
+### Suggesting Agents
+
+Want a new agent in CITADEL? Open an issue with:
+- **Agent name & role** — What does it do?
+- **Inspiration** — Which legendary dev/designer/thinker inspires it?
+- **Philosophy** — One line that captures its worldview
+- **Team** — Which C-suite does it report to? (CTO, CPO, CGO, CISO, CDO)
+- **Level** — Maker or Checker?
+- **Rules** — 3-5 immutable rules it follows
+
+### Submitting Code
+
+1. Fork the repo
+2. Create a branch: `git checkout -b feat/your-feature`
+3. Make your changes
+4. Run the build: `npm run build`
+5. Test it: `node dist/cli/index.js agents` (should show 42 agents)
+6. Commit: `git commit -m "feat: description"`
+7. Push: `git push origin feat/your-feature`
+8. Open a Pull Request
+
+### Commit Convention
+
+We use [Conventional Commits](https://www.conventionalcommits.org/):
+
+- `feat:` — New feature or agent
+- `fix:` — Bug fix
+- `docs:` — Documentation only
+- `refactor:` — Code change that doesn't add features or fix bugs
+- `test:` — Adding tests
+- `chore:` — Maintenance, deps, CI
+
+### Code Standards
+
+CITADEL enforces its own standards:
+
+- TypeScript strict mode
+- Max 200 lines per file
+- Max 30 lines per function
+- Meaningful names — no abbreviations
+- Every public function should be documented
+
+### Project Structure
+
+```
+src/
+├── agents/registry.ts    # All 42 agent definitions
+├── core/
+│   ├── orchestrator.ts   # ATLAS brain
+│   ├── memory.ts         # Persistent memory
+│   ├── gates.ts          # Quality gates
+│   ├── loops.ts          # Iteration loops
+│   ├── chinese-wall.ts   # Maker ≠ Checker
+│   └── types.ts          # TypeScript types
+├── llm/provider.ts       # LLM abstraction
+├── ui/terminal.ts        # CLI interface
+└── cli/                  # CLI commands
+```
+
+## Development Setup
+
+```bash
+git clone https://github.com/YOUR_USERNAME/citadel-ai.git
+cd citadel-ai
+npm install
+npm run build
+node dist/cli/index.js agents  # Should list 42 agents
+```
+
+## Questions?
+
+Open a Discussion or Issue. No question is too basic.
+
+---
+
+Built with 🏰 by humans who talk to machines.

package/LICENSE

@@ -0,0 +1,5 @@
+MIT License
+Copyright (c) 2026 Citadel Contributors
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files, 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.

package/README.md

@@ -0,0 +1,254 @@
+# 🏰 CITADEL
+
+**Command Intelligence Tower for Architected Development with Enforced Layers**
+
+> Enterprise-grade AI development framework. 42 specialized agents. C-suite governance. Chinese Walls. Persistent memory. You talk, they build.
+
+[![npm version](https://img.shields.io/npm/v/citadel-ai.svg)](https://www.npmjs.com/package/citadel-ai)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## What is CITADEL?
+
+CITADEL is an AI-powered development framework where **you never write code**. You describe what you want to build, and a team of 42 specialized AI agents — organized like a real engineering company — designs, builds, reviews, and ships it.
+
+```bash
+npx citadel-ai init
+npx citadel-ai run
+```
+
+That's it. You talk. They build.
+
+---
+
+## Why CITADEL?
+
+Most AI coding tools are a single brain doing everything. CITADEL is an **organization** with separation of concerns, checks and balances, and enforced quality gates.
+
+| Feature | Single AI | CITADEL |
+|---------|-----------|---------|
+| Architecture decisions | Vibes | ADRs reviewed by CTO agent |
+| Security | Hope | CISO with **absolute veto power** |
+| Code quality | Maybe | Chinese Wall: Maker ≠ Checker |
+| Testing | Optional | 80% coverage minimum, test pyramid enforced |
+| Data design | Inline | Schema-first, 3NF minimum, FK on every relationship |
+| Memory | None | 4-layer persistent memory across sessions |
+| Progress | Unknown | 5 mandatory gates with explicit sign-offs |
+
+---
+
+## The 42 Agents
+
+### Command Layer (1)
+
+| Agent | Role | Inspiration |
+|-------|------|-------------|
+| ⚡ **ATLAS** | Orchestrator | Andy Grove |
+
+### C-Suite (5)
+
+| Agent | Role | Inspiration | Superpower |
+|-------|------|-------------|------------|
+| 🏗️ **LINUS** | CTO | Linus Torvalds + Martin Fowler | Architecture, ADRs, tech stack |
+| 🎯 **MARTY** | CPO | Marty Cagan | PRDs, user stories, scope |
+| 📈 **SEAN** | CGO | Sean Ellis + Andrew Chen | Growth, analytics, SEO |
+| 🛡️ **BRUCE** | CISO | Bruce Schneier | **ABSOLUTE VETO POWER** |
+| 🗄️ **MONICA** | CDO | Monica Rogati | Data architecture, AI/ML |
+
+### Maker Teams (20 builders)
+
+**CTO Team:** ⚙️ UNCLE BOB (Backend) · 🎨 DAN (Frontend) · 📱 STEIPETE (Mobile) · 🚀 KELSEY (DevOps) · 📡 GRACE (API Design) · 🔭 CHARITY (Observability)
+
+**CPO Team:** ✏️ JONY (UX) · 📊 TERESA (Analyst) · 📝 STRUNK (Spec Writer) · 📚 RICH (Documentation)
+
+**CGO Team:** 📉 DJ PATIL (Analytics) · 🔎 CYRUS (SEO) · 🧬 CHAMATH (Growth)
+
+**CISO Team:** 🔐 FILIPPO (Auth) · 🔒 MOXIE (Encryption) · 📋 MAX (Compliance)
+
+**CDO Team:** 🏛️ CODD (Data Architect) · 🤖 KARPATHY (ML/AI) · 🧠 HARRISON (Agentic AI) · 🔌 ALEX (MCP) 
+
+### Checker Teams (16 validators)
+
+**CTO Checkers:** 🔍 GUIDO (Code Review) · 🧪 KENT (Tests) · ⚡ BRENDAN (Performance)
+
+**CPO Checkers:** 👁️ JAKOB (UX Review) · 📏 RAZOR (Scope) · ✅ LISA (Acceptance) · ♿ AARON (Accessibility)
+
+**CGO Checkers:** ✔️ NATE (Data Validation) · 🕷️ ALEYDA (SEO Audit) · 🎯 PEEP (Conversion)
+
+**CISO Checkers:** ⚔️ CHARLIE (Pentest) · 🔬 WINDOW (Security Audit) · 📜 TRAIL (Audit Trail)
+
+**CDO Checkers:** 🧐 DATE (Schema Review) · 🏅 DEMING (Data Quality) · 🔄 FLYWAY (Migration)
+
+---
+
+## Core Principles
+
+### 1. Maker ≠ Checker (Chinese Wall)
+
+The agent that builds can **never** validate its own work. Enforced at the system level.
+
+### 2. CISO Veto Power
+
+BRUCE (CISO) can block **any** deployment. No exceptions. Not even from you.
+
+### 3. 5 Mandatory Gates
+
+| Gate | Name | Blocker |
+|------|------|---------|
+| Gate 0 | **Inception** | All C-levels must sign off |
+| Gate 1 | **Pre-Design** | PRD approved, acceptance criteria complete |
+| Gate 2 | **Pre-Build** | ADR + schema + security review approved |
+| Gate 3 | **Pre-Ship** | All checkers PASS + CISO veto |
+| Gate 4 | **Post-Deploy** | Auto-rollback if critical metrics degrade |
+
+### 4. Persistent Memory
+
+CITADEL remembers everything across sessions:
+
+```
+.citadel/
+├── memory/
+│   ├── project.json       # Tech stack, architecture, scope
+│   ├── decisions.json     # Every ADR, product decision, tradeoff
+│   ├── errors.json        # Error history + root causes + fixes
+│   └── session.json       # Current state, active agent, gate
+├── gates/
+│   ├── gate-0-inception.json
+│   ├── gate-1-predesign.json
+│   ├── gate-2-prebuild.json
+│   ├── gate-3-preship.json
+│   └── gate-4-postdeploy.json
+└── specs/
+    ├── prd.md
+    ├── adr.md
+    ├── security.md
+    └── data-model.md
+```
+
+### 5. Web Research When Stuck
+
+If any agent loops more than 2 times on a problem, ATLAS automatically triggers web research.
+
+---
+
+## Quick Start
+
+```bash
+# Initialize in your project directory
+npx citadel-ai init
+
+# Start building
+npx citadel-ai run
+```
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `citadel init` | Initialize CITADEL in your project |
+| `citadel run` | Start the interactive build session |
+| `citadel status` | Show current phase and gate progress |
+| `citadel agents` | List all 42 agents |
+
+### In-Session Commands
+
+| Command | Description |
+|---------|-------------|
+| `status` | Show phase, gate, and progress |
+| `advance` | Move to next phase (if gate passed) |
+| `help` | Show available agents and options |
+| `exit` | Save and quit |
+
+---
+
+## How It Works
+
+1. **You describe** what you want to build in plain language
+2. **ATLAS** (orchestrator) routes your request to the right expert
+3. **C-Suite agents** make strategic decisions (architecture, product, security, data, growth)
+4. **Maker agents** build (backend, frontend, mobile, auth, data, etc.)
+5. **Checker agents** validate (code review, tests, pentest, UX audit, etc.)
+6. **Gates enforce** quality at every phase transition
+7. **Memory persists** decisions, errors, and context across sessions
+
+---
+
+## LLM Support
+
+CITADEL works with:
+
+- **Anthropic Claude** (recommended) — `claude-sonnet-4-20250514`
+- **OpenAI GPT-4o** — `gpt-4o`
+
+Set your API key:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+# or
+export OPENAI_API_KEY=sk-...
+```
+
+---
+
+## Coding DNA
+
+Every agent carries these principles in their DNA:
+
+1. **Code is for Humans First** — Readability over cleverness
+2. **Simplicity Over Cleverness** — The simplest solution that works
+3. **Measurement Before Optimization** — Profile, don't guess
+4. **Single Responsibility** — One function, one job
+5. **Test-Driven Development** — Red → Green → Refactor
+6. **Low Coupling, High Cohesion** — Modules that stand alone
+7. **Evolutionary Design** — Architecture that adapts
+
+### Anti-Patterns Registry (Auto-Detected)
+
+God Objects · Primitive Obsession · Long Parameter Lists · Magic Numbers · Error Swallowing · Callback Hell · Framework Coupling · Speculative Generality
+
+---
+
+## Architecture
+
+```
+citadel-ai/
+├── src/
+│   ├── agents/
+│   │   └── registry.ts      # 42 agent definitions with soul
+│   ├── core/
+│   │   ├── orchestrator.ts   # ATLAS brain — routing & flow
+│   │   ├── memory.ts         # 4-layer persistent memory
+│   │   ├── gates.ts          # 5 mandatory quality gates
+│   │   ├── loops.ts          # Design/Build/Security/Debug loops
+│   │   ├── chinese-wall.ts   # Maker ≠ Checker enforcement
+│   │   └── types.ts          # TypeScript types
+│   ├── llm/
+│   │   └── provider.ts       # Anthropic/OpenAI abstraction
+│   ├── ui/
+│   │   └── terminal.ts       # CLI interface
+│   └── cli/
+│       ├── init.ts           # npx citadel init
+│       ├── run.ts            # npx citadel run
+│       └── index.ts          # CLI router
+├── bin/
+│   └── citadel.js            # Entry point
+├── templates/                 # .citadel scaffolding
+└── package.json
+```
+
+---
+
+## Contributing
+
+CITADEL is built for vibe coders — people who build with AI without being traditional developers. If that's you, you're welcome here.
+
+---
+
+## License
+
+MIT
+
+---
+
+Built with 🏰 by humans who talk to machines.

package/bin/citadel.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/cli/index.js').catch((e) => { console.error('Run "npm run build" first:', e.message); process.exit(1); });

package/dist/agents/registry.d.ts

@@ -0,0 +1,16 @@
+import type { AgentDefinition, AgentLevel, TeamId } from '../core/types.js';
+export declare const AGENT_REGISTRY: Map<string, AgentDefinition>;
+export declare function getAgent(id: string): AgentDefinition | undefined;
+export declare function getAgentsByTeam(team: TeamId | 'command'): AgentDefinition[];
+export declare function getAgentsByLevel(level: AgentLevel): AgentDefinition[];
+export declare function getMakersByTeam(team: TeamId): AgentDefinition[];
+export declare function getCheckersByTeam(team: TeamId): AgentDefinition[];
+export declare function getCSuiteAgents(): AgentDefinition[];
+export declare function getAllAgentIds(): string[];
+export declare function getAgentCount(): {
+    total: number;
+    command: number;
+    csuite: number;
+    makers: number;
+    checkers: number;
+};