devteam-plan

Current session: !source "${CLAUDE_PLUGIN_ROOT}/scripts/state.sh" && get_current_session 2>/dev/null || echo "No active session" Active sprint: !source "${CLAUDE_PLUGIN_ROOT}/scripts/state.sh" && get_kv_state "active_sprint" 2>/dev/null || echo "None" Failure count: !source "${CLAUDE_PLUGIN_ROOT}/scripts/state.sh" && get_kv_state "consecutive_failures" 2>/dev/null || echo "0"

DevTeam Plan Command

Command: /devteam:plan [options]

Conduct interactive requirements gathering, research the codebase, create a PRD, and generate a development plan with tasks and sprints.

Usage

/devteam:plan                                # Start interactive planning
/devteam:plan "Build a task manager"         # Start with description
/devteam:plan --feature "Add dark mode"      # Plan a feature for existing project
/devteam:plan --from spec.md                 # Load from single spec file
/devteam:plan --from specs/                  # Load from folder of spec files
/devteam:plan --from existing                # Auto-detect existing docs in project
/devteam:plan --skip-research                # Skip research phase

Options

| Option | Description | |--------|-------------| | --feature "<desc>" | Plan a feature for existing project | | --from <path> | Load from spec file or folder | | --skip-research | Skip codebase research phase | | --skip-interview | Skip interview (use with --from) |

File-Based Specification Support

Supported File Formats

| Format | Extensions | Best For | |--------|------------|----------| | Markdown | .md | Human-readable specs, PRDs | | YAML | .yaml, .yml | Structured specs, existing PRDs | | JSON | .json | API specs, structured data | | Plain Text | .txt | Simple requirements lists | | PDF | .pdf | Formal documents (extracted) |

Single File Mode (--from file.md)

Reads a specification file and extracts:

• Project description
• Features/requirements (from headers, lists)
• Technical constraints
• User stories
• Acceptance criteria

Example Input (project-spec.md):

# Task Manager App

## Overview
A simple task management app for teams.

## Features
- User authentication with OAuth
- Create, edit, delete tasks
- Assign tasks to team members
- Due date reminders

## Technical Requirements
- Backend: FastAPI
- Database: PostgreSQL
- Frontend: React + TypeScript

Process:

1. Read and parse file
2. Extract structured information
3. Confirm understanding with user (brief)
4. Skip redundant interview questions
5. Generate PRD from extracted data

Folder Mode (--from specs/)

Reads all spec files from a folder and merges them:

specs/
├── overview.md           # Project overview
├── features/
│   ├── auth.md          # Authentication spec
│   ├── tasks.md         # Task management spec
│   └── notifications.md # Notification spec
├── api-design.yaml      # API specification
└── wireframes.md        # UI descriptions

Process:

1. Scan folder recursively
2. Categorize files by type/content
3. Merge into unified understanding
4. Resolve conflicts (ask user if ambiguous)
5. Generate comprehensive PRD

Auto-Detect Mode (--from existing)

Searches project for existing documentation:

Search locations:

docs/                    # Common docs folder
documentation/           # Alternative name
spec/                    # Spec folder
specifications/          # Alternative name
requirements/            # Requirements folder
*.md in root            # README, CONTRIBUTING, etc.
.github/                # Issue templates, etc.

Process:

1. Scan project structure
2. Find and list discovered docs
3. Ask user to confirm which to use
4. Parse and extract requirements
5. Fill gaps with brief questions

File Parsing Examples

From Markdown with headers:

# Feature: User Authentication

## Requirements
- [ ] OAuth 2.0 support (Google, GitHub)
- [ ] Session management
- [ ] Password reset flow

## Acceptance Criteria
1. User can sign in with Google
2. Session persists for 7 days
3. Password reset email sent within 1 minute

Extracted as:

{
  "feature": {
    "name": "User Authentication",
    "requirements": [
      "OAuth 2.0 support (Google, GitHub)",
      "Session management",
      "Password reset flow"
    ],
    "acceptance_criteria": [
      "User can sign in with Google",
      "Session persists for 7 days",
      "Password reset email sent within 1 minute"
    ]
  }
}

From YAML directly:

# Already structured - use as-is
project:
  name: Task Manager
features:
  - name: Authentication
    priority: must_have

From JSON (OpenAPI):

{
  "openapi": "3.0.0",
  "paths": {
    "/tasks": { "get": {...}, "post": {...} }
  }
}

Extract API endpoints as features

User Confirmation

After parsing file-based specs, always confirm:

Loaded specification from: project-spec.md

Extracted:
  - Project: Task Manager App
  - Features: 4 identified
  - Tech Stack: FastAPI + PostgreSQL + React
  - Constraints: None specified

Is this correct? (yes/edit/add more)

If edit: Allow user to modify extracted data If add more: Continue with remaining interview questions

Your Process

This command combines PRD generation and sprint planning into a single workflow.

Phase 0: Git Repository Check (REQUIRED)

Before any planning, verify git repository exists:

# Check for git repository
git rev-parse --git-dir 2>/dev/null

If NOT a git repository:

Git Repository Required

DevTeam requires a git repository for:
- Change tracking and rollback
- Parallel plan execution (worktrees)
- Safe merge of feature branches
- Circuit breaker recovery

Initialize a git repository now? (yes/no): _

If user says yes:

git init
git add .
git commit -m "Initial commit before DevTeam planning"
echo "Git repository initialized"

If user says no:

Cannot proceed without git repository.

To initialize manually:
  git init
  git add .
  git commit -m "Initial commit"

Then run /devteam:plan again.

If git repo exists but has uncommitted changes:

Uncommitted Changes Detected

You have uncommitted changes in your working directory.
It's recommended to commit before planning.

Options:
  1. Commit changes now (recommended)
  2. Stash changes temporarily
  3. Continue anyway (changes tracked but not snapshotted)

Select option (1/2/3): _

Option 1:

git add -A
git commit -m "Pre-planning snapshot"
echo "Changes committed"

Phase 1: Requirements Interview

Skip if: --from flag provided with comprehensive spec and --skip-interview flag.

Technology Stack Selection (FIRST):

1. Ask: "What external services, APIs, or integrations will you need?"
2. Based on answer, recommend Python or TypeScript with reasoning:
3. Python: Better for data processing, ML, scientific computing
4. TypeScript: Better for web apps, real-time features, npm ecosystem
5. Confirm with user
6. Document choice

Requirements Gathering (ONE question at a time):

1. "What problem are you solving?"
2. "Who are the primary users?"
3. "What are the must-have features?"
4. "What are the nice-to-have features?"
5. "What scale do you expect? (users, data volume)"
6. "Any specific constraints? (timeline, budget, compliance)"
7. "How will you measure success?"

Be efficient: If user provides comprehensive initial description, skip questions already answered.

Phase 2: Research Phase

Skip if: --skip-research flag provided.

Purpose: Investigate the codebase and technologies before planning to:

• Identify existing patterns to follow
• Find potential blockers early
• Make informed technology recommendations
• Prevent "discover problems during implementation" scenarios

Research Agent Tasks:

// Spawn Research Agent
const researchResults = await Task({
    subagent_type: "research:research-agent",
    model: "opus",
    pr