crisp-execute

CRISP — The Mileva Method

A BA/PM framework for AI implementors. Go from vague client brief to Claude Code-ready spec — without building the wrong thing.

Most AI implementations fail before a single line of code is written. Not because the model was wrong. Not because the tools weren't good enough. Because nobody defined the problem. Nobody measured the baseline. Nobody asked why before asking how.

You're an AI implementor. You know how to build. You probably even know which tools to use. What you might not have — yet — is the methodology to make sure you're building the right thing.

This is that methodology.

---

→ START HERE

---

What is CRISP?

CRISP is an open-source AI project management framework for builders, consultants, and AI agencies. It's a structured 5-phase methodology that takes you from a vague client request to a fully specced, Claude Code-ready implementation brief — before a single line of code gets written.

Built for:

• AI agency owners running client implementations
• Solo builders using Claude Code, Cursor, or similar agentic tools
• Consultants who need a repeatable discovery-to-spec process
• Product managers working on AI-native products

---

What's new in V2

V2 makes CRISP a system, not a collection of prompts. Everything that was previously reliant on discipline is now enforced by structure.

/crisp-orchestrator — new recommended entry point

Replaces the manual "which phase am I on?" problem. Detects docs/crisp-state.json, reports current phase and open questions, routes automatically. Works for new projects and resumption.

crisp-state.json — machine-readable project state

One JSON file in docs/ updated at the end of each phase. Every phase reads it first; every phase writes to it on exit. Claude stops re-interpreting markdown it half-remembered from Phase C when it's in Phase S.

New mandatory Phase S outputs

• Logging spec (docs/logging-spec.md) — log levels, PII rules, format, destination. Mandatory, not optional.
• Bearer security scanning — Critical/High findings block PR merge. Enforced as a hard gate, not a suggestion.
• Analytics spec (docs/analytics-spec.md) — GA4 event map tied directly to Phase R success metrics. External UI products only.
• Landing page brief (docs/landing-page-brief.md) — compiled from VPC, market research, UX discovery. For external products, landing page build is MVP-tagged — not a post-launch afterthought.
• Agent security spec (docs/agent-security.md) — AIUC-1-aligned. Mandatory when an agent is in scope. Covers identity/permissions, data handling, failure modes.
• Progress report (docs/progress-report.md) — handoff artifact for clients and continuity across sessions.

Improved Phase S elicitation

• OSS library research — structured GitHub evaluation for every open source dependency before committing. Stars, last commit, license, alternatives rejected with reason.
• Data mapping elicitation — mandatory section in Phase I/S for features involving structured data extraction or transformation. Source → field mapping → DB schema → edge cases.
• Spec→Sprint transition — Phase S now explicitly tells you to say "Start Sprint 1." No mode switching, no new setup.

Decision log across all phases

docs/decisions.md — every key decision logged with rationale and what was rejected. Auditable. Protects you when client asks "why did you build it this way?"

Memory ownership question

New field in Phase C (problem-statement.md) and Phase S tech stack: does the client require portability of agent memory across platforms? Surfaces before the contract is signed.

Backward compatibility

Nothing breaks. /crisp-start still works. All phase skills behave exactly as before. If no crisp-state.json exists, every phase falls back gracefully. V2 adds structure on top — it doesn't remove anything.

---

Why CRISP exists

Every AI project failure I've seen had the same root cause.

Builder gets a brief → skips straight to the stack → builds something technically impressive → delivers it → client says "this isn't what I meant."

Six weeks. Wasted.

The gap isn't in the build. It's in everything before it. CRISP fills that gap with a repeatable, client-tested process — from problem definition to sprint-ready AI specs.

---

The CRISP principles

Elicit, don't interrogate. Every question in CRISP follows the same pattern: pre-fill from what you already know, present a hypothesis, let the client correct. People react better than they originate. Corrections surface real intent faster than open questions.

Every document has an upstream source. Nothing is invented twice. Every deliverable is derived from prior phase outputs — not created from scratch. The data pipeline is explicit: you know exactly where each field comes from.

Pre-fill synthesis, elicit discovery. Documents that compile prior decisions are pre-filled and confirmed. Documents that surface new information (stakeholder impacts, hidden risks, unstated goals) get active elicitation moves before confirmation.

No spec = no build. Claude Code never touches a sprint without a locked AI Spec. Every open question in the spec must be resolved before the sprint starts. A spec with unanswered questions is a wishlist, not a brief.

Version everything. Claude defaults to its training data. Pinned versions in the tech stack table — and version rules in CLAUDE.md — are the only way to prevent silent drift.

Security is not optional. API keys never touch the client. All 3rd party credentials stay server-side. Bearer runs on every PR — Critical/High findings block merge. These rules ship in every project's CLAUDE.md from day one.

---

How to use

1. Drop the /.claude/skills folder into your Claude Code project
2. Run /crisp-orchestrator to start a new project or resume an existing one — detects where you are automatically
3. Use /templates as your deliverable starting points — fill outputs into docs/ in your project, never overwrite the blank templates
4. Run phases in order — do not skip
5. Check the exit checklist before moving to the next phase
6. Write one AI Spec per sprint before building anything
7. After Phase S: just say "Start Sprint 1" — Claude Code reads the AI Spec and starts building. No new setup needed.

---

How it connects

Every phase feeds the next. Nothing lives in isolation.

C — Clarify
  problem-statement ─────────────────────────────────────────────────────────┐
  buy-vs-build-matrix ────────────────────────────────────────────