Open-source product · CLI and MCP · 2026

Whale Igniter: project intelligence for coding agents

I created a local-first system that helps every coding agent inherit the same product decisions, understand their reasoning, and verify the implementation against them.

Open Whale Igniter ↗View npm package

Role: Creator, Product Designer, and Maintainer
Release: May 2026
Scope: Product definition, agent experience, system design, documentation, CLI, and MCP

Challenge

Project decisions disappear between agents

Coding agents can generate quickly, but each new session starts with an incomplete understanding of the product.

Important choices often live in chat history, memory, or scattered documentation. A new agent may know the codebase without knowing why the system uses specific tokens, components, patterns, or exceptions.

The product opportunity was to make that reasoning part of the repository and keep it close to implementation.

Before

Scattered context

Chats, handoffs, docs, and decisions lose connection.

Whale

Versioned intelligence

One source of truth lives next to the code.

After

Shared agent context

Every configured agent inherits the same decisions.

Product model

A repository-owned source of truth

Whale stores project intelligence as JSON and Markdown. The files stay versioned with the product, so teams and agents can review how decisions change over time.

A sync regenerates agent briefs and a wiki for Claude Code, Codex, Cursor, and Copilot. The source remains consistent even when the interface consuming it changes.

Foundations

Stack, theme, tokens, spacing, radii, and project conventions.

Components

Files, variants, states, tokens, and implementation coverage.

Decisions

One versioned record for each architectural choice and its reason.

Refinements

Approved exceptions that preserve the context behind intentional drift.

Project structuremy-app

whale.config.json
CLAUDE.md
AGENTS.md
intelligence/
  components.json
  decisions/
  refinements/
llm-wiki/

Experience

Four flows cover the project lifecycle

The command model separates setup, adoption, synchronization, and validation. Each command answers one clear user need and keeps automation predictable.

The four Whale Igniter commands and what each one does
Command	Flow
`whale ignite my-app`	Start with shared context Creates foundations, agent instructions, project intelligence, and a readable wiki for a new project.
`whale adopt`	Bring an existing repo in Scans the codebase and proposes components and foundations for review before writing them.
`whale sync`	Keep every agent current Regenerates the wiki and instruction files for the configured coding agents.
`whale check`	Verify alignment Runs validation and project insights to reveal drift, gaps, and unresolved decisions.

Agent interface

Structured context through MCP

Agents can read project decisions before changing code and record useful knowledge while they work.

The MCP layer turns project intelligence into focused tools. An agent can request only the context needed for the current task instead of loading a full documentation set.

Tools the MCP layer exposes to a coding agent
Tool	Returns
`whale_project_overview`	Project stack, foundations, packs, and context
`whale_list_components`	Component files, variants, states, and tokens
`whale_list_decisions`	Architectural choices with rationale and status
`whale_list_refinements`	Approved exceptions and their context
`whale_insights`	Orphans, coverage gaps, tensions, and drift
`whale_record_decision`	A way for agents to preserve new knowledge

Verification

Check decisions against implementation

Whale reads CSS, JSX, Vue, and Svelte files to detect values that fall outside the project foundations. Current checks cover spacing, colors, and radii.

An intentional difference can be recorded as a refinement. The system preserves its reason and stops treating it as unexplained drift.

Verification outputwhale insights

$ whale insights drift spacing
  3 off-grid values found

$ whale insights drift color
  2 raw colors outside tokens

$ whale insights drift radii --review
  review, accept, or queue each issue

Outcome

A public, local-first product

Whale Igniter reached version 1.6.3 through 22 published versions in its first two months.

Core workflows run offline and require no API key. The package has no telemetry, uses an MIT license, and keeps generated files under the user's control.

1.6.3

Current npm version

Published versions

Agent ecosystems supported

Telemetry in core workflows

Reflection

What this project explored

Agentic UX needs durable context, clear boundaries, and verifiable outputs.
Versioned files make AI-facing decisions reviewable through normal development workflows.
Deterministic local tools can support AI workflows without requiring an AI call for every task.
Approved exceptions are product knowledge and deserve the same care as formal standards.

Next direction

Continue improving project health insights, agent integrations, and the bridge between design foundations and implementation.

Next project

Batch Frame Creator

A Figma plugin that turns repetitive setup into one batch.