start-work

name	start-work
description	Initializes a feature/task-level planning structure in .planning/ directory for organizing work items (features, refactors, bug fixes). Creates work directories with BRIEF.md, ROADMAP.md, and phases/ structure. Use when starting new work items similar to JIRA issues.

Initialize a structured planning directory for organizing work items (features, refactors, bug fixes, enhancements) similar to JIRA issues. Creates a `.planning/[identifier]-[work-name]/` directory with BRIEF.md (scope/vision), ROADMAP.md (phases), and phases/ subdirectory for detailed execution plans.

Supports both auto-numbered work items (ID-01, ID-02) and custom identifiers (mdo-123, gh-456, JIRA-789) from external tracking systems.

<quick_start> Usage:

• /start-work - Interactive prompts for work details
• /start-work [identifier] [work-name] - With arguments

Example:

/start-work mdo-123 api-refactor

Creates: .planning/mdo-123-api-refactor/ with BRIEF.md, ROADMAP.md, and phases/ </quick_start>

## Step 1: Gather Work Information

Accept arguments or prompt using AskUserQuestion:

1. Work identifier (optional):

   • Leave blank → auto-generate as ID-[nn] (scans existing directories)
   • Provide custom → use as-is (mdo-123, gh-456, JIRA-789)

2. Work name (required):

   • Short kebab-case description
   • Examples: parallels-session-updates, fix-auth-bug, api-refactor

3. Brief description (required):

   • What needs to be done and why
   • Used to populate BRIEF.md Objective section

4. Work type (required):

   • Options: Feature, Bug Fix, Refactor, Enhancement

Step 2: Auto-Detect Next ID Number

If identifier is blank:

• Scan .planning/ directory for ID-[nn] pattern directories
• Extract numbers, find max, increment by 1
• Format as ID-[nn] with zero-padding (ID-01, ID-02, ..., ID-10, etc.)
• Handle gaps gracefully (if ID-01, ID-03 exist → next is ID-04)
• Custom identifiers don't affect auto-numbering sequence

Step 3: Check for Duplicate Directory

Check if .planning/[identifier]-[work-name]/ already exists:

• If exists → auto-append -02, -03, etc. suffix
• Example: mdo-123-api-refactor exists → create mdo-123-api-refactor-02
• Note: Original directory is implicitly "-01" (no suffix)

Step 4: Create Directory Structure

.planning/[identifier]-[work-name]/
  BRIEF.md           # Work-level scope/vision
  ROADMAP.md         # Work-level phases
  phases/            # Execution plans go here (01-01-PLAN.md, etc.)

Auto-create .planning/ if it doesn't exist.

Step 5: Gather Relevant Files

Use AskUserQuestion to prompt for relevant file paths:

Question: "Would you like to specify relevant files for this work?"

Options:

1. Yes, I'll provide paths - Prompt for comma-separated or line-separated relative paths
   • Accept formats: src/file.ts, ./src/file.ts, src/dir/
   • Store paths for inclusion in BRIEF.md
2. No, scan automatically - Use work name keywords to scan codebase
   • Search for files matching keywords from work name
   • Present findings for user confirmation before including
3. Skip - No files section in BRIEF.md

If user provides paths:

• Validate paths exist (warn if not found, but include anyway)
• Store as-is for BRIEF.md

If automatic scan:

• Extract keywords from work name (e.g., api-refactor → api, refactor)
• Use Grep/Glob to find relevant files
• Present list to user for confirmation/refinement
• Only include confirmed files

Step 6: Generate BRIEF.md

Use template from templates/work-brief.md:

• Replace [Work Name] with provided work name
• Replace [identifier] with actual identifier (ID-01 or mdo-123)
• Replace [Type] with selected work type
• Replace [What needs to be done and why] with brief description
• Add planning instructions header with actual identifier
• If relevant files were provided/confirmed:
  • Add a "## Relevant Files" section after Objective
  • List files as markdown links: [filename](relative/path/to/file)
  • Group by directory if multiple files from same location

Step 7: Generate ROADMAP.md

Use template from templates/work-roadmap.md:

• Replace [Work Name] with provided work name
• Replace [identifier] with actual identifier

Step 8: Output Next Steps

Display to user:

✅ Created work structure: .planning/[identifier]-[work-name]/

Next steps:
1. Review and refine BRIEF.md and ROADMAP.md
2. Use `/create-plan` to create detailed phase plans in phases/ subdirectory
3. Use `/run-plan` to execute plans
4. Commits: Use standard prefixes (feat:, fix:, refactor:, docs:)

Step 9: Offer Root-Level Docs (If Missing)

Check if root-level BRIEF.md and ROADMAP.md exist in .planning/:

• If missing → Use AskUserQuestion to offer creating them
• Use templates from templates/project-brief.md and templates/project-roadmap.md
• Always ask first, never auto-create

<commit_behavior>

Invocation Context Detection

Auto-detect invocation context:

• User-invoked: Direct skill call → Manual commit workflow (user provides messages)
• Subagent-invoked: Called via Task tool → Allow auto-commit with identifier

Commit format:

• User: Standard prefixes only: feat:, fix:, refactor:, docs:
• Subagent: Include identifier: feat([identifier]-01):, fix(mdo-123-02):

Implementation: Check if running in subagent context and adjust behavior accordingly. </commit_behavior>

<directory_conventions>

• Always lowercase
• Use kebab-case for work names
• Format: [identifier]-[work-name]
• Identifier: custom (mdo-123) or auto (ID-01)
• Duplicate handling: Append -02, -03 suffix if exists </directory_conventions>

<identifier_examples>

User Input	Work Name	Generated Directory
(blank)	parallels-ui-updates	ID-01-parallels-ui-updates/
(blank)	fix-auth-bug	ID-02-fix-auth-bug/
mdo-123	api-refactor	mdo-123-api-refactor/
gh-456	performance-optimization	gh-456-performance-optimization/
JIRA-789	database-migration	JIRA-789-database-migration/
</identifier_examples>

## Works With Existing Skills

• /create-plan - Create detailed phase plans in phases/ subdirectory
• /run-plan - Execute plans created in work directory

Plans are numbered 01-01, 01-02, etc. (phase-plan format) within the phases/ subdirectory.

<success_criteria> Skill execution is successful when:

• .planning/[identifier]-[work-name]/ directory created
• BRIEF.md generated with correct identifier and work details
• ROADMAP.md generated with Phase 01 placeholder
• phases/ subdirectory exists
• User informed of next steps
• Root-level docs offered if missing (always ask first)
• Duplicate directories handled (auto-append suffix)
• Auto-numbering works correctly (ID-01, ID-02, etc.) </success_criteria>