Paradigm

Structure for AI-Native Development

Paradigm is a developer tools ecosystem that brings structured context, authorization topology, and on-demand intelligence to modern software projects — designed for both human developers and AI agents.

The Problem

Modern development has a context problem:

Context evaporates — What does this feature do? What auth does it need? AI doesn't know. New team members don't know. Sometimes YOU don't know.
Authorization is a black box — Who can access what? It's buried in middleware, scattered across files, impossible to visualize.
AI agents work blind — Your AI assistant reads thousands of tokens but misses the forest for the trees.

The Solution

Three pillars, one ecosystem:

Pillar	What It Does
Purpose	Define what things are and why they exist (`.purpose` files)
Portal	Define who can access what, under what conditions (`portal.yaml`)
Premise	Aggregate everything into a queryable knowledge graph

Plus tooling that makes it all work:

Tool	What It Does
MCP Server	50+ tools for AI agents to query context on-demand (~100 tokens vs ~2000 per query)
Sentinel	Incident tracking, failure patterns, symbol-correlated observability
University	Interactive courses and PLSAT certification exam
Multi-Agent Orchestration	Coordinate architect, builder, reviewer, tester, and security agents

Measured Results

We built the same project management API twice — once with traditional docs, once with Paradigm. Same features, same AI agent, same prompts.

Metric	Traditional	Paradigm	Difference
Time to complete	~12 minutes	~7 minutes	42% faster
Context per task	~14,000 tokens	~1,500 tokens	8.5x less
Token cost	$0.50/task	$0.06/task	88% cheaper
Auth gates documented	0%	100%	—

Why? Structured context beats raw context. A 50-line .purpose file declaring signals and dependencies beats a 500-line source file that buries them in implementation details.

Full study →

Symbol System

Five symbols create a shared language between code, developers, and AI:

Symbol	Name	Example	Meaning
`#`	Component	`#checkout`, `#Button`	Any documented code unit
`$`	Flow	`$checkout-flow`	Multi-step process
`^`	Gate	`^authenticated`	Authorization checkpoint
`!`	Signal	`!login-failed`	Event or side effect
`~`	Aspect	`~audit-required`	Cross-cutting rule with code anchor

Classification uses tags instead of extra prefixes: [feature], [integration], [state], [idea], etc.

These symbols work everywhere — code comments, commit messages, documentation, AI prompts, and visual tools.

Installation

Quick Install (Recommended)

curl -fsSL https://a-company.org/paradigm/install.sh | bash

This clones to ~/.paradigm-cli/, builds, and installs the paradigm and paradigm-mcp CLIs globally. Re-running the same command updates to the latest version.

Or download and inspect first:

curl -fsSL https://a-company.org/paradigm/install.sh -o install.sh
chmod +x install.sh
./install.sh

Note: The source directory at ~/.paradigm-cli/ must be kept — the global CLIs symlink to it. To uninstall: npm uninstall -g @a-company/paradigm @a-company/paradigm-mcp && rm -rf ~/.paradigm-cli

Manual Install

# 1. Clone and build (keep this directory — CLIs symlink to it)
git clone https://github.com/ascend42/a-paradigm.git ~/.paradigm-cli
cd ~/.paradigm-cli
npm install && npm run build

# 2. Install CLI globally
cd packages/paradigm && npm install -g . && cd ../..

# 3. Install MCP server globally
cd packages/paradigm-mcp && npm install -g . && cd ../..

# 4. Verify
paradigm --version

Note: Paradigm is not yet published to npm. Install from source using the methods above. npm registry publishing is planned.

Quick Start

One Command Setup

paradigm init --quick && paradigm sync --all && paradigm mcp setup --client all && paradigm constellation && paradigm beacon && paradigm doctor

This initializes config, generates IDE files, configures MCP, builds the symbol graph, creates AI orientation, and verifies everything.

Step-by-Step

# 1. Initialize configuration
paradigm init --quick

# 2. Generate IDE instruction files
paradigm sync --all

# 3. Configure MCP for AI tools
paradigm mcp setup --client all

# 4. Generate symbol graph and orientation
paradigm constellation
paradigm beacon

# 5. Verify setup
paradigm doctor

Minimal Start

You don't need everything. Start small:

paradigm init
# Edit src/features/.purpose (or wherever your features live)
paradigm beacon

Your AI assistant reads beacon.md for instant context. Add portal.yaml, MCP, and more as needed.

What Gets Created

your-project/
├── .paradigm/              # Configuration & specs
│   ├── config.yaml         # Main configuration
│   ├── specs/              # Logger, symbols, context specs
│   ├── docs/               # Patterns, troubleshooting
│   ├── wisdom/             # Team antipatterns & decisions
│   ├── history/            # Implementation history
│   ├── tasks/              # Persistent work items (runtime)
│   ├── assessments/        # Assessment arcs & reflections (runtime)
│   └── tags.yaml           # Project tag bank
├── .purpose                # Feature & component context
├── portal.yaml             # Authorization topology
├── beacon.md               # AI quick-start orientation
├── CLAUDE.md               # Claude Code instructions
├── AGENTS.md               # Universal agent instructions
└── .cursor/rules/          # Cursor IDE instructions

