Sherpy CLI Planner

Sherpy CLI Planner

Runs the complete Sherpy planning pipeline using the Sherpy CLI prompt command to load step-specific instructions on demand. This provides a token-efficient alternative to installing 14 individual skill files — all instructions are embedded in the sherpy binary.

Prerequisites

The sherpy CLI must be installed. Verify with:

sherpy --help

If not installed:

go install github.com/validkeys/sherpy@latest

Usage

/sherpy-cli-planner [output-directory]

If no directory is provided, prompt the user: "Where should I create the planning documents?"

Wait for the user to provide a path before proceeding.

The Pipeline

The same 12 steps as sherpy-flow, but instructions are loaded via sherpy prompt instead of individual skills:

Step 1   Gap Analysis Worksheet         → gap-analysis-worksheet.md
Step 2   Business Requirements          → business-requirements.yaml
Step 3   Technical Requirements         → technical-requirements.yaml
Step 4   Style Anchors Collection       → style-anchors/index.yaml + *.md
Step 5   Implementation Planner         → milestones.yaml + milestone-m*.tasks.yaml
Step 6   UX/Wireframe Planning          → wireframe-spec.yaml + wireframes/*.pen (conditional)
Step 7   Implementation Plan Review     → implementation-plan-review.yaml
Step 8   Definition of Done             → milestones.yaml (enhanced with acceptance_criteria)
Step 9   Architecture Decision Records  → adrs/INDEX.md + adrs/ADR-*.md
Step 10  Delivery Timeline              → timeline.yaml
Step 11  QA Test Plan                   → qa-test-plan.yaml
Step 12  Developer Summary              → developer-summary.md
Step 13  Executive Summary              → executive-summary.md

All artifacts are automatically organized into:

<output-directory>/
├── requirements/       (requirements, gap analysis)
├── implementation/
│   ├── milestones.yaml (with optional acceptance_criteria)
│   └── tasks/          (milestone task files)
├── ux/                 (wireframe spec + Pencil wireframes)
│   ├── wireframe-spec.yaml
│   ├── wireframes.pen
│   └── PAGE-001.png
├── delivery/           (timeline, QA test plan)
├── architecture/
│   └── adrs/           (ADRs)
├── artifacts/          (reviews, interview transcripts, style anchors, etc.)
└── summaries/          (developer & executive summaries)

Process

Step 0: Verify CLI and List Prompts

Before starting, verify the CLI is installed and show available prompts:

sherpy prompt --list

If this fails, instruct the user to install the CLI and exit.

Step 1: Determine Output Directory

If no directory was provided as a parameter, prompt the user:

"Where should I create the planning documents?"

Wait for user response. Store the provided path as base_directory.

Do not create any folders at this stage. Folders will be created on-demand as you generate files.

Step 2: Scan for Existing Artifacts

Check the base_directory for existing files in the organized structure:

Artifact Detection Logic:

• Check expected location within base_directory
• If file exists, step is considered complete

Step 3: Show Pipeline Status

Display a visual status of the pipeline before doing any work:

## Sherpy CLI Planner — [Project Directory]

 ✓  Step 1   Gap Analysis Worksheet
 ✓  Step 2   Business Requirements
 →  Step 3   Technical Requirements        ← resuming here
 ○  Step 4   Style Anchors Collection
 ○  Step 5   Implementation Planner
 ○  Step 6   UX/Wireframe Planning
 ○  Step 7   Implementation Plan Review
 ○  Step 8   Definition of Done
 ○  Step 9   Architecture Decision Records
 ○  Step 10  Delivery Timeline
 ○  Step 11  QA Test Plan
 ○  Step 12  Developer Summary
 ○  Step 13  Executive Summary

Resuming from Step 3. Type "start over" to restart from Step 1,
or specify a step number to jump to a specific point.

Legend: ✓ complete · → current · ○ pending

Then ask:

"Ready to continue from Step [n]: [Step Name]? (yes / start over / jump to step N)"

Wait for confirmation before proceeding.

Step 4: Execute Each Step

For each pending step, load the instructions via sherpy prompt and follow them:

Step Execution Pattern

For every step:

1. Load instructions:

   sherpy prompt -t <prompt-type>
   

2. Follow the printed instructions to complete the step

3. After completion, validate the output (if YAML):

   sherpy validate -t <type> -f <output-file> --strict
   

4. Ask user to confirm before proceeding to next step:

   "Step [n] complete. Continue to Step [n+1]? (yes / no / jump to N)"

CRITICAL EXECUTION RULES:

1. NEVER proceed to the next step without explicit user confirmation — wait after EVERY step completion
2. Step 4 (Style Anchors Collection) MUST NOT be skipped automatically — always prompt the user and show risk warning if they want to skip
3. If a step requires input that doesn't exist (e.g., Step 5 needs style anchors), STOP and warn the user before proceeding

Step-Specific Commands

Step 1: Gap Analysis Worksheet

# Load instructions
sherpy prompt -t gap-analysis-worksheet

# Follow the instructions, then continue...

Step 2: Business Requirements

# Load instructions
sherpy prompt -t business-requirements-interview

# After generating business-requirements.yaml, validate:
sherpy validate -t business-requirements -f {base_directory}/requirements/business-requirements.yaml --strict

Step 3: Technical Requirements

# Load instructions
sherpy prompt -t technical-requirements-interview

# After generating technical-requirements.yaml, validate:
sherpy validate -t technical-requirements -f {base_directory}/requirements/technical-requirements.yaml --strict

Step 4: Style Anchors Collection

# Load instructions
sherpy prompt -t style-anchors-collection

# Follow the instructions...
# No validation needed (produces markdown files)

Step 5: Implementation Planner

# Load instructions
sherpy prompt -t implementation-planner

# After generating milestones.yaml, validate:
sherpy validate -t milestones -f {base_directory}/implementation/milestones.yaml --strict

# After generating milestone task files, validate each:
sherpy validate -t milestone-tasks -f {base_directory}/implementation/tasks/milestone-m0.tasks.yaml --strict
sherpy validate -t milestone-tasks -f {base_directory}/implementation/tasks/milestone-m1.tasks.yaml --strict
# ... for each milestone

Step 6: UX/Wireframe Planning (conditional — auto-skips if no UI changes)

# Load instructions
sherpy prompt -t ux-wireframe-planning

# After generating wireframe-spec.yaml, validate:
sherpy validate -t wireframe-spec -f {base_directory}/ux/wireframe-spec.yaml --strict

Step 7: Implementation Plan Review

# Load instructions
sherpy prompt -t implementation-plan-review

# Follow the instructions...
# No validation needed (produces review document)

Step 8: Definition of Done

# Load instructions
sherpy prompt -t definition-of-done

# After enhancing milestones.yaml, validate:
sherpy validate -t milestones -f {base_directory}/implementation/milestones.yaml --strict

Step 9: Architecture Decision Records

# Load instructions
sherpy prompt -t architecture-decision-record

# Follow the instructions...
# No validation needed (produces markdown files)

Step 10: Delivery Timeline

# Load instructions
sherpy prompt -t delivery-timeline

# After generating timeline.yaml, validate:
sherpy validate -t timeline -f {base_directory}/delivery/timeline.yaml --strict

Step 11: QA Test Plan

# Load instructions
sherpy prompt -t qa-test-plan

# After generating qa-test-plan.yaml, validate:
sherpy validate -t qa-test-plan -f {base_directory}/delivery/qa-test-plan.yaml --strict

Step 12: Developer Summary

# Load instructions
sherpy prompt -t developer-summary

# Follow the instructions...
# No validation needed (produces markdown file)

Step 13: Executive Summary

# Load instructions
sherpy prompt -t executive-summary

# Follow the instructions...
# No validation needed (produces markdown file)

Step 5: Final Summary

After all steps are complete, show a summary:

## Planning Complete! 🎉

All artifacts have been generated and validated:

✓ Requirements documented
✓ Implementation planned with TDD tasks
✓ Delivery timeline established
✓ QA test plan created
✓ Summaries generated

Files are organized in: {base_directory}/

Next steps:
1. Review the developer summary: {base_directory}/summaries/developer-summary.md
2. Share the executive summary with stakeholders
3. Begin implementation using the task files in implementation/tasks/

Run validation at any time:
  sherpy validate -t <type> -f <file> --strict

Transition Rules

Same as sherpy-flow:

Between Steps:

• Always wait for user confirmation before advancing
• User can type "start over" to reset to Step 1
• User can type "jump to N" to skip to a specific step
• If user asks to skip a step, warn about dependencies

Skipping Steps:

• Steps 1-3 (requirements) can be skipped if files exist
• Step 4 (style anchors) should NOT be skipped without warning — show risk of implementation drift
• Steps 5-12 depend on requirements — stop if missing

Error Handling:

• If validation fails, STOP and show error
• User must fix the YAML and re-run validation
• Do not proceed until validation passes
• If CLI command fails, show error and stop

CLI Reference

List available prompts:

sherpy prompt --list

Load specific prompt:

sherpy prompt -t <prompt-type>

Validate YAML:

sherpy validate -t <type> -f <file> --strict

List document types:

sherpy types

Comparison to sherpy-flow

Notes

• The sherpy CLI embeds all prompt content at build time — no network required
• Each sherpy prompt call outputs the full instructions for that step
• Validation is integrated after each step that produces YAML
• The same 12 steps as sherpy-flow, just loaded differently
• Style anchors (Step 4) are critical — never skip without warning