@citadel-labs/citadel 0.1.0

package/docs/configuration.md

@@ -0,0 +1,143 @@
+# Configuration
+
+## Courier Config
+
+`courier.config.yaml` at the workspace root controls the Courier daemon:
+
+```yaml
+citadel_root: .
+poll_interval_ms: 500          # filesystem poll interval
+debounce_ms: 200               # write stabilization delay
+default_max_citizens: 3        # max concurrent citizens per outpost
+citizen_timeout_seconds: 1800  # kill citizens after 30 minutes
+log_level: INFO                # DEBUG, INFO, WARN, ERROR
+log_path: .citadel/logs/courier.log
+```
+
+### Optional Webhook
+
+```yaml
+webhook:
+  url: https://hooks.example.com/citadel
+  timeout_ms: 5000
+```
+
+On SUCCESS tribute, POSTs a summary to the configured URL.
+
+## Outpost Registry
+
+`.citadel/outposts.json` is managed by `citadel outpost register`:
+
+```json
+{
+  "schema_version": "1.0",
+  "outposts": [
+    {
+      "slug": "api-gateway",
+      "path": "/absolute/path/to/repo",
+      "status": "ACTIVE",
+      "registered_at": "2026-01-15T10:00:00.000Z",
+      "default_archetype": "software-engineer",
+      "max_citizens": 3
+    }
+  ]
+}
+```
+
+### Outpost Fields
+
+| Field | Required | Description |
+|---|---|---|
+| `slug` | Yes | Unique identifier for the outpost |
+| `path` | Yes | Absolute path to the git repository |
+| `status` | Yes | `ACTIVE`, `INACTIVE`, or `SUSPENDED` |
+| `registered_at` | Yes | ISO8601 timestamp |
+| `default_archetype` | No | Archetype to use if none specified in dispatch |
+| `max_citizens` | No | Override `default_max_citizens` for this outpost |
+
+## Grand Archives
+
+`grand-archives/` contains archetype configurations:
+
+```
+grand-archives/
+  registry.json              # lists all archetypes and their status
+  first-officer/
+    config.json              # FO settings: retry policy, nudge retention
+    system-prompt.md
+    toolset.json
+  archetypes/
+    software-engineer/
+      archetype.json         # archetype definition
+      system-prompt.md       # role-specific instructions
+      toolset.json           # allowed tools
+  shared/
+    base-tools.json
+    base-prompt-preamble.md  # prepended to all system prompts
+```
+
+### First Officer Config
+
+`grand-archives/first-officer/config.json`:
+
+```json
+{
+  "schema_version": "1.0",
+  "display_name": "First Officer",
+  "singleton": true,
+  "agent": "claude-code",
+  "retry_policy": {
+    "max_retries": 3,
+    "retry_on": ["PARTIAL", "FAILED", "TRIBUTE_INVALID"],
+    "partial_strategy": "remaining_criteria_only",
+    "on_ceiling_reached": "ESCALATE_TO_COMMANDER"
+  },
+  "nudge_retention": 500
+}
+```
+
+### Archetype Config
+
+`grand-archives/archetypes/<key>/archetype.json`:
+
+```json
+{
+  "key": "software-engineer",
+  "schema_version": "1.0",
+  "display_name": "Software Engineer",
+  "system_prompt": {
+    "preamble_ref": "shared/base-prompt-preamble.md",
+    "body_ref": "archetypes/software-engineer/system-prompt.md"
+  },
+  "toolset": {
+    "base_ref": "shared/base-tools.json",
+    "override_ref": "archetypes/software-engineer/toolset.json"
+  },
+  "constraints": {
+    "max_tokens_per_turn": 8192,
+    "temperature": 0.2,
+    "model": "claude-opus-4"
+  }
+}
+```
+
+## Agent Runtime
+
+CITADEL is agent-agnostic. Set the runtime at session start:
+
+```bash
+citadel start --agent claude-code   # default
+citadel start --agent cursor
+citadel start --agent copilot
+```
+
+Citizens receive these environment variables:
+
+| Variable | Description |
+|---|---|
+| `CITADEL_OUTPOST` | Outpost slug |
+| `CITADEL_ARCHETYPE` | Archetype key |
+| `CITADEL_CITIZEN_ID` | Unique citizen identifier |
+| `CITADEL_TASK_ID` | Task identifier |
+| `CITADEL_WORKTREE` | Path to isolated git worktree |
+| `CITADEL_BEADS_ROOT` | Path to citadel workspace root |

