Project name: AltoiDDD — CLI command: alto

Your AI builds apps fast. alto makes sure they don't fall apart.

AI coding tools (Cursor, Claude Code, OpenCode, Roo Code) are amazing at writing code. You type "build me an invoice app" and get a working prototype in minutes.

But here's what nobody tells you: that prototype becomes unmaintainable within weeks.

Why? Because the AI jumped straight to writing code without understanding:

• What your business actually does
• Which parts are complex and which are simple
• Where the boundaries should be so changes don't break everything

And even when you do plan, your plans go stale. You finish researching one piece and the findings change everything else — but nobody updates the other tasks. Your team (human or AI) starts work based on outdated context, and the problems compound.

The result: you ship fast, then spend months fixing things — or throw it away and start over.

alto is the planning step that happens before coding starts. Think of it as hiring a senior architect who:

1. Listens to your idea — You describe what you want in 4-5 plain sentences
2. Asks the right questions — Not "what framework?" but "what does your business do? what are the rules? what changes often?"
3. Draws the blueprint — Which parts of your app should be separate, how they connect, what the rules are
4. Creates a build plan — Ordered tasks that tell your AI tool exactly what to build, in what order, with tests already defined
5. Sets up guardrails — Automated checks that catch mistakes before they become problems

Then you hand it to Cursor, Claude Code, or any AI tool — and it builds within the guardrails, not from scratch on a blank canvas.

# Starting a new project
alto init

# Already have a project that's gotten messy? Apply structure to it
alto init --existing

# Check if your documentation is still accurate
alto doc-health

# Check if knowledge about AI tools is still fresh
alto kb drift

alto init guides you through everything. It shows you what it will do, asks you to confirm, and never touches files without your permission.

alto maintains knowledge about AI tool conventions (Claude Code, Cursor, Roo Code, OpenCode). This knowledge needs to stay fresh because these tools update frequently.

# Check all tools for stale knowledge
alto kb drift

# Check a specific tool
alto kb drift claude-code

By default, knowledge entries are considered stale after 14 days (2 weeks). This aggressive threshold exists because AI tools like Claude Code and Cursor typically release updates weekly, and convention changes can break your configurations.

Download the latest binary for your platform from the releases page:

# macOS (Apple Silicon)
curl -L -o /usr/local/bin/alto https://github.com/jaigouk/altoiddd/releases/latest/download/alto-darwin-arm64
chmod +x /usr/local/bin/alto

# macOS (Intel)
curl -L -o /usr/local/bin/alto https://github.com/jaigouk/altoiddd/releases/latest/download/alto-darwin-amd64
chmod +x /usr/local/bin/alto

# Linux (amd64)
curl -L -o /usr/local/bin/alto https://github.com/jaigouk/altoiddd/releases/latest/download/alto-linux-amd64
chmod +x /usr/local/bin/alto

On Windows, download alto-windows-amd64.exe from the releases page and add it to your PATH.

go install github.com/jaigouk/altoiddd/cmd/alto@latest

Or build from the repo:

git clone https://github.com/jaigouk/altoiddd.git
cd altoiddd
make release
./bin/alto version

This produces two binaries in bin/:

• alto — CLI tool
• alto-mcp — MCP server for AI tool integration

Your idea (a few sentences)
     |
     v
alto runs a Domain Storytelling conversation about your business
     |
     v
Creates a blueprint: what belongs together, what stays separate
     |
     v
Generates a build plan: tasks in the right order, with tests
     |
     v
Configures your AI tool with your specific rules and language
     |
     v
Your AI tool builds it — correctly, within guardrails
     |
     v
Task completed? alto flags affected tasks for review
     |
     v
Your plan stays fresh — no stale context, no outdated assumptions

Every other tool starts writing code immediately. alto starts by understanding your business through Domain Storytelling — proposing concrete stories about how your system works, then refining them with you. The 20 minutes of storytelling saves you 20 hours of rewrites.

alto doesn't just write rules in a document — it creates automated tests that catch mistakes. If anyone (human or AI) writes code that crosses a boundary, the test fails. Your architecture enforces itself.

After planning, you get an ordered list of tasks. Each task tells you:

• What to build
• What test to write first
• What "done" looks like
• What must be built before it

No guessing. No jumping ahead. Just follow the list.

alto is not another AI coding tool. It's the prep work for the tool you already use. It generates configuration files in your tool's native format — so Claude Code, Cursor, or any other tool understands your project's rules from the start.

This is the one nobody else does. When you complete a task, alto automatically flags every related task that might be affected.

Here's the problem: you finish a research spike and discover the architecture needs to change. But five other tasks were written assuming the old architecture. Every project management tool (Jira, Linear, GitHub) only detects staleness by time — "this ticket hasn't been touched in 30 days." None of them detect staleness by event — "the thing this ticket depends on just changed."

alto does. When a task closes, it:

• Traverses the dependency graph to find affected open tasks
• Records what changed (the context diff) so reviewers know what's different
• Flags those tasks as needing review
• Shows you exactly what might need updating and lets you decide

No more starting work based on outdated assumptions. No more discovering mid-sprint that the plan changed three tickets ago.

Already have a codebase that's become hard to change? alto init --existing analyzes what you have, identifies the problems, and creates a step-by-step migration plan — all on a separate branch. Your existing code is never touched until you approve every change.

• You see everything before it happens — Nothing runs without your OK
• Your files are never overwritten — Conflicts get renamed, never replaced
• Existing projects stay safe — Always works on a new branch, never on your main code
• Your tests must still pass — If anything breaks, everything rolls back automatically

• Go 1.26+
• golangci-lint (for linting)
• gofumpt (for formatting)

make build      # Quick build (no optimization)
make test       # Run tests with race detector
make lint       # Run golangci-lint
make check      # All quality gates: build → vet → test → lint → deadcode
make ci         # Alias for check (CI-friendly)
make fmt        # Format code with gofumpt
make clean      # Remove build artifacts

Go implementation complete. Core CLI commands (init, doc-health, detect) are functional.

Apache-2.0