Setup cc-track Command

Guide the user through setting up cc-track in their project. This is the primary entry point for new users after installing the plugin.

Important Pre-Checks

Before proceeding with setup, verify:

1. Bun Runtime Verification

Check if Bun is installed:

bun --version

If this fails:

Stop immediately and show the Bun installation error message
Guide user to install Bun based on their platform:
- Windows: powershell -c "irm bun.sh/install.ps1 | iex" or download from https://bun.sh
- macOS/Linux: curl -fsSL https://bun.sh/install | bash
Ask them to restart their terminal and try /setup-cc-track again

2. Plugin Dependencies Verification

Check if plugin dependencies are installed by verifying these directories exist:

${CLAUDE_PLUGIN_ROOT}/node_modules/@anthropic-ai/claude-agent-sdk
${CLAUDE_PLUGIN_ROOT}/node_modules/ccusage

Use the file system to check existence (platform-independent).

If either directory doesn't exist:

Stop immediately and show the missing dependencies error message
Guide user to run:
```
cd ${CLAUDE_PLUGIN_ROOT}
bun install
```
Ask them to try /setup-cc-track again after installation completes

3. npm/Plugin Conflict Detection

Check if the old npm version of cc-track is still installed:

macOS/Linux: which cc-track
Windows: where cc-track or Get-Command cc-track

If this returns a path (meaning npm version is installed):

Stop immediately and show the npm/plugin conflict error message
Explain that both versions cannot coexist in the same project
Guide user to uninstall npm version:
```
npm uninstall -g cc-track
```
Verify removal: the command above should show "not found" or error
Ask them to try /setup-cc-track again

All three checks must pass before proceeding with setup.

Setup Workflow

Once pre-checks pass, guide the user through:

1. Project Analysis

Ask about their project:

What type of project? (web app, library, CLI tool, etc.)
What languages/frameworks? (TypeScript, React, Next.js, etc.)
Do they use GitHub? (for GitHub integration)
Do they have existing .claude/ or .cc-track/ files? (migration vs new setup)

2. Git Status Check

Run git status to verify:

Is this a git repository?
Are there uncommitted changes?

If uncommitted changes exist:

Suggest committing them first: "I see uncommitted changes. Would you like to commit them before setup?"
If yes, help create a commit
If no, warn that setup will create files and suggest being careful

If not a git repo:

Offer to initialize: "This isn't a git repository yet. Would you like to initialize one?"
If yes, run git init
If no, warn that some features (git branching, GitHub integration) won't work

3. Feature Selection

Present feature options and let user choose what to enable:

Always Enabled (Core Functionality):

Task management via /cc-track:specify, /cc-track:plan, /cc-track:tasks workflow
Context preservation (CLAUDE.md with imports)
Basic project structure in .cc-track/

Optional Features:

Development Workflow:

edit_validation - Real-time TypeScript and lint checking on file edits
- ✅ Pros: Immediate feedback, catches errors early, enforces code quality
- ⚠️ Cons: Blocks edits if errors found (by design - prevents context poisoning)
- Ask: "Would you like real-time validation? (recommended for TypeScript projects)"
pre_tool_validation - Task file integrity checks before tool use
- ✅ Pros: Prevents manual task status changes, enforces proper workflow
- ⚠️ Cons: Blocks any attempt to manually edit task metadata
- Ask: "Would you like task file validation?"
branch_protection - Prevent edits on protected branches (main/master)
- ✅ Pros: Prevents accidental commits to main, enforces feature branch workflow
- ⚠️ Cons: Must use /cc-track:plan or /cc-track:specify to create feature branches first
- Configurable: Which branches to protect, allow edits to gitignored files
- Ask: "Would you like branch protection? (recommended for teams)"
- If yes, ask: "Which branches should be protected?" (default: main, master)

Git & GitHub Integration:

git_branching - Automatic feature branch creation from tasks
- ✅ Pros: Keeps work isolated, enforces clean git workflow, automatic naming
- ⚠️ Cons: Creates branches you need to manage/clean up later
- Ask: "Create feature branches automatically for each task?"
github_integration - Issue and PR automation
- ✅ Pros: Full GitHub workflow automation, links tasks to issues/PRs, team visibility
- ⚠️ Cons: Requires GitHub CLI installed and authenticated
- Requires: GitHub CLI (gh) installed and authenticated
- Sub-options:
  - auto_create_issues - Create GitHub issue for each task (recommended for teams)
  - use_issue_branches - Use gh issue develop for issue-linked branches
  - auto_create_prs - Create PR on task completion rather than auto-merge