package/docs/contributing.md

@@ -0,0 +1,65 @@
+# Contributing
+
+## Development Setup
+
+```bash
+git clone https://github.com/citadel-labs-hq/citadel.git
+cd citadel
+npm install
+npm run build
+npm test
+```
+
+## Scripts
+
+| Script | Description |
+|---|---|
+| `npm run build` | Compile TypeScript to `dist/` |
+| `npm run dev` | Watch mode compilation |
+| `npm test` | Run all tests (vitest) |
+| `npm run test:watch` | Run tests in watch mode |
+| `npm run test:coverage` | Run tests with v8 coverage |
+| `npm run test:e2e` | Build and run CLI e2e tests |
+| `npm run lint` | Run ESLint on `src/` |
+
+## Project Structure
+
+```
+src/
+  cli/           # CLI commands (commander.js)
+  core/          # Business logic
+    fo-handlers/ # First Officer signal handlers
+  types/         # TypeScript type definitions
+  __tests__/     # Unit and integration tests
+    cli-e2e/     # CLI end-to-end test helpers
+  index.ts       # Public API exports
+```
+
+## Testing
+
+- Tests use [Vitest](https://vitest.dev/)
+- Each core module should have a corresponding test file in `src/__tests__/`
+- Tests create temporary directories and clean up after themselves
+- Git operations in tests use isolated temp repos
+
+## Code Style
+
+- TypeScript strict mode
+- ESLint with `typescript-eslint`
+- Husky pre-commit hook runs `npm run lint`
+- Conventional commits: `type(scope): description`
+
+## Pull Requests
+
+1. Create a feature branch
+2. Write tests for new functionality
+3. Ensure `npm run lint` and `npm test` pass
+4. Use conventional commit messages
+5. Keep PRs focused — one feature or fix per PR
+
+## Architecture Notes
+
+- All state is in append-only JSONL files (Beads)
+- Cross-process safety via `proper-lockfile`
+- Agent-agnostic design — no coupling to specific LLM providers
+- File-based communication — no PIDs, pipes, or network protocols

package/docs/getting-started.md

@@ -0,0 +1,88 @@
+# Getting Started
+
+## Prerequisites
+
+- Node.js v20+
+- Git
+- An LLM agent CLI (Claude Code is the default)
+
+## Install
+
+```bash
+npm install -g @citadel-labs/citadel
+```
+
+## Initialize a Workspace
+
+```bash
+citadel init my-project
+cd my-project
+```
+
+This creates:
+- `.citadel/` — identity, nudges, commands, outpost registry
+- `grand-archives/` — archetype configurations
+- `courier.config.yaml` — daemon settings
+
+## Register an Outpost
+
+An Outpost is a code repository where Citizens work:
+
+```bash
+citadel outpost register --slug api-gateway --path ../api-gateway
+```
+
+## Start a Session
+
+```bash
+citadel start
+```
+
+This writes an Identity Bead, rotates stale nudges, and reconstructs state from existing beads.
+
+## Dispatch a Task
+
+```bash
+citadel dispatch --outpost api-gateway \
+  --task "Implement GET /health endpoint"
+```
+
+Or using the full form:
+
+```bash
+citadel command dispatch --outpost api-gateway \
+  --task "Implement GET /health endpoint" \
+  --archetype software-engineer
+```
+
+## Check Status
+
+```bash
+citadel status
+```
+
+Shows session info, per-outpost ceiling/pending counts, and unprocessed nudge/command counts.
+
+## View Results
+
+```bash
+# View tribute (work output) for a task
+citadel tribute --task <task-id>
+
+# Full event timeline
+citadel trace --task <task-id>
+```
+
+## Stop a Session
+
+```bash
+citadel stop
+```
+
+Clears unprocessed nudges and writes a shutdown entry to the session log.
+
+## Next Steps
+
+- [Architecture](./architecture.md) — understand the chain of command
+- [CLI Reference](./cli-reference.md) — all commands and flags
+- [Configuration](./configuration.md) — customize courier and archetype settings

package/grand-archives/archetypes/architect/archetype.json

@@ -0,0 +1,18 @@
+{
+  "key": "architect",
+  "schema_version": "1.0",
+  "display_name": "Architect",
+  "system_prompt": {
+    "preamble_ref": "shared/base-prompt-preamble.md",
+    "body_ref": "archetypes/architect/system-prompt.md"
+  },
+  "toolset": {
+    "base_ref": "shared/base-tools.json",
+    "override_ref": "archetypes/architect/toolset.json"
+  },
+  "constraints": {
+    "max_tokens_per_turn": 8192,
+    "temperature": 0.2,
+    "model": "claude-opus-4"
+  }
+}

package/grand-archives/archetypes/qa-engineer/archetype.json

@@ -0,0 +1,18 @@
+{
+  "key": "qa-engineer",
+  "schema_version": "1.0",
+  "display_name": "QA Engineer",
+  "system_prompt": {
+    "preamble_ref": "shared/base-prompt-preamble.md",
+    "body_ref": "archetypes/qa-engineer/system-prompt.md"
+  },
+  "toolset": {
+    "base_ref": "shared/base-tools.json",
+    "override_ref": "archetypes/qa-engineer/toolset.json"
+  },
+  "constraints": {
+    "max_tokens_per_turn": 8192,
+    "temperature": 0.2,
+    "model": "claude-opus-4"
+  }
+}

package/grand-archives/archetypes/software-engineer/archetype.json

@@ -0,0 +1,18 @@
+{
+  "key": "software-engineer",
+  "schema_version": "1.0",
+  "display_name": "Software Engineer",
+  "system_prompt": {
+    "preamble_ref": "shared/base-prompt-preamble.md",
+    "body_ref": "archetypes/software-engineer/system-prompt.md"
+  },
+  "toolset": {
+    "base_ref": "shared/base-tools.json",
+    "override_ref": "archetypes/software-engineer/toolset.json"
+  },
+  "constraints": {
+    "max_tokens_per_turn": 8192,
+    "temperature": 0.2,
+    "model": "claude-opus-4"
+  }
+}

package/grand-archives/archetypes/software-engineer/system-prompt.md

@@ -0,0 +1,39 @@
+# Software Engineer — Behavioral Contract
+
+## Core Directives
+
+1. Your identity is CITADEL_CITIZEN_ID. Your workspace is CITADEL_WORKTREE.
+   All Bead reads/writes use CITADEL_BEADS_ROOT — not your worktree.
+
+2. Read your full inbox from $CITADEL_BEADS_ROOT/mail/ in arrival order.
+
+3. If no TASK_ASSIGNMENT found: write TASK_REPORT BLOCKED + exit cleanly.
+
+4. If TRIBUTE_INVALID is in your inbox (retry):
+   - Read the errors carefully
+   - Inspect $CITADEL_WORKTREE for prior attempt's code
+   - Decide: build on it, partially reset, or start from scratch
+   - Use git reset inside your worktree if needed — the branch is yours
+   - Do not blindly repeat what failed
+
+5. Mark each Mail read. Synthesize full context before writing code.
+
+6. Work only inside $CITADEL_WORKTREE.
+
+7. Write tests before or alongside implementation.
+
+8. Your branch already exists: citizen/<task_id>.
+
+9. Determine attempt number: count lines in
+   $CITADEL_BEADS_ROOT/tribute/<task_id>_tribute.jsonl
+
+## Completion Sequence
+
+1. Run tests. Confirm they pass.
+2. Commit changes inside $CITADEL_WORKTREE.
+3. Open PR from citizen/<task_id> against main.
+4. Write Tribute to $CITADEL_BEADS_ROOT/tribute/<task_id>_tribute.jsonl
+   - artifacts MUST be relative to Outpost root (e.g. src/routes/health.ts)
+   - NOT relative to worktree (not worktrees/citizen/<task_id>/src/...)
+5. Write upward Mail to $CITADEL_BEADS_ROOT/mail/ if needed.
+6. exit(0)

package/grand-archives/archetypes/software-engineer/toolset.json

@@ -0,0 +1,15 @@
+{
+  "schema_version": "1.0",
+  "description": "Software Engineer toolset — full development capabilities",
+  "tools": [
+    { "name": "read_bead", "enabled": true },
+    { "name": "scan_beads", "enabled": true },
+    { "name": "write_mail", "enabled": true },
+    { "name": "write_tribute", "enabled": true },
+    { "name": "bash", "enabled": true },
+    { "name": "write_file", "enabled": true },
+    { "name": "git", "enabled": true },
+    { "name": "github_pr", "enabled": true },
+    { "name": "web_search", "enabled": false }
+  ]
+}

package/grand-archives/first-officer/config.json

@@ -0,0 +1,21 @@
+{
+  "schema_version": "1.0",
+  "display_name": "First Officer",
+  "singleton": true,
+  "assignable": false,
+  "agent": "claude-code",
+  "system_prompt_ref": "first-officer/system-prompt.md",
+  "toolset_ref": "first-officer/toolset.json",
+  "model": "claude-opus-4",
+  "constraints": {
+    "temperature": 0.2,
+    "max_tokens_per_turn": 8192
+  },
+  "retry_policy": {
+    "max_retries": 3,
+    "retry_on": ["PARTIAL", "FAILED", "TRIBUTE_INVALID"],
+    "partial_strategy": "remaining_criteria_only",
+    "on_ceiling_reached": "ESCALATE_TO_COMMANDER"
+  },
+  "nudge_retention": 500
+}

package/grand-archives/first-officer/system-prompt.md

@@ -0,0 +1,47 @@
+# First Officer — Behavioral Contract
+
+## On Session Start
+
+1. Read Identity Bead (last line of .citadel/identity.jsonl)
+2. Load .citadel/outposts.json
+3. Scan all Outpost .beads/mail/ and .beads/tribute/ — these are your state sources
+4. Scan .citadel/commands/ for unprocessed Command Beads
+5. Reconstruct full system state from Mail + Tribute Beads only.
+   Do NOT reconstruct state from Nudge history.
+6. Write startup report to .citadel/logs/session.log
+7. Process any unprocessed Nudge Beads as fresh signals
+8. Process any unprocessed Command Beads
+9. Watch .citadel/nudges.jsonl — this is your signal channel
+
+## Core Responsibilities
+
+1. Dispatch tasks — Archetype, citizen_id, TASK_ASSIGNMENT with spawn_hint.
+   Respect max_citizens ceiling per Outpost.
+
+2. Process Tribute — validate (schema + criteria only), broadcast, retry, escalate.
+   Check attempt count from Tribute Bead — not from validateTribute().
+
+3. Slot-open dispatch — on TRIBUTE_WRITTEN SUCCESS, re-scan the Outpost inbox
+   for unread TASK_ASSIGNMENT Mail. The inbox is the queue. Dispatch if found
+   and under ceiling.
+
+4. Handle PARALLELISM_CEILING_HIT — informational only. Log it. The inbox holds
+   the pending work. You will dispatch when the next slot opens.
+
+5. Manage retries — worktree is left as-is for the retry Citizen.
+   New Citizen reads TRIBUTE_INVALID and assesses prior state autonomously.
+
+6. Resolve dependencies — getRegisteredOutpostMailDirs() on SUCCESS.
+
+7. Forward relays — RELAY_REQUEST -> PEER_RELAY with spawn_hint.
+
+8. Escalate — at retry ceiling: summarize all attempts, recommend action.
+
+## What You Never Do
+
+- Reconstruct state from Nudge history. State lives in Mail + Tribute Beads.
+- Omit spawn_hint from downward Mail.
+- Write files, run git, or touch Outpost code directly.
+- Maintain an internal queue — the inbox is the queue.
+- Check retry ceilings inside validateTribute().
+- Write Mail addressed to `citadel`.

package/grand-archives/first-officer/toolset.json

@@ -0,0 +1,19 @@
+{
+  "schema_version": "1.0",
+  "description": "First Officer toolset — orchestration only",
+  "tools": [
+    { "name": "read_bead", "enabled": true },
+    { "name": "scan_beads", "enabled": true },
+    { "name": "write_mail", "enabled": true },
+    {
+      "name": "citadel_cli",
+      "enabled": true,
+      "allowed_commands": ["status", "dispatch", "note", "retry", "resolve", "trace", "worktree"]
+    },
+    { "name": "bash", "enabled": false },
+    { "name": "write_file", "enabled": false },
+    { "name": "git", "enabled": false },
+    { "name": "github_pr", "enabled": false },
+    { "name": "web_search", "enabled": false }
+  ]
+}

package/grand-archives/registry.json

@@ -0,0 +1,8 @@
+{
+  "schema_version": "1.0",
+  "archetypes": [
+    { "key": "software-engineer", "description": "Features, bugs, tests, PRs.", "status": "active" },
+    { "key": "qa-engineer", "description": "Integration/E2E tests, regressions.", "status": "planned" },
+    { "key": "architect", "description": "ADRs, design review, scalability.", "status": "planned" }
+  ]
+}

package/grand-archives/shared/base-prompt-preamble.md

@@ -0,0 +1,25 @@
+# CITADEL Citizen — Base Preamble
+
+You are a CITADEL Citizen — an autonomous LLM agent operating within the CITADEL orchestration system.
+
+## Environment
+
+- `CITADEL_OUTPOST` — the Outpost you are assigned to
+- `CITADEL_ARCHETYPE` — your role archetype
+- `CITADEL_CITIZEN_ID` — your unique identity for this task
+- `CITADEL_TASK_ID` — the task you are executing
+- `CITADEL_WORKTREE` — your isolated workspace (git worktree)
+- `CITADEL_BEADS_ROOT` — path to shared .beads/ directory for all Bead I/O
+
+## Bead I/O Rules
+
+- ALL Bead reads and writes go through `CITADEL_BEADS_ROOT` — never worktree-local paths.
+- Mail: `$CITADEL_BEADS_ROOT/mail/`
+- Tribute: `$CITADEL_BEADS_ROOT/tribute/`
+- Artifact paths in Tribute must be relative to the Outpost root, not the worktree.
+
+## Communication
+
+- You write upward Mail (to: citadel) for reports, relay requests, and status.
+- You never address other Outposts directly — use RELAY_REQUEST via the First Officer.
+- You never write downward Mail.

package/grand-archives/shared/base-tools.json

@@ -0,0 +1,10 @@
+{
+  "schema_version": "1.0",
+  "description": "Base toolset shared across all Archetypes",
+  "tools": [
+    { "name": "read_bead", "enabled": true },
+    { "name": "scan_beads", "enabled": true },
+    { "name": "write_mail", "enabled": true },
+    { "name": "write_tribute", "enabled": true }
+  ]
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@citadel-labs/citadel",
+  "version": "0.1.0",
+  "description": "Multi-agent orchestration system — cold-start, hub-and-spoke coordination for autonomous LLM Citizens",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "citadel": "dist/cli/index.js"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "files": [
+    "dist",
+    "grand-archives",
+    "docs"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "lint": "eslint src/",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "npm run build && vitest run src/__tests__/cli-e2e/",
+    "prepublishOnly": "npm run build",
+    "version:patch": "npm version patch -m 'chore(release): v%s'",
+    "version:minor": "npm version minor -m 'chore(release): v%s'",
+    "version:major": "npm version major -m 'chore(release): v%s'",
+    "changelog": "git log --pretty=format:'* %s (%h)' $(git describe --tags --abbrev=0 2>/dev/null || echo HEAD~20)..HEAD",
+    "release:patch": "npm run lint && npm test && npm run version:patch && git push && git push --tags",
+    "release:minor": "npm run lint && npm test && npm run version:minor && git push && git push --tags",
+    "prepare": "husky"
+  },
+  "keywords": [
+    "citadel",
+    "agent",
+    "orchestration",
+    "llm",
+    "multi-agent"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/citadel-labs/citadel.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "chokidar": "^5.0.0",
+    "commander": "^14.0.3",
+    "nanoid": "^5.1.6",
+    "proper-lockfile": "^4.1.2",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.5",
+    "@types/proper-lockfile": "^4.1.4",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^10.0.2",
+    "husky": "^9.1.7",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.1",
+    "vitest": "^4.0.18"
+  }
+}