Prism AI Project

CLI scaffolder that creates smart parent folders for software projects, with agent orchestration via Claude Code and RAG via OpenRAG.

What Prism Does

Prism generates the entire structure that Claude Code needs to work as an agent orchestrator in your project:

• 9 orchestration agents that coordinate the workflow
• 7 specialized agents (architect, backend, frontend, database, devops, reviewer, git)
• 4 default pipelines (feature, simple fix, structural fix, improvement)
• OpenRAG connection for persistent memory via RAG
• An MCP Server that connects Claude Code to your knowledge base

When you open Claude Code in a Prism-created project, it automatically loads the RAG context and follows a structured workflow.

Prerequisites

| Requirement | Minimum Version | Purpose | |---|---|---| | Node.js | 20+ | CLI and MCP Server runtime | | Claude Code | any | Orchestrator that uses the agents | | OpenRAG | - | RAG engine (Langflow + OpenSearch + Docling) |

Running OpenRAG Locally

OpenRAG must be running before using prism start. See the OpenRAG documentation for installation instructions.

By default, Prism expects OpenRAG at http://localhost:3000.

Installation

Via npm (global)

npm install -g prism-ai-project

For local development

git clone https://github.com/your-user/prism-ai-project.git
cd prism-ai-project
npm install
npm run build
npm link    # makes the 'prism' command available globally

After installation, the prism command is available in the terminal:

prism --help

Step-by-Step Guide

Step 1 — Create the Project

prism init my-project

The CLI asks interactive questions:

? OpenRAG URL:              http://localhost:3000
? OpenRAG API Key:          ********
? Embedding model:          text-embedding-3-small
? OpenSearch index name:    documents

To skip the questions (tests/CI), use --no-interactive — it will use default values.

When finished, the following structure is created:

my-project/
  CLAUDE.md                      # orchestrator instructions
  prism.config.json              # central configuration
  .env                           # OpenRAG credentials
  .gitignore
  .claude/
    settings.json                # registers the Prism MCP Server
    agents/                      # 16 agents (.md)
      ContextLoader.md
      PromptSanitizer.md
      RAGQuerier.md
      Presenter.md
      TaskClassifier.md
      PipelineExecutor.md
      TaskPlanner.md
      FileNormalizer.md
      RAGInjector.md
      tech-architect.md
      backend-dev.md
      database-architect.md
      frontend-dev.md
      devops.md
      code-reviewer.md
      git-manager.md
    rules/                       # 4 rules (.md)
      rag-source-of-truth.md
      agent-behavior.md
      doc-standards.md
      pipeline-rules.md
    skills/                      # empty — add with prism add skill
  docs/
    adrs/                        # architectural decisions
    specs/                       # technical design
    tasks/                       # execution plans
    memory/                      # agent learnings
    stack/                       # technical stack
    context/                     # business rules

Step 2 — Customize the Specialized Agents

This is the most important step. Open each specialized agent in .claude/agents/ and fill in the sections marked with [FILL IN]:

tech-architect.md — Define the stack, architectural patterns and conventions:

# [FILL IN] Technical stack:
Stack: Go 1.22, PostgreSQL 16, Redis 7, gRPC

# [FILL IN] Architectural patterns:
Patterns: Clean Architecture, CQRS for writes

# [FILL IN] Conventions:
Conventions: handlers/ for HTTP, services/ for logic, repos/ for persistence

backend-dev.md — Language, framework, commands:

# [FILL IN] Language and version:
Language: Go 1.22

# [FILL IN] Frameworks and libs:
Stack: Chi router, sqlc, golang-migrate

# [FILL IN] Test and lint commands:
Commands: go test ./... && golangci-lint run

database-architect.md — Database, migrations, driver:

# [FILL IN] Database and version:
Database: PostgreSQL 16

# [FILL IN] Migration tool:
Migrations: golang-migrate

# [FILL IN] Access driver:
Driver: pgx v5

frontend-dev.md — Framework, design system:

# [FILL IN] Framework and version:
Framework: Next.js 15 (App Router)

# [FILL IN] Design system:
Design: shadcn/ui + Tailwind CSS

devops.md — Containers, CI/CD:

# [FILL IN] Container orchestration:
Containers: Docker Compose local, Kubernetes prod

# [FILL IN] CI/CD:
CI/CD: GitHub Actions

code-reviewer.md — Patterns and blockers:

# [FILL IN] Mandatory patterns:
Patterns: SOLID, tests for all business logic

# [FILL IN] What blocks the commit:
Blockers: failing tests, lint errors, function without test

git-manager.md — Commit convention:

# [FILL IN] Commit convention:
Convention: Conventional Commits — feat: fix: docs: chore:

# [FILL IN] What to never do:
Forbidden: never push to main, never --force, never commit .env

Step 3 — Validate the Environment

cd my-project
prism start

prism start runs the following validations:

✓ prism.config.json found
✓ .env valid
✓ OpenRAG reachable — http://localhost:3000
✓ Knowledge Filters — 6 created
✓ Langflow Flows — 6 created
✓ Prism MCP registered in .claude/settings.json

