planf3

name	planf3
description	Creates a concise engineering implementation plan based on user requirements and saves it to specs directory
argument-hint	[user-prompt] [questionable]

Plan F3

Purpose

Create a detailed, HTML-first implementation plan based on the USER_PROMPT variable. The plan is authored as a single self-contained .html page so it can be opened in a browser, embed focused images with a synced visual identity, and be created/updated/consumed by the agent trifecta (engineer, team, AI agents). Analyze the request, think through the implementation approach, follow the ## Instructions, and work through the ## Workflow to produce the plan from the ## Plan Template.

Variables

USER_PROMPT: $1 QUESTIONABLE: $2 - default false PLAN_OUTPUT_DIRECTORY: specs/ PLAN_FILE: PLAN_OUTPUT_DIRECTORY/<descriptive-kebab-name>.html IMAGES_OUTPUT_DIR: PLAN_OUTPUT_DIRECTORY/<plan-name>/ AI_DOCS: AI_DOCS/ APP_DOCS: APP_DOCS/ IDE: code BROWSER: chrome

Instructions

• IMPORTANT: If no USER_PROMPT is provided, stop and ask the user to provide it
• Carefully analyze the user's requirements provided in the USER_PROMPT variable
• Think deeply (ultrathink) about the best approach to implement the requested functionality or solve the problem
• Explore the codebase to understand existing patterns, documentation, previous specs and architecture
• The plan is HTML-first: produce a single self-contained .html document from the ## Plan Template below
• The template uses {{PLACEHOLDER}} variables — replace EVERY {{...}} with real content. Do not leave any {{}} token in the final file
• Blocks marked with <!-- repeat --> are repeatable: duplicate them as many times as the plan needs (e.g. one block per phase, task, file, or Q&A entry) and delete the comment markers
• Keep the document self-contained: all CSS lives in the single <style> block; do not link external stylesheets or scripts
• Maintain a synced visual identity between the html styling and the generated images. We want a professional, focused, minimal theme based on the original USER_PROMPT that created the plan. The CSS custom properties in :root define the palette/typography. Any embedded image must be generated to match this same identity.
• For every image created keep them professional and focused on one or two primary ideas. Keep text bloat down by minimizing the total number of sets of words requested in the image prompt under 10. The goal is to build images that aid the plan and convey the core information throughout the plan given the section the image was created for.
• Build images for professional software engineers to convey exactly what is going to be built. Be sure to center and space images properly.
• Embed images via the {{...IMAGE}} slots. During Create, leave them as commented placeholders noting the intended subject; the Image Generation workflow fills them later
• Populate the metadata header (created, modified, commits, agent, session, back/forward references) — these are updatable across the plan's lifecycle. Every metadata field except CREATED_ISO is a comma-separated list that must only ever be appended to — never overwrite or remove existing entries
• If QUESTIONABLE is true, actively surface open questions/assumptions in the toggleable Q&A section rather than silently deciding
• Ensure the plan is detailed enough that another developer (or agent) could follow it to implement the solution
• Include code examples or pseudo-code where appropriate to clarify complex concepts
• Consider edge cases, error handling, and scalability concerns
• Save the complete plan to PLAN_FILE using a descriptive kebab-case filename

Workflow

Based on the USER_PROMPT, select the single best-matching workflow below and read its file for the step-by-step instructions before acting.

Workflow	When to call it	File to read
Create Plan	The prompt asks to plan, spec, or design new work and no existing plan is referenced	workflows/create-plan.md
Update Plan	The prompt asks to change, extend, or revise the content of an existing plan	workflows/update-plan.md
Update References	The prompt asks to refresh plan metadata or back/forward references (created, modified, commits, agent, session)	workflows/update-references.md
Build Plan	The prompt asks to implement, execute, or carry out the work described in an existing plan	workflows/build-plan.md

Subworkflow

Called by other workflows rather than selected directly from the USER_PROMPT.

Subworkflow	When it's called	File to read
Image Generation	Invoked by other workflows (e.g. Create Plan) to generate, fill, or regenerate the embedded images in a plan	workflows/image-generation.md

Plan Template

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Plan: {{PLAN_TITLE}}</title>
</head>
<body>
<main>

  <!-- ===== HEADER + UPDATABLE METADATA ===== -->
  <header>
    <h1>Plan: {{PLAN_TITLE}}</h1>
    <details class="meta">
      <summary>Metadata</summary>
      <dl>
        <dt>created</dt>      <dd>{{CREATED_ISO}}</dd>
        <dt>modified</dt>     <dd>{{MODIFIED_ISO_LIST}}</dd>
        <>commits      {{COMMIT_SHA_LIST}}
        agent name        {{AGENT_NAME_LIST}}
        session id      {{SESSION_ID_LIST}}
        back refs    {{BACK_REFERENCES}}
        forward refs {{FORWARD_REFERENCES}}
      
    
  

  
  
    
    {{HERO_IMAGE_CAPTION}}
  

  
  
    Purpose
    {{PURPOSE}}
  

  
    Problem
    {{PROBLEM}}
    
      
      {{PROBLEM_IMAGE_CAPTION}}
    
  

  
    Solution
    {{SOLUTION}}
    
      
      {{SOLUTION_IMAGE_CAPTION}}
    
  

  
  
    Relevant Files

    Existing Files
    
      
      existing {{EXISTING_FILE_PATH}} — {{WHY_RELEVANT}}
    

    New Files
    
      
      new {{NEW_FILE_PATH}} — {{WHY_NEEDED}}
    
  

  
  
    Implementation Phases
    IMPORTANT: Execute every phase and task step by step, in order, top to bottom.
    Status markers: [] idle · [wip] in progress · [x] complete · [f] failed. All start as []; the Build Plan workflow updates them as it works.

    
    
      [] Phase {{PHASE_NUMBER}}: {{PHASE_NAME}}
      {{PHASE_DESCRIPTION}}

      
      
        
        {{PHASE_IMAGE_CAPTION}}
      

      
      {{TASK_NUMBER}}. {{TASK_NAME}}
      
        
        [] {{SPECIFIC_ACTION}}
      

      
      {{LAST_TASK_NUMBER}}. Testing Strategy
      {{TESTING_APPROACH: technology used to test/validate, including edge cases}}
      
        
        [] {{VALIDATION_COMMAND}} — {{WHAT_IT_PROVES}}
      
      
        🔁 Do not exit this phase until every box above is checked.
        If any command fails, fix the cause and re-run — loop until all pass.
      
    
  

  
  
    Validation Commands
    Execute these commands to validate the entire plan is complete:
    
      
      [] {{VALIDATION_COMMAND}} — {{WHAT_IT_PROVES}}
    
    
      🔁 The plan is not complete until every box is checked and every command passes. If for some reason a step is not possible to complete, mark it with [f] and move on if possible.
    
  

  
  
    Questionables
    
    
      
      {{QUESTIONABLES_IMAGE_CAPTION}}
    
    
    
      {{QUESTIONABLE}}
      {{ASSUMPTION_OR_RATIONALE}}
    
  

  
  
  
    Notes
    {{NOTES: free-form. Capture anything that helps the trifecta understand, build,
      or extend this plan — context, dependencies (new libraries via `uv add`),
      tradeoffs, rejected approaches, risks, future work, references. Author rich,
      bespoke HTML as needed.}}
    
    
      
      {{NOTES_IMAGE_CAPTION}}
    
  

  
  
  
    Amendments
    
    
      {{AMEND_ISO}} — {{AMEND_SUMMARY}}
      {{AMEND_DETAIL: what changed and why}}