refactor: rename planning terminology to plan

Rename 'planning' to 'plan' throughout the codebase to match OpenCode's
built-in agent naming conventions (plan, build, evaluation).

Changes:
- planningModel → planModel (config, types, CLI)
- --planning-model → --plan-model (CLI flag)
- OPENCODER_PLANNING_MODEL → OPENCODER_PLAN_MODEL (env var)
- Phase 'planning' → 'plan' (types, state)
- generatePlanningPrompt → generatePlanPrompt (plan.ts)
- generateIdeaPlanningPrompt → generateIdeaPlanPrompt (plan.ts)
- runPlanning → runPlan (builder.ts)
- runIdeaPlanning → runIdeaPlan (builder.ts)
- runPlanningPhase → runPlanPhase (loop.ts)
- Updated all docs, tests, and example config
- Updated release.yml workflow for Bun cross-compilation

Signed-off-by: leocavalcante <[email protected]>

Author: leocavalcante

.github/workflows/release.yml

@@ -14,40 +14,41 @@ jobs:
       matrix:
         include:
           - os: ubuntu-latest
-            target: x86_64-linux
-            artifact: opencoder-linux-amd64
+            target: bun-linux-x64
+            artifact: opencoder-linux-x64
           - os: ubuntu-latest
-            target: aarch64-linux
+            target: bun-linux-arm64
             artifact: opencoder-linux-arm64
           - os: macos-latest
-            target: x86_64-macos
-            artifact: opencoder-macos-amd64
+            target: bun-darwin-x64
+            artifact: opencoder-darwin-x64
           - os: macos-latest
-            target: aarch64-macos
-            artifact: opencoder-macos-arm64
+            target: bun-darwin-arm64
+            artifact: opencoder-darwin-arm64
     runs-on: ${{ matrix.os }}
 
     steps:
       - uses: actions/checkout@v4
 
-      - name: Setup Zig
-        uses: mlugg/setup-zig@v2
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
         with:
-          version: 0.15.2
+          bun-version: latest
 
-      - name: Build release
-        run: zig build -Doptimize=ReleaseSafe -Dtarget=${{ matrix.target }}
-
-      - name: Rename binary
-        run: mv zig-out/bin/opencoder ${{ matrix.artifact }}
+      - name: Install dependencies
+        run: bun install
 
-      - name: Strip binary
-        if: matrix.os == 'ubuntu-latest'
-        run: strip ${{ matrix.artifact }}
+      - name: Build release
+        run: bun build --compile --minify --target=${{ matrix.target }} src/index.ts --outfile ${{ matrix.artifact }}
 
-      - name: Calculate checksum
+      - name: Calculate checksum (Linux)
+        if: runner.os == 'Linux'
         run: sha256sum ${{ matrix.artifact }} > ${{ matrix.artifact }}.sha256
 
+      - name: Calculate checksum (macOS)
+        if: runner.os == 'macOS'
+        run: shasum -a 256 ${{ matrix.artifact }} > ${{ matrix.artifact }}.sha256
+
       - name: Upload artifact
         uses: actions/upload-artifact@v4
         with:
@@ -67,15 +68,16 @@ jobs:
           merge-multiple: true
 
       - name: Create checksums.txt
+        working-directory: artifacts
         run: cat *.sha256 > checksums.txt
 
       - name: Create release
         uses: softprops/action-gh-release@v2
         with:
           files: |
-            opencoder-linux-amd64
-            opencoder-linux-arm64
-            opencoder-macos-amd64
-            opencoder-macos-arm64
-            checksums.txt
+            artifacts/opencoder-linux-x64
+            artifacts/opencoder-linux-arm64
+            artifacts/opencoder-darwin-x64
+            artifacts/opencoder-darwin-arm64
+            artifacts/checksums.txt
           generate_release_notes: true

AGENTS.md

