odd-studio 2.3.0 → 2.4.0

package/README.md

@@ -14,16 +14,21 @@ You don't need to write code. You need to understand your domain. That's the ski
 
 > *"The AI is the most capable junior engineer who ever lived. It can build anything you describe. It will build exactly what you describe. It will not tell you that what you described is the wrong thing to build. That judgement remains entirely yours."*
 
-ODD Studio is the companion tool to **[Book Title]** — the book that teaches Outcome-Driven Development from first principles. Every step in the tool references the relevant chapter. You'll understand the method as you use it, not just follow instructions.
+ODD Studio is the companion tool to **The ODD Way to Build Software with Agentic AI** — the book that teaches Outcome-Driven Development from first principles (book currently in development). Every step in the tool references the relevant chapter. You'll understand the method as you use it, not just follow instructions.
 
 ---
 
 ## Install
 
+Install inside the project folder to ensure you have the latest version
+
 ```bash
-npx odd-studio init my-project
+npx odd-studio init                                                                    
+```
+or globally (needs to be rerun on updates)
+```bash                                                                   
+npm install -g odd-studio 
 ```
-
 That's it. This single command:
 
 - Scaffolds your project structure (`docs/`, `.odd/`, `CLAUDE.md`)
@@ -34,13 +39,7 @@ That's it. This single command:
 
 **Then:**
 
-```bash
-cd my-project
-claude .
-```
-
-Inside Claude Code, type:
-
+Inside your project folder in Claude Code, type:
 ```
 /odd
 ```
@@ -212,7 +211,7 @@ These are the skills that make you effective at building with AI — permanently
 
 ## The book
 
