AI PM Flow

The AI PM is a hierarchical agent system that runs inside Claude Code. It consists of slash commands, specialized agents, workflow orchestrators, and templates.

How It Works

The AI PM follows a structured workflow:

/propelkit:new-project
    |
    v
Deep Questioning → Research → Requirements → Roadmap → Design → Build
    |                                                              |
    v                                                              v
"What are you building?"                              Phase-by-phase execution
"Who are your users?"                                 with atomic commits
"What's the core value?"                              and verification

The /propelkit:new-project Flow

This is the master command that takes you from idea to ready-to-build. It runs through these phases:

Phase 1-2: Setup & Deep Questioning

• Checks for existing project artifacts
• Asks "What do you want to build?" and follows conversational threads
• Understands your target users, core value proposition, and constraints
• Detects if this is a greenfield or brownfield project

Phase 3-4: Project Documentation

• Synthesizes the conversation into PROJECT.md (your project's vision document)
• Presents back for confirmation: "Is this what you're building?"

Phase 5-6: Feature Detection

• Infers which optional features you need from the conversation
• Multi-tenancy: "You mentioned teams — enabling organizations"
• Credits: "You mentioned usage limits — enabling credit system"
• Payment processor: Based on target market (India → Razorpay, Global → Stripe)
• Writes src/config/features.ts with your flags

Phase 7: Schema Generation

• Optionally generates database migrations based on detected features
• Creates seed data for subscription plans

Phase 8-9: Workflow & Research

• Asks: Interactive mode (confirms decisions) or YOLO mode (auto-approves)?
• Asks: Want domain research? (spawns 4 parallel researcher agents)
• Stack researcher — Best technologies for your domain
• Features researcher — Table stakes vs differentiators
• Architecture researcher — System design patterns
• Pitfalls researcher — Common mistakes to avoid
• Synthesizes research into actionable insights

Phase 10: Requirements & Roadmap

• Defines v1 requirements with unique IDs (AUTH-01, PAY-02, etc.)
• Scopes: v1 (must have), v2 (future), out-of-scope (won't do)
• Spawns the roadmapper agent to create a phased plan
• Every v1 requirement maps to exactly one phase
• Each phase has 2-5 observable success criteria
• 100% requirement coverage validated — no orphans

Phase 10.5: Intelligent Design Flow

If Lovable was selected during setup:

• Collects inspiration (screenshots, URLs, descriptions)
• Detects your industry and recommends a design style
• Asks about colors and brand voice
• Generates a comprehensive, context-aware Lovable prompt
• The prompt includes every page from the roadmap, not just generic screens

Phase 0: Landing Page

Every roadmap starts with Phase 0: Landing Page. This is mandatory because:

• Quick win — you see your product come alive in the first session
• Momentum — nothing motivates like a real deployed page
• Validation — forces clarity on messaging and value proposition
• Foundation — establishes brand theming, layout, and navigation

Phase 0 is always small (1-2 plans max). The landing page will be refined as features get built.

The Build Cycle

After initialization, the AI PM follows a repeating cycle: Plan Phase → Execute Phase → Verify → Next Phase.

Planning

Run /propelkit:plan-phase N to create execution plans:

• Breaks the phase into 2-3 atomic plans
• Each plan has specific tasks, files to modify, and verification criteria
• Plans are grouped into "waves" — independent plans run in parallel, dependent ones run sequentially

Execution

Run /propelkit:execute-phase N to build:

• Spawns executor agents for each plan
• Creates per-task git commits
• Handles deviations automatically (bug fixes, missing dependencies, security issues)
• Pauses at checkpoints for user decisions
• Generates SUMMARY.md documenting what was built

Verification

Run /propelkit:verify-work N for user acceptance testing:

• Conversational user acceptance testing
• Tests one feature at a time
• If issues found: diagnoses root cause and creates fix plans

Agent System

The AI PM uses specialized agents for different tasks:

• Roadmapper — Creates phase structure from requirements (spawned by /propelkit:new-project)
• Planner — Breaks phases into executable plans (spawned by /propelkit:plan-phase)
• Executor — Writes code, creates commits (spawned by /propelkit:execute-phase)
• Verifier — Tests features against success criteria (spawned by /propelkit:verify-work)
• Debugger — Investigates bugs using scientific method (spawned by /propelkit:debug)
• Researcher (x4) — Explores domain best practices (spawned by /propelkit:new-project, optional)
• Synthesizer — Combines research into actionable summary (after researchers complete)
• Phase Researcher — Investigates specific phase decisions (spawned by /propelkit:plan-phase)
• Plan Checker — Reviews plans before execution (spawned by /propelkit:plan-phase)
• Integration Checker — Verifies cross-phase connections (phase transitions)

Goal-Backward Methodology

The AI PM uses goal-backward thinking at every level:

• Roadmap level: "What must be TRUE for users when this phase completes?"
• Phase level: "What must exist for these success criteria to pass?"
• Plan level: "What code must be written for this task to be done?"

This prevents scope creep and ensures every line of code serves a verifiable outcome.

Session Management

Pausing Work

Run /propelkit:pause-work to save your position:

• Creates a .continue-here file with your exact position
• Updates STATE.md with session context
• Next time you return, the AI PM knows exactly where you left off

Resuming Work

Run /propelkit:resume-work to pick up where you left off:

• Same day: "Picking up where we left off."
• 1-3 days: "Here's where things stand."
• 4-14 days: "Let me catch you up."
• 15+ days: "Let me give you the full picture."
• Shows progress delta since your last session
• Estimates time for the next task
• Detects incomplete work, interrupted agents, and pending todos

Checking Progress

Run /propelkit:progress for a visual overview:

• ASCII progress bar with percentage
• Motivational message based on progress (e.g., "Halfway there" at 31-50%)
• "Ship This Weekend" mode: When you have 8 or fewer plans left, shows estimated time remaining
• Smart routing to the next action (execute, plan, or verify)

Debugging

Run /propelkit:debug "issue description" for systematic debugging:

• Creates a persistent investigation file in .planning/debug/
• Uses scientific method: gather symptoms → form hypothesis → test → confirm
• Survives context resets (/clear) — run /propelkit:debug with no args to resume
• Archives resolved issues for future reference

Milestone Management

When all phases in a milestone are complete:

• /propelkit:complete-milestone 1.0.0 — Creates MILESTONES.md entry with stats, archives full details, creates a git tag, prepares workspace for the next version
• /propelkit:new-milestone — Starts the next milestone cycle, re-runs the questioning → research → requirements → roadmap flow, builds on top of what already exists

Project Files

The AI PM creates and maintains a .planning/ directory:

.planning/
|-- PROJECT.md            # Project vision and requirements
|-- ROADMAP.md            # Phase breakdown with success criteria
|-- STATE.md              # Living memory (position, decisions, issues)
|-- REQUIREMENTS.md       # Scoped requirements with REQ-IDs
|-- config.json           # Workflow mode, depth, parallelization
|-- research/             # Domain research (if selected)
|   |-- STACK.md
|   |-- FEATURES.md
|   |-- ARCHITECTURE.md
|   |-- PITFALLS.md
|   |-- SUMMARY.md
|-- todos/                # Captured ideas and tasks
|-- debug/                # Active debug sessions
|-- phases/
    |-- 00-landing-page/
    |   |-- 00-01-PLAN.md
    |   |-- 00-01-SUMMARY.md
    |-- 01-auth/
    |   |-- 01-01-PLAN.md
    |   |-- 01-01-SUMMARY.md
    |-- 02-core-features/
        |-- 02-01-PLAN.md
        |-- 02-01-SUMMARY.md

Command Reference

Core Workflow

• /propelkit:new-project — Initialize new project (questioning → research → roadmap)
• /propelkit:plan-phase N — Create execution plans for phase N
• /propelkit:execute-phase N — Execute all plans in phase N
• /propelkit:verify-work N — User acceptance testing for phase N

Roadmap Management

• /propelkit:add-phase "desc" — Add new phase to end of roadmap
• /propelkit:discuss-phase N — Articulate vision before planning
• /propelkit:complete-milestone — Archive milestone and prepare for next

Session Management Commands

• /propelkit:progress — Visual progress + smart routing to next action
• /propelkit:pause-work — Save state and create handoff file
• /propelkit:resume-work — Restore context with comeback mode

Tools

• /propelkit:wire-ui — Auto-wire Lovable designs into Next.js
• /propelkit:debug "issue" — Systematic debugging with persistent state
• /propelkit:help — Show command reference

npm Scripts

• npm run dev — Start development server
• npm run demo — Start in demo mode (no external services)
• npm run build — Production build
• npm run test — Run test suite
• npm run setup — Re-run setup wizard