@@ -258,7 +258,7 @@ describe("module", () => {
 ### Environment Variables
 
 ```bash
-OPENCODER_PLANNING_MODEL=anthropic/claude-sonnet-4
+OPENCODER_PLAN_MODEL=anthropic/claude-sonnet-4
 OPENCODER_BUILD_MODEL=anthropic/claude-sonnet-4
 OPENCODER_VERBOSE=true
 OPENCODER_MAX_RETRIES=3
@@ -271,7 +271,7 @@ OPENCODER_TASK_PAUSE_SECONDS=2
 
 ```json
 {
-  "planningModel": "anthropic/claude-sonnet-4",
+  "planModel": "anthropic/claude-sonnet-4",
   "buildModel": "anthropic/claude-sonnet-4",
   "verbose": false,
   "maxRetries": 3,
@@ -288,7 +288,7 @@ opencoder --model anthropic/claude-sonnet-4
 # With project directory and hint
 opencoder -m anthropic/claude-sonnet-4 -p ./myproject "focus on tests"
 
-# Different models for planning and build
+# Different models for plan and build
 opencoder -P anthropic/claude-opus-4 -B anthropic/claude-sonnet-4
 
 # Verbose output
@@ -302,19 +302,19 @@ Opencoder includes an **ideas queue system** that allows users to provide specif
 ### How It Works
 
 1. **Ideas Directory**: `.opencoder/ideas/` - Users place `.md` files here
-2. **Planning Integration**: Before each planning cycle, the loop checks for ideas
+2. **Plan Integration**: Before each plan cycle, the loop checks for ideas
 3. **Selection Logic**:
    - **1 idea**: Used directly (no AI selection call)
    - **2+ ideas**: AI evaluates all and picks the simplest/quick-win considering dependencies
 4. **Build**: Selected idea is deleted, plan is created from idea content
-5. **Fallback**: When ideas are exhausted, returns to autonomous planning
+5. **Fallback**: When ideas are exhausted, returns to autonomous plan
 
 ### Key Modules
 
 - **`ideas.ts`**: Core module with `Idea` interface, `loadAllIdeas()`, `formatIdeasForSelection()`
-- **`plan.ts`**: Contains `generateIdeaSelectionPrompt()` and `generateIdeaPlanningPrompt()`
-- **`builder.ts`**: Has `runIdeaSelection()` and `runIdeaPlanning()` methods
-- **`loop.ts`**: Integrates ideas check before planning phase
+- **`plan.ts`**: Contains `generateIdeaSelectionPrompt()` and `generateIdeaPlanPrompt()`
+- **`builder.ts`**: Has `runIdeaSelection()` and `runIdeaPlan()` methods
+- **`loop.ts`**: Integrates ideas check before plan phase
 
 ### Selection Criteria
 
@@ -351,7 +351,7 @@ bun run dev -- -m anthropic/claude-sonnet-4 -p test-project
 ### Implementation Notes
 
 - Ideas take **full precedence** over user hints
-- Idea files are **deleted before planning** (prevents retry loops)
+- Idea files are **deleted before plan** (prevents retry loops)
 - Empty/invalid ideas are **automatically cleaned up**
 - No naming conventions required - any `.md` file works
 

README.md

@@ -8,8 +8,8 @@
 
 - **Autonomous Development Loop** - Continuously plans, builds, and evaluates without stopping
 - **OpenCode SDK Integration** - Direct SDK integration with real-time event streaming
-- **Ideas Queue** - Drop markdown files in `.opencoder/ideas/` to prioritize specific tasks before autonomous planning
-- **Two-Model Architecture** - Uses a high-capability model for planning and a faster model for building
+- **Ideas Queue** - Drop markdown files in `.opencoder/ideas/` to prioritize specific tasks before autonomous plan
+- **Two-Model Architecture** - Uses a high-capability model for plan and a faster model for building
 - **Live Output Streaming** - Real-time display of AI thinking, tool calls, and results
 - **State Persistence** - Resumes from where it left off after interruptions (JSON format)
 - **Exponential Backoff** - Graceful retry logic for transient failures
@@ -57,7 +57,7 @@ Instead of interactive sessions where you guide the AI, OpenCoder creates an *au
 
 ### The Philosophy
 
-OpenCoder treats software development as an **infinite game**. There's always another test to write, another edge case to handle, another optimization to make. OpenCoder embraces this by never declaring "done"—it continuously cycles through planning, building, and evaluation until you tell it to stop.
+OpenCoder treats software development as an **infinite game**. There's always another test to write, another edge case to handle, another optimization to make. OpenCoder embraces this by never declaring "done"—it continuously cycles through plan, build, and evaluation until you tell it to stop.
 
 ## Installation
 
@@ -111,19 +111,19 @@ opencoder --model anthropic/claude-sonnet-4
 opencoder -m anthropic/claude-sonnet-4 -p ./myproject "build a REST API"
 ```
 
-### With Different Planning and Build Models
+### With Different Plan and Build Models
 
 ```bash
-# Use a more capable model for planning, faster model for building
+# Use a more capable model for plan, faster model for building
 opencoder -P anthropic/claude-opus-4 -B anthropic/claude-sonnet-4
 ```
 
 ### Options
 
 | Flag | Description |
 |------|-------------|
-| `-m, --model MODEL` | Model for both planning and build (provider/model format) |
-| `-P, --planning-model MODEL` | Model for planning/evaluation phases |
+| `-m, --model MODEL` | Model for both plan and build (provider/model format) |
+| `-P, --plan-model MODEL` | Model for plan/evaluation phases |
 | `-B, --build-model MODEL` | Model for build phase |
 | `-p, --project DIR` | Project directory (default: current directory) |
 | `-v, --verbose` | Enable verbose logging |
@@ -155,7 +155,7 @@ OpenCoder implements an **agentic development loop** with three phases:
                     (start new cycle)
 ```
 
-1. **Planning Phase** - Analyzes the project and creates a markdown checklist with 3-7 actionable tasks
+1. **Plan Phase** - Analyzes the project and creates a markdown checklist with 3-7 actionable tasks
 2. **Build Phase** - Works through each task sequentially, making code changes
 3. **Evaluation Phase** - Reviews completed work and decides whether to start a new cycle (COMPLETE/NEEDS_WORK)
 
@@ -169,7 +169,7 @@ Create an `opencoder.json` in your project directory:
 
 ```json
 {
-  "planningModel": "anthropic/claude-sonnet-4",
+  "planModel": "anthropic/claude-sonnet-4",
   "buildModel": "anthropic/claude-sonnet-4",
   "verbose": false,
   "maxRetries": 3,
@@ -182,7 +182,7 @@ Create an `opencoder.json` in your project directory:
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `OPENCODER_PROJECT_DIR` | `$PWD` | Default project directory |
-| `OPENCODER_PLANNING_MODEL` | - | Model for planning phase |
+| `OPENCODER_PLAN_MODEL` | - | Model for plan phase |
 | `OPENCODER_BUILD_MODEL` | - | Model for build phase |
 | `OPENCODER_VERBOSE` | `false` | Enable verbose logging |
 | `OPENCODER_MAX_RETRIES` | `3` | Max retries per operation |
@@ -272,7 +272,7 @@ opencoder -m anthropic/claude-sonnet-4
    - **1 idea**: Uses it directly (no extra API call)
    - **2+ ideas**: AI evaluates all and picks the simplest/quick-win, considering dependencies
 3. **Build** - Selected idea is deleted, plan is created specifically for it
-4. **Fallback** - When ideas are exhausted, returns to autonomous planning
+4. **Fallback** - When ideas are exhausted, returns to autonomous plan
 
 ### Selection Criteria
 

opencoder.json.example

@@ -1,6 +1,6 @@
 {
-  "planningModel": "anthropic/claude-sonnet-4",
-  "executionModel": "anthropic/claude-sonnet-4",
+  "planModel": "anthropic/claude-sonnet-4",
+  "buildModel": "anthropic/claude-sonnet-4",
   "verbose": false,
   "maxRetries": 3,
   "backoffBase": 10,

src/builder.ts

@@ -8,9 +8,9 @@ import type { Logger } from "./logger.ts"
 import {
 	extractPlanFromResponse,
 	generateEvaluationPrompt,
-	generateIdeaPlanningPrompt,
+	generateIdeaPlanPrompt,
 	generateIdeaSelectionPrompt,
-	generatePlanningPrompt,
+	generatePlanPrompt,
 	generateTaskPrompt,
 } from "./plan.ts"
 import type { BuildResult, Config } from "./types.ts"
@@ -68,12 +68,12 @@ export class Builder {
 	}
 
 	/**
-	 * Run the planning phase
+	 * Run the plan phase
 	 */
-	async runPlanning(cycle: number, hint?: string): Promise<string> {
-		this.logger.header(`CYCLE ${cycle} - PLANNING PHASE`)
+	async runPlan(cycle: number, hint?: string): Promise<string> {
+		this.logger.header(`CYCLE ${cycle} - PLAN PHASE`)
 
-		const prompt = generatePlanningPrompt(cycle, hint)
+		const prompt = generatePlanPrompt(cycle, hint)
 
 		// Create a new session for this cycle
 		const session = await this.client.session.create({
@@ -87,8 +87,8 @@ export class Builder {
 		this.sessionId = session.data.id
 		this.logger.logVerbose(`Created session: ${this.sessionId}`)
 
-		// Send the planning prompt
-		const result = await this.sendPrompt(prompt, this.config.planningModel, "Planning")
+		// Send the plan prompt
+		const result = await this.sendPrompt(prompt, this.config.planModel, "Planning")
 
 		return extractPlanFromResponse(result)
 	}
@@ -131,7 +131,7 @@ export class Builder {
 
 		const prompt = generateEvaluationPrompt(cycle, planContent)
 
-		return await this.sendPrompt(prompt, this.config.planningModel, "Evaluating")
+		return await this.sendPrompt(prompt, this.config.planModel, "Evaluating")
 	}
 
 	/**
@@ -156,7 +156,7 @@ export class Builder {
 			const result = await this.sendPromptToSession(
 				tempSessionId,
 				prompt,
-				this.config.planningModel,
+				this.config.planModel,
 				"Selecting",
 			)
 			return result
@@ -171,13 +171,13 @@ export class Builder {
 	}
 
 	/**
-	 * Run planning for a specific idea
+	 * Run plan for a specific idea
 	 */
-	async runIdeaPlanning(ideaContent: string, ideaFilename: string, cycle: number): Promise<string> {
-		this.logger.header(`CYCLE ${cycle} - IDEA PLANNING`)
+	async runIdeaPlan(ideaContent: string, ideaFilename: string, cycle: number): Promise<string> {
+		this.logger.header(`CYCLE ${cycle} - IDEA PLAN`)
 		this.logger.info(`Planning for: ${ideaFilename}`)
 
-		const prompt = generateIdeaPlanningPrompt(ideaContent, ideaFilename, cycle)
+		const prompt = generateIdeaPlanPrompt(ideaContent, ideaFilename, cycle)
 
 		// Create a new session for this cycle
 		const session = await this.client.session.create({
@@ -191,7 +191,7 @@ export class Builder {
 		this.sessionId = session.data.id
 		this.logger.logVerbose(`Created session: ${this.sessionId}`)
 
-		const result = await this.sendPrompt(prompt, this.config.planningModel, "Planning")
+		const result = await this.sendPrompt(prompt, this.config.planModel, "Planning")
 
 		return extractPlanFromResponse(result)
 	}

src/cli.ts

@@ -21,16 +21,16 @@ export async function run(): Promise<void> {
 		.version(VERSION)
 		.argument("[hint]", "Optional hint/instruction for the AI")
 		.option("-p, --project <dir>", "Project directory (default: current directory)")
-		.option("-m, --model <model>", "Model for both planning and build (provider/model format)")
-		.option("-P, --planning-model <model>", "Model for planning phase (provider/model format)")
+		.option("-m, --model <model>", "Model for both plan and build (provider/model format)")
+		.option("-P, --plan-model <model>", "Model for plan phase (provider/model format)")
 		.option("-B, --build-model <model>", "Model for build phase (provider/model format)")
 		.option("-v, --verbose", "Enable verbose logging")
 		.action(async (hint: string | undefined, opts: Record<string, unknown>) => {
 			try {
 				const cliOptions: CliOptions = {
 					project: opts.project as string | undefined,
 					model: opts.model as string | undefined,
-					planningModel: opts.planningModel as string | undefined,
+					planModel: opts.planModel as string | undefined,
 					buildModel: opts.buildModel as string | undefined,
 					verbose: opts.verbose as boolean | undefined,
 				}
@@ -49,33 +49,33 @@ export async function run(): Promise<void> {
 		`
 Examples:
   $ opencoder --model anthropic/claude-sonnet-4
-    Run with Claude Sonnet for both planning and build
+    Run with Claude Sonnet for both plan and build
 
   $ opencoder -m anthropic/claude-sonnet-4 "build a REST API"
     Run with a specific hint/instruction
 
   $ opencoder -P anthropic/claude-opus-4 -B anthropic/claude-sonnet-4
-    Use different models for planning and build
+    Use different models for plan and build
 
   $ opencoder -m openai/gpt-4o -p ./myproject -v
     Run with verbose logging in a specific directory
 
 Options:
     -p, --project <dir>         Project directory (default: current directory)
-    -m, --model <model>         Model for both planning and build
-    -P, --planning-model        Model for planning phase
+    -m, --model <model>         Model for both plan and build
+    -P, --plan-model            Model for plan phase
     -B, --build-model           Model for build phase
     -v, --verbose               Enable verbose logging
 
 Environment variables:
-    OPENCODER_PLANNING_MODEL    Default planning model
+    OPENCODER_PLAN_MODEL        Default plan model
     OPENCODER_BUILD_MODEL       Default build model
     OPENCODER_VERBOSE           Enable verbose logging (true/1)
     OPENCODER_PROJECT_DIR       Default project directory
 
 Config file (opencoder.json):
     {
-      "planningModel": "anthropic/claude-sonnet-4",
+      "planModel": "anthropic/claude-sonnet-4",
       "buildModel": "anthropic/claude-sonnet-4",
       "verbose": false
     }