Key Commands

Setup & Validation

paradigm init              # Initialize Paradigm (smart detection)
paradigm init --migrate    # Output migration prompt for existing rules
paradigm sync --all        # Sync all IDEs (Cursor, Claude, Copilot, Windsurf)
paradigm doctor            # Health check and validation
paradigm lint              # Validate .purpose files for schema errors
paradigm scan auto         # Auto-generate .purpose from code analysis
paradigm shift             # Propagate updates across all your projects

AI Context

paradigm beacon            # Quick-start orientation for AI
paradigm constellation     # Generate symbol relationship graph
paradigm ripple #checkout  # Impact analysis before changes
paradigm cost              # Token cost analysis (static vs MCP)

Session & History

paradigm thread            # Session continuity — save/load context
paradigm echo AUTH_001     # Map error codes to symbols
paradigm watch             # Watch for changes, update indexes
paradigm history           # View implementation history
paradigm wisdom            # View team antipatterns & decisions

Multi-Agent Orchestration

paradigm team orchestrate "Add user authentication"
paradigm team spawn builder --task "Implement login endpoint"
paradigm team handoff --to reviewer
paradigm team agents suggest "Add payment processing"
paradigm team models       # View/configure agent model assignments

Default agents: architect → builder → reviewer → tester + security

MCP Server (AI Integration)

For dynamic, mid-conversation context, Paradigm provides an MCP server with 50+ tools that works with Claude Code, Claude Desktop, Cursor, and other MCP-compatible clients.

Why MCP?

Approach	Tokens per Query	Total for 10 Tasks
Read source files	~2,000	~20,000
MCP tool call	~100-300	~1,000-3,000

Key Tools

Tool	What It Does
`paradigm_status`	Project overview (~100 tokens)
`paradigm_search`	Find symbols by name or tag
`paradigm_navigate`	Locate code by symbol, area, or task
`paradigm_ripple`	Impact analysis — what breaks if you change this?
`paradigm_gates_for_route`	Suggest auth gates for an endpoint
`paradigm_wisdom_context`	Get team knowledge before implementing
`paradigm_flows_affected`	Check which flows a change impacts
`paradigm_orchestrate_inline`	Plan multi-agent task execution
`paradigm_sentinel_triage`	View and filter incidents
`paradigm_task_create`	Create persistent work items that survive context windows
`paradigm_assessment_record`	Add reflections to assessment arcs
`paradigm_pm_preflight`	Pre-implementation compliance check

Setup

paradigm mcp setup --client all

Or manually configure your AI client:

{
  "mcpServers": {
    "paradigm": {
      "command": "paradigm-mcp",
      "args": ["."],
      "cwd": "/path/to/your/project"
    }
  }
}

Sentinel (Observability)

Symbol-correlated incident tracking and failure pattern matching.

paradigm sentinel          # Launch the dashboard

