sj2-ai

SJ2 — The Autonomous AI Engineering Platform

A working scaffold: npm-workspaces monorepo, a real multi-provider AI abstraction layer, a 4-agent orchestration pipeline, and a CLI with commands that actually execute (init, learn, plan, explain, implement, doctor). See ARCHITECTURE.md for what's built vs. planned, mapped against the full product spec.

Requirements

• Node.js >= 18
• npm (workspaces support is built in — no extra tooling needed)
• Optional: Ollama running locally for the free/local provider path, or an API key for any of: OpenAI, Anthropic, Groq, Gemini, OpenRouter, Mistral, Cohere, Azure OpenAI.

Install & build

npm install
npm run build          # builds all packages via TypeScript project references

Link the CLI

npm link --workspace apps/cli
sj2 --help

Or run it without linking:

node apps/cli/dist/index.js --help

Configure an AI provider

Copy .env.example to .env in whatever project you run sj2 from, or just export the variable in your shell:

export ANTHROPIC_API_KEY=sk-ant-...
# or
export OPENAI_API_KEY=sk-...
# or run Ollama locally — no key needed:
ollama serve

The router tries providers in this order by default: Ollama → Groq → Gemini → OpenRouter → OpenAI → Anthropic → Azure → Mistral → Cohere — local and free tiers first, matching the spec's local-first principle. Run sj2 doctor to see which ones it currently detects as configured.

Try it on a real project

cd /path/to/any/repo
sj2 init                     # creates .sj2/
sj2 learn                    # scans the repo, writes .sj2/architecture.md
sj2 plan "add rate limiting to the API"
sj2 plan "add rate limiting to the API" --optimize-for cost   # model benchmarking
sj2 explain src/index.ts
sj2 implement "add a health check endpoint"   # full 4-agent pipeline
sj2 workflow list                             # see all pipeline templates + 13 agents
sj2 workflow run full-review "add OAuth login"
sj2 doctor                   # environment diagnostics

sj2 implement/sj2 workflow run do not write files or touch git yet — see ARCHITECTURE.md §3 for why that's a deliberate sequencing decision.

Repo layout

packages/shared     logger, typed errors, shared types
packages/core       .sj2/ project state, repo scanner, memory store
packages/ai         9 providers behind one interface, router, model benchmarking
packages/agents     13 agents (Architect, Planner, Engineer, Reviewer, QA, Security,
                     DevOps, Database, UI Engineer, AI Engineer, CTO Advisor,
                     Engineering Manager, Product Manager) + Orchestrator
packages/workflows  reusable pipelines with parallel execution (the workflow builder)
packages/mcp        minimal MCP stdio client
packages/auth       RBAC, audit logging, generic OIDC SSO client
packages/billing    pricing tiers, entitlements, NayaPay manual-confirmation payment flow
packages/plugins    plugin manifest schema + loader
apps/cli            the sj2 command-line tool
apps/cloud          minimal billing + audit-log API (Fastify)
examples/plugins/docker   a working example plugin

Cloud/billing API (apps/cloud)

cd apps/cloud
npm run build && node dist/index.js     # listens on :4000
curl localhost:4000/health
curl localhost:4000/billing/plans

Set NAYAPAY_ID, NAYAPAY_ACCOUNT_NUMBER, NAYAPAY_IBAN (your real payment details — never commit real values to .env.example, only to your own untracked .env) to enable billing. Without them, /billing/payment-request returns a clear 503 rather than pretending to work.

NayaPay has no public automated checkout/webhook API, so this is a two-step, human-confirmed flow rather than an instant redirect:

# 1. Customer requests to pay for a plan — gets your payment details + a reference code
curl -X POST localhost:4000/billing/payment-request \
  -H "Content-Type: application/json" \
  -d '{"organizationId":"org_123","planId":"sigma"}'

# 2. Customer pays you directly via NayaPay, including that reference code

# 3. An admin confirms the transfer arrived — this is what actually activates the plan
curl -X POST localhost:4000/billing/confirm-payment \
  -H "Content-Type: application/json" \
  -H "x-sj2-role: owner" -H "x-sj2-user: you@example.com" \
  -d '{"referenceCode":"SJ2-A1B2C3D4"}'

The x-sj2-role/x-sj2-user headers are a demo stand-in for real admin auth — see the warning comment in apps/cloud/src/routes/billing.ts. This is the route that activates a paid plan, so replace that header check with a verified session before handling real payments.

Development

npm run typecheck            # tsc --noEmit across every workspace
npm run build                # tsc -b (incremental, respects project references)

Each package builds independently — cd packages/ai && npm run build works without building the whole repo, because dependencies are declared as TypeScript project references, not implicit ordering.

Next steps

See ROADMAP.md for the full phased plan — including how the more ambitious "Plus" features (background agents, voice mode, the visual dependency explorer, team analytics, a plugin marketplace) map to concrete future work and the specific infrastructure each one is blocked on.