Guides

Getting Started

This guide walks you through installing Ananke Plexus, initializing a project, and running your first governed development lifecycle.

The whole first run, animated with real output (more walkthroughs):

Installation

With uv (recommended)

uv tool install ananke-plexus

With pip

pip install ananke-plexus

With extras

# MCP server support
pip install "ananke-plexus[mcp]"

# Jira integration
pip install "ananke-plexus[jira]"

# OpenTelemetry
pip install "ananke-plexus[telemetry]"

# Skill & agent registry accelerators (zstd, jsonschema, blake3)
pip install "ananke-plexus[registry]"

# All extras
pip install "ananke-plexus[all]"

Behind a package firewall

Some firewalls block any package version published in the last week or two. When a dependency, such as pydantic, has a release that new, installing Ananke fails even though Ananke itself is allowed. uv can skip the newest releases of the named packages and keep everything else current:

uv pip install ananke-plexus \
  --exclude-newer-package pydantic=2026-10-22 \
  --exclude-newer-package pydantic-core=2026-10-22

Each release’s scan report (scan-report/summary.md, under Maturity) lists which dependencies were days old when it was published, and the exact command.

From source (development)

git clone https://github.com/neo-pragnya/ananke-plexus
cd ananke-plexus
pip install -e ".[dev]"

Verify installation

ananke version
ananke --help
apm --help

Read the docs offline

No PyPI or GitHub access needed — the whole site (this page included) ships inside the package:

pip install "ananke-plexus[docs]"
ananke docs serve   # builds + serves locally, opens a browser tab

Initialize a project

cd my-project
ananke init

This creates:

my-project/
└── .ananke/
    ├── config.toml             — project configuration
    ├── config.local.toml.example
    ├── policy/
    │   └── default.toml        — baseline policy
    ├── architecture/
    │   └── system.calm.json    — CALM architecture skeleton
    ├── secrets/
    │   └── adapters.env        — credential store (gitignored)
    ├── specs/
    ├── graph/
    ├── skills/
    ├── runs/
    └── evidence/

Run diagnostics:

ananke doctor
ananke doctor --json  # machine-readable

Install a policy pack

ananke policy install-pack python-library

Create your first requirement

ananke spec create \
  --id PROJ-101 \
  --title "Add idempotent payment webhook" \
  --acceptance "Duplicate events are deduplicated" \
  --acceptance "Idempotency key stored per transaction" \
  --acceptance "Returns 200 on replay"

This creates .ananke/specs/PROJ-101/requirement.md.

Complete the spec workflow

# Generate spec, plan, tasks
ananke spec plan --feature-dir .ananke/specs/PROJ-101
ananke spec tasks --feature-dir .ananke/specs/PROJ-101

# Compile BMAD contracts (behavior tests, model schema, architecture contract)
ananke bmad compile --feature-dir .ananke/specs/PROJ-101

# Lock the spec (records hashes for drift detection)
ananke spec lock --feature-dir .ananke/specs/PROJ-101

# View traceability
ananke bmad trace --feature-dir .ananke/specs/PROJ-101

Build the code graph

ananke graph build
ananke graph status
ananke graph query --text "webhook"

Run verification

ananke verify

This runs all configured gates and produces an evidence bundle in .ananke/evidence/.

Install git hooks

ananke hooks install
ananke hooks status

Pre-commit will run Ruff and secrets scan. Pre-push will run the full verification suite.

Start the MCP server

Add to your IDE’s MCP configuration:

{
  "mcpServers": {
    "ananke": {
      "command": "ananke",
      "args": ["serve-mcp"]
    }
  }
}

Your agent can now query ananke://spec/PROJ-101, ananke://graph/snapshot, and use tools like ananke.graph.impact.

Register and resolve skills and agents

ananke registry init
ananke registry learn ./skills/graph-review
ananke registry promote core/graph-review@1.0.0 --trust approved --channel stable
ananke registry resolve core/graph-review@^1 --explain
ananke sync --activate       # writes ananke.lock and activates what it locks

See the Registry Guide for the full tour.

Run the demo golden journey

ananke run start DEMO-101 --backend fake

Expected output:

✓ Requirement captured
✓ Spec locked                 sha256:...
✓ Behavior contract compiled  2 scenarios
✓ Model contract compiled     2 schemas
✓ Architecture validated
✓ Isolated worktree created
✓ Backend completed implementation
✓ Ruff passed
✓ Type checking passed
✓ Tests passed
✓ Secret scan passed
✓ Evidence bundle finalized

Common patterns

Pattern 1 — Human-led, agent-assisted

# Human specifies
ananke spec create --id T-1 --title "Feature"
# Agent implements via IDE with MCP
# Ananke verifies
ananke verify
# Human reviews PR

Pattern 2 — Jira to PR automation

ananke lifecycle issue-transition --ticket PROJ-101 --state "In Progress"
ananke run start PROJ-101

Pattern 3 — Architecture refactoring

ananke arch validate        # find drift
ananke arch diff            # show declared vs observed
ananke graph impact --files src/old_module.py

Configuration

Edit .ananke/config.toml:

[project]
name = "my-service"
default_branch = "main"

[ananke]
mode = "developer"
fail_closed = true
offline = false

[spec]
provider = "native"
contract_mode = "ananke-bmad"

[graph]
providers = ["native"]
primary = "native"

[security]
secret_scan = true
sast = true
sca = true
license_scan = true

For credentials, use .ananke/secrets/adapters.env:

ANANKE_JIRA_TOKEN=your-token-here
ANANKE_BITBUCKET_APP_PASSWORD=your-password

See Configuration Reference for full details.

Edit this page on GitHub ↗