Mastering `cm-planning`: The Complete Guide

The greatest trap in the modern era of “Vibe Coding” is not the lack of talent or the limitations of LLMs—it is the seductive lure of the Immediate Implementation. You have an idea, your adrenaline is spiking, and you prompt the AI: “Build me a real-time dashboard with telemetry.” Within seconds, you have 400 lines of code. It looks perfect. You run it. It crashes. You ask for a fix. The AI changes three files. Now the authentication is broken. Two hours later, you are trapped in a “hallucination loop,” wondering where your afternoon went.

This is the “Vibe Coding Tax.” It is the price we pay for skipping the architectural phase. To solve this, we don’t need to return to the slow, bureaucratic waterfall methods of the 1990s. We need a modern, AI-native protocol for thinking before doing. This is where cm-planning comes in.

In this guide, we will explore why cm-planning is the most critical skill in your Vibe Coding arsenal and how to use it to transform “AI-assisted chaos” into “architectural mastery.”

The Core Problem: Epistemic Drift in AI Sessions

When you start a coding session with an AI, you are managing “Epistemic Quality.” At the start, the AI knows the codebase (if you’ve provided context), but it doesn’t know your unspoken intent. If you jump straight to implementation, the AI makes a thousand micro-decisions on your behalf—variable naming, state management patterns, error handling strategies—without checking if they align with your long-term goals.

By the time you notice a mistake, the “state” of the conversation has drifted. The AI is now trying to fix code it shouldn’t have written in the first place. cm-planning is the circuit breaker for this drift. It forces a “Design-First” gate that ensures the AI understands the What, the Why, and the How before it touches a single semicolon.

What is `cm-planning`?

cm-planning is a specialized skill within the Todyle/Cody Master ecosystem designed to facilitate Intent Exploration and Plan Documentation. It is a mandatory gate for any creative work or multi-step task. Instead of generating code, it generates a task_plan.md—a contract between you and the AI.

How It Works: The Three Pillars of Planning

The cm-planning workflow is built on three distinct pillars that move the project from a vague “vibe” to a concrete “execution.”

1. Intent Discovery (The “Why”)

Before deciding how to build a feature, the agent must understand the business logic and the user’s ultimate goal. If you say, “I want a button that exports data,” cm-planning won’t just suggest a React component. It will ask:

What format? (CSV, JSON, PDF?)
Is it client-side or server-side?
What happens if the dataset is 100,000 rows? (Memory constraints?)

2. Architectural Reduction (The “What”)

Once the intent is clear, the agent maps the request against your existing tech stack. It identifies which files need to be modified, which new services need to be created, and—crucially—what can be removed or simplified. This prevents “feature creep” where the AI adds unnecessary libraries or complexity.

3. The Execution Blueprint (The “How”)

The output of a cm-planning session is not code; it is a structured, markdown-based plan. This plan includes:

Requirements: A checklist of functional goals.
Design Decisions: Explicit choices about architecture (e.g., “We will use the Strangler Fig pattern for this refactor”).
Implementation Steps: A logical sequence of atomic tasks.
Verification Gates: How we will prove each step works (TDD, linting, manual checks).

Practical Example: Building a “Smart SEO Injector”

Let’s look at cm-planning in action. Imagine you are working on an Astro-based project and you want to implement a system that dynamically injects SEO metadata based on the content of a page.

The “Vibe” Approach (High Risk)

User: “Add SEO metadata to my pages based on the content.” AI Response: Generates a massive SEO.astro component and starts modifying every page file simultaneously. It forgets to handle OpenGraph tags and breaks the build because it didn’t account for Astro’s content.config.ts.

The `cm-planning` Approach (High Success)

User: activate_skill("cm-planning") -> “I want to add dynamic SEO metadata to my Astro pages.”

The AI’s Thinking Process:

Research: It reads astro.config.mjs and src/content.config.ts.
Inquiry: It asks: “Should we pull keywords from the frontmatter or use an AI-based extraction? Do we need to support Twitter Cards?”
Drafting: It proposes a plan.

The Resulting `task_plan.md`:

# Plan: Dynamic SEO Injection System

## 1. Requirements
- Automatically generate Meta Title and Description.
- Support OpenGraph (Facebook) and Twitter Card tags.
- Fallback to global defaults if frontmatter is missing.

## 2. Architecture
- **Component:** Create `src/components/SEO.astro`.
- **Logic:** Centralize metadata resolution in a utility `src/utils/seo-resolver.ts`.
- **Integration:** Inject into `src/layouts/BaseLayout.astro`.

## 3. Implementation Steps
- [ ] Task 1: Create `seo-resolver.ts` with unit tests for edge cases (long titles).
- [ ] Task 2: Create `SEO.astro` component utilizing the resolver.
- [ ] Task 3: Modify `BaseLayout.astro` to accept `seoProps`.

## 4. Verification
- Run `npm run test` for resolver logic.
- Run `astro check` to ensure type safety.
- Visual check of `<head>` tags in dev mode.

By approving this plan, you have given the AI a “definition of done.” If the AI deviates, you can point back to the plan and say, “Wait, we agreed on Task 1 first.”

Interactive Guide: How to Invoke Mastery

To get the most out of cm-planning, you must treat the AI as a Senior Architect, not a junior coder. Here is the step-by-step interactive protocol:

Step 1: The Activation

Start your session by explicitly calling for the planning gate.

“I have a complex feature to implement. Before you write any code, I want to use cm-planning to explore the requirements and document a task plan.”

Step 2: The “Thinking” Dialogue

The agent will likely ask 3-5 clarifying questions. Do not give short, one-word answers. Use this time to transfer your “vibe” into the context. Explain the constraints. Mention that you hate a certain library or that you want to prioritize performance over readability.

Step 3: Reviewing the Blueprint

When the agent presents the plan, look for “Atomic Failures.” If a task looks too big (e.g., “Implement the whole backend”), ask the agent to break it down. A good task should take no more than 5 minutes for an AI to execute.

Step 4: The Commitment

Once you are satisfied, give the command:

“The plan looks solid. Save this as docs/plan/feature-x.md and let’s begin with Task 1.”

Best Practices & Pro-Tips

1. Never Code in Silence

If the AI starts writing code without a plan, stop it. Every line of “unplanned” code is a liability. It might work now, but it adds to the “context rot” that makes the AI stupider later in the session.

2. The “Design-First” Rule

Use cm-planning to decide on the UI before the logic. If you are building a dashboard, have the agent describe the layout and the components in the plan. This ensures the frontend doesn’t become an afterthought.

3. Identify “Sharp Edges”

During the planning phase, ask the agent: “What are the ‘sharp edges’ of this implementation? Where is it most likely to fail?” This prompts the agent to consider race conditions, API rate limits, or browser compatibility issues before they happen.

4. Parallel Research is a Planning Step

If you are using a new library (e.g., “I want to use framer-motion for this”), the plan should include a research task.

Task 0: Research framer-motion documentation for “Layout Animations.” This ensures the AI isn’t hallucinating API signatures from 2022.

5. Document “Non-Goals”

A great plan doesn’t just say what it will do; it says what it won’t do.

“Non-goal: We are NOT implementing user authentication in this PR. Use a mock user object for now.” This keeps the AI focused and prevents it from wandering into unrelated parts of the codebase.

Troubleshooting the Planning Phase

“The AI’s plan is too vague.”

Solution: Ask for a “Technical Specification” first. Tell the agent: “Before the task plan, write a 2-paragraph technical spec on how you will handle state management for this feature.”

“The AI is suggesting a massive refactor for a small feature.”

Solution: Use the “Architectural Reduction” prompt. Say: “I want the ‘Minimum Viable Refactor.’ How can we implement this with the least amount of change to the existing structure?”

“I’ve already started coding, can I still use this?”

Solution: Yes. Use the “Reverse Plan” technique. Say: “We’ve made some progress, but I feel we’re losing the vibe. Stop coding. Analyze our current changes and generate a cm-planning task plan to get us to the finish line.”

Conclusion: From Vibe to Velocity

Vibe Coding is powerful because it removes the friction between thought and creation. However, without a steering mechanism, that power leads to a crash. cm-planning is the steering wheel.

By adopting a “Plan-First” discipline, you aren’t slowing down; you are removing the rework. You are ensuring that every token spent on code generation is a token spent on the correct code. You move from being a “Prompt Engineer” who hopes for the best, to a “Vibe Architect” who commands the outcome.

Next time you feel the urge to say “Just build it,” take a breath, activate cm-planning, and build the blueprint first. Your future self (and your Git history) will thank you.

Mastering cm-planning: The Complete Guide