nexus-sdlc 2.30.4

AI SDLC Orchestration Framework CLI and MCP server

Nexus — AI SDLC Orchestration Framework

Structure software development through 100+ specialized agent roles with full pipeline traceability.

Nexus is a project-agnostic AI SDLC orchestration framework that automates multi-stage development pipelines. It coordinates business analysis, architecture, design, implementation, and quality assurance across autonomous AI agents—all with complete observability, feedback loops, and escalation chains.

---

Quick Start

Claude Code (Claude.ai)

# 1. Install the plugin
claude plugin marketplace add https://gitlab.com/stellaxis/nexus/core_service.git
claude plugin install nexus@stellaxis

# 2. Go to your project
cd /path/to/your/project

# 3. Initialize Nexus
/nexus:setup

# 4. Plan your work
/nexus:discover "Add user authentication"

# 5. Run the pipeline
/nexus:dispatch feature "Add OAuth2 login"

Gemini CLI

# 1. Install the extension
gemini extension add https://gitlab.com/stellaxis/nexus/core_service.git

# 2. Go to your project and initialize
cd /path/to/your/project
/nexus setup

# 3. Plan and dispatch
/nexus discover "Add user authentication"
/nexus dispatch feature "Add OAuth2 login"

From Source (Development)

git clone https://gitlab.com/stellaxis/nexus/core_service.git
cd nexus

# For Claude Code
claude --plugin-dir $(pwd)

# For Gemini CLI
gemini extension add $(pwd)

---

Before & After

Scenario	Without Nexus	With Nexus
Prompting	"Claude, build auth"	/nexus:discover "Add authentication"
Scope	One agent, one shot	BA analyzes, Governance reviews cost/legal
Design	Hope it works	Architect designs, Lead writes spec
Build	No validation	Dev implements, QA validates
Audit Trail	None	Full JSONL observability, Valkey Streams events, NebulaGraph knowledge graph
Feedback	Restart from scratch	Loop feedback to dev/architect automatically

---

Key Features

122 Specialized Agents

• Level 0: Director (1 — orchestrates everything)
• Level 1a: SMEs (14 — BA, domain experts, feasibility, market research)
• Level 1b: Governance (4 — cost, legal, compliance, tech debt)
• Level 1c: Architects (8 — backend, frontend, infra, quality, solution, POC, migration, mobile)
• Level 2: Leads & Orchestrators (19 — engineering leads, pipeline leads, specialists)
• Level 3: Builders (71 — specialized developers for frameworks, languages, patterns)
• Cross-cutting: Documentation, error tracking, git management, stage recording, validation (5)

10 Engagement Types

Type	Pipeline	Use Case
poc	feasibility → architect → lead → dev	Validate idea quickly
prototype	architect → design → lead → dev	Build proof-of-concept
mvp	ba → architect → lead → dev → qa	Ship minimum viable product
spike	research → evaluate → report	Investigate unknown territory
integration	analyze → architect → lead → dev → qa	Connect systems
migration	analyze → architect → lead → dev → validate → qa	Upgrade/refactor existing code
enhancement	ba → governance → architect → lead → dev → qa	Add feature to existing product
full-product	ba → governance → architect → lead → dev → qa	Build complete product
audit	analyze → review → report	Security/compliance review
rescue	analyze → triage → stabilize → remediate → qa	Fix production incidents

15-Phase Planning Engine

/nexus:discover scopes work before execution:

• Break down goals into tasks
• Estimate token budget and cost
• Identify stakeholders and blockers
• Show work plan for user approval
• Never auto-execute — always ask first

Autonomous Execution

Pipelines run to completion with zero human intervention:

• Sequential stage execution (BA → Design → Dev → QA)
• Parallel subtasks within stages
• Automatic escalation (Dev → Lead → Architect → Director)
• Feedback loops (QA rejection → Dev re-execution with context)
• Local-first mode (no Temporal needed)

