Planner: The AI System That Reads Your Entire Codebase Before Writing a Single Line

The first rule of AI-powered development that nobody talks about: the quality of the output is determined by the quality of the plan, not the quality of the model.

Give a capable AI model a vague task description and it will produce vague, inconsistent results. Give it a precise, context-rich plan that accounts for the existing codebase, established patterns, dependency ordering, and potential failure modes, and it will produce work that looks like it came from someone who deeply understands the project.

Planner is our system for producing those plans. It reads every relevant file in your codebase before generating a single step. It mines patterns from existing code so new code matches what is already there. It decomposes tasks into dependency-aware directed acyclic graphs so steps execute in the right order. It spawns parallel execution teams for independent work streams. It tracks progress, detects drift, and auto-recovers from failures.

Planning is not a preliminary step we rush through to get to the "real work" of code generation. Planning IS the product. Everything downstream -- the code quality, the architectural consistency, the design system adherence -- flows from the quality of the plan.

---

Why Most AI Coding Workflows Fail

The typical AI coding workflow looks like this: a human describes a feature in natural language, an AI model generates code, someone reviews it, and maybe it gets deployed.

This workflow produces inconsistent results because it skips the step that every experienced developer performs instinctively: understanding the existing system before making changes.

A senior developer joining a new project spends days reading code before writing any. They learn the project's conventions: how files are organized, what naming patterns are used, which libraries handle which responsibilities, how the data flows, what the testing strategy is. They build a mental model of the system.

AI models do not do this by default. They generate code based on their training data and the immediate context in the prompt. They produce syntactically correct code that follows general best practices but may violate every convention in the specific project.

Planner solves this by making the "understand the system" step explicit and systematic.

---

The Six-Phase Analysis

When Planner receives a task, it runs a six-phase analysis before generating any steps.

Phase 1: Deep Read

Planner reads every relevant file in the project. Not just the files directly related to the task, but the surrounding context: configuration files, design system definitions, utility functions, type definitions, existing components with similar responsibilities, and documentation.

For a full project plan, this means reading dozens to hundreds of files. The system is built to handle this scale. Context windows are managed carefully, with files prioritized by relevance and summarized when full content would exceed limits.

Phase 2: Pattern Mining

After reading the code, Planner extracts the implicit conventions that no documentation captures:

• How are components structured? Single file or directory with index?
• What is the naming convention? PascalCase components, camelCase utils, kebab-case routes?
• How is state managed? Context, Zustand, URL state, server state?
• What error handling pattern is used? Try/catch, error boundaries, result types?
• How are API calls structured? Direct fetch, custom hooks, server actions?
• What is the testing pattern? Colocated tests, test directory, integration-first?

These patterns become constraints for every step in the plan. When MORPHEUS executes a step, it receives not just what to build but how to build it in a way that matches the existing codebase.

Phase 3: Vision Understanding

If product documents exist (PRD, design system specs, brand guidelines, UX backlogs), Planner ingests them. It understands not just what needs to be built technically but what the product should feel like to users.

This is where AI planning differs from traditional project management. Planner can synthesize technical constraints, design requirements, brand guidelines, and UX principles into a coherent plan that addresses all dimensions simultaneously.

Phase 4: Risk Assessment

Every step gets a risk assessment: what could go wrong? What is the blast radius if this step fails?

Steps that modify shared components or database schemas get flagged as high-risk because failures cascade. Steps that add new isolated features get flagged as low-risk. High-risk steps get additional verification requirements and are never parallelized with other high-risk steps.

Phase 5: Decomposition

The task gets decomposed into concrete steps using an adaptive layering system. Simple features might produce 5 steps. A full product build might produce 50 or more.

Each step specifies:

• A clear title and description
• The specific files to create or modify
• Context files to read before starting (relevant existing code)
• Dependencies on other steps (what must complete first)
• Estimated effort
• Risk level
• The type of agent best suited to execute it

Phase 6: DAG Construction

Steps are organized into a directed acyclic graph based on their dependencies. This is critical for parallel execution.

Consider building a dashboard feature. The data model step has no dependencies. The API routes depend on the data model. The UI components depend on the API routes. But the unit tests for the data model can run in parallel with the API routes, as long as the data model itself is done.

Planner's DAG captures these relationships precisely. When executed with team agents, independent branches of the graph run simultaneously while dependent steps wait for their prerequisites.

---

Mini-Plans vs Full Plans

Not every task needs a six-phase analysis and a 50-step DAG. Planner operates in two modes:

Mini-Plan Mode

For MEDIUM-complexity tasks (multi-file, known pattern, 5 to 30 minutes of work), Planner creates a lightweight tracker with 3 to 10 steps. No deep analysis. No team agents. Just a quick scan of relevant files, a sensible sequence of steps, and immediate execution.

Mini-plans are created in seconds and executed inline. They bring the benefits of structured planning (clear steps, progress tracking, session resume) without the overhead of full analysis.

Full Plan Mode

For COMPLEX and EPIC tasks, the full six-phase pipeline runs. This takes 2 to 5 minutes for analysis and produces a comprehensive plan with milestones, dependency graphs, risk assessments, and team agent assignments.

Full plans are stored in a .planner/ directory with machine-readable JSON. They can be paused, resumed, exported to Linear or GitHub, and compared between iterations.

---

Session Resume

One of the most practical features: Planner detects active plans on session start.

When you open a new session in a project that has an in-progress plan, Planner automatically shows:

• The task name and overall progress percentage
• How many steps are completed versus total
• What the next pending step is
• Whether any steps are blocked