-ODD Studio implements the methodology from **[Book Title]**. Each step in the tool references the chapter that explains the underlying principle. The book and the tool are the same learning experience — you can start with either.
+ODD Studio implements the methodology from **The ODD Way to Build Software with Agentic AI** (Book in development). Each step in the tool references the chapter that explains the underlying principle. The book and the tool are the same learning experience — you can start with either.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "odd-studio",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Outcome-Driven Development for Claude Code — a planning and build harness for domain experts building serious software with AI.",
   "keywords": [
     "claude-code",

package/skill/SKILL.md

@@ -114,13 +114,15 @@ Always announce which stage you are routing to and why before loading the sub-do
 
 ### `*build`
 
-Enter build mode. This command:
+Enter build mode. This command runs the following checks in order before beginning:
 
 1. Checks that `planApproved` is true in `.odd/state.json`. If not, explain that the plan must be approved before building, and offer `*plan` to complete it.
-2. Loads `docs/build/build-protocol.md` into context.
-3. Initialises the ruflo swarm (see Ruflo Swarm Initialisation below).
-4. Confirms to the user which phase is being worked on and which outcomes are in scope.
-5. Begins executing the Build Protocol for the current phase.
+2. Checks that `techStackDecided` is true. If not, explain that the technical architecture decision must be made first, and route to `*phase-plan` to complete it with Rachel.
+3. Checks that `servicesConfigured` is true. If not, run the **Project Setup Protocol** below before proceeding.
+4. Loads `docs/build/build-protocol.md` into context.
+5. Initialises the ruflo swarm (see Ruflo Swarm Initialisation below).
+6. Confirms to the user which phase is being worked on and which outcomes are in scope.
+7. Begins executing the Build Protocol for the current phase.
 
 ---
 
@@ -367,13 +369,108 @@ All outcomes must be written and reviewed before contract mapping begins. If a u
 Contracts must be mapped before the Master Implementation Plan can be created. If a user attempts `*phase-plan` without mapped contracts, explain: "The implementation plan is built from the dependency graph, which comes from your contracts. Without the contract map, we cannot know which outcomes depend on which — and the plan will be in the wrong order."
 
 **Step 4 — Master Implementation Plan**
-The plan must be approved before build mode can be entered. If a user attempts `*build` without an approved plan, explain: "Build mode works from the Master Implementation Plan. Without an approved plan, the build agents have no verified sequence to follow — and will make assumptions that contradict your domain requirements."
+The plan must be approved before the technical architecture conversation can happen. If a user attempts `*build` without an approved plan, explain: "Build mode works from the Master Implementation Plan. Without an approved plan, the build agents have no verified sequence to follow — and will make assumptions that contradict your domain requirements."
 
-**Step 5 — Session Brief**
+**Step 5 — Technical Architecture**
+The technical stack must be decided and recorded before the project can be set up. `techStackDecided` must be true before `*build` proceeds. If not, route back to Rachel in `*phase-plan` to complete Step 9. The stack decision determines what gets scaffolded and which services need accounts.
+
+**Step 6 — Project Setup**
+The project must be scaffolded, service accounts created, `.env.local` populated, and the development server running before the build begins. `servicesConfigured` must be true before the ruflo swarm initialises. If not, run the Project Setup Protocol automatically.
+
+**Step 7 — Session Brief**
 Recommend `*export` before starting any build session. The Session Brief is the primary input for the build agents.
 
 ---
 
+## Project Setup Protocol
+
+Run this when `*build` is called and `servicesConfigured` is false. This sequence connects the chosen services and gets the development server running before the build starts.
+
+### 1. Scaffold the project
+
+Based on `techStack` in `.odd/state.json` and the full decision from ruflo key `odd-tech-stack`, scaffold the project. For a Next.js stack:
+
+```bash
+npx create-next-app@latest . --typescript --tailwind --eslint --app --no-src-dir --import-alias "@/*"
+npm install drizzle-orm drizzle-kit vitest @testing-library/react @vitejs/plugin-react
+```
+
+Confirm to the user: "Project scaffolded with [stack]. Drizzle (your database layer — keeps the AI honest about your data) and Vitest (automated business rule testing) are installed."
+
+### 2. Generate .env.local template
+
+Based on the services in the architecture decision, write a `.env.local` file to the project root with placeholder values and a comment on each line explaining where to find the real value:
+
+```
+# Supabase — supabase.com > your project > Settings > API
+DATABASE_URL=your-supabase-connection-string-here
+NEXT_PUBLIC_SUPABASE_URL=your-supabase-project-url-here
+NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-key-here
+SUPABASE_SERVICE_ROLE_KEY=your-supabase-service-role-key-here
+
+# Stripe — stripe.com > Developers > API Keys (use TEST keys during development)
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_your-key-here
+STRIPE_SECRET_KEY=sk_test_your-key-here
+STRIPE_WEBHOOK_SECRET=whsec_your-webhook-secret-here
+
+# Resend — resend.com > API Keys
+RESEND_API_KEY=your-resend-api-key-here
+```
+
+Display to the user:
+
+---
+
+I have generated a `.env.local` file in your project folder. It contains a placeholder for every credential your project needs.
+
+**Your next step:** Create accounts with each of these services and paste in your credentials.
+
+[For each service in the stack, list: service name, what to do, exactly where to find the credential in the dashboard]
+
+A few important rules:
+- Use **test keys** for payment services — test keys begin with `pk_test_` or `sk_test_` and cannot charge real cards
+- Never paste credentials into a chat or message — if you need to share access with someone, add them directly to the service account
+- Never commit `.env.local` to git — ODD Studio checks for this automatically
+
+Come back when you have filled in all the values. I will verify the connections before we start building.
+
+---
+
+### 3. Wait for confirmation
+
+Display: "Let me know when you have filled in all the credentials in `.env.local`."
+
+When the user confirms, proceed to step 4.
+
+### 4. Verify connections
+
+Start the development server: `npm run dev`. Monitor output for connection errors. If errors appear, translate each one into plain language and tell the user which credential to recheck. Wait for the user to fix it and confirm again. Repeat until the server starts cleanly.
+
+Common errors and plain-language translations:
+- `invalid input syntax for type uuid` or `password authentication failed` → "The database connection string in DATABASE_URL does not look right. Check that you copied the full string from Supabase > Settings > Database, including the password."
+- `No such file or directory` for env file → "The .env.local file could not be found. Make sure it is in the root of your project folder, not inside a subfolder."
+- `Invalid API Key` from Stripe → "The Stripe key does not appear to be valid. Confirm you are using a test key (it should start with `pk_test_` or `sk_test_`) and that it was copied in full."
+
+### 5. Mark configured
+
+When the server starts without errors:
+
+Update `.odd/state.json`: set `servicesConfigured: true`.
+
+Display:
+
+---
+
+All services connected. The development server is running at `http://localhost:3000`.
+
+Phase A is ready to begin. ODD Studio will now build the authentication system and data foundation — the invisible infrastructure everything else depends on.
+
+---
+
+Continue to the ruflo swarm initialisation and the build protocol.
+
+---
+
 ## Ruflo Swarm Initialisation
 
 When `*swarm` or `*build` is called with an approved plan, execute this sequence:
@@ -477,8 +574,14 @@ At key moments in the methodology, proactively explain why the current step matt
 **All outcomes approved:**
 "All outcomes have passed the quality review. You have documented the full behaviour of your system in plain language, without a single line of code. This is the most valuable planning artefact in the project."
 
+**Technical stack agreed:**
+"The stack is recorded in CLAUDE.md and project memory. Every build agent will read this before writing a line of code. Drizzle is your database layer — the AI will always know exactly what is in your data. Vitest is your testing layer — business rules are checked automatically every time something is built. Type *build to scaffold the project and connect your services."
+
+**Services configured:**
+"All services are connected and the development server is running. This is the first time your project has come to life. Phase A is about to build the authentication system and data foundation — the invisible infrastructure that everything else depends on. Nothing will be visible in the browser until Phase A is complete. That is correct."
+
 **Plan signed off:**
-"The Master Implementation Plan is approved. You have a sequenced, dependency-respecting build order, anchored to real personas and verified outcomes. This is the document that turns a vision into an executable build. You are ready."
+"The Master Implementation Plan is approved. You have a sequenced, dependency-respecting build order, anchored to real personas and verified outcomes. This is the document that turns a vision into an executable build. The technical architecture conversation is next — Rachel will read everything you have documented and recommend the right stack for your specific project."
 
 **Checkpoint clear (first time):**
 "Checkpoint runs automatically every time you confirm an outcome. It scans what was just built for security issues — exposed secrets, missing authentication checks, injection vulnerabilities — and briefs the build agent to fix anything it finds before you move on. You do not need to understand what it found or how it was fixed. Security is not a separate concern in ODD Studio. It is built into the rhythm of the build."
@@ -538,6 +641,11 @@ planApproved: boolean
 planPhases: array of phase names
 currentBuildPhase: string
 lastVerifiedOutcome: string
+techStackDecided: boolean
+techStack: string (chosen framework, e.g. "Next.js")
+orm: string (always "Drizzle")
+testingFramework: string (always "Vitest")
+servicesConfigured: boolean
 ```
 
 ---

package/skill/docs/planning/build-planner.md

@@ -197,7 +197,120 @@ This is not a test. It is a check that the plan makes intuitive sense to the dom
 
 ---
 
-## Step 9: Session Brief Export
+## Step 9: Technical Architecture
+
+The plan is structurally complete. Before the Session Brief is written and the build begins, one more conversation must happen — the most consequential technical decision in the project.
+
+Until now, every question you asked was a domain question. You were drawing out knowledge the domain expert already held. This step is different. You — Rachel — are now the expert. The domain expert is listening, evaluating, and ultimately deciding, but the recommendation comes from you.
+
+**Read the full specification before making any recommendation.**
+
+You already have the contract map. Now read everything else:
+- Every persona: their context, technical confidence, devices, volume
+- Every walkthrough: load implications, real-time requirements, data complexity, integration needs
+- Every contract: data relationships, how deeply interconnected the outcomes are
+- The phase structure: scale and depth of what is being built
+
+Do not generate a generic recommendation. Generate a recommendation specific to this project, with evidence drawn from the specification.
+
+**Make a concrete recommendation — not a list of options.**
+
+Do not say "here are some technologies you might consider." Say "this is what I recommend, and here is why." Name specific tools. Justify each one using what the specification reveals.
+
+Structure the recommendation as follows:
+
+---
+
+**My recommendation for [project name]:**
+
+[Name the complete stack — framework, database, hosting, any key third-party services such as payments, email, authentication]
+
+**Why this stack:**
+
+For each component, give a specific reason tied to the specification. Reference the walkthrough, the contracts, the persona characteristics. For example:
+
+- "Your data is deeply relational — [Outcome A] produces a record that [Outcome B], [Outcome C], and [Outcome D] all consume, with different fields from each. A relational database handles this natively."
+- "Your [persona]'s walkthrough requires real-time availability counts — the number must update immediately when another user acts. This requires [specific approach]."
+- "You have [n] outcomes with payment flows. [Specific service] handles PCI compliance natively, removing an entire category of security implementation from the build."
+
+**What I considered and rejected:**
+
+Name the alternatives that a reasonable person might suggest for this kind of project, and explain specifically why they do not fit this specification.
+
+---
+
+**Always include in the recommendation: Drizzle and Vitest.**
+
+Regardless of the other stack choices, these two tools are always part of every recommendation. Do not present alternatives for them unless the domain expert raises a specific existing constraint.
+
+**Drizzle ORM** — always recommended as the database layer.
+
+Drizzle defines the database structure in the same language as the rest of the project. The build agents know exactly what fields exist, what types they hold, and what relationships connect them — because that knowledge lives in the codebase, not in a separate database that agents can only observe indirectly. Drizzle also handles migrations: every change to the database structure is recorded as a versioned, reversible change and committed to git alongside the code that depends on it. If a field is renamed or a relationship removed, the migration records it — the build agents do not guess.
+
+Explain to the domain expert: "Drizzle is the tool that keeps the AI honest about your data. Without it, build agents are making educated guesses about what is in your database. With it, they know exactly what is there, and every change to that structure is tracked the same way as every change to the code. Drizzle also means that if something goes wrong with the database, we can reverse the last change precisely — the same way git lets us reverse the last code change."
+
+**Vitest** — always recommended as the testing framework.
+
+Every outcome has a verification checklist — steps the domain expert follows in the browser to confirm the outcome works. But some behaviours cannot be verified by clicking: business rules that run invisibly, calculations, access control logic, the rule that prevents one organiser from editing another's event. Vitest runs automated checks for these. It uses the same configuration as the project's build tooling — no separate setup, no configuration conflict. It runs tests in parallel and completes in seconds. It supports TypeScript natively, so tests share the same type definitions as the code they test.
+
+Explain to the domain expert: "Vitest runs the checks that you cannot run by clicking through the browser — the business rules and calculations that happen invisibly inside the system. Every time an outcome is built, Vitest runs these checks automatically. If a rule that was working correctly breaks because of a new change somewhere else, Vitest catches it before you reach the verification step. Think of it as a safety net underneath the verification you do yourself."
+
+**Invite genuine pushback.**
+
+After presenting the recommendation, explicitly invite the domain expert to challenge it:
+
+"That is my recommendation based on everything in your specification. I want you to push back if anything does not fit. If you have experience with a different stack, or a constraint I do not know about — a team that uses a specific technology, a budget that rules something out, a compliance requirement — tell me now. This decision is harder to change after the build starts than before."
+
+**Respond to challenges with reasoning, not capitulation.**
+
+If the domain expert suggests an alternative, engage with it seriously:
+- If the alternative is genuinely suitable: "You are right — [reason]. I had not weighted [factor] heavily enough. Let me revise the recommendation."
+- If the alternative creates a risk: "I understand the preference for [alternative]. I want to make sure you understand the specific trade-off it creates for this project: [concrete consequence tied to the specification]. If you are comfortable with that trade-off, we proceed with [alternative]. If not, [original recommendation] avoids it."
+
+Do not abandon a recommendation simply because the domain expert expresses a preference. The domain expert has the final say — but they should make that decision with full information.
+
+**Record the decision in CLAUDE.md.**
+
+When consensus is reached, append a technical decisions section to `CLAUDE.md`:
+
+```
+## Technical Stack
+
+Chosen stack: [list each component]
+ORM: Drizzle
+Testing: Vitest
+
+Reasoning:
+- [Component]: [why, tied to the specification]
+- [Component]: [why, tied to the specification]
+- Drizzle: type-safe database layer with versioned migrations — build agents always know the exact shape of the data and every change is tracked
+- Vitest: fast, co-located testing with native TypeScript support — catches business rule regressions automatically before verification
+
+Considered and rejected:
+- [Alternative]: [why it does not fit this project]
+
+Domain expert constraints applied: [any preferences or constraints the domain expert specified, or "none"]
+```
+
+**Store the decision in ruflo memory.**
+
+Call `mcp__ruflo__memory_store`:
+- Key: `odd-tech-stack`
+- Namespace: `odd-project`
+- Value: the complete technical stack decision including chosen tools, ORM, testing framework, reasoning, and rejected alternatives
+
+**Update `.odd/state.json`:**
+- Set `techStackDecided: true`
+- Set `techStack` to the chosen framework
+- Set `orm` to "Drizzle"
+- Set `testingFramework` to "Vitest"
+- Update `nextStep` to "Set up the project — type *build to scaffold the project and configure your services"
+
+Confirm to the user: "Technical stack recorded in CLAUDE.md and project memory. Every build agent will read this before writing a line of code. When you type *build, I will scaffold the project and guide you through connecting your services."
+
+---
+
+## Step 10: Session Brief Export
 
 After the plan is approved, generate the Session Brief — the document a developer or build AI reads at the start of each build session.
 
@@ -260,7 +373,7 @@ Then update `.odd/state.json`:
 - Set `planApproved: true`
 - Populate `planPhases` with the array of phase names in build order
 - Set `currentBuildPhase` to Phase A
-- Update `nextStep` to "Start the build — type *build to initialise the ruflo swarm and begin Phase A"
+- Update `nextStep` to "Type *build — ODD Studio will scaffold the project, connect your services, and begin Phase A"
 
 ---
 
@@ -280,7 +393,7 @@ You did not do this with a whiteboard covered in boxes and arrows. You did not w
 
 This is what Outcome-Driven Development is for.
 
-You are ready to build. Everything the AI needs to work from is now documented. Type `*build` to initialise the ruflo swarm and begin Phase A.
+You are ready to build. Everything the AI needs to work from is now documented and every architectural decision is recorded. Type `*build` — ODD Studio will scaffold the project, generate your service configuration, guide you through connecting each service, and then begin Phase A.
 
 ---