Ritual

Resolve ambiguity before coding.

Ritual surfaces the questions you should answer before writing code, then generates a risk-first Build Brief that your AI coding agent uses as its primary implementation guide. Works with Claude Code, Cursor, Kiro, Codex, GitHub Copilot, Gemini CLI, and Windsurf.

Install

npm install -g @ritual-ai/cli

That gives you the ritual CLI plus the skill files for every supported coding agent.

Quickstart

# Inside your project
ritual init                       # scaffold skills into .claude/, .cursor/, etc.
ritual login                      # authenticate to Ritual Cloud (optional — see modes below)

Then in your coding agent:

/ritual explore "Add multi-tenant RBAC"
/ritual brief
/ritual build "Add notification preferences"

Full command reference →

Two modes — pick what fits

| | Light mode | Cloud mode | |---|---|---| | Setup | ritual init | ritual init + ritual login | | Auth | None | Free Ritual Cloud account | | Discovery questions | Local — saved to RITUAL.md | Generated by AI pipeline, reviewed in app.ritual.work | | Knowledge sources | Local files | Uploaded + indexed for cross-exploration retrieval | | Recommendations | Inferred locally from codebase + RITUAL.md | Synthesized via the agentic pipeline | | Build Brief | Generated from RITUAL.md | Generated from accepted recommendations + requirement packages | | Collaboration | Solo only | Invite teammates to answer blocking questions |

Both modes work in any supported coding agent. Light mode is great for solo work or evaluating Ritual without an account. Cloud mode unlocks the team-collaboration loop.

What you'll see

A /ritual explore "..." run produces output like:

SCOPE BROKEN INTO SUB-PROBLEMS

  • Tenant boundaries
  • Role hierarchy & guards
  • Invite & join flow
  • Audit & ownership transfer

→ tackle what matters first

Then /ritual build walks you through reviewing recommendations one at a time:

─── recommendation 1 of 4 · epic: Authentication ───

  RECOMMENDATION
    Use Postgres RLS for tenant scoping

  WHAT IT DOES
    Enforces isolation at the data layer; application bugs can't leak rows.

  HOW TO BUILD IT
    • Add row-level security policies on each tenant-scoped table
    • Set tenant context via SET LOCAL in API request middleware
    • Verify with tenant-isolation integration tests

  TRADEOFF
    Migrations heavier; admin tooling needs SET LOCAL role.

  WHY THIS WINS
    Defense-in-depth survives application bugs that ACL-based isolation wouldn't.

Accept, edit, reject — your call. Ritual then generates a Build Brief leading with review-blocking items, and your coding agent implements against it.

About this repository

This is a public, source-available mirror of an internal Ritual repo, force-pushed on every release.

• Most users don't need to clone it — install the CLI from npm above.
• We welcome issues (bugs, feature requests, security via SECURITY.md).
• We don't accept external pull requests — see CONTRIBUTING.md for the rationale.

The hosted MCP server runs at mcp.ritual.technology. Clients connect via the CLI; you don't run your own.

How it works

For the architecture, MCP protocol details, available tools, rate limits, and module layout, see docs/architecture.md.

For the outbound MCP client API (used internally to connect to Confluence / Drive / Jira / Slack), see docs/mcp-client-api.md.

For Claude Code-specific setup, see docs/claude-code-setup.md.

License

Apache 2.0 — see LICENSE.