@prodara/compiler

The core compilation engine, workflow orchestrator, and programmatic API for the Prodara product engineering platform.

Installation

npm install @prodara/compiler

Tip: prodara init installs this package automatically. No separate install step needed.

Overview

The compiler takes .prd specification files through a 13-phase pipeline:

1. Discovery → Lexing → Parsing → Binding → Type Checking → Semantic Validation
2. Graph Building → Graph Validation → Constitution Resolution
3. Diffing → Impact Propagation → Planning
4. Incremental Spec → Workflow Engine → Review/Fix Loop → Verification

How It Fits Together

The primary way to use Prodara is through the /prodara command in your AI agent. prodara init generates a single prompt file that orchestrates the full lifecycle — the AI agent generates .prd specs from your description, the compiler validates and builds them, and the agent implements the resulting plan.

The compiler powers the core CLI commands the agent calls:

• prodara validate — parse and type-check .prd files
• prodara build — full pipeline: compile → workflow → review → verify
• prodara test — run spec-level tests

Implementation Phase

The build pipeline includes an AI-driven implementation phase:

• Extracts implementation instructions from the workflow engine
• Dispatches each task to an AI agent with structured prompts containing task ID, action, node context, related edges, and product graph data
• Supports two modes:
  • Prompt files (default) — Generates .md prompt files for IDE-based agents (Copilot, Claude, Cursor, etc.)
  • Headless (--headless) — Sends prompts directly via API to OpenAI, Anthropic, or other providers
• In headless mode, extracts code blocks from AI responses and writes output files to disk
• Supports a validate-after-implement retry loop (configurable via agent.maxImplementRetries)

Use --no-implement to skip the implementation phase. Use --dry-run to preview tasks without executing.

Programmatic API

import { compile, buildGraph, serializeGraph, formatDiagnosticsJson } from '@prodara/compiler';

const result = compile('./my-project');

if (result.diagnostics.hasErrors) {
  console.error(formatDiagnosticsJson(result.diagnostics));
} else {
  console.log(serializeGraph(result.graph!));
}

See the root README for the full API reference.

Customization

Custom Reviewers

Drop .md files in .prodara/reviewers/ to create custom reviewer agents. The filename becomes the reviewer name (e.g., performance.md → performance reviewer).

import { discoverCustomReviewers, loadReviewerPrompt } from '@prodara/compiler';

const customs = await discoverCustomReviewers('/path/to/project');
const prompt = await loadReviewerPrompt(
  { promptPath: '.prodara/reviewers/performance.md' },
  '/path/to/project',
);

Constitution

A project-level constitution provides global instructions injected into all AI prompts:

{
  "constitution": {
    "path": ".prodara/constitution.md"
  }
}

Template Overrides

Override any built-in template with a local .md file:

{
  "templateOverrides": {
    "phase:implement": ".prodara/templates/implement.md"
  }
}

Pre-Review Loop

Run reviewers before implementation to catch spec-level issues early:

{
  "preReview": {
    "enabled": true,
    "maxIterations": 2,
    "fixSeverity": ["critical", "error"]
  }
}

AI Agent Integration

prodara init --ai <agent> generates a single prompt file for 26 supported AI agents. The prompt drives the full 8-phase lifecycle:

1. Clarify → 2. Specify → 3. Validate → 4. Build → 5. Govern → 6. Implement → 7. Review → 8. Deliver

Each agent gets one file adapted to the platform's format (.prompt.md for Copilot, .md for Claude, .mdc for Cursor, etc.).

CLI

When installed as a project dependency, provides a local prodara binary:

npx prodara init                       # Scaffold project (auto-installs compiler)
npx prodara init --ai copilot          # Generate prompt file for an AI agent
npx prodara upgrade                    # Update project to latest version
npx prodara build                      # Full pipeline including AI implementation
npx prodara build --headless           # Use API driver instead of prompt files
npx prodara build --dry-run            # Preview tasks without executing
npx prodara validate --format json     # Parse and type-check .prd files
npx prodara test                       # Run spec-level tests

Testing

npm test              # 1,500+ tests
npm run test:coverage # Enforces 100% coverage
npm run typecheck     # Zero errors

License

Apache 2.0