jimiryquai/pi-agent/plan

Create a plan for a new feature or bug fix

Introduction

Note: The current year is 2026. Use this when dating plans and searching for recent documentation.

Transform feature descriptions, bug reports, or improvement ideas into well-structured markdown files issues that follow project conventions and best practices. This command provides flexible detail levels to match your needs.

Feature Description

<feature_description> #$ARGUMENTS </feature_description>

If the feature description above is empty, ask the user: "What would you like to plan? Please describe the feature, bug fix, or improvement you have in mind."

Do not proceed until you have a clear feature description from the user.

Phase 1: Context and Persona

1. Assign Persona: This skill is a collaboration between the researcher and the architect.
2. Researcher Phase:

• Scan for existing requirements in docs/brainstorms/.
• Use the `search_learnings` tool to find institutional knowledge (gotchas, patterns) related to this feature.
• Read the full contents of any relevant matches with `read_learning`.
• Summarize the "AS-IS" state of the codebase relevant to this feature.

1. Architect Phase:

• Transform requirements and research into a technical implementation plan.
• Design the schema and file architecture.

Phase 2: Create the Plan

Write or update a plan in docs/plans/. Use the format: YYYY-MM-DD-NNN-<type>-<kebab-case-title>-plan.md.

Document structure:

---
title: [Issue Title]
type: [feat|fix|refactor]
status: active
date: YYYY-MM-DD
origin: docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md  # if originated from a requirements doc, otherwise omit
---
 
# [Issue Title]
 
## Overview
[Comprehensive description]
 
## Proposed Solution
[High-level approach]
 
## Technical Considerations
-Architecture impacts
-Schema changes
-Security/Performance considerations
 
## Acceptance Criteria
-[ ] Detailed requirement 1
-[ ] Detailed requirement 2
-[ ] Integration testing requirements
 
## Implementation Units
1.[Unit 1]: [Goal] -> [Files]
2.[Unit 2]: [Goal] -> [Files]
 
## Sources & References
-**Origin document:** [docs/brainstorms/path]
-Similar implementations: [file_path:line_number]

Phase 3: Handoff

Present next steps using the platform's blocking question tool:

• Proceed to work (Recommended) - Run /work
• Review and refine - Improve the document
• Done for now - Return later

If user selects "Proceed to work (Recommended)": Immediately run /work in the current session.