Workflow

Purpose

Manage the development environment lifecycle for ticket-based work. This skill handles setup (branch, worktree, context) and delegates implementation to /bugfix or /task based on ticket type.

Quick Reference

• •Creates: Feature branch, worktree, workflow context file
• •Requires: Ticket source (Linear ID or plain text description)
• •Delegates to: /bugfix (fix tickets) or /task (feat, chore, refactor, docs)

Config Location

Config path depends on how the plugin was installed:

Precedence when reading (first found wins):

1. •.claude/skills/workflow.local.yaml
2. •.claude/skills/workflow.yaml
3. •Skill defaults

When to Use

• •Starting work on a new ticket or feature
• •Beginning a bug fix from a ticket system (Linear)
• •Creating an isolated worktree for development
• •Completing work and cleaning up after PR merge

Commands

Related: Use /pr-merge to merge PRs, /deploy to deploy after merge.

Configure Mode

Configure workflow preferences during framework setup:

/workflow configure

Discovers:

• •Worktree base path preference
• •IDE preference (Cursor, VSCode, WebStorm)
• •Environment file copying settings

Outputs: .claude/workflow-config.json (via workflow-setup)

This is typically run once during framework setup wizard.

When to Start a Workflow

Only start a new workflow when on main branch.

Key Rules:

• •main is the only non-working branch
• •Any branch other than main is a working branch
• •If already on a working branch, continue working there unless user explicitly requests a new workflow
• •Trigger phrases on main: "start a workflow", "let's work on...", "fix this issue...", or any code change task

Session Continuation

After /workflow start opens the IDE with the new worktree, run this in the new Claude session:

/workflow continue

What it does:

1. •Checks current branch name
2. •Looks for .claude/workflow/<branch>/pending-action.json
3. •If found, reads the pending action and context
4. •Prompts user based on the type:
   • •fix → Invoke /bugfix skill (B1: Reproduce)
   • •feat/other → Invoke /task skill (T1: Scope)

When to use:

• •After /workflow start opens a new IDE window
• •Resuming work on a ticket in an existing worktree

Phase 1: Start

/workflow start PROJ-123                     # From Linear ticket
/workflow start "Add user notifications"  # From plain text

Pre-condition: Must be on main branch (or user explicitly requested new workflow)

Procedure:

1. •Detect source type (Linear ID pattern XXX-### vs plain text)
2. •If Linear: fetch ticket details via MCP
3. •Check for uncommitted changes (warn if present)
4. •Determine branch type from context: feat, fix, refactor, docs, chore, test
5. •Generate branch name with type prefix:
   • •Linear: <type>/<ticket-id-lowercase>-<kebab-description>
   • •Plain text: <type>/<kebab-description>
6. •Call workflow-setup:
   • •Create git worktree at configured path
   • •Copy .env* files to worktree
   • •Install dependencies in worktree
   • •Create .claude/workflow/<branch>/ directory
   • •Copy plan if .claude/plan.md exists
   • •Write pending-action.json for session handoff
   • •Open IDE with worktree
7. •Output next steps message telling user to run /workflow continue in the new session
8. •--- HANDOFF: User opens new Claude session in IDE ---
9. •User runs /workflow continue to resume the workflow
10. •Delegate based on type:
    • •fix → Invoke /bugfix skill (5-phase debugging methodology)
    • •feat/other → Invoke /task skill (4-phase implementation methodology)

Task Delegation

Based on the ticket type detected in start:

Both /bugfix and /task have a Plan phase (B2/T2) that:

• •Uses /developer for code patterns
• •Requires user approval before proceeding

Retrospective (After Implementation)

After completing the implementation (feature or bug fix), capture learnings before committing:

Procedure:

1. •Scan conversation for signals:
   • •Corrections (high confidence): "No, don't use X, use Y"
   • •Rules (high confidence): "Always do X", "Never do Y"
   • •Approvals (medium): "Perfect!", "That's exactly right"
2. •Route learnings to appropriate skill MEMORY.md files:
   • •Testing patterns → tdd/MEMORY.md
   • •Domain concepts → domain-expert/MEMORY.md
   • •Architecture rules → arch/MEMORY.md
   • •General code → developer/MEMORY.md

Learning Quality Rules:

• •Must be actionable (DO/DON'T/USE/AVOID)
• •Must be complete sentences, not fragments
• •Must NOT be questions
• •Must include WHY, not just WHAT

Commit and PR

After retrospective, use the dedicated skills:

1. •Commit changes: /commit
2. •Create PR: /pr-create

These skills handle conventional commit messages, PR formatting, and CI validation.

Phase 2: Status

/workflow status

Shows:

• •Current branch and ticket info
• •Implementation plan progress (or bug fix phase for type: fix)
• •PR status (if created)

Phase 3: Finish

/workflow finish
/workflow finish feat/proj-123-feature-name    # Explicit branch

Pre-condition: PR must be merged before finishing.

Procedure:

1. •Resolve target branch (current branch or argument)
2. •Verify PR is merged via gh pr list --head <branch> --state merged
3. •Switch to main branch and pull latest
4. •Remove worktree: git worktree remove <path>
5. •Delete local branch: git branch -D <branch>
6. •Clean up workflow context: rm -rf .claude/workflow/<branch>/
7. •Report completion

See workflow-finish skill for detailed procedure and sharp edges.

Workflow Context

Stored in .claude/workflow-context.json (gitignored):

{
  "source": "linear",
  "ticketId": "PROJ-123",
  "title": "Add user notifications",
  "branch": "feat/proj-123-add-user-notifications",
  "type": "feat",
  "createdAt": "2026-01-21T...",
  "prUrl": null
}

Branch Naming

Format: <type>/<ticket-id-lowercase>-<kebab-description> or <type>/<kebab-description>

Branch naming convention:

• •Type prefix first (feat/, fix/, chore/, docs/, refactor/, test/)
• •Ticket ID in lowercase (if from Linear)
• •Followed by kebab-case description from title

Examples:

• •feat/proj-123-add-user-notifications
• •fix/proj-456-fix-date-parsing-error
• •chore/eng-789-add-skill-for-claude-code-to-set-up-dev-environment
• •feat/add-metrics-dashboard (plain text, no ticket)

Automation

See skill.yaml for the full procedure and patterns. See sharp-edges.yaml for common failure modes.