Record incidents with symbolic context (#checkout failed at ^authenticated)
Define failure patterns and auto-match against new incidents
Triage and prioritize by symbol, severity, environment
Track health with per-symbol stability scores and MTTR
AI-suggested patterns from incident clusters

Built with Express + React, SQLite storage via sql.js (no external DB required).

University (Learning Platform)

Interactive courses and certification for learning Paradigm.

paradigm university        # Launch the learning platform

Courses

Course	Title	Topics
PARA 101	Foundations	The 5 symbols, `.purpose` files, tags, logger
PARA 201	Architecture	Flows, gates, aspects, `portal.yaml`, disciplines
PARA 301	Operations	History, wisdom, ripple, doctor, sync, sentinel
PARA 401	Orchestration	Multi-agent coordination, MCP tools, context handoffs

PLSAT Certification

The Paradigm Licensure Standardized Assessment Test — 50 questions, 45 minutes, 80% to pass. Covers symbol identification, flow design, gate configuration, and real-world scenarios. Generates a printable certificate.

Runs locally with no auth or external dependencies.

IDE Support

Generate instructions for every major AI-native editor from a single config:

IDE	Format	Command
Cursor	`.cursor/rules/*.mdc`	`paradigm sync cursor`
Claude Code	`CLAUDE.md`	`paradigm sync claude`
GitHub Copilot	`.github/instructions/*.md`	`paradigm sync copilot`
Windsurf	`.windsurfrules`	`paradigm sync windsurf`
Universal	`AGENTS.md`	`paradigm sync agents`
VS Code	Extension (`.vsix`)	`paradigm-vscode`

All generated from .paradigm/config.yaml — one source of truth.

Enforcement Hooks

Rules files (.mdc, CLAUDE.md) are advisory — agents can ignore them. Paradigm also provides deterministic enforcement hooks that execute as shell scripts at guaranteed lifecycle points:

Hook	Claude Code	Cursor	Behavior
Session start	—	`sessionStart`	Injects mandatory protocol as `additional_context`
Stop	`Stop`	`stop`	Blocks if .purpose files not updated, missing portal.yaml, no lore entry
After file edit	`PostToolUse`	`afterFileEdit`	Advisory reminder about .purpose coverage
Before commit	`PreToolUse`	`beforeShellExecution`	Auto-rebuilds symbol index

Cursor's stop hook outputs a followup_message that auto-retries compliance (up to 3 loops).

Install hooks per-project:

paradigm shift                        # Full setup (includes hooks)
paradigm hooks install                # All hooks (git + Claude Code + Cursor)
paradigm hooks install --cursor       # Cursor hooks only
paradigm hooks install --claude-code  # Claude Code hooks only

Plugins

Paradigm ships plugins for both Claude Code and Cursor that bundle hooks, skills, and MCP configuration:

Plugin	Location	Format	Distribution
Claude Code	`plugins/paradigm/`	`.claude-plugin/`	`/plugin marketplace add ascend42/a-paradigm`
Cursor	`plugins/paradigm-cursor/`	`.cursor-plugin/`	Manual install (Cursor plugin marketplace TBD)

Plugin vs per-project setup:

Plugins provide hooks + skills + MCP globally — install once, works in every project
paradigm shift creates per-project files (.paradigm/, .purpose, .cursor/rules/, portal.yaml) committed to git
Most teams use both: plugin for enforcement, paradigm shift for project-specific context

Packages

Package	Version	Description
`@a-company/paradigm`	3.3.0	Unified CLI
`@a-company/paradigm-mcp`	3.3.0	MCP server for AI integrations
`@a-company/purpose-core`	0.1.0	`.purpose` file parsing and validation
`@a-company/portal-core`	0.1.0	`portal.yaml` parsing and validation
`@a-company/portal-sdk`	0.1.0	Runtime authorization SDK
`@a-company/portal-manager`	0.1.0	Portal testing and validation
`@a-company/portal-viewer`	0.1.0	Gate activation visualization
`@a-company/portal-e2e`	1.0.0	AI-driven E2E testing for portals
`@a-company/premise-core`	0.2.0	Symbol aggregation and knowledge graph
`@a-company/probe-core`	0.2.0	Visual discovery layer
`@a-company/sentinel`	0.1.1	Incident tracking and observability
`@a-company/university`	0.1.0	Learning platform and PLSAT certification
`@a-company/paradigm-logger`	1.0.0	Symbol-typed structured logging
`paradigm-vscode`	1.0.1	VS Code extension

Documentation

Complete Documentation Hub →

Quick Start Guide — Step-by-step setup walkthrough
Command Reference — Detailed guides for all commands
MCP Setup — AI client integration guide
Changelog

Individual command guides:

paradigm init — Initialize your project
paradigm sync — Update IDE files
paradigm ripple — Analyze change impact
paradigm beacon — Generate AI context

Development

git clone https://github.com/ascend42/a-paradigm.git
cd a-paradigm
npm install && npm run build

# Install CLI globally for testing
cd packages/paradigm && npm install -g .

Philosophy

Context should be structured — Not buried in comments or tribal knowledge
Authorization deserves visualization — Topology over scattered middleware
AI needs on-demand context — Queries beat static files, 8.5x cheaper
One source of truth — Generate IDE-specific files from shared config
Compliance through automation — Hooks enforce conventions, not willpower

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT

Author

Built for developers who want their AI to actually understand their project.

Name		Name	Last commit message	Last commit date
Latest commit History 263 Commits
.changeset		.changeset
.claude-plugin		.claude-plugin
.cursor		.cursor
.github		.github
.paradigm		.paradigm
assets		assets
case-study		case-study
docs		docs
packages		packages
plugins		plugins
prompts		prompts
scripts		scripts
.gitignore		.gitignore
.nvmrc		.nvmrc
.premise		.premise
.prettierignore		.prettierignore
.prettierrc		.prettierrc
.purpose		.purpose
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE-ASSESSMENT.md		CLAUDE-ASSESSMENT.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
DISTRIBUTION.md		DISTRIBUTION.md
GATES-REFRAME.md		GATES-REFRAME.md
LICENSE		LICENSE
README.md		README.md
install.sh		install.sh
models.json		models.json
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
portal.yaml		portal.yaml
tsconfig.base.json		tsconfig.base.json

License

ascend42/a-paradigm

Folders and files

Latest commit

History

Repository files navigation

Paradigm

The Problem

The Solution

Measured Results

Symbol System

Installation

Quick Install (Recommended)

Manual Install

Quick Start

One Command Setup

Step-by-Step

Minimal Start

What Gets Created

Key Commands

Setup & Validation

AI Context

Session & History

Multi-Agent Orchestration

MCP Server (AI Integration)

Why MCP?

Key Tools

Setup

Sentinel (Observability)

University (Learning Platform)

Courses

PLSAT Certification

IDE Support

Enforcement Hooks

Plugins

Packages

Documentation

Development

Philosophy

Contributing

License

Author

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

Packages