Session ready.
Open Claude Code in this directory.

If any validation fails, the CLI shows the error message and what to do to fix it.

Step 4 — Use with Claude Code

Open Claude Code inside the project directory:

cd my-project
claude    # or open via VS Code

What happens automatically:

1. Claude Code reads CLAUDE.md and understands it is a Prism project
2. The MCP Server (prism-mcp) is started via .claude/settings.json
3. ContextLoader is invoked — loads the knowledge base from RAG
4. Claude is ready to work as orchestrator

How the Workflow Works

When you send a prompt to Claude Code inside a Prism project, it follows this flow:

Zone 1 — Pre-approval (read-only)

You send a prompt
  -> PromptSanitizer    transforms into semantic queries
  -> RAGQuerier          searches RAG via MCP
  -> Presenter           summarizes and presents context
  -> Do you approve?
       No + reason -> goes back to RAGQuerier with refined query
       Yes -> proceeds to Zone 2

Zone 2 — Post-approval (execution)

Before starting, the Presenter collects:

1. Type: feature | fix | improvement
2. Scope: simple | structural (only for fix)
3. Layer: backend | frontend | database | infra | integration | security | architecture

TaskClassifier     identifies the pipeline in prism.config.json
  -> PipelineExecutor  executes in 3 phases:

  Phase 1 — Planning (disk):
    tech-architect -> database-architect? -> TaskPlanner
    -> FileNormalizer -> RAGInjector (user approves SPEC + TASKS injection)
    -> PAUSE — SPEC + TASKS are now in RAG

  Phase 2 — Implementation (RAG):
    backend-dev -> frontend-dev? -> devops?
    (all agents fetch SPEC/TASKS from RAG via query_rag — never from disk)

  Phase 3 — Post-implementation:
    code-reviewer -> git-manager
    -> FileNormalizer -> RAGInjector (user approves MEMORY injection)

Zone 2 never starts without your explicit approval. RAGInjector never injects without your confirmation. Implementation agents fetch context exclusively from RAG via query_rag().

Default Pipelines

Prism comes with 4 pre-configured pipelines:

feature

New functionality from scratch.

Phase 1: tech-architect -> database-architect? -> TaskPlanner
         -> [FileNormalizer -> RAGInjector -> approve SPEC+TASKS]
Phase 2: backend-dev -> frontend-dev? -> devops?  (all via RAG)
Phase 3: code-reviewer -> git-manager
         -> [FileNormalizer -> RAGInjector -> approve MEMORYs]

fix-simple

Point fix without behavior change. No planning phase — agents query existing RAG context.

Phase 2: backend-dev -> frontend-dev?  (query existing context from RAG)
Phase 3: code-reviewer -> git-manager
         -> [FileNormalizer -> RAGInjector -> approve MEMORYs]

fix-structural

Fix that changes behavior — generates new SPEC and deprecates previous.

Phase 1: tech-architect -> database-architect? -> TaskPlanner
         -> [FileNormalizer -> RAGInjector -> approve SPEC+TASKS]
Phase 2: backend-dev -> frontend-dev?  (all via RAG)
Phase 3: code-reviewer -> git-manager
         -> [FileNormalizer -> RAGInjector -> approve MEMORYs]

improvement

Improvement — always deprecates previous SPEC and creates new version.

Phase 1: tech-architect -> database-architect? -> TaskPlanner
         -> [FileNormalizer -> RAGInjector -> approve SPEC+TASKS]
Phase 2: backend-dev -> frontend-dev? -> devops?  (all via RAG)
Phase 3: code-reviewer -> git-manager
         -> [FileNormalizer -> RAGInjector -> approve MEMORYs]

Steps marked with ? are conditional — the TaskClassifier asks if they are needed. [FileNormalizer -> RAGInjector] runs at phase boundaries — the pipeline pauses until the user approves.

Adding Resources

Register a service (microservice, monorepo, etc.)

prism add service api-gateway

The CLI detects if the directory already exists, if it has git, and registers it in prism.config.json.

Add a specialized agent

prism add agent legal-advisor

Creates .claude/agents/legal-advisor.md with a template to fill in and registers it in config.

Add a custom pipeline

prism add pipeline feature-mobile

The CLI asks the task type (feature/fix/improvement) and creates a pipeline skeleton in prism.config.json.

Add a skill

prism add skill go-patterns

Creates .claude/skills/go-patterns/SKILL.md with a template to fill in.

Configuration — prism.config.json

The central configuration file. Structure:

