@wizdear/atlas-code

AI-powered multi-agent engineering system for pi-coding-agent. Automates feature development from requirements to implementation through role-based agent orchestration.

Overview

Given a natural-language requirement, vibe decomposes it into features, assigns specialized agents, and executes an end-to-end pipeline: Discovery → Planning → Design → Implementation → Testing → Review → Documentation.

Prerequisites

• Node.js >= 20.0.0 (download)
• An LLM provider account — OAuth subscription (Claude Pro/Max, ChatGPT Plus, etc.) or an API key (Anthropic, OpenAI, Google, etc.)

Installation

Option A: As a pi Extension (interactive TUI)

One command installs everything — pi-coding-agent, atlas-code, and configures the extension:

npx @wizdear/atlas-code setup

For Windows, you can run a bootstrap script that installs Node.js LTS automatically (if missing), then runs setup:

if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
  winget install OpenJS.NodeJS.LTS --accept-package-agreements --accept-source-agreements
}
npx @wizdear/atlas-code setup

Then navigate to your project and start pi:

cd /path/to/your/project
acode

Authentication & Model Selection

After launching pi, authenticate with your LLM provider:

• OAuth subscription (Claude Pro/Max, ChatGPT Plus, etc.): type /login and select a provider
• API key: set an environment variable before launching

  export ANTHROPIC_API_KEY="sk-ant-..."

Once authenticated, type /model (or press Ctrl+L) to select a model.

Option B: As a Standalone SDK (programmatic, CI/CD)

1. Create a Node.js project (or use an existing one):

   mkdir my-project && cd my-project
   npm init -y

2. Install vibe:

   npm install @wizdear/atlas-code

3. Set your LLM API key:

   export ANTHROPIC_API_KEY="sk-ant-..."

4. Create a script (e.g. vibe-fix.mjs):

   import { createVibeSession } from "@wizdear/atlas-code";
   
   const vibe = await createVibeSession({
     projectRoot: process.cwd(),
     model: { provider: "anthropic", id: "claude-sonnet-4-20250514" },
     apiKey: process.env.ANTHROPIC_API_KEY,
   });
   
   const result = await vibe.fixAndWait("TypeError at src/user-service.ts:42");
   console.log(result.status); // "done" | "failed" | "blocked"

5. Run:

   node vibe-fix.mjs

Workflow Types

| Type | Use Case | Pipeline | |------|----------|----------| | new_feature | New functionality | Discovery → Plan → Design → Implement → Test → Regression → Review → Document | | enhancement | Improve existing code | Discovery → Analyze → Plan → Analyze → Design → Implement → Test → Regression → Review | | bugfix | Fix a bug | Discovery → Investigate → Diagnose → Implement → Test → Regression → Review | | refactor | Restructure code | Discovery → Analyze → Plan → Analyze → Design → Implement → Regression → Review | | (default) | No subcommand — system infers type per feature | Analyzes requirements and assigns new_feature, enhancement, bugfix, or refactor per feature |

Agent Roles

| Agent | Role | |-------|------| | Discovery | Refines requirements through conversational Q&A | | Project Analyzer | Scans project structure, tech stack, conventions | | Planner | Decomposes requirements into features with dependencies | | Analyzer | Assesses impact on existing codebase | | Architect | Designs interfaces and component structure | | Developer | Implements code changes | | Tester | Writes and runs tests | | Diagnostician | Investigates and diagnoses bugs | | Reviewer | Reviews code quality and architecture compliance | | Documenter | Updates project docs and README | | Standards Enricher | Injects project-specific standards from context |

pi Extension Usage

# Auto-detect workflow type (no subcommand needed)
/vibe "Add user authentication with OAuth2"

# Explicit workflow types
/vibe new "Build a REST API for user management"
/vibe enhance "Add rate limiting to API endpoints"
/vibe fix "Login returns 500 when token expires" --issue 127
/vibe refactor "Split auth module into separate services"

# Project setup
/vibe init          # Initialize .vibe/ directory
/vibe analyze       # Generate project-context.md
/vibe config        # Interactive settings editor

# Pipeline control
/vibe status                 # Show active pipelines
/vibe status feat-001        # Show feature detail
/vibe pause feat-001         # Pause after current step
/vibe resume                 # Resume from saved state
/vibe resume feat-001        # Resume specific feature
/vibe steer feat-001 "Use PostgreSQL instead of MySQL"

SDK Usage

The SDK provides programmatic access to vibe pipelines without the pi TUI. Useful for CI/CD integration, scripting, and automated workflows.

Basic Example

import { createVibeSession } from "@wizdear/atlas-code";

const vibe = await createVibeSession({
  projectRoot: "/path/to/project",
  model: { provider: "anthropic", id: "claude-sonnet-4-20250514" },
  apiKey: process.env.ANTHROPIC_API_KEY!,
});

// Stream events
for await (const event of vibe.newFeature("Add user authentication")) {
  console.log(`[${event.type}] ${event.featureId}`);
}

// Or wait for completion
const result = await vibe.newFeatureAndWait("Add user authentication");
console.log(result.status); // "done" | "failed" | "blocked"

Bug Fix

const result = await vibe.fixAndWait("TypeError at src/user-service.ts:42", {
  issueRef: "#127",
});

Gate Policies

Control how quality gates (test, review, regression) are handled:

// Auto-approve all gates (default)
const vibe = await createVibeSession({
  projectRoot: "/path/to/project",
  model: { provider: "anthropic", id: "claude-sonnet-4-20250514" },
  apiKey: process.env.ANTHROPIC_API_KEY!,
  gatePolicy: "auto_approve",
});

// Auto-reject all gates
const vibe2 = await createVibeSession({
  // ...
  gatePolicy: "auto_reject",
});

// Custom gate handler
const vibe3 = await createVibeSession({
  // ...
  gatePolicy: async (summary) => {
    console.log("Gate:", summary);
    return { passed: true, action: "approved" };
  },
});

CI/CD Self-Healing

Use the SDK in CI/CD pipelines to automatically fix failing tests:

import { createVibeSession } from "@wizdear/atlas-code";

// In your CI/CD pipeline after test failure:
const vibe = await createVibeSession({
  projectRoot: process.cwd(),
  model: { provider: "anthropic", id: "claude-sonnet-4-20250514" },
  apiKey: process.env.ANTHROPIC_API_KEY!,
  gatePolicy: "auto_approve",
});

const result = await vibe.fixAndWait(
  `Test failure in user-service.test.ts: Expected 200 but got 500. 
   Stack trace: TypeError: Cannot read property 'id' of undefined at UserService.getUser`
);

if (result.status === "done") {
  console.log("Fix applied successfully");
  // Run tests again, commit if green
}

SDK API Reference

createVibeSession(options): Promise<VibeSession>

| Option | Type | Description | |--------|------|-------------| | projectRoot | string | Absolute path to the project root | | model | SdkModelSpec | Provider and model ID (e.g. { provider: "anthropic", id: "claude-sonnet-4-20250514" }) | | apiKey | string | LLM API key | | gatePolicy | GatePolicy | "auto_approve" (default), "auto_reject", or custom callback | | logger | VibeLogger | Custom logger (noop by default) |

VibeSession Methods

| Method | Description | |--------|-------------| | newFeature(requirement) | Run new_feature pipeline, yields VibeEvent | | enhance(requirement, options?) | Run enhancement pipeline | | fix(description, options?) | Run bugfix pipeline | | refactor(purpose, options?) | Run refactor pipeline | | newFeatureAndWait(requirement) | Run and wait for VibeSessionResult | | enhanceAndWait(requirement, options?) | Run and wait | | fixAndWait(description, options?) | Run and wait | | refactorAndWait(purpose, options?) | Run and wait |

VibeSessionResult

interface VibeSessionResult {
  status: "done" | "failed" | "blocked";
  completed: string[];   // completed feature IDs
  failed: string[];      // failed feature IDs
  skipped: string[];     // skipped feature IDs
  events: VibeEvent[];   // all events from the run
}

Autonomy Levels

| Level | Behavior | |-------|----------| | full_auto | Runs to completion, no user intervention | | gate_auto | Pauses at quality gates for approval (recommended) | | step_by_step | Pauses at every step for approval |

Project Structure

After /vibe init, the following structure is created:

.vibe/
├── config.json              # Project configuration
├── project-context.md       # Auto-generated project analysis
├── requirements.md          # Refined requirements from Discovery
├── plan.json                # Feature decomposition plan
├── orchestration-state.json # Resume state (auto-managed)
├── standards/               # 14 standard template files
│   ├── coding-style.md
│   ├── coding-conventions.md
│   ├── tech-stack.md
│   ├── architecture-principles.md
│   ├── testing-standards.md
│   └── ...
├── skills/                  # Agent skills (e.g. QMD memory)
│   └── qmd-memory/
│       └── SKILL.md
├── features/                # Per-feature artifacts
│   ├── feat-001/
│   │   ├── spec.md
│   │   ├── design.md
│   │   ├── test-report.md
│   │   ├── review.md
│   │   └── status.json
│   └── feat-002/
│       └── ...
└── logs/                    # Daily log files
    └── 2025-01-15.log

Standards System

Vibe ships with 14 standard templates that are automatically loaded per agent role. Standards are enriched with project-specific context after Discovery and Planning phases.

| Standard | Applied To | |----------|------------| | coding-style.md | Developer, Reviewer | | testing-standards.md | Tester | | architecture-principles.md | Architect, Reviewer | | security-policy.md | Developer, Reviewer | | git-workflow.md | CI/CD | | ... | ... |

Edit files in .vibe/standards/ to customize project conventions.

Key Features

• Multi-agent orchestration: Features execute in dependency order with parallel-safe coordination
• Quality gates: Configurable approval points for requirements, plans, tests, reviews, and merges
• Automatic retry: Failed tests and reviews are retried with feedback loops
• Session persistence: Abort and resume workflows across sessions
• Context compaction: Automatic conversation history compaction to stay within context limits
• Standards enrichment: Project-specific coding standards injected per agent role
• Traceability: Requirements mapped to features with unmapped requirement warnings
• Skill discovery: Agents discover and use project-specific skills (e.g. QMD memory search)
• Pipeline UI: Real-time step progress with activity log in the terminal
• Programmatic SDK: createVibeSession() for CI/CD and scripting without the TUI

License

MIT