Project-owned decisions
Foundations, components, decisions and approved exceptions stay as versioned JSON and Markdown next to your code.
Whale gives each agent the decisions that apply to its task, then verifies the change with deterministic checks.
Whale Igniter 2.0 beta is available. Try the decision engine while the stable 1.x workflow remains supported.
2.0.0-beta.1 · Node ≥ 20 · No API key required · MIT
Whale keeps decisions and their reasoning in the repo, scopes them to the files being changed and checks the result.
Foundations, components, decisions and approved exceptions stay as versioned JSON and Markdown next to your code.
CLI and MCP compile only the decisions relevant to the files an agent will change.
Deterministic checks return exact evidence. Approved exceptions remain narrow, expiring and visible.
$ whale ignite my-app # a structured intelligence layer, in one command my-app/ ├── whale.config.json foundations, stack, theme ├── CLAUDE.md agent brief, auto-synced ├── intelligence/ │ ├── components.json catalog, variants, states │ ├── decisions/ one ADR per decision │ └── refinements/ approved exceptions └── llm-wiki/ readable, one file per concern # every agent inherits the same decisions and reasons
Whale can discern what applies to a task, verify the resulting diff and keep every exception explicit.
$ whale decide # record a scoped policy and its reason $ whale context --files src/Card.css # compile only relevant decisions $ whale check --diff origin/main # return exact blocking evidence $ whale exception propose # request a narrow, expiring waiver $ whale exception approve EXC-0001 --approved-by design-platform
MCP clients receive scoped context and structured findings from the same deterministic model used by the CLI.
| Tool | What it does |
|---|---|
| whale_project_overview | Full project brief: stack, foundations, packs, context. |
| whale_list_components | Component catalog with files, variants, states and tokens. |
| whale_list_decisions | Architectural decisions with rationale and status. |
| whale_constraints_for_files | Only the enforceable decisions that apply to the files being changed. |
| whale_explain_policy | Scope, rationale, consequences and enforcement for one decision. |
| whale_check_diff | Deterministic findings and applied exceptions for added diff lines. |
A proposal never weakens enforcement. Approval records who accepted it, where it applies and when it expires.
$ whale exception propose # status: proposed · enforcement unchanged $ whale exception approve EXC-0001 --approved-by design-platform # status: approved · scoped waiver active · audit trail preserved
Fully local and deterministic. No API key required for any core flow.
| Command | What it does |
|---|---|
| whale ignite my-app | Bootstrap a new Whale workspace. |
| whale adopt | Scan an existing project and propose components and foundations. |
| whale decide | Record a scoped, enforceable decision. |
| whale context --files <paths...> | Compile the decisions relevant to an agent task. |
| whale check --diff <ref> | Verify added lines against active decisions. |
| whale exception propose | Request an expiring exception without changing enforcement. |
| whale mcp config --client cursor | Configure an MCP client (Claude Code, Cursor, Zed). |
Try the 2.0 beta in a real project. Stable 1.x workflows remain available.