00-orchestrator

ryu-next (workshop)

A locally-installed workflow kit for AI-assisted coding. ryu init drops a structured workflow surface (.ryu/, .claude/, .codex/, .cursor/) into any project — bridge classifier (T0/T1/T2/COUNCIL routes + clarify lane), behavioral gates, telemetry into Arize, optional Docker-wrapped SocratiCode for semantic search, council on demand for hard decisions, and the @prds/v7.md feature surface.

This repo is the workshop. The active deployable lives at ryu-next-deploy-v24/ (v24 / bundle 0.24.0). Don't conflate the two — see @docs/process.md for the mental model. For navigation across all docs, start at @docs/README.md.

Repo layout (high level)

ryu-next/
├── bundle/                   # workshop runtime (the next thing to package)
│   ├── bin/ryu.mjs           # CLI entrypoint
│   ├── lib/                  # commands, lanes, hooks, providers, TUI, MCP, registry, classifier
│   ├── lib/context/          # ContextProvider routing layer (Bedi pattern)
│   ├── migrations/sqlite/    # schema migrations (per-project + workshop registry)
│   ├── schemas/              # JSON Schema (envelope, mcp, config, lane-result)
│   ├── templates/            # personas, skills, Docker per-type templates, deploy CLAUDE.md
│   └── test/                 # integration tests, smoke harness, fixtures
├── scripts/                  # validate, traceability, audit, clean-ryu-docker
├── docs/                     # user-facing docs (curated subset ships in deploys)
│   ├── README.md             # ← doc index (start here)
│   ├── archive/              # archived obsolete docs (workshop-only)
│   └── audits/               # historical audit evidence (workshop-only)
├── prds/                     # product version PRDs
│   ├── INDEX.md              # version table (workshop-only)
│   ├── v7.md                 # current product PRD (deployable)
│   └── archive/              # superseded v1.md … v6.md (workshop-only)
├── harness-research/         # concurrent research workstream (workshop-only — never deployed)
├── ryu-next-deploy-v24/      # ACTIVE deploy (frozen between /package runs)
├── archive/                  # frozen older deploys (immutable per workshop rule §1.5)
├── deployments/CATALOG.md    # append-only log of every packaged version + refresh rows
└── .claude/                  # workshop bootstrap: commands/, skills/, worktrees/

What v24 ships (the active deploy)

v24 is a same-architecture refresh of v23 driven by callouts from the v23 functional test. v23 rebuilt the routing brain: replaced the 25-signal regex classifier with a 30-feature bridge classifier producing structured RouteDecision, laid bandit telemetry under it, refit ryu eval as trace-first analytical surface, integrated DACS into council, and put an Oracle Gap diagnostic in front of any fine-tune commitment.

v24 fix-on-discovery rollup (no new features):

• ryu init rejects unknown flags with init.unknown_flag events (fixed --bullshit-flag returning ok).
• ryu council --health distinguishes managed_auth_no_cli_key under Claude Code managed auth and downgrades it to a non-fatal warn.
• mcp-runner-handshake doctor check ceiling raised 3s→10s with single retry on transient failure.
• Oracle Gap --task-shape-floor override surfaced when corpus density is partial.
• query_codebase description rewritten to call out the four real differentiators vs upstream mcp__socraticode__codebase_search.
• /ryu:council framing tightened — council reserved for architecture decisions with ≥3 viable options, persistent T0/T1/T2 failures, security audits, verifier escalation. Quick-class prompts and single-persona prompts now answer inline (no surface engagement).
• 3-iteration autonomous loop, project-size suppression for council, multi-line JSON parsing in verify-test-prereqs, pheromone stop-hook ceiling 3000ms.

Foundational architecture (v22 established, v23 inherits, v24 inherits): Ryu does not invoke LLMs from bundle/lib/. Council and autopilot MCP providers return directive plans; the parent Claude Code session executes them via the Task tool (Claude work) or the codex@openai-codex plugin's codex:codex-rescue subagent (Codex work). Auth is OAuth on both sides.

See @prds/v7.md for the full product spec and @deployments/CATALOG.md for every packaged version.

Quick start

The shipped quick-start lives in the active deploy: ryu-next-deploy-v24/QUICKSTART.md. From npm-global:

npm i -g ryu-next
ryu init                 # interactive — auto-detects project type and existing Docker
ryu doctor               # health checks
ryu                      # opens the TUI
ryu projects list        # cross-project visibility (works from any cwd)

Drop-in install for an existing project: see @docs/install-into-existing-project.md.

Process and rules