Feedback Loops & Escalation

QA Validation
  ├─ PASS → Shipped Code
  ├─ REJECTED → Dev re-executes with feedback
  │   ├─ PASS → QA re-validates
  │   ├─ REJECTED (iteration 2) → Lead reviews
  │   └─ REJECTED (iteration 3) → Escalate to Architect
  └─ TIMEOUT → Escalate to Director

Full Observability

All events logged to .nexus/logs/events.jsonl with 30+ event types:

• pipeline_started, pipeline_completed
• stage_started, stage_completed, stage_failed, stage_rejected
• agent_assigned, agent_thinking, agent_output
• task_created, task_completed, task_failed
• feedback_loop_detected, escalation_triggered
• Error events with classification (syntax, timeout, auth, rate_limit, etc.)

Dual-write to Valkey Streams and NebulaGraph when configured.

Local-First, Cloud Optional

Always works:

• Runs entirely in Claude Code or Gemini CLI
• All results saved to .nexus/results/
• JSONL event logging (no external service required)

Enhanced with infrastructure:

• Temporal — Workflow state, audit trail, cross-session resume
• Valkey Streams — Real-time event bus, agent communication
• NebulaGraph — Knowledge graph of decisions, components, relationships

Multi-Platform

Platform	Type	Status
Claude Code	Plugin	LIVE — 122 agents, 13 commands
Gemini CLI	Extension	LIVE — TOML-wrapped commands, same agents
Antigravity IDE	TBD	Deferred

Same agent specs and protocols. Different interfaces.

---

10 Core Commands

Command	Purpose
/nexus:setup	Initialize Nexus in current project
/nexus:discover "goal"	Plan work scope, estimate cost, get approval before execution
/nexus:dispatch <type> "desc"	Run full SDLC pipeline (type: feature, bugfix, hotfix, spike, etc.)
/nexus:auto <mode> <duration>	Run autonomously for N hours/days (proactive agents, no user input)
/nexus:pipeline	Show current pipeline status, agents assigned, stage progress
/nexus:validate	Run build, lint, test checks (backend, frontend, database)
/nexus:report <task-id>	Generate execution report with timeline, decisions, cost
/nexus:configure	View/edit project config (stack, validation, infrastructure)
/nexus:cloud provision	Provision PostgreSQL, Valkey, NebulaGraph via Terraform (GCP)
/nexus:gaps	Show framework gap registry, missing features, roadmap

Full reference: see PRODUCT.md § 3.

---

How It Works

User Input (CLI or Chat)
    │
    ├─→ /nexus:discover     ← Plan & scope
    │      │
    │      └─→ Director reads task
    │           BA scopes work
    │           Governance estimates cost
    │           Show user approval prompt
    │
    ├─→ /nexus:dispatch     ← Execute pipeline
         │
         ├─→ Stage 1: BA Analysis
         │   └─→ claude -p subprocess
         │
         ├─→ Stage 2: Governance Review
         │   ├─→ Cost Analyst (parallel)
         │   └─→ Legal Review (parallel)
         │       └─→ Consolidated output
         │
         ├─→ Stage 3: Architecture
         │   └─→ Architect subprocess
         │
         ├─→ Stage 4: Dev Implementation
         │   └─→ Dev subprocess
         │       └─→ Git commits pushed
         │
         ├─→ Stage 5: QA Validation
         │   └─→ QA subprocess
         │       ├─→ Build check
         │       ├─→ Lint check
         │       └─→ Test check
         │
         ├─→ Feedback Loop?
         │   ├─→ REJECTED → Jump back to Dev
         │   ├─→ ESCALATE → Jump to Lead/Architect
         │   └─→ PASS → Continue
         │
         └─→ Observability
             ├─→ .nexus/logs/events.jsonl (ALWAYS)
             ├─→ Valkey Streams (if configured)
             └─→ NebulaGraph (if configured)

---

Configuration

Each project carries a lightweight .nexus/config.yaml:

project:
  name: my-product
  team: Engineering
  stack:
    backend: golang
    frontend: nextjs
    database: postgresql

pipelines:
  feature: [ba, governance, architect, lead, dev, qa]
  bugfix: [architect, lead, dev, qa]
  hotfix: [lead, dev]
  spike: [research, evaluate, report]

validation:
  backend:
    build: "go build ./..."
    test: "go test ./... -v"
    lint: "golangci-lint run"
  frontend:
    build: "npm run build"
    test: "npm test"
    lint: "eslint ."

# Optional — infrastructure (omit for local-only mode)
infrastructure:
  temporal:
    address: "localhost:7233"
    namespace: "my-project"
  valkey:
    host: "localhost"
    port: 6379
  nebulagraph:
    host: "localhost"
    port: 9669

execution:
  local_only_mode: false     # Set true to skip infrastructure recording
  max_iterations: 3          # Max feedback loops before escalation
  timeout_minutes: 60        # Pipeline timeout

observability:
  log_level: info            # debug, info, warn, error
  capture_llm_io: false      # Log LLM requests/responses (verbose)

Full schema: see PRODUCT.md § 6.

---

Directory Structure

nexus/
├── .claude-plugin/          Claude Code plugin manifest
│   └── plugin.json          Plugin definition, commands, permissions
│
├── agents/                  122 agent role specifications
│   ├── level-0/             Director (1)
│   ├── level-1a/            SMEs (11 — BA, domain experts, etc.)
│   ├── level-1b/            Governance (4 — cost, legal, compliance, tech debt)
│   ├── level-1c/            Architects (7 — backend, frontend, infra, etc.)
│   ├── level-2/             Leads & orchestrators (19)
│   ├── level-3/             Builders (59 — specialized developers)
│   └── cross-cutting/       Documentation, error tracking, git (3)
│
├── commands/                Gemini CLI TOML commands (10)
│   └── *.toml               Thin wrappers referencing skills/*/SKILL.md
│
├── core/                    Director Bridge + Protocol
│   ├── director-bridge.sh   CLI to cloud infrastructure
│   └── protocol.md          Communication protocol spec
│
├── protocols/               Protocol specifications
│   ├── DISPATCH.md          Task dispatch protocol
│   ├── SESSION_STATE.md     Session memory protocol
│   ├── TEMPORAL.md          Temporal workflow protocol
│   ├── ENGAGEMENTS.md       Engagement type definitions
│   ├── TOKEN_OPTIMIZATION.md Budget & token management
│   ├── PLAN_AWARE_ROUTING.md Model selection by plan tier
│   └── OBSERVABILITY.md     Event logging & classification
│
├── workflows/               Temporal Python workflow
│   ├── sdlc_workflow.py     Main workflow definition
│   ├── autonomous_workflow.py Executor with feedback loops
│   ├── pipeline_workflow.py PipelineWorkflow orchestrator (composable)
│   ├── activities.py        Activity definitions (Valkey, NebulaGraph)
│   ├── nebula_graph.py      NebulaGraph client (sole knowledge graph backend)
│   ├── test_workflow_logic.py Workflow logic unit tests
│   └── test_nebula_graph.py NebulaGraph integration tests
│
├── skills/                  Shared skill instructions (10)
│   ├── discover/
│   ├── setup/
│   ├── dispatch/
│   ├── auto/
│   ├── pipeline/
│   ├── validate/
│   ├── report/
│   ├── configure/
│   ├── gaps/
│   └── cloud/
│
├── templates/               Project integration templates
│   ├── project-config.yaml  Master config template
│   ├── session-state.yaml   Session memory template
│   ├── claude-md-snippet.md Appended to project CLAUDE.md
│   ├── gemini-md-snippet.md Appended to project GEMINI.md
│   └── result-template.md   Result file template
│
├── scripts/                 Setup & provisioning utilities
│   ├── cloud-provision.sh   Interactive cloud setup
│   ├── cloud-setup-vm.sh    VM bootstrap script
│   ├── cloud-teardown.sh    Infrastructure cleanup
│   ├── providers/
│   │   ├── gcp.sh           Google Cloud functions
│   │   └── doctl.sh         DigitalOcean functions
│   └── health-check.sh      Infrastructure health probe
│
├── k8s/                     Kubernetes manifests
│   ├── temporal-deployment.yaml Temporal deployment
│   ├── redis-streams.yaml       Valkey Streams deployment
│   └── temporal-worker-deployment.yaml Temporal worker
│
├── terraform/               Terraform modules for GCP (Cloud SQL, Valkey, NebulaGraph)
│
├── docker-compose.yml       Local infrastructure (Valkey + NebulaGraph)
├── PRODUCT.md               Authoritative product specification
├── CLAUDE.md                Guidance for working ON Nexus
├── GEMINI.md                Guidance for working ON Nexus
├── package.json             Package metadata
├── gemini-extension.json    Gemini CLI extension manifest
└── docs/                    Framework documentation
    ├── POC.md               Proof of concept results (all 10 hypotheses validated)
    ├── proactive-agent-triggers.md 260+ trigger rules for self-activation
    └── ...                  Additional docs

---

Proof of Concept (v1.2.0)

All 10 core hypotheses validated on real projects:

Hypothesis	Status	Evidence
122 agent specs parse and dispatch at runtime	✅ PROVEN	All 122 specs load, correct agents assigned per stage
Full 6-stage pipeline runs autonomously	✅ PROVEN	Enhancement pipeline: BA → Governance → Architect → Lead → Dev → QA (~130s)
Multi-agent stages work	✅ PROVEN	Governance stage with 4 agents (Cost, Legal, Compliance, Tech Debt)
Feedback loops work	✅ PROVEN	QA rejects → Dev re-executes with feedback → QA re-validates
Escalation chains work	✅ PROVEN	Iteration max → Lead review → Architect review → Director resolution
Non-standard pipelines work	✅ PROVEN	Spike (3-stage), Rescue (5-stage) pipelines complete correctly
Infrastructure integration works	✅ PROVEN	Valkey Streams events, NebulaGraph knowledge graph, Temporal state
Works on real consumer projects	✅ PROVEN	Live Rescue pipeline: 12 fixes, 3 commits, zero human intervention
Local-first mode works	✅ PROVEN	Consumer project ran without Temporal, using only inline claude -p
Observability captures all events	✅ PROVEN	v1.2.0 logs 30+ event types, 20 error classes, JSONL format

See docs/POC.md for detailed validation results, regression test suite (110 tests), and architectural diagrams.

---

Documentation

• PRODUCT.md — Full product specification (agent hierarchy, engagement types, configuration schema, protocols)
• CLAUDE.md — Guidance for working ON Nexus framework (for contributors)
• GEMINI.md — Guidance for working ON Nexus framework (for Gemini CLI developers)
• docs/POC.md — Proof of concept results (validation tests, regression suite)
• protocols/ — Detailed protocol specifications (DISPATCH, SESSION_STATE, TEMPORAL, OBSERVABILITY, etc.)
• docs/proactive-agent-triggers.md — 260+ trigger rules for autonomous agent activation

---

Contributing

Contributions are welcome. Before submitting a PR:

1. Read CLAUDE.md — framework development rules
2. Test changes on a consumer project: /nexus:dispatch bugfix "test change"
3. Verify all 110 tests pass: pytest workflows/test_*.py -v
4. Check Temporal UI and Valkey Streams if using cloud mode
5. Submit PR with clear description of what you changed and why

See CONTRIBUTING.md for detailed guidelines.

---

License

MIT — See LICENSE for details.

---

Built by

Stellaxis — AI engineering platform on GitLab

Repository: https://gitlab.com/stellaxis/nexus/core_service