{
  "project": {
    "name": "my-project",
    "description": "",
    "version": "1.0.0"
  },
  "openrag": {
    // credentials are in .env — kept empty here for security
    "embedding_model": "text-embedding-3-small",
    "index": "documents"
  },
  "context_loader": {
    "doc_types": ["memory", "stack", "context", "adr", "spec", "tasks"],
    "score_threshold": 0.7,
    "max_documents": 5,      // max per type
    "total_limit": 30         // total document ceiling for context
  },
  "services": [],
  "agents": { "specialized": [] },
  "pipelines": [ /* ... 4 default pipelines ... */ ],
  "knowledge_filters": {
    "adr": "filter-adr",
    "spec": "filter-spec"
    // ...
  },
  "file_conventions": {
    "adr": "ADR-{number}-{slug}.md",
    "spec": "SPEC_{slug}.md",
    "tasks": "TASKS_{slug}.md",
    "memory": "MEMORY_{agent}_{slug}.md",
    "stack": "STACK_{layer}.md",
    "context": "CONTEXT_{area}.md"
  },
  "ingestion": {
    "flows": {
      "adr":    { "chunk_size": 5000, "overlap": 600 },
      "spec":   { "chunk_size": 2000, "overlap": 300 },
      "tasks":  { "chunk_size": 2500, "overlap": 400 },
      "memory": { "chunk_size": 800,  "overlap": 80  },
      "stack":  { "chunk_size": 4000, "overlap": 500 },
      "context":{ "chunk_size": 3000, "overlap": 400 }
    }
  }
}

Environment Variables — .env

OPENRAG_URL=http://localhost:3000
OPENRAG_API_KEY=your-api-key
OPENRAG_EMBEDDING_MODEL=text-embedding-3-small
OPENRAG_INDEX=documents

The .env is in .gitignore — it will never be committed.

RAG Document Types

| doc_type | File | Description | Limit | |---|---|---|---| | adr | ADR-{number}-{slug}.md | Architectural decisions | 5000 chars | | spec | SPEC_{slug}.md | Technical design of features | 1800 chars/endpoint | | tasks | TASKS_{slug}.md | Execution plans | 2000 chars/block | | memory | MEMORY_{agent}_{slug}.md | Agent learnings | 600 chars | | stack | STACK_{layer}.md | Technical stack per layer | 3500 chars | | context | CONTEXT_{area}.md | Business rules | 2500 chars |

Document Status

• active — current and valid version
• deprecated — replaced by newer version
• draft — generated, awaiting approval

Update Rules

• RAG never edits — only adds new versions
• improvement always deprecates the previous SPEC
• structural fix deprecates SPEC when generating new one
• simple fix never deprecates

MCP Server — Prism MCP

Prism includes an MCP Server that exposes 4 tools to Claude Code:

| Tool | Description | |---|---| | load_context() | Loads general context from RAG — used at session start | | query_rag(query, doc_type?) | Semantic search on RAG | | get_session_state() | Returns current session state (loaded docs, queries made) | | inject_to_rag(content, metadata) | Injects document into RAG (requires approval) |

The MCP Server is started automatically by Claude Code via .claude/settings.json. It reads credentials from .env and configuration from prism.config.json in the current directory.

Command Reference

# Create project
prism init <name>                # interactive
prism init <name> --no-interactive  # default values (for CI/tests)

# Validate and prepare session
prism start

# Add resources
prism add service <name>         # register microservice/repo
prism add agent <name>           # extra specialized agent
prism add pipeline <name>        # custom pipeline
prism add skill <name>           # domain skill

# Help
prism --help
prism <command> --help

Development

Build

npm run build     # compile with tsup
npm run dev       # watch mode

Tests

npm test          # run all tests with vitest

Source Code Structure

src/
  cli/
    commands/
      init.ts              # prism init
      start.ts             # prism start
      add/
        service.ts         # prism add service
        agent.ts           # prism add agent
        pipeline.ts        # prism add pipeline
        skill.ts           # prism add skill
    index.ts               # CLI entry point
  mcp/
    server.ts              # MCP Server (stdio)
    session.ts             # session management
    tools/
      load-context.ts      # tool: load_context
      query-rag.ts         # tool: query_rag
      get-session.ts       # tool: get_session_state
      inject-rag.ts        # tool: inject_to_rag
  openrag/
    client.ts              # HTTP client for OpenRAG
    filters.ts             # knowledge filter creation
    flows.ts               # Langflow flow creation
  templates/
    agents/
      orchestration/       # 9 orchestration agents
      specialized/         # 7 specialized agents + template
      index.ts
    rules/
      index.ts             # 4 base rules
    config.ts              # prism.config.json generator
    claude-md.ts           # CLAUDE.md generator
    settings-json.ts       # .claude/settings.json generator
    gitignore.ts           # .gitignore content
  utils/
    fs.ts                  # config and .env reading
    git.ts                 # git operations
    validation.ts          # input validations

Troubleshooting

"prism.config.json not found"

You are outside the project directory. Run cd my-project first.

"Missing variables in .env"

Edit .env and fill in OPENRAG_URL, OPENRAG_API_KEY, OPENRAG_EMBEDDING_MODEL and OPENRAG_INDEX.

"OpenRAG is not responding"

Check that OpenRAG is running at http://localhost:3000 (or at the URL configured in .env).

MCP Server not connecting

Check that the path in .claude/settings.json points to the correct server.js. If you installed with nvm or fnm, you may need to adjust the path manually.

Agents not working in Claude Code

Make sure you filled in the [FILL IN] sections in the specialized agents. Agents with empty fields may not work correctly.

License

MIT