Metadata-Version: 2.4
Name: nexus-sdlc
Version: 2.30.2
Summary: AI SDLC Orchestration Framework CLI and MCP server
Author: Stellaxis
License: MIT
Keywords: agents,claude-code,mcp,orchestration,sdlc
Requires-Python: >=3.11
Requires-Dist: mcp<2,>=1.0.0
Requires-Dist: pydantic<3,>=2.6.0
Requires-Dist: pyyaml<7,>=6.0.1
Requires-Dist: redis<6,>=5.0.0
Requires-Dist: rich<14,>=13.7.0
Requires-Dist: typer<1.0,>=0.14.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: textual-dev>=0.65.0; extra == 'dev'
Provides-Extra: tui
Requires-Dist: nebula3-python<4,>=3.4.0; extra == 'tui'
Requires-Dist: textual<1.0,>=0.65.0; extra == 'tui'
Description-Content-Type: text/markdown

# Nexus — AI SDLC Orchestration Framework

[![Version 1.2.0](https://img.shields.io/badge/version-1.2.0-blue.svg)](https://gitlab.com/stellaxis/nexus/core_service/-/releases/v1.2.0)
[![License MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Claude Code](https://img.shields.io/badge/Claude%20Code-Plugin-purple.svg)](https://claude.ai)
[![Gemini CLI](https://img.shields.io/badge/Gemini%20CLI-Extension-blue.svg)](https://gemini.google.com)

**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)

```bash
# 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

```bash
# 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)

```bash
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](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`:

```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](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](docs/POC.md) for detailed validation results, regression test suite (110 tests), and architectural diagrams.

---

## Documentation

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

---

## Contributing

Contributions are welcome. Before submitting a PR:

1. Read [CLAUDE.md](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](CONTRIBUTING.md) for detailed guidelines.

---

## License

MIT — See [LICENSE](LICENSE) for details.

---

## Built by

**[Stellaxis](https://gitlab.com/stellaxis)** — AI engineering platform on GitLab

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