You can continue from where the previous session left off, or start fresh (the old plan gets archived, not deleted). This means complex multi-session work does not lose context between sessions. The plan is the continuity mechanism.

For cross-project visibility, a global status command shows all active plans across every project. If you are managing multiple workstreams, you can see at a glance which projects have work in progress and how far along each one is.

---

Team Agent Orchestration

For EPIC tasks, Planner can spawn a team of Opus-class agents that execute steps in parallel.

The orchestration works like this:

1. Planner identifies which steps in the DAG can run simultaneously (no mutual dependencies)
2. It creates a team with TeamCreate
3. For each parallel-ready step, it dispatches an agent as a team member
4. Each agent receives the step context: what to build, which files to modify, which patterns to follow, which context files to read
5. Agents work independently, reporting completion through Nerve
6. When a step completes, Planner checks which downstream steps are now unblocked
7. Newly unblocked steps get dispatched to available agents
8. This continues until all steps are complete or a blocking failure occurs

The result is wall-clock time reduction proportional to the parallelism in the DAG. A plan with 20 steps might have 4 independent branches, reducing execution time by up to 75 percent compared to sequential execution.

---

Drift Detection

Code changes do not always follow the plan. A developer (human or AI) might modify files that the plan did not account for, or modify planned files in ways that diverge from the plan's assumptions.

Planner's drift detection compares the current state of the codebase against what the plan expected. When drift is detected:

• Modified files that are targets of upcoming steps get flagged
• The affected steps are marked for re-planning
• If drift is minor (formatting, comments), it gets noted but does not trigger re-planning
• If drift is significant (structural changes, new dependencies), the relevant portion of the plan gets regenerated

This prevents the common failure mode where a plan becomes stale because the codebase evolved underneath it.

---

Auto-Recovery

When a step fails during execution, Planner does not simply stop. It runs a recovery protocol:

1. Log the failure with full context (error message, file state, preceding steps)
2. Analyze the failure: was it a transient error (build flake, network issue) or a structural problem?
3. For transient errors: retry with the same context (maximum 3 attempts)
4. For structural errors: re-plan the failed step accounting for the new information
5. If re-planning produces a viable alternative: execute it
6. If the step is truly stuck after re-planning: mark it as blocked with evidence and continue with non-dependent steps

This means a plan with 30 steps does not grind to a halt because step 8 failed. The failure gets contained, documented, and either resolved automatically or isolated so the rest of the plan can continue.

---

Export and Integration

Plans are not locked inside Planner. They export to multiple formats:

• Markdown -- Human-readable plan documents for sharing with stakeholders
• CSV -- For importing into spreadsheets or project management tools
• Linear tickets -- Each step becomes a Linear issue with proper labels, estimates, and dependencies
• GitHub issues -- Each step becomes a GitHub issue linked to the repository
• Reusable templates -- A successful plan for "SaaS MVP" can be saved as a template and applied to the next SaaS project, with automatic adaptation to the new codebase

The template system is particularly valuable. After building several similar products, the plans stabilize into patterns. The tenth e-commerce checkout flow benefits from everything learned in the first nine.

---

Integration with AISB

Planner is KEYMAKER in the AISB hierarchy. When ORACLE classifies a task as COMPLEX or EPIC, KEYMAKER (Planner) is the first agent spawned.

The flow:

1. ORACLE classifies task as COMPLEX
2. ORACLE spawns KEYMAKER with the task description and project context
3. KEYMAKER runs the six-phase analysis and produces a plan
4. ORACLE receives the plan and begins dispatching MORPHEUS workers for each step
5. After each milestone, ORACLE optionally spawns SERAPH for quality audit
6. Progress is tracked through Nerve's task dependency system
7. On completion, SMITH captures the plan and execution data for future improvement

This tight integration means planning is not a separate workflow. It is a built-in phase of the execution pipeline, activated automatically when the task complexity warrants it.

---

Visualization

For complex plans, visual understanding matters. Planner generates:

• ASCII DAG -- A text-based dependency graph showing which steps depend on which, with status indicators (pending, in-progress, completed, blocked)
• Critical path -- The longest chain of dependent steps, which determines the minimum possible execution time
• Burndown chart -- ASCII burndown showing planned versus actual progress over time
• Estimation accuracy -- Retrospective comparison of estimated effort versus actual effort, used to improve future estimates

These are generated on demand and displayed in the terminal. No external tools required.

---

Lessons from Building This

Context is everything. The difference between a plan created with full codebase context and one created from just a task description is the difference between a senior developer's implementation plan and a generic to-do list. Investing 2 to 5 minutes in deep reading saves hours of rework during execution.

Dependency ordering prevents cascading failures. Our early planning attempts created flat lists of steps. Executing them in order worked until step 12 modified a shared component that step 3 through 11 had already used. DAGs with explicit dependencies eliminated this entire category of failures.

Mini-plans for everything. Full analysis for a small feature is overkill. But no planning at all for multi-file changes leads to inconsistency and missed dependencies. Mini-plans hit the sweet spot: enough structure to prevent mistakes, little enough overhead to feel natural.

Session resume is not optional. Complex tasks span multiple sessions. Without automatic plan detection and resume, context gets lost between sessions. Developers waste time reconstructing where they left off. Planner makes this a zero-cost operation.

---

Further Reading

• Hunt: The 15-Agent Debugging Pipeline -- How we verify what Planner builds
• AI Super Brain: 12-Agent Orchestration System -- The orchestration brain that activates Planner
• Multi-Agent Orchestration Production Guide -- Scaling agent systems in production