How to Create Custom Plans with “plan.md” in Goose

What is Goose?
Goose is a developer agent that enhances software development by automating coding tasks within your terminal or IDE. Guided by your input, it intelligently analyzes your project’s needs, generates the necessary code, and implements changes autonomously. When working with Goose, having a structured way to guide its execution toward specific goals is essential. This is where the plan.md file comes in. A plan.md file allows you to define a customized plan for Goose, using flexible text formatting and the power of Jinja templating to create dynamic, reusable, and goal-oriented plans.

How to Set Up Goose
Before creating your custom plan.md file, you need to set up Goose.

Step1: Fork the Goose and Goose Plugin repositories on GitHub and clone them.

Step2: Install Homebrew — Visit brew.sh and follow the installation steps, or run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Step3: To install Goose, use pipx. First ensure pipx is installed:

brew install pipx
pipx ensurepath

Step4: Then install Goose:

pipx install goose-ai

Step 5: Start a session — From your terminal, navigate to the directory you’d like to start from and run:

goose session start

Goose works with your preferred LLM. By default, it uses openai as the LLM provider. You'll be prompted to set an API key.

What Are “plan.md”Files?

The plan.md file is a text file that serves as a blueprint for Goose to follow. It consists of two essential components:

A kickoff message that sets the context and overall goal
A structured list of tasks for Goose to execute.

Why Use plan.md file?

• Customization:
  You can tailor Goose’s actions for specific tasks or projects.

• Reusability:
  Templates make it easy to reuse and modify plans for similar goals.

• Clarity:
  Outlining goals and steps ensures better control and predictability.

Creating Your First plan.md File

Let’s say you want Goose to help set up a new design system. Here’s an example of how your plan.md might look:

Your goal is to set up a fresh design system for our app's redesign.

- Create folders for design components (buttons, forms, colors)
- Set up color palette based on brand guidelines
- Create typography styles for headings and body text
- Design basic button components with all states
- Create form elements (inputs, dropdowns)

See those dashes (-) at the start of each line in the tasks? Super important! Goose looks for these to understand what steps it needs to take. To run Goose with this plan:

goose session start --plan plan.md

Using Jinja Templating in Plans
Jinja is a templating engine that allows you to embed variables, loops, and conditionals directly in your text files. With Jinja, you can make plan.md files dynamic and adaptable.

Key Jinja Syntax

• Variables: {{ variable }}

• Loops: {% for item in list %}...{% endfor %}

• Conditionals: {% if condition %}...{% endif %}

Remember our plan.md file, here’s what an enhanced version using jinja templating would look like.

# Design System Setup Plan for {{ brand_name }}

## Goal
Set up a fresh design system for the {{ project_name }} app's redesign.

---

## Steps to Follow

### 1. Create Folders
Organize design components into well-structured folders:
- **Buttons:** Include all button components and their states (default, hover, active, disabled).
- **Forms:** Include inputs, dropdowns, checkboxes, and radio buttons.
- **Colors:** Store primary, secondary, and accent color palettes.

### 2. Set Up Color Palette
Define a consistent color palette adhering to the brand guidelines:
- **Primary Color:** {{ primary_color }} 
- **Secondary Color:** {{ secondary_color }}
- **Accent Colors:** {{ accent_colors | join(", ") }}
- **Neutral Colors:** Add greys, whites, and blacks for backgrounds and borders.
- **Accessibility:** Ensure color contrast meets accessibility standards (WCAG).

### 3. Create Typography Styles
Define text styles for the app:
- **Headings:** {{ heading_styles | join(", ") }} 
- **Body Text:** Include base styles, captions, and links.
- **Font Guidelines:** Use {{ font_family }} with font sizes ranging from {{ font_sizes | join(", ") }}.

### 4. Design Button Components
Design the following button states:
- Default
- Hover
- Active
- Disabled

Ensure all buttons are:
- **Responsive:** Scalable across device sizes.
- **Accessible:** Incorporate clear focus states for keyboard navigation.

