How pantheralabs/intentcompiler works
1. What this repository is
- Intent Compiler is a fullstack Next.js application that turns a user’s high-level goal into structured AI workflows and instruction files.
- The core architectural idea is a pipeline: capture intent → enrich context → select models → compile steps/instructions → validate → execute/export.
2. Primary user entrypoints
- app/page.tsx is the main intake experience for entering an intent and refining it.
- app/workflow/page.tsx is the interactive execution surface for step-by-step workflow run and review.
- These pages are supported by reusable UI components in components/, especially ContextForm, WorkflowContainer, ExecutionPanel, InputForm, and RepoInput.
3. Frontend composition
- The UI is a stateful React client built around intent collection, suggestions, workflow visualization, and execution controls.
- FileTree, HistoryPanel, StepCard, ModelRecommendationBadge, and IntelligentQuestionsModal represent distinct interaction zones rather than a single monolithic screen.
- VibeLibrary and WelcomeIntro add template onboarding and preset browsing for faster workflow creation.
4. API boundary
- The server side is exposed through App Router route handlers under app/api/*.
- Each route isolates a capability: analysis, compilation, generation, execution, validation, suggestions, model selection, and model recommendation.
- This gives the frontend a set of focused service endpoints instead of a single generic backend.
5. Intent analysis and context gathering
- app/api/analysis and lib/projectAnalyzer.ts / lib/repoAnalyzer.ts detect project characteristics, repo structure, and tech stack.
- RepoInput in the UI likely feeds this path so the system can bootstrap context from an existing repository.
- lib/intelligentQuestioner.ts and app/api/suggestions provide targeted clarification when user intent is vague.
6. Compilation pipeline
- The compilation layer is centered in lib/contextCompiler.ts, lib/instructionGenerator.ts, lib/instructionAssembler.ts, and lib/compile* API routes.
- Its job is to transform refined intent into structured plans, step instructions, and instruction-file outputs.
- The README’s export targets such as CLAUDE.md, AGENTS.md, .cursorrules, and .windsurfrules are produced through this path.
7. Model orchestration and provider abstraction
- lib/aicc.ts, lib/modelRouter.ts, lib/superIntelligentModel.ts, and lib/tierConfig.ts implement the model-selection layer.
- The system supports multiple providers and runtimes: OpenAI, OpenRouter, Groq, and local Ollama.
- Architecturally, this layer sits between product logic and the LLM providers, so task-specific model choice is decoupled from UI and workflow logic.
8. Multi-agent and role system
- lib/agentOrchestrator.ts, lib/dynamicRoles.ts, lib/roleMatcher.ts, lib/roleDatabase.ts, and lib/skillsRegistry.ts define a specialized agent-coordination subsystem.
- This is used for more complex generation tasks where the system dispatches work to role-specific agents rather than one general model call.
- The presence of multi-agent-generator.js and test files suggests this path is important for advanced generation scenarios.
9. Execution and validation loop
- lib/executionEngine.ts, lib/validationCheckpoint.ts, lib/stepQuality.ts, and app/api/execution form the runtime workflow engine.
- The architecture supports executing steps individually, validating results, and recovering or rolling back when quality checks fail.
- This is the “reactive workflow” part of the product: generation is not the end state; generated steps can be run and refined.
10. Quality gates and scoring
- lib/instructionQuality.ts, lib/stepQuality.ts, and app/api/validation provide scoring and validation boundaries.
- The README describes six evaluation dimensions: correctness, specificity, executability, safety, compatibility, and brevity.
- In the architecture, this acts as a control layer between generation and execution to keep outputs usable.
11. Persistence, storage, and logs
- lib/db.ts with SQLite/better-sqlite3 stores local application state, history, or configuration.
- lib/vibeStorage.ts and lib/core/vibeStorage.ts indicate persistence for template or “vibe” assets.
- logs/ and output/ are operational artifacts: logs capture runs and tests, while output/ stores generated project bundles and prompt files.
12. Export and artifact generation
- lib/fileExporter.ts handles packaging outputs such as ZIPs and PDFs, which matches the README’s export-oriented workflow.
- The checked-in output/ folder shows the system already materializes full generation runs into structured folders with quickstarts, prompts, and role instructions.
- This makes the repo both an app and an artifact factory.
13. Shared schemas and safety
- lib/schemas.ts, lib/actionSchemas.ts, lib/jsonGuard.ts, and lib/core/jsonGuard.ts provide input/output shaping and JSON resilience.
- lib/logger.ts and lib/integrationLogger.ts handle observability around model calls and orchestration.
- These are important architectural boundaries because almost every API path relies on validated structured data.
14. Overall system shape
- The repository is organized as a pipeline-driven orchestration platform built on Next.js, not just a UI dashboard.
- Frontend components collect intent and visualize progress; route handlers expose capabilities; lib/ contains the real domain engine for analysis, compilation, model routing, execution, and validation.
- For an architecture diagram, the main nodes are: intent intake UI, analysis/suggestion APIs, compilation/orchestration engine, model provider layer, validation/execution engine, local persistence, and generated output artifacts.
Main entry points: page.tsx Intake page · instructionGenerator.ts Instruction pipeline · executionEngine.ts Execution engine · instructionQuality.ts Quality gate
Components 25
User experience
Intent intake, workflow review, and reusable interface components.
- Intake page · Main intent capture and refinement entrypoint.
app/page.tsx - Workflow page · Interactive workflow execution and review surface.
app/workflow/page.tsx - Context form · Collects intent, repo context, and refinement inputs.
components/ContextForm.tsx - Workflow shell · Coordinates workflow state and screen composition.
components/WorkflowContainer.tsx - Execution panel · Displays step execution controls and results.
components/ExecutionPanel.tsx - Repo input · Entry point for analyzing an existing repository.
components/RepoInput.tsx - Clarification modal · Prompts targeted questions when intent is underspecified.
components/IntelligentQuestionsModal.tsx - Vibe library · Preset and template browser for faster starting points.
components/VibeLibrary.tsx
Service API
App Router endpoints that expose analysis, generation, compilation, validation, and execution capabilities.
- Analysis API · Repo scanning and intent-context analysis endpoints.
app/api/analysis/route.ts - Generation API · Intent refinement and generation orchestration endpoints.
app/api/generation/route.ts - Compilation API · Builds context, compiles behavior, and assembles instructions.
app/api/compilation/route.ts - Execution API · Runs workflow steps and feeds execution state back to the UI.
app/api/execution/route.ts - Validation API · Checks quality and acceptance of generated or executed output.
app/api/validation/route.ts - Model APIs · Model selection, model listing, and recommendation endpoints.
app/api/model-selection/route.ts
Core engine
Library modules that analyze repos, compile workflows, route models, and run validation/execution.
- Project analysis · Detects project structure, tech stack, and repository characteristics.
lib/projectAnalyzer.ts - Context compiler · Transforms analysis and intent into structured workflow context.
lib/contextCompiler.ts - Instruction pipeline · Generates, assembles, and quality-checks workflow instructions.
lib/instructionGenerator.ts - Model router · Selects providers and tiers across OpenAI, OpenRouter, Groq, and Ollama.
lib/modelRouter.ts - Agent orchestrator · Coordinates role-based agents for advanced generation tasks.
lib/agentOrchestrator.ts - Execution engine · Executes steps, manages checkpoints, and supports recovery.
lib/executionEngine.ts - Quality gate · Scores instructions and step outputs before they progress.
lib/instructionQuality.ts
Persistence and outputs
Local storage, logs, and generated artifacts produced by runs.
- Local DB · Stores application state, history, or configuration locally.
lib/db.ts - Vibe storage · Persists templates and vibe assets.
lib/vibeStorage.ts - File exporter · Packages generated outputs into downloadable artifacts.
lib/fileExporter.ts - Generated output · Materialized workflow bundles, prompts, quickstarts, and instructions.
output/2026-03-31_15-13-42_build_a_recipe_app_for_cooking
Connections 26
- Intake page → Context form: collect intent · The intake page is built around the main context form.
- Intake page → Repo input: bootstrap repo · Users can provide a repository to analyze from the intake screen.
- Intake page → Clarification modal: clarify gaps · The UI can ask targeted follow-up questions when intent is vague.
- Intake page → Vibe library: browse presets · Templates and presets help seed a new workflow.
- Workflow page → Workflow shell: host workflow · The workflow page mounts the main orchestration shell.
- Workflow shell → Execution panel: show steps · The container renders step execution and review controls.
- Analysis API → Project analysis: scan repo · API analysis routes rely on repository inspection logic.
- Analysis API → Context compiler: seed context · Analysis results feed the context-building pipeline.
- Generation API → Agent orchestrator: dispatch roles · Generation can fan out to role-specific agents.
- Generation API → Model router: choose model · Generation requests are routed to an appropriate model/provider.
- Compilation API → Context compiler: build context · Compilation routes assemble structured workflow context.
- Compilation API → Instruction pipeline: compile instructions · Compilation routes generate and assemble instruction files.
- Execution API → Execution engine: run workflow · Execution endpoints drive the runtime workflow engine.
- Validation API → Quality gate: score output · Validation endpoints apply quality checks and scoring.
- Model APIs → Model router: select provider · Model endpoints expose routing and recommendation decisions.
- Project analysis → Model router: use model · Analysis and enrichment can depend on model-backed reasoning.
- Context compiler → Instruction pipeline: feed plan · Compiled context becomes the input for instruction generation.
- Instruction pipeline → Quality gate: verify quality · Generated instructions are checked before use.
- Quality gate → Execution engine: approve run · Validated work can move into execution.
- Agent orchestrator → Model router: call models · Agents use the shared provider abstraction.
- Execution engine → Quality gate: checkpoint · Executed steps are validated at checkpoints.
- Local DB → Analysis API: persist state · Local state supports analysis and workflow continuity.
- Vibe storage → Vibe library: load presets · Template assets back the preset browser.
- File exporter → Generated output: write artifacts · Exports materialize into the checked-in output structure.
- Instruction pipeline → File exporter: export files · Compiled instructions can be packaged for download or export.
- Execution engine → Generated output: emit run output · Workflow runs produce concrete artifact folders.