> ## Documentation Index > Fetch the complete documentation index at: https://docs.blink.so/docs/llms.txt > Use this file to discover all available pages before exploring further. # Planning Agent > Build a Blink agent that helps you clarify requirements, compare approaches, and break down complex work. ## Overview Blink lets you build an agent that acts as a planning partner. This type of agent can help you scope features, compare technical approaches, break down complex work into milestones, and de-risk decisions before you commit to building. This page shows you what's possible and provides prompts you can use in Edit Mode to build your own planning agent. ## Getting started 1. Create a new agent directory and run `blink init` 2. Start the dev server with `blink dev` 3. Press `Ctrl+T` to toggle to Edit Mode 4. Describe your planning agent using the ideas below ## What you can build Here are examples of what you can ask your planning agent to do once you've built it. These show the end result: scroll down to see how to build an agent that can handle these requests. ``` You are planning work for a small feature. Context: - Repo: - Area: notifications service (Go), stores messages in Postgres - Problem: daily summary email sometimes duplicates entries - Constraints: keep DB schema stable - Success: no duplicates; add an integration test; draft PR Task: Propose 2-3 approaches with trade-offs (risk, complexity, testability). Then propose a step-by-step plan for the lowest-risk path with clear acceptance criteria and a first milestone suitable for a small PR. ``` ``` We're evaluating background job frameworks. Context: - Framework: Node.js 20 - Current stack: Express, Prisma, Postgres - Needs: retries, delayed jobs, metrics, horizontal scaling Task: Compare BullMQ vs. Bree vs. Temporal (self-hosted). Provide: pros/cons, code snippets for a minimal worker, migration risk, and the safest recommendation for our team skill level. End with a suggested proof-of-concept plan (1-2 days). ``` ``` We need to add OAuth login to our application. Context: - Current: email/password only - Stack: Next.js 14, Prisma, PostgreSQL - Providers needed: Google, GitHub - Must maintain existing user sessions Task: Break this into small, shippable milestones. For each milestone, provide: what ships, acceptance criteria, risk level, and estimated size. Start with the smallest valuable increment. ``` ``` We're considering migrating from REST to GraphQL. Context: - Current: Express REST API with 50+ endpoints - Team: 3 backend engineers, familiar with REST - Clients: React web app, React Native mobile app - Timeline: need decision in 2 weeks Task: Identify the top 5 risks of this migration. For each risk, rate severity (1-5) and provide a mitigation strategy. Then recommend: full migration, partial migration, or stay with REST. Include a proof-of-concept plan to test the riskiest assumption. ``` ``` Users report intermittent 500 errors on checkout. Context: - Happens ~5% of the time - Stack: Python/Django, Redis for sessions, Stripe for payments - Error logs show "Connection timeout" from payment service - No pattern in time of day or user type Task: Propose 3 hypotheses for the root cause, ranked by likelihood. For the most likely cause, provide: diagnostic steps, temporary mitigation, permanent fix plan, and testing strategy. ``` ## Building your planning agent Switch to Edit Mode (`Ctrl+T`) and use these prompts to build your agent. Copy and customize them based on what you want your agent to do. You don't need to use all of these prompts. Start with 2-3 that match your needs, test the agent, then add more capabilities as needed. ### Make it analyze trade-offs ``` When I describe a technical decision or feature, the agent should propose 2-3 different approaches. For each approach, provide: implementation complexity, risk level, performance implications, and maintenance burden. Always recommend the best option with clear reasoning. ``` ### Make it break down large features ``` When I describe a large feature, the agent should break it into small, shippable milestones. For each milestone: describe what ships, provide acceptance criteria, estimate complexity (small/medium/large), and identify risks. Always start with the smallest valuable increment. ``` ### Make it identify risks proactively ``` Before proposing any plan, the agent should identify top risks and unknowns. For each risk, rate severity (1-5) and suggest a mitigation strategy. If a risk is severe, recommend a proof-of-concept to validate assumptions before committing to the full build. ``` ### Make it ask clarifying questions ``` When I provide a vague request, the agent should ask clarifying questions before proposing solutions. It should ask about: constraints (time, resources, breaking changes), success criteria, team expertise, and whether this needs to integrate with existing systems. ``` ### Make it format plans consistently ``` When presenting a plan, the agent should use this structure: 1) Problem statement (2 sentences) 2) Recommended approach with reasoning 3) Step-by-step implementation plan 4) Acceptance criteria for each step 5) Risks and mitigation strategies 6) Suggested first milestone for a small PR ``` ### Make it reference code structure ``` Give the agent access to read files in the codebase. When planning work, it should reference specific files, functions, and patterns that already exist. It should suggest solutions that match the existing code style and architecture. ``` ### Make it estimate scope realistically ``` The agent should estimate work in T-shirt sizes (XS, S, M, L, XL) based on: lines of code, number of files touched, testing complexity, and integration points. Flag any work larger than M and suggest breaking it down further. ``` ### Make it suggest proof-of-concepts ``` For any risky or uncertain technical decision, the agent should suggest a time-boxed proof-of-concept (1-3 days max). The POC should test the riskiest assumption and produce clear success/failure criteria. ``` ### Make it compare frameworks and tools ``` When evaluating technical options (frameworks, libraries, services), the agent should compare them on: learning curve, community support, performance, cost, and migration risk. Provide code snippets showing how each option would work in our stack. ``` ### Make it create debugging plans ``` When I describe a bug, the agent should propose 3-5 hypotheses ranked by likelihood. For the most likely cause, provide: diagnostic steps to confirm, temporary mitigation, permanent fix plan, and testing strategy to prevent regression. ``` ## How it works behind the scenes When you use the prompts above, Edit Mode automatically implements the right tools for your agent. You don't need to code anything; just describe what you want. Common tools include: * **File reading** - Access codebase to understand existing patterns * **Web search** - Research frameworks, libraries, and best practices * **Code analysis** - Identify complexity and integration points * **Structured output** - Format plans with consistent structure Edit Mode handles all the technical implementation. Your job is to describe the agent's planning behavior and decision-making process. ## Iterating on your agent As you test, you'll discover what works and what needs adjustment. Use these Edit Mode prompts to refine your agent's behavior: ``` The agent should be more specific. Every plan must include: exact file paths for changes, specific function or component names, and clear acceptance criteria that can be tested. No hand-waving or "implement the feature" steps. ``` ``` The agent should calibrate its estimates based on our team velocity. Ask me for feedback: was this estimate accurate? Use that feedback to adjust future estimates. Err on the side of smaller chunks. ``` ``` Every plan must include a risks section. The agent should proactively identify: breaking changes, performance impacts, security implications, and dependencies on other systems. Never present a plan without discussing risks. ``` ``` Before proposing any solution, the agent must confirm: what problem are we actually solving? What constraints exist? What's the success criteria? If I provide an unclear request, push back and ask clarifying questions. ``` ``` Every recommendation must explain WHY, not just WHAT. Compare options explicitly: "Option A is better than Option B because..." Always tie recommendations back to our constraints and goals. ``` ## Advanced capabilities Once your basic agent works well, consider these enhancements: ``` Add a memory system that tracks past technical decisions and their outcomes. When proposing new approaches, reference similar decisions we've made before. Learn from what worked and what didn't. Let me ask "show me similar decisions we've made" at any time. ``` ``` Connect to Jira, Linear, or GitHub Issues. When breaking down features, create actual tickets with proper formatting. Update ticket descriptions as the plan evolves. Link related tickets and track dependencies. ``` ``` Track how long previous features actually took vs. initial estimates. Use this data to calibrate future estimates. If our velocity is 20 story points per sprint, flag any plan that exceeds that and suggest breaking it down. ``` ``` For major technical decisions, generate RFC (Request for Comments) documents with: problem statement, proposed solutions, trade-off analysis, open questions, and decision criteria. Format it ready to share with the team. ``` ## Tips for success **When you're building:** * Start with basic trade-off analysis and milestone breakdown * Give Edit Mode examples of good plans you've created before * Test the agent on real planning scenarios from your backlog * Iterate based on whether the plans feel actionable **When you're ready to scale:** * Add codebase reading so plans reference actual code * Integrate with your project management tools * Build in memory to learn from past decisions * Share the agent with your team for consistent planning Focus on getting the core planning behavior right first. You can always add sophistication like velocity tracking or RFC generation later.