### 5. Create Form Elements
Design essential form components:
- Input Fields (default, focused, error)
- Dropdowns (expanded, collapsed)
- Checkboxes and Radio Buttons (checked, unchecked, disabled)
- Submit Buttons (loading, error)

---

## Additional Notes
- Test designs for usability and accessibility before finalizing.

Passing Arguments to Plan
Arguments can be passed into a plan.md file during execution. For example, to make our design system setup plan dynamic and reusable, we use Jinja templating, which allows us to pass arguments that customize the content based on specific projects, brands, or design requirements. By passing different sets of arguments, we can easily generate personalized plans for any redesign or product.

Example: Passing Arguments with Jinja

Define the Data: The first step is to prepare the data you want to pass into the template. This includes values like the brand name, colors, typography styles, and other design-specific details.

{
    "brand_name": "AwesomeApp",
    "project_name": "AwesomeApp Redesign",
    "primary_color": "#3498db",
    "secondary_color": "#2ecc71",
    "accent_colors": ["#e74c3c", "#9b59b6", "#f1c40f"],
    "heading_styles": ["H1 (32px)", "H2 (24px)", "H3 (20px)"],
    "font_family": "Roboto, sans-serif",
    "font_sizes": ["12px", "14px", "16px", "18px", "24px", "32px"],
}

To run Goose with this plan and arguments, you would run the following command:

goose session start --plan plan.md --args brand_name=AwesomeApp,project_name="AwesomeApp Redesign",primary_color="#3498db",secondary_color="#2ecc71",accent_colors="#e74c3c,#9b59b6,#f1c40f",heading_styles="H1 (32px),H2 (24px),H3 (20px)",font_family="Roboto, sans-serif",font_sizes="12px,14px,16px,18px,24px,32px"

Goose will populate the placeholders in plan.md with these values.

# Design System Setup Plan for AwesomeApp

## Goal
Set up a fresh design system for the AwesomeApp Redesign app's redesign.

---

## Steps to Follow

### 1. Create Folders
Organize design components into well-structured folders:
- **Buttons:** Include all button components and their states (default, hover, active, disabled).
- **Forms:** Include inputs, dropdowns, checkboxes, and radio buttons.
- **Colors:** Store primary, secondary, and accent color palettes.

### 2. Set Up Color Palette
Define a consistent color palette adhering to the brand guidelines:
- **Primary Color:** #3498db
- **Secondary Color:** #2ecc71
- **Accent Colors:** #e74c3c, #9b59b6, #f1c40f
- **Neutral Colors:** Add greys, whites, and blacks for backgrounds and borders.
- **Accessibility:** Ensure color contrast meets accessibility standards (WCAG).

### 3. Create Typography Styles
Define text styles for the app:
- **Headings:** 
  - H1 (32px)
  - H2 (24px)
  - H3 (20px)
- **Font Family:** Roboto, sans-serif
- **Font Sizes:** 
  - 12px
  - 14px
  - 16px
  - 18px
  - 24px
  - 32px

### 4. Design Button Components
Design the following button states:
- Default
- Hover
- Active
- Disabled

Ensure all buttons are:
- **Responsive:** Scalable across device sizes.
- **Accessible:** Incorporate clear focus states for keyboard navigation.

### 5. Create Form Elements
Design essential form components:
- Input Fields (default, focused, error)
- Dropdowns (expanded, collapsed)
- Checkboxes and Radio Buttons (checked, unchecked, disabled)
- Submit Buttons (loading, error)

---

## Additional Notes
- Test designs for usability and accessibility before finalizing.

Best Practices and Tips

• Define Clear Goals: Ensure each plan starts with a clear objective.
• Use Reusable Templates: Create general templates that can be customized for different projects.
• Document Assumptions: Add comments or notes to explain placeholders and structure.
• Test Small Changes: Validate each change in the plan.md file to ensure correct rendering.

Conclusion
The plan.md file is a versatile tool for guiding Goose's execution in achieving your goals. By combining clear objectives, structured steps, and dynamic Jinja templating, you can create reusable and highly customizable plans. Whether you're improving a mobile app's UX or tackling a complex project, plan.md empowers you to provide clarity, adaptability, and precision to Goose.