Commands

Note: These are EXAMPLE commands. Create your own, modify existing ones, or skip commands entirely and work directly with agents.

Introduction

Commands are pre-built workflows that orchestrate multiple agents to execute common development tasks. Commands simplify complex workflows by combining multiple agent actions into single executable commands.

Key Point: Commands are optional convenience tools. You can work directly with agents instead or create your own custom commands.

📑 Table of Contents

Quick Navigation: Jump to any command or section below

⚡ Available Commands

#	Command	Purpose
1	/init-task	Initialize task with PM requirements and architect planning
2	/execute-task	Execute complete development workflow (Backend → Frontend → QA → Review)
3	/document-feature	Generate comprehensive documentation for completed features
4	/scope-change	Handle scope changes during development with validation
5	/fix-build	Automatically detect and fix build errors with specialized agents
6	/release	Analyze changes and create semantic version releases

📚 Additional Sections

• Creating Custom Commands - Build your own workflow automation
• Command Best Practices - When and how to use commands effectively
• Command Workflow Patterns - Linear, conditional, and parallel workflows
• Command Execution Flow - How commands are processed internally
• Debugging Commands - Troubleshoot command issues
• Command Cheat Sheet - Quick reference table
• Advanced Command Patterns - Composable and parameterized commands

---

Available Commands

/init-task

Purpose: Initialize a new task with PM requirements and architect planning

Syntax:

/init-task [feature description]

Example:

/init-task Add user profile edit functionality

What It Does:

Phase 1 - Product Manager:

1. Analyzes feature description
2. Defines business requirements
3. Creates ClickUp task (if enabled)
4. Initializes session folder
5. Creates clickup_task_{feature}.md
6. Creates context_{feature}.md

Phase 2 - Architecture Supervisor:

1. Reads business requirements
2. Creates technical implementation plan
3. Defines 4 phases (Backend, Frontend, Integration, QA)
4. Creates plan_{feature}.md
5. Creates progress_{feature}.md template
6. Updates context_{feature}.md

Output:

• Complete session folder with 4 files
• ClickUp task created (optional)
• Ready for development

When to Use:

• Starting any new feature
• Need structured planning
• Want complete task tracking

Alternative:

• Launch product-manager and architecture-supervisor agents manually

---

/execute-task

Purpose: Execute complete development workflow (Backend → Frontend → QA → Review)

Syntax:

/execute-task [session-name]

Example:

/execute-task user-profile-edit

Or interactive selection:

/execute-task
# Shows list of available sessions
# User selects by number or name

What It Does:

Phase 1 - Backend Development:

1. Launches backend-developer
2. Implements Phase 1 from plan
3. Marks progress in progress_{feature}.md
4. Validates build passes

Phase 2 - Frontend Development:

1. Launches frontend-developer
2. Implements Phase 2 from plan
3. Marks progress in progress_{feature}.md
4. Validates build passes

Phase 3 - QA Testing:

1. Launches qa-tester
2. Executes test cases from Phase 4
3. Updates ClickUp status to "qa"
4. Creates bug sub-tasks if needed

Phase 4 - Auto-Retry Loop (if bugs):

• If bugs found: Return to appropriate developer
• Developer fixes bugs
• QA retests
• Repeats until all tests pass

Phase 5 - Code Review:

1. Launches code-reviewer
2. Performs comprehensive review
3. Posts review to ClickUp
4. Updates context file

Output:

• Complete feature implementation
• All tests passed
• Code review complete
• Ready for merge

When to Use:

• Session has been initialized
• Ready for full development cycle
• Want automated workflow

Alternative:

• Launch each agent manually in sequence

---

/document-feature

Purpose: Generate comprehensive documentation for completed feature

Syntax:

/document-feature [session-name]

Example:

/document-feature user-profile-edit

What It Does:

Validation:

1. Verifies session exists
2. Checks QA completed
3. Checks code review completed

Documentation Generation:

1. Launches documentation-writer
2. Reads session files for context
3. Generates feature documentation
4. Creates API documentation (if applicable)
5. Updates changelog
6. Adds code examples

Output:

• Feature documentation in appropriate section
• API reference (if applicable)
• Updated changelog
• Code examples

When to Use:

• Feature is complete and approved
• QA and code review passed
• Ready to document for users/developers

Prerequisites:

• QA status: ✅ Completed
• Code Review status: ✅ Completed
• Session files complete

Alternative:

• Launch documentation-writer agent manually

---

/scope-change

Purpose: Handle scope changes during development

Syntax:

/scope-change [description of changes]

Example:

/scope-change Need to add photo crop functionality and remove bio field

What It Does:

Phase 1 - Documentation Update (PM):

1. Analyzes scope changes
2. Reads current session context
3. Updates ClickUp task description
4. Adds ClickUp comment documenting changes
5. Updates session files
6. Creates scope change log entry

Phase 2 - Quality Validation (Code Reviewer):

1. Reviews changes against new scope
2. Validates implementation still aligns
3. Checks for technical debt introduced
4. Posts review to ClickUp

Output:

• Updated ClickUp task
• Updated session files
• Scope change documented
• Quality validation complete

When to Use:

• Requirements change mid-development
• New features added to scope
• Features removed from scope
• Need to document scope evolution

Alternative:

• Update ClickUp manually
• Update session files manually
• Launch code-reviewer for validation

---

/fix-build

Purpose: Automatically detect and fix build errors by launching specialized agents

Syntax:

/fix-build [optional error description]

Examples:

# Auto-detect and fix current build errors
/fix-build

# With context about the error
/fix-build "unused imports after refactoring"

# With specific error message
/fix-build "TypeScript error in UserProfile.tsx"

What It Does:

Phase 1 - Error Detection:

1. Runs pnpm build to capture errors
2. Analyzes error output (stderr)
3. Categorizes errors:
   • FRONTEND: React components, hooks, TypeScript in app/
   • BACKEND: API routes, server logic, database errors
   • PLUGIN: Plugin configs, registry issues
   • REGISTRY: Build scripts, dynamic imports, registry generation

Phase 2 - Agent Selection:

• Frontend errors → Launches frontend-developer
• Backend errors → Launches backend-developer
• Plugin errors → Launches dev-plugin
• Registry errors → Launches backend-developer (for build scripts)
• General errors → User manual review (no agent)

Phase 3 - Automated Fixing:

1. Agent reads affected files
2. Analyzes error context
3. Makes targeted fixes
4. Runs pnpm build to verify
5. Updates TodoWrite with progress

Phase 4 - Iteration Loop:

• If build succeeds → Done ✅
• If build still fails → Repeat (max 5 attempts)
• If max attempts reached → Report to user for manual intervention

Output:

• Build errors fixed automatically
• TodoWrite task tracking
• Summary of changes made
• Build status confirmation

Real-World Examples:

Example 1: Unused Imports (Frontend)

/fix-build

Output:

🔧 /fix-build - Automated Build Error Fixing

📋 Step 1: Running build...
❌ Error: 'useState' is declared but never used
   at app/components/UserProfile.tsx:1:10

📊 Category: FRONTEND
🤖 Launching frontend-developer agent...

✅ Fixed: Removed unused import 'useState'
✅ Build succeeded!

Attempts: 1/5
Agent: frontend-developer

Example 2: Session Type Error (Backend)

/fix-build "session type error in API"

Output:

🔧 /fix-build - Automated Build Error Fixing

📋 Step 1: Running build...
❌ Error: Property 'userId' does not exist on type 'Session | null'
   at app/api/v1/todos/route.ts:15:25

📊 Category: BACKEND
🤖 Launching backend-developer agent...

✅ Fixed: Added session null check
✅ Build succeeded!

Changes:
- Added type guard for session validation
- Added 401 response for missing session

Attempts: 1/5
Agent: backend-developer

Example 3: Plugin Registry Error (Plugin)

/fix-build "AI plugin not loading"

Output:

🔧 /fix-build - Automated Build Error Fixing

📋 Step 1: Running build...
❌ Error: Cannot find module '@/contents/plugins/ai/config'
   at core/lib/registries/plugin-registry.ts:12:5

📊 Category: PLUGIN
🤖 Launching dev-plugin agent...

✅ Fixed:
- Rebuilt plugin registry
- Fixed config.ts default export
- Verified plugin registration

✅ Build succeeded!

Attempts: 2/5
Agent: dev-plugin

When to Use:

• Build fails during development
• Quick iterative fixes needed
• Post-merge integration errors
• Refactoring cleanup
• Plugin configuration issues

When NOT to Use:

• Major architectural changes (use /init-task instead)
• Environment/config issues (manual fix needed)
• Deliberate breaking changes (plan first)
• Learning opportunities (fix manually to learn)

Error Categories Detected:

Frontend Patterns:

• Unused imports/variables
• React Hook rules violations
• TypeScript errors in components
• Component prop type mismatches
• Import path errors

Backend Patterns:

• API route errors
• Session/auth type errors
• Database query errors
• Middleware errors
• Server-side TypeScript errors

Plugin Patterns:

• Plugin configuration errors
• Plugin registry generation failures
• Plugin type export issues
• Plugin dependency errors

Registry Patterns:

• Dynamic import violations
• Registry build script errors
• Hardcoded imports from @/contents
• Theme/plugin discovery failures

Iteration & Success:

• Max attempts: 5 iterations
• Success criteria: pnpm build exits with code 0
• Failure handling: Reports to user after max attempts
• TodoWrite tracking: All progress tracked in todo list

Alternative:

• Launch specialized agents manually (frontend-developer, backend-developer, etc.)
• Fix errors manually (better for learning)
• Use /init-task for complex refactoring requiring planning

---

/release

Purpose: Analyze changes and create semantic version releases with intelligent version determination

Syntax:

/release [optional: version type or specific version]

Examples:

# Auto-detect version type (recommended)
/release

# Explicit version type
/release make a patch
/release make a minor
/release make a major

# Specific version
/release as v2.0.0
/release version 1.5.3

What It Does:

Phase 1 - Prerequisites Verification:

1. Checks git working directory is clean
2. Verifies on main/master branch
3. Confirms core.version.json exists

Phase 2 - Release Analysis (Release Manager):

1. Reads current version from core.version.json
2. Reads release documentation (core/docs/17-updates/02-release-version.md)
3. Analyzes recent git commits
4. Checks for active session context
5. Categorizes changes:
   • BREAKING CHANGES → MAJOR version
   • NEW FEATURES → MINOR version
   • BUG FIXES → PATCH version

Phase 3 - User Approval:

1. Presents analysis with categorized changes
2. Recommends version bump with justification
3. Waits for user approval:
   • "yes" → Proceed with recommendation
   • "no" → Cancel release
   • "patch/minor/major" → Use specified type
   • "vX.Y.Z" → Use specific version

Phase 4 - Release Execution:

1. Executes pnpm release --<type> or pnpm release --version X.Y.Z
2. Updates core.version.json
3. Creates Git commit and tag
4. Pushes tags to remote repository
5. Reports completion with new version

Output:

📊 Release Analysis Complete

Current Version: v0.1.0
Analyzed: 15 commits, 42 files changed

Changes Detected:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[Category 1: NEW FEATURES]
  ✓ Added release-manager agent
  ✓ Added /release command
  ✓ New updates documentation system

[Category 2: BUG FIXES]
  ✓ Fixed pagination in docs

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Recommendation: MINOR version bump
New Version: v0.2.0

Justification:
- New features added (release system, docs)
- No breaking changes detected
- Backward-compatible additions

Do you approve this release?
  • Type 'yes' to proceed with v0.2.0
  • Type 'no' to cancel
  • Type 'patch/minor/major' for different version type
  • Type 'vX.Y.Z' for specific version

[User approves]

✅ Release v0.2.0 Created Successfully!

Summary:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Previous Version: v0.1.0
  New Version: v0.2.0
  Release Type: MINOR
  
Git Status:
  ✓ Version file updated (core.version.json)
  ✓ Commit created: "chore: release v0.2.0"
  ✓ Tag created: v0.2.0
  ✓ Pushed to remote: origin/main

Next Steps:
  1. ✓ Release is live on remote repository
  2. Create GitHub Release (optional)
  3. Announce release to team/users

When to Use:

• Feature development complete and committed
• Bug fixes ready for release
• Ready to publish new version
• Need semantic version guidance

Prerequisites:

• ✅ All changes committed (clean git status)
• ✅ On main or master branch
• ✅ Changes reviewed and approved
• ✅ Tests passing

When NOT to Use:

• Uncommitted changes in working directory
• On feature branch (must be on main/master)
• Experimental changes not ready for release
• Breaking changes without proper review

Version Decision Guide:

PATCH (0.1.0 → 0.1.1):

• Bug fixes
• Security patches
• Documentation updates
• Performance improvements
• Internal refactoring

MINOR (0.1.0 → 0.2.0):

• New features (backward-compatible)
• New plugins or themes
• New API endpoints
• New components
• Optional features with defaults

MAJOR (0.5.0 → 1.0.0):

• Breaking API changes
• Removed features
• Database schema changes
• Major refactoring
• Migration required

Alternative:

• Manual release: pnpm release --patch/minor/major
• Launch release-manager agent directly
• Create Git tags manually for non-semantic releases

See Also:

• Release Version Documentation - Complete guide to releases
• Core Updates Documentation - Updating to new releases

---

Creating Custom Commands

Command File Structure

---
description: Brief description of what command does
---

# Command Name

Detailed description and instructions

**Input:**
{{{ input }}}

## Phase 1: First Agent

Launch `agent-name` to do...

## Phase 2: Second Agent

Launch `agent-name` to do...

## Output

What this command produces...

Example: Custom /qa-only Command

File: .claude/commands/qa-only.md

---
description: Run only QA testing for an already-developed feature
---

# QA Only Testing

Execute only the QA testing phase for a feature that's been developed but not tested yet.

**Session Name:**
{{{ input }}}

## Phase 1: Validation

Verify session exists and development is complete:

```typescript
const sessionPath = `.claude/sessions/${sessionName}/`
const progress = readFile(`${sessionPath}progress_{sessionName}.md`)

// Check Phase 1 and 2 are complete
if (!phasesComplete(progress, [1, 2])) {
  throw new Error('Development not complete. Backend and Frontend phases must be done.')
}

Phase 2: QA Testing

Launch qa-tester agent to:

1. Read session files
2. Execute test cases
3. Create bug reports if needed
4. Update ClickUp status

Output

• QA test results
• Bug sub-tasks (if issues found)
• ClickUp status updated

### Usage

```bash
/qa-only user-profile-edit

---

Command Best Practices

When to Use Commands

✅ DO use commands when:

• Workflow is repetitive
• Multiple agents needed in sequence
• Want automation
• Teaching workflow to team

❌ DON'T use commands when:

• Single agent is enough
• Need fine control
• Workflow is unique
• Experimenting with approach

Command Design

Good Command Characteristics:

• Clear, single purpose
• Predictable workflow
• Good validation
• Clear error messages
• Documented output

Bad Command Characteristics:

• Too many phases
• Ambiguous behavior
• Poor error handling
• Unclear purpose

Command vs Direct Agent Usage

Use Command:

/init-task Add payment integration
# Automatic: PM → Architect → Done

Use Direct Agents:

# More control over each step
Launch product-manager to create task: Add payment integration
# Review PM output
Launch architecture-supervisor to create technical plan
# Review architect output, make adjustments

Choose based on:

• Need for automation vs control
• Workflow complexity
• Team experience level

---

Command Workflow Patterns

Linear Workflow

Phase 1 → Phase 2 → Phase 3 → Done

Example: /init-task

• PM creates requirements
• Architect creates plan
• Done

Conditional Workflow

Phase 1 → Phase 2 → [Decision] → Phase 3a or Phase 3b

Example: /execute-task with QA

• Development completes
• QA tests
• If bugs: Loop back to development
• If passed: Proceed to review

Parallel Workflow

        ┌─> Phase 2a ─┐
Phase 1 ┤             ├─> Phase 3
        └─> Phase 2b ─┘

Example: Custom simultaneous documentation + deployment

• Feature complete
• Generate docs + Deploy to staging (parallel)
• Final review

---

Command Execution Flow

1. Command Invocation

User: /init-task Add dark mode toggle

2. Input Parsing

const commandName = 'init-task'
const input = 'Add dark mode toggle'

3. Command File Loading

const commandFile = `.claude/commands/${commandName}.md`
const commandContent = readFile(commandFile)

4. Agent Orchestration

// Execute phases sequentially
await executePhase1(input) // Launch PM
await executePhase2(input) // Launch Architect

5. Output Reporting

console.log(`
✅ Task Initialized: Dark Mode Toggle

Session: .claude/sessions/dark-mode-toggle/
ClickUp Task: #86abc123
Status: Ready for development
`)

---

Debugging Commands

Command Not Found

Error: Command '/init-task' not found

Solution:

• Verify file exists: .claude/commands/init-task.md
• Check file naming (kebab-case, .md extension)
• Ensure frontmatter is valid

Agent Launch Failed

Error: Could not launch agent 'product-manager'

Solution:

• Verify agent file exists: .claude/agents/product-manager.md
• Check agent configuration
• Review agent file for syntax errors

Session File Missing

Error: Session file not found: clickup_task_feature.md

Solution:

• Verify session folder exists
• Check session naming matches command input
• Run /init-task first to create session

---

Command Cheat Sheet

Command	Purpose	Agents Used	Output
/init-task	Initialize new task	PM, Architect	Session folder, ClickUp task
/execute-task	Full development cycle	Backend, Frontend, QA, Reviewer	Complete feature
/document-feature	Generate docs	Documentation Writer	Feature docs
/scope-change	Handle scope changes	PM, Reviewer	Updated task, validation
/fix-build	Auto-fix build errors	Frontend/Backend/Plugin (auto-selected)	Fixed build, summary
/release	Create version release	Release Manager	Version bump, Git tags

Typical Workflow:

# 1. Initialize task
/init-task Add user notifications

# 2. Execute development
/execute-task user-notifications

# 3. Fix build errors (if any)
/fix-build

# 4. Generate documentation
/document-feature user-notifications

# 5. Create release
/release

# Feature complete and released!

---

Advanced Command Patterns

Composable Commands

Create commands that call other commands:

---
description: Initialize and immediately execute task
---

# Init and Execute

## Phase 1: Initialize
Run /init-task command with input

## Phase 2: Execute
Run /execute-task command with same input

Parameterized Commands

/execute-task user-profile-edit --skip-qa --no-review

Handle parameters in command file:

const skipQA = args.includes('--skip-qa')
const noReview = args.includes('--no-review')

Multi-Session Commands

/batch-execute session1,session2,session3

Execute same workflow for multiple sessions.

---

Next Steps

• ClickUp Integration - Optional project management setup
• Customization - Create custom commands and workflows
• Development Workflow - See commands in action