Go to home

SKILL.md

Implementation Planning for AI Agent Execution

Overview

Plan your implementation approach before writing code. This creates a structured execution roadmap for you (the AI agent) to follow, ensuring you make key technical decisions upfront and implement in the right order.

Output: An execution plan you'll follow to implement the specification. Use bd tool to tracks the plan. See the references/bd-instructions.md and learn how to use the tool.

Planning Process

1. Understand What You're Building

Read the specification completely. Understand requirements, constraints, success criteria, and scope. If anything is unclear, document questions before proceeding.

Identify the deliverable type:

  • API/backend service
  • Data pipeline or ETL
  • CLI tool or script
  • Frontend application
  • Infrastructure configuration
  • Integration layer
  • Library or module
  • workflow

Knowing what you're building shapes your approach.

2. Make Technical Decisions

Choose your implementation approach before coding. Do not generate multiple options to compare unless the best path is ambiguous.

Record your decisions for these key areas:

  • Core Architecture: (e.g., Monolith vs Microservices, Sync vs Async)
  • Tech Stack: (Language, Database, Frameworks)
  • Data Model: (Schema structure, Storage strategy)

For each decision, state:

  1. The Choice: What you selected.
  2. The Rationale: The specific requirement or constraint from the spec that dictated this choice.

3. Map Dependencies

Identify what must exist before you can implement certain parts.

External dependencies:

  • Third-party APIs you'll call use api-doc-retriever to get accurate info.
  • External services or databases
  • Required credentials or access
  • Data that must be available

Implementation order dependencies:

  • What must you build before other parts?
  • What can you build in parallel?
  • What's on the critical path?

If dependencies are missing:

  • Can you mock them for now?
  • Can you implement them yourself?
  • Do you need to request access?
  • Should you implement something else first?

4. Plan Implementation Order

Break the work into phases you'll execute sequentially.

Typical order:

  1. Setup: Project structure, dependencies, configuration
  2. Foundation: Core utilities, data models, error handling
  3. Core logic: Main functionality, business rules
  4. Integration: Connect to external systems
  5. Testing: Validation and test coverage
  6. Polish: Error messages, logging, documentation

Within each phase, order tasks by:

  • Dependencies (build foundations before dependent code)
  • Risk (tackle uncertain parts early to validate feasibility)
  • Validation (build in a way you can test incrementally)

For each implementation step, specify and record them as bd issues:

Title: [Desciptive name]
Description: [What you'll implement]
Design Notes: [Details like Files you'll create/modify]
Validation: [How you'll verify it works]
Dependencies: [What must exist first references to other issues]

Reference references/task-breakdown-examples.md for common patterns.

5. Identify Critical Unknowns

Identify parts of the specification that are ambiguous or technically uncertain.

For each unknown, add a specific task to your plan:

  • Unclear APIs/Integration: Add a Spike Task to "prototype integration with [Service]" early in the plan.
  • Performance Uncertainty: Add a Benchmark Task to validation criteria.
  • Ambiguous Requirements: Make a detailed technical assumption, document it, and proceed.

Rule: Do not list "risks." Convert every uncertainty into a Task (to find out) or an Assumption (to move forward).

6. Define Verification Steps

For each phase in your plan, define how you will prove it works immediately after building it.

Do not check for vague qualities (e.g., "Is code readable?"). Define executable verification actions:

  • Automated Tests: Create specific unit/integration tests (e.g., "Test calculate_total with empty input").
  • Reproduction Scripts: Create a script to trigger the new functionality.
  • Console Verification: A specific command to run and the expected output.

Rule: Every implementation task must include a "Validation" field with these specific steps.

7. Create Execution Roadmap

Document your plan in beads (bd).

This roadmap is for you, not for humans. It should guide your execution.

Usage Guidelines

Before you start coding:

  1. Read and understand the full specification
  2. Work through this planning process
  3. Create your execution plan
  4. Review it for completeness
  5. Then begin implementation following your plan

During implementation:

  • Follow your planned order
  • Validate at each checkpoint
  • Update plan if you discover issues
  • Document deviations and reasons

When facing uncertainty:

  • Prototype/spike the uncertain part first
  • Validate your approach before building on it
  • Update your plan based on what you learn

Adjust your plan as needed:

Plans change during implementation. That's normal. Update your plan when you discover:

  • Hidden complexity requiring different approach
  • Missing requirements needing clarification
  • Better technical approach than originally planned
  • Dependencies you hadn't identified

Execution Rules

Follow these strict constraints during planning and execution:

  1. No Code Without Plan: Do not generate implementation code until the full plan is recorded in bd.
  2. Spec Fidelity: Implement exactly what is specified. Do not add "nice-to-have" features or anticipate future needs.
  3. Living Plan: If you discover a better approach during implementation, update the plan (the bd issues) before writing the code.
  4. Validation First: Do not mark a task as "done" until its verification step has passed.

Reference Materials

references/task-breakdown-examples.md

Common implementation patterns broken into steps for APIs, data pipelines, frontends, infrastructure, and integrations.

references/bd-instructions.md

Instructions on how to use beads(bd) for planning

Notes

You are both planner and executor. The plan guides your execution. Make it useful for yourself.

Balance planning and execution. Spend 10-20% of total time planning, 80-90% implementing. Don't over-plan.

Validate as you go. Don't wait until the end to test. Build in validation checkpoints throughout.