- Ask: "Enable GitHub integration? (requires gh CLI)"
- If yes, verify gh is installed: gh --version
- If yes, ask which sub-options to enable

Display & Monitoring:

statusline - Custom status line with task, costs, API limits
- ✅ Pros: Always-visible context (current task, cost tier, rate limits, branch)
- ⚠️ Cons: Takes up 2 lines in Claude Code UI, requires restart to activate
- Shows: Model/cost tier/rate/tokens (line 1), branch/task (line 2)
- Ask: "Enable custom status line in Claude Code UI?"
- Note: Requires Claude Code restart after setup
api_timer - API rate limit timer display in statusline
- ✅ Pros: Helps avoid hitting rate limits by showing countdown timer
- ⚠️ Cons: Can clutter statusline if you rarely hit limits
- Options:
  - "sonnet-only" (default) - Show timer only for Claude Sonnet (most common limit)
  - "show" - Always show timer for all models
  - "hide" - Never show timer
- Ask: "How should API rate limit timer display?" (default: sonnet-only)

Code Quality:

code_review - Automated code review integration
- ✅ Pros: Get AI-powered code review feedback before task completion, catch issues early
- ⚠️ Cons: Reviews can take several minutes, requires additional tools installed
- Options:
  - claude - Uses Claude Code SDK for fast, context-aware reviews (10min timeout)
  - codex - Uses Codex CLI for systematic, thorough reviews (30min timeout)
  - coderabbit - Uses CodeRabbit CLI to analyze code changes (30min timeout)
- Ask: "Enable automated code review? Choose: 'claude', 'codex', 'coderabbit', or 'skip' to disable"
- If enabled, verify tool is installed and explain timeout expectations

Advanced:

autoflow - Autonomous operation mode for unattended task completion
- ✅ Pros: Claude works through tasks without constant "should I continue?" prompts
- ✅ Pros: Per-message opt-in (include "autoflow" in your message to activate)
- ✅ Pros: Throttle detection prevents runaway sessions (default: 3 auto-continues per 5 minutes)
- ⚠️ Cons: Permission requests are denied with "find safe alternative" guidance
- How it works:
  - Include "autoflow" in your message to activate for that task
  - Claude auto-continues when stopped if work remains
  - Permission requests denied → Claude must find safe workarounds or stop
  - Deactivates when: task complete, throttle limit hit, or next message without "autoflow"
- Configurable:
  - throttle_limit - Max auto-continues before exit (default: 3)
  - window_duration_minutes - Throttle detection window (default: 5)
- Ask: "Enable autoflow mode? (autonomous operation for unattended tasks)"
private_journal - Use private journal MCP for context preservation
- ✅ Pros: Claude can record learnings and reflections privately for future reference
- ⚠️ Cons: Requires mcp-private-journal MCP server installed
- Ask: "Enable private journal MCP? (requires mcp-private-journal installed)"
websearch_validation - Validate WebSearch tool usage
- ✅ Pros: Ensures web searches are relevant and necessary before execution
- ⚠️ Cons: Adds validation overhead to every web search operation
- Ask: "Enable web search validation? (helps prevent unnecessary searches)"

Windows Only:

powershell_guidance - Windows compatibility hook with two functions:
1. Command conversion: Auto-converts simple Linux commands (cat, rm, cp, mv, head, tail, etc.) to PowerShell
2. Path normalization: Converts forward slashes to backslashes in file operations (workaround for Claude Code #7918)
- ✅ Pros: Auto-converts simple Linux commands to PowerShell equivalents
- ✅ Pros: Rejects complex commands with clear PowerShell alternatives and syntax examples
- ✅ Pros: Prevents trial-and-error when Claude tries Linux commands that fail on Windows
- ✅ Pros: Fixes "File has been unexpectedly modified" errors on Windows (Claude Code bug #7918)
- ⚠️ Only useful on Windows - do NOT enable on macOS/Linux
- Ask: (only if on Windows) "Enable Windows compatibility hook? (fixes path issues, auto-converts Linux commands)"
- Note: This is a PreToolUse hook that intercepts Bash, Edit, Write, Read, and MultiEdit tools

4. Configuration File Creation

Based on user selections, create .cc-track/track.config.json:

Read the template from ${CLAUDE_PLUGIN_ROOT}/templates/track.config.json and customize based on user's feature selections.

Example structure:

{
  "hooks": {
    "edit_validation": {
      "enabled": true/false,
      "typecheck": {
        "enabled": true/false
      },
      "lint": {
        "enabled": true/false
      }
    },
    "pre_tool_validation": {
      "enabled": true/false
    },
    "powershell_guidance": {
      "enabled": true/false
    },
    "autoflow": {
      "enabled": true/false,
      "throttle_limit": 3,
      "window_duration_minutes": 5
    }
  },
  "features": {
    "statusline": {
      "enabled": true/false
    },
    "git_branching": {
      "enabled": true/false
    },
    "private_journal": {
      "enabled": true/false
    },
    "branch_protection": {
      "enabled": true/false,
      "protected_branches": ["main", "master"],
      "allow_gitignored": true
    },
    "api_timer": {
      "display": "hide"|"show"|"sonnet-only"
    },
    "github_integration": {
      "enabled": true/false,
      "auto_create_issues": true/false,
      "use_issue_branches": true/false,
      "auto_create_prs": true/false
    },
    "code_review": {
      "enabled": true/false,
      "tool": "claude"|"codex"|"coderabbit"
    },
    "websearch_validation": {
      "enabled": true/false
    }
  },
  "logging": {
    "enabled": true,
    "level": "info",
    "retentionDays": 7
  }
}

Set enabled flags based on user's choices from step 3.

5. Create Customized Project Files

CRITICAL: Only create files that don't already exist. Never overwrite existing files without explicit user permission.

First, create the .cc-track/ directory structure:

Use Claude Code's file system tools to create directories (platform-independent), or:

macOS/Linux: mkdir -p .cc-track/specs
Windows: mkdir .cc-track\specs (creates parent directories automatically)

Then create customized project files in .cc-track/ ONLY if they don't exist:

For each file:

Check if it exists first - If it exists, skip it and inform the user
Read the corresponding template from ${CLAUDE_PLUGIN_ROOT}/templates/
Customize the content based on user's project information (gathered in step 1)
Write the customized file to the project's .cc-track/ directory

Files to create (read templates, customize, write):

CLAUDE.md (project root)
- Read: ${CLAUDE_PLUGIN_ROOT}/templates/CLAUDE.md
- Customize: Replace "[Project Name]" with actual project name, adjust @ imports for project structure (pointing to .cc-track/)
- Write: CLAUDE.md
.cc-track/no_active_task.md
- Read: ${CLAUDE_PLUGIN_ROOT}/templates/no_active_task.md
- Customize: Minimal (just use template content)
- Write: .cc-track/no_active_task.md
.cc-track/product_context.md
- Read: ${CLAUDE_PLUGIN_ROOT}/templates/product_context.md
- Customize: Fill in project purpose, audience, features based on user's answers from step 1
- Write: .cc-track/product_context.md
.cc-track/system_patterns.md
- Read: ${CLAUDE_PLUGIN_ROOT}/templates/system_patterns.md
- Customize: Add detected framework/language patterns based on project type
- Write: .cc-track/system_patterns.md
.cc-track/decision_log.md
- Read: ${CLAUDE_PLUGIN_ROOT}/templates/decision_log.md
- Customize: Add initial setup decisions (features enabled, etc.)
- Write: .cc-track/decision_log.md
.cc-track/code_index.md
- Read: ${CLAUDE_PLUGIN_ROOT}/templates/code_index.md
- Customize: Scan project directory structure and populate with actual directories
- Write: .cc-track/code_index.md
.cc-track/user_context.md
- Read: ${CLAUDE_PLUGIN_ROOT}/templates/user_context.md
- Customize: Minimal (template provides structure for future updates)
- Write: .cc-track/user_context.md
.cc-track/backlog.md
- Read: ${CLAUDE_PLUGIN_ROOT}/templates/backlog.md
- Customize: Minimal (empty list, ready for future items)
- Write: .cc-track/backlog.md
.cc-track/progress_log.md
- Read: ${CLAUDE_PLUGIN_ROOT}/templates/progress_log.md
- Customize: Minimal (template provides structure for future updates)
- Write: .cc-track/progress_log.md

After creating files, inform the user:

"Created X new customized files"
"Skipped Y existing files (not overwritten)"
"Files are ready for your project - you can further customize them anytime"

7. Hooks Configuration

Based on enabled features, configure hooks in Claude Code settings.

Show user what hooks will be enabled:

edit_validation → PostToolUse hook
pre_tool_validation → PreToolUse hook
powershell_guidance → PreToolUse hook (Windows only)

Explain:

Hooks execute TypeScript files from ${CLAUDE_PLUGIN_ROOT}/hooks/
User can disable individual hooks via /config-track later
The powershell_guidance hook intercepts Bash/Edit/Write/Read tools to:
- Convert Linux commands to PowerShell or provide guidance
- Normalize file paths to Windows backslash format (fixes Claude Code bug #7918)

8. Configure Claude Code Settings (if statusline enabled)

If the user enabled the statusline feature, configure it in the project-local .claude/settings.json file.

Create or update .claude/settings.json in the project root:

{
  "statusLine": {
    "type": "command",
    "command": "bun run ${CLAUDE_PLUGIN_ROOT}/scripts/statusline.ts",
    "padding": 0
  }
}

Use Claude Code's Write tool to create/update this file (platform-independent).

Inform the user:

"✓ Configured Claude Code statusline in .claude/settings.json"
"⚠️ You may need to restart Claude Code for the statusline to appear"

Note: The statusline uses ${CLAUDE_PLUGIN_ROOT} which Claude Code expands automatically. This works cross-platform.

9. Final Steps

After setup completes:

Verify installation:
- Check .cc-track/track.config.json exists
- Check customized files created
- Check CLAUDE.md has proper @ imports
Next steps guidance:
- "Setup complete! 🚅"
- "Optional: Run /cc-track:constitution to set up project guardrails and architectural constraints"
- "Try creating your first spec: /cc-track:specify \"your feature idea\""
- "Configure anytime with: /config-track"
- If statusline configured: "⚠️ Restart Claude Code to see the custom statusline"
GitHub setup (if enabled):
- "To use GitHub integration:"
- "1. Install GitHub CLI: https://cli.github.com"
- "2. Authenticate: gh auth login"
- "3. Run /cc-track:specify to create your first task with auto-issue creation"

Error Messages

Use these pre-formatted messages for common issues:

Bun Not Installed

⚠️ Bun runtime not found

cc-track plugin requires Bun runtime to execute TypeScript directly.

To install Bun:

**Windows (PowerShell):**
powershell -c "irm bun.sh/install.ps1 | iex"

**macOS/Linux:**
curl -fsSL https://bun.sh/install | bash

Or visit https://bun.sh for installation instructions.

After installing Bun, restart your terminal and try `/setup-cc-track` again.

Plugin Dependencies Missing

⚠️ Plugin dependencies not installed

cc-track plugin dependencies are not installed. You need to run `bun install` in the plugin directory.

To install dependencies:
```bash
cd ${CLAUDE_PLUGIN_ROOT}
bun install

After installing, try /setup-cc-track again.


### npm/Plugin Conflict

⚠️ npm/plugin conflict detected

You have both the npm package and plugin versions of cc-track installed. This will cause conflicts. Please uninstall the npm version first.

To uninstall the npm version: npm uninstall -g cc-track

Verify removal:

macOS/Linux: which cc-track (should show: not found)
Windows: where cc-track (should show: not found or error)

After uninstalling, try /setup-cc-track again.


---

## Important Notes

- **Never run git commands without user permission** (except read-only like `git status`)
- **Never overwrite existing files without asking** (check existence first)
- **Always explain what each feature does** before enabling
- **Provide undo instructions** for any destructive actions
- **Be explicit about dependencies** (gh CLI, Bun, etc.)
- **Show next steps clearly** after successful setup

This is the user's first experience with cc-track - make it smooth and transparent! 🚅