Quickstart

Use this guide when you want the shortest path from “I have Apogee” to “I’m running lifecycle workflows against my project.” For a full component status breakdown (what ships, what’s built, what’s planned), see Why Apogee.

What Apogee Does

Apogee is an AI-assisted software development lifecycle governance framework. It provides reusable skills, lifecycle chains, manifest-based codebase analysis, and governance gates — all exposed through an MCP server for integration with AI coding assistants like Claude Code and Cursor.

What Ships vs What Is Optional

Component

Status

What it does

MCP server

Core

IDE-integrated skill discovery, lifecycle chains, and manifest tools via stdio transport

Skill library (skills/)

Core

104 reusable lifecycle workflows: design, plan, implement, test, review, verify

Compiled skill runtime

Core

Markdown skill compiler, generated Python modules, runtime registry

Lifecycle chains

Core

Ordered multi-step execution with checkpoints, conditions, and resume

Governance gates

Core

Policy-driven approval gates at lifecycle boundaries

Proof harness

Core

Release verification framework with structured proof reports and trust evaluation

CPG engine + manifest generator

Optional

Rust CLI with tree-sitter parsing across 8 languages, DuckDB CPG store, structural analysis tools

CI templates

Optional

GitLab CI and GitHub Actions verification templates

Layered org/team/user skills

Optional

Organization, team, and user skill layers via env vars

Prerequisites

  • Python 3.10+ for the MCP server, skill runtime, and test runners

  • Rust toolchain for the CPG engine (install via rustup)

Install Apogee

Apogee has two install steps: a global server install (once) and a per-repo bootstrap (each project).

Step 1: Install the server globally

From the Apogee checkout:

# Install the Apogee server and tools globally
just install

# Configure your IDE (pick one, or multiple)
just install-claude   # Claude Code
just install-cursor   # Cursor

# Update after pulling Apogee changes
just update

Step 2: Bootstrap each project repo

# Bootstrap with IDE support
apogee-repo bootstrap /path/to/your/repo --claude
apogee-repo bootstrap /path/to/your/repo --cursor

# Or via install script
./scripts/install_repo.sh --target /path/to/your/repo

Or via just: just bootstrap target=/path/to/your/repo.

Ongoing management — after bootstrap, use apogee-repo to manage your repos:

apogee-repo status ~/projects/my-app   # check health
apogee-repo update all                 # refresh after Apogee update
apogee-repo validate ~/projects/my-app # detect config conflicts
apogee-repo list                       # show all managed repos

See apogee-repo for the full CLI reference.

This creates apogee_artifacts/, project_memories/, merges .gitignore patterns, configures IDE/MCP connections, and generates an initial manifest. No framework files are copied — the server and tools are installed globally.

apogee-repo handles all IDE configuration (Claude Code, Cursor, and any future MCP-compatible host) automatically during bootstrap. Use apogee-repo update to refresh configs after Apogee updates.

Configure .gitignore

The repo installer (install_repo.sh) merges these patterns automatically. If you set up manually, add them to your target repo’s .gitignore:

# Apogee lifecycle artifacts (private working state)
apogee_artifacts/
design-docs/

# Apogee local config (per-developer, not shared)
.mcp.json
.design-approved

Pattern

Reason

apogee_artifacts/

Generated lifecycle outputs: designs, plans, review prompts, chain checkpoints. Working artifacts, not committed source.

design-docs/

Local roadmap work, scratch synthesis, draft exploration.

.mcp.json

Per-developer MCP client configuration (host-specific paths).

.design-approved

Local approval marker used by the design workflow.

For the full committed-vs-private contract, see spec/artifact_privacy.md.

Generate Your First Manifest and CPG

The manifest generator analyzes your codebase and builds a Code Property Graph (CPG) in DuckDB. This powers all structural analysis tools (security scanning, cross-branch comparison, impact analysis).

apogee-manifest --repo . --label current

This parses source files via tree-sitter across 8 languages (C, C++, Python, Go, Rust, Java, JavaScript, TypeScript), extracts functions, call edges, types, and data flow, and persists everything to .apogee/cpg.duckdb. The manifest JSON is written to project_memories/manifests/.

Understand Your Scores

After generation, look at scores in the manifest:

  • parse_coverage_score: files parsed successfully

  • symbol_coverage_score: files with extracted symbols

  • relationship_coverage_score: files with dependency edges

  • overall_score: weighted summary (>= 95 is high-coverage)

Smoke Test

After setup, verify the stack works:

  1. Run unit tests: ./scripts/run_unit_tests.sh — confirms the framework itself is healthy.

  2. Start the server (if installed): apogee-mcp (or python -m mcp_server.server from checkout).

  3. Check server status: read apogee://status/server — should show registry size and repo root.

  4. Discover a skill: call find_skill("commit feature") — should return task.git.commit_feature.

  5. Prepare a workflow: call run_skill("task.git.commit_feature") — should return prompt text and resolved inputs.

  6. Run integration tests: ./scripts/run_integration_tests.sh --mcp — validates the MCP protocol surface.

If all steps succeed, your setup is complete and ready for real workflow use.

Common Tasks

Once connected to an AI assistant, describe what you want in natural language. Apogee routes your intent to the right workflow.

Design and implement features:

“I’ve been researching how we should handle auth. We need OAuth for the web app and API keys for the CLI. Let’s run this through the multi-feature workflow.”

The assistant runs feature identification, groups the work, generates design specs, runs adversarial review, scaffolds plans, and executes them — with your approval at each gate.

Analyze code for impact:

“What’s the blast radius if I change the payment processing function?”

cpg_impact_analysis(function="process_payment",
                    file="src/billing/checkout.py")

Find security issues:

“Scan the API layer for functions that take user input without validation.”

cpg_security_scan(subsystem="src/api",
                  branch="main")

Cross-branch analysis (kernel scale):

“Compare our RHEL kernel branch against mainline. What functions diverged in the crypto subsystem?”

cpg_full_audit("mainline", "rhel-9.4",
               subsystem="crypto")

Update documentation:

“We haven’t updated the docs in months. Run a comprehensive audit and tell me what’s missing.”

The assistant runs docs-update in comprehensive mode, scans all implemented series against all doc pages, and produces a prioritized plan grouped by doc file.

Commit, release, and maintain:

  • “Commit my changes” → commit workflow with signoff and AI attribution

  • “Bump to version 0.4.0 and tag it” → auto-detects version files, bumps, commits, tags

  • “Check the health of all my managed repos” → apogee-repo status / apogee-repo validate

For environment variables, build tasks, CI integration, and troubleshooting, see Configuration.

Next Steps

  • Read Glossary to align on this framework’s terminology.

  • Read skills/CATALOG.md to understand the available workflow and task skills.

  • Read CONTRIBUTING.md for development and extension guidance.

  • Read Architecture for the design overview and component map.

Note

This page is also available as a man page: man apogee-quickstart

See Also