# Core Concepts

This document is an LLM-consumable reference for CEXAI's architecture. It covers the six primitives that make the system work: the 8F pipeline, 12 pillars, GDP, kinds, builders, and nuclei.

---

## The 8F Pipeline

Every task in CEXAI -- research, writing, coding, orchestration, anything -- passes through eight sequential functions. This is the reasoning protocol, not a build checklist. It activates on every input, not just "build" commands.

### F1 CONSTRAIN

Resolve the artifact type. Read `kinds_meta.json` to find the matching kind. Load the pillar schema (`P{xx}/_schema.yaml`). Set constraints: max bytes, naming pattern, output directory.

This is where free-form user input becomes a typed tuple: `{kind, pillar, nucleus, verb}`. If the user says "make me a landing page," F1 resolves it to `kind=landing_page, pillar=P05, nucleus=N03`.

### F2 BECOME

Load the specialized builder for this kind. Each builder has 12 ISOs (instruction files), one per pillar. The builder transforms the LLM from a generic assistant into a domain expert for this specific artifact type.

The sin lens of the assigned nucleus also activates here. N02 (Creative Lust) writes differently than N01 (Analytical Envy), even when producing the same kind.

### F3 INJECT

Assemble context: the kind's knowledge card, similar existing artifacts, brand configuration, builder examples, and any relevant domain knowledge. The retriever (`cex_retriever.py`) uses TF-IDF to find related documents.

Sub-steps:
- **F3b PERSIST**: Declare what new knowledge was discovered and should be saved.
- **F3c GROUND**: Record provenance for each injected source (path, confidence, freshness).

### F4 REASON

Plan the approach. Decide the number of sections, the structural template, and the density target. If a similar artifact exists with a match score above 60%, use it as a template (Template-First Construction Triad).

This is where the LLM does its thinking before generating. The plan is explicit, not implicit.

### F5 CALL

Activate tools. List available tools (compile, doctor, index, signal). Search for existing similar artifacts that can be reused or referenced. Execute any pre-build queries.

### F6 PRODUCE

Generate the complete artifact: YAML frontmatter (id, kind, title, version, quality, tags) plus structured body. Follow the builder instructions from F2. Hit the density target of 0.85 or higher.

### F7 GOVERN

Validate the output against quality gates:
- **H01-H07**: Seven hard gates (frontmatter present, schema compliance, naming convention, etc.)
- **12LP checklist**: All 12 pillar points satisfied
- **5D scoring**: Five weighted quality dimensions (D1-D5)

If the score is below 8.0, return to F6 for up to 2 retries.

Sub-step:
- **F7b LEARN**: Capture what patterns led to high or low scores for future improvement.

### F8 COLLABORATE

Persist the result:
1. Save the `.md` file to the correct pillar directory
2. Compile metadata: `python _tools/cex_compile.py {path}`
3. Rebuild index: `python _tools/cex_index.py`
4. Git commit
5. Emit a completion signal so other agents know this artifact exists

---

## The 12 Pillars

Pillars are taxonomic domains, not departments. Every nucleus works across all 12. Every builder produces ISOs for all 12. The 12 pillars are the capability dimensions of the system.

| ID | Name | Domain | What lives here |
|----|------|--------|-----------------|
| P01 | Knowledge | Information assets | Knowledge cards, RAG sources, glossaries, citations, learning records |
| P02 | Model | Agent identity | Agent definitions, LLM provider configs, personality layers, nucleus definitions |
| P03 | Prompt | Prompt engineering | System prompts, prompt templates, chains, context window configs, taglines |
| P04 | Tools | Executable capabilities | MCP servers, API clients, browser tools, webhooks, messaging gateways |
| P05 | Output | Deliverables | Landing pages, formatters, parsers, output templates |
| P06 | Schema | Contracts and types | Input/output schemas, validators, type definitions, interfaces |
| P07 | Evaluation | Quality measurement | Quality gates, scoring rubrics, benchmarks, LLM judges |
| P08 | Architecture | Structural blueprints | Agent cards, component maps, decision records, diagrams |
| P09 | Config | Runtime settings | Environment configs, rate limits, feature flags, secret management |
| P10 | Memory | Persistent state | Entity memory, knowledge indexes, prompt caches, session stores |
| P11 | Feedback | Improvement loops | Bug loops, guardrails, learning signals, regression checks, monetization |
| P12 | Orchestration | Coordination | Workflows, dispatch rules, schedules, crew templates, pipeline templates |

### Directory structure

Every nucleus mirrors the 12 pillars:

```
N03_engineering/
  P01_knowledge/
  P02_model/
  P03_prompt/
  ...
  P12_orchestration/
```

This fractal layout means that any tool, query, or validation that works for one nucleus works for all of them. Convention over configuration.

---

## Guided Decision Protocol (GDP)

GDP governs **who decides what**. The rule: user decides WHAT (tone, audience, style, branding), LLM decides HOW (files, pipeline, structure, tooling).

### Two modes

| Mode | When | GDP active? |
|------|------|-------------|
| **Co-pilot** | User is in the chat (`/guide`, `/init`, `/mission` interactive) | Yes -- present options, wait for user, record answers |
| **Autonomous** | Nucleus dispatched via grid or solo | No -- read the decision manifest, execute without asking |

### The decision manifest

Before dispatching nuclei, N07 identifies subjective decisions, presents them to the user as Decision Points, and records answers in `.cex/runtime/decisions/decision_manifest.yaml`. This manifest is the single source of truth. Dispatched nuclei read it and never re-ask the user.

### When GDP triggers

| Situation | GDP? |
|-----------|------|
| "Build a landing page for my SaaS" | Yes -- layout, tone, CTA need decisions |
| "Build a knowledge card about React patterns" | No -- factual, no subjective choices |
| "Fix this bug" | No -- mechanical, one correct answer |
| "Write ad copy for Black Friday" | Yes -- audience, urgency level, brand voice |
| User says "just do it" or "you decide" | No -- user waived GDP explicitly |

---

## Kinds

A kind is a named artifact type. CEXAI has 300 of them, registered in `.cex/kinds_meta.json`.

Examples of kinds: `knowledge_card`, `agent`, `prompt_template`, `landing_page`, `workflow`, `guardrail`, `crew_template`, `scoring_rubric`, `mcp_server`, `entity_memory`.

### What a kind provides

| Component | Location | Purpose |
|-----------|----------|---------|
| Builder | `archetypes/builders/{kind}-builder/` | 12 ISOs that teach the LLM how to produce this kind |
| Knowledge card | `N00_genesis/P01_knowledge/library/kind/kc_{kind}.md` | Reference documentation about the kind itself |
| Schema | `N00_genesis/P{xx}/_schema.yaml` | Structural rules and constraints |
| Sub-agent | `.claude/agents/{kind}-builder.md` | Claude Code sub-agent definition |
| Registry entry | `.cex/kinds_meta.json` | Metadata: pillar, function, max bytes, description |

### Kind to pillar mapping

Each kind has a primary pillar. `knowledge_card` lives in P01. `agent` lives in P02. `landing_page` lives in P05. The mapping is defined in `kinds_meta.json` and enforced by F1 CONSTRAIN.

### Extending the taxonomy

To add a new kind:
1. Register it: `python _tools/cex_kind_register.py --kind my_new_kind --pillar P0X`
2. Create the knowledge card: `kc_my_new_kind.md`
3. Create the builder: 12 ISOs in `archetypes/builders/my-new-kind-builder/`
4. Materialize the sub-agent: `python _tools/cex_materialize.py --kind my_new_kind`
5. Validate: `python _tools/cex_doctor.py`

---

## Builders

A builder is a 12-file specification that teaches an LLM how to produce a specific kind. There are 300+ builders (one per kind, plus a meta-builder).

### The 12 ISOs

Each builder contains 12 ISOs (instruction specification objects), one per pillar:

| ISO file | Pillar | 8F function | What it specifies |
|----------|--------|-------------|-------------------|
| `bld_knowledge_{kind}.md` | P01 | INJECT | What domain knowledge to load |
| `bld_model_{kind}.md` | P02 | BECOME | Identity, role, behavioral instructions |
| `bld_prompt_{kind}.md` | P03 | PRODUCE | Prompt template and generation rules |
| `bld_tools_{kind}.md` | P04 | CALL | Which tools to use during build |
| `bld_output_{kind}.md` | P05 | PRODUCE | Output format, structure, examples |
| `bld_schema_{kind}.md` | P06 | CONSTRAIN | Schema rules, field requirements |
| `bld_eval_{kind}.md` | P07 | GOVERN | Evaluation criteria and scoring rubric |
| `bld_architecture_{kind}.md` | P08 | CONSTRAIN | Structural constraints and patterns |
| `bld_config_{kind}.md` | P09 | CONSTRAIN | Configuration and defaults |
| `bld_memory_{kind}.md` | P10 | INJECT | Memory sources and context injection |
| `bld_feedback_{kind}.md` | P11 | GOVERN | Feedback loops and improvement rules |
| `bld_orchestration_{kind}.md` | P12 | COLLABORATE | Handoff and coordination rules |

At F2 BECOME, the 8F pipeline loads all 12 ISOs for the resolved kind. The builder is the "expert knowledge" that transforms a generic LLM into a specialist for that artifact type.

### Builder location

All builders live in `archetypes/builders/{kind}-builder/`. Shared instructions (common to all builders) live in `archetypes/builders/_shared/`.

---

## Nuclei

A nucleus is an autonomous AI agent that acts as a specialized department. CEXAI has 7 operational nuclei plus 1 archetype.

### N00 Genesis (archetype)

N00 is not operational. It is the template that all other nuclei inherit from. The 12 pillar schemas, shared builders, and universal prompt compiler live in `N00_genesis/`.

### N01 Intelligence (Analytical Envy)

Research, competitive analysis, data gathering. Optimizes for depth and coverage under ambiguity.

### N02 Marketing (Creative Lust)

Copy, campaigns, brand voice, content. Optimizes for creative quality and emotional impact.

### N03 Engineering (Inventive Pride)

Builds artifacts, scaffolds code, creates new kinds and builders. Optimizes for technical precision. Defaults to higher-tier models (large context for full repo awareness).

### N04 Knowledge (Knowledge Gluttony)

Documentation, RAG setup, knowledge organization. Optimizes for completeness and density.

### N05 Operations (Gating Wrath)

Testing, deployment, CI/CD, code review. Optimizes for correctness enforcement.

### N06 Commercial (Strategic Greed)

Pricing, monetization, sales funnels, brand strategy. Optimizes for revenue and market advantage.

### N07 Orchestrator (Orchestrating Sloth)

Dispatches work to N01-N06. Never builds artifacts directly. Plans waves, manages handoffs, monitors signals, consolidates results. Defaults to higher-tier models (large context for grid coordination).

> Per-nucleus model is configurable in `.cex/config/nucleus_models.yaml`. The defaults route reasoning-heavy roles to higher tiers, but every nucleus can run on any provider (Claude / Codex / Gemini / Ollama) at any tier.

### Sin lenses

Each nucleus runs on one of the seven deadly sins. The sin is not decorative -- it determines what the nucleus optimizes for when the task is ambiguous. When N02 (Lust) and N01 (Envy) both write about competitors, N02 will produce seductive copy while N01 will produce exhaustive data tables.

### Multi-runtime support

All nuclei can run on Claude, GPT, Gemini, or Ollama. Routing is configured in `.cex/config/nucleus_models.yaml` with fallback chains. The same artifacts, pipelines, and quality gates work across all providers.

### Nucleus directory structure

Each nucleus mirrors the 12 pillars:

```
N03_engineering/
  P01_knowledge/    # Domain knowledge cards
  P02_model/        # Nucleus identity, agent definitions
  P03_prompt/       # Prompt templates
  P04_tools/        # Tool configs
  P05_output/       # Output artifacts
  P06_schema/       # Schemas
  P07_evals/        # Evaluation results
  P08_architecture/ # Agent card, component map
  P09_config/       # Configs
  P10_memory/       # Memory stores
  P11_feedback/     # Feedback signals
  P12_orchestration/# Workflows, crews
  rules/            # Nucleus identity rules
  compiled/         # Auto-generated (gitignored)
```

---

## How They Connect

The three core primitives compose multiplicatively:

- **8F** is the reasoning process (how to think about any task)
- **12 Pillars** organize where artifacts live (taxonomic dimensions)
- **300 Kinds** define what you are producing (typed artifact templates)

A single `/build` activates one kind, in one pillar, through all 8 functions. A `/mission` dispatches multiple kinds across multiple nuclei, each running its own 8F pipeline. N07 coordinates the grid.

```
User input: "launch my product"
    |
    v
N07 decomposes into tasks:
    - N01: research competitors     (kind: knowledge_card, P01)
    - N02: write launch copy        (kind: prompt_template, P03)
    - N03: build landing page       (kind: landing_page, P05)
    - N05: deploy and test          (kind: env_config, P09)
    - N06: set pricing tiers        (kind: content_monetization, P11)
    |
    v
Each nucleus runs 8F independently:
    F1 -> F2 -> F3 -> F4 -> F5 -> F6 -> F7 -> F8
    |                                            |
    constrain                              commit + signal
    |
    v
N07 consolidates: verify, score, report
```

---

## The Exchange

The X in CEXAI stands for Exchange. Every `.md` artifact with YAML frontmatter is a self-describing exchange unit. It carries its kind, quality score, pillar, and nucleus origin. You can export a knowledge card, a builder, or an entire nucleus from one CEXAI instance and import it into another. Run `cex_doctor.py` and it validates automatically.

Intelligence compounds faster when exchanged.

---

## See Also

- [Quickstart](quickstart.md) -- Build your first artifact
- [CLI Reference](cli-reference.md) -- All 150+ tools
- [SDK Reference](sdk-reference.md) -- Python API
- [Glossary](glossary.md) -- Term definitions
- [Vocabulary](vocabulary.md) -- Full controlled vocabulary