Claude Issues - Systematic Workflow System

A workflow orchestration system for Claude Code that provides structured guidance through systematic issue-based development.

What is this?

Claude Issues is an NPM package that installs hooks and protocols into your Claude Code project, providing:

• Workflow Activation: Opt-in per session - activate with /work or by referencing issues
• Authorization System: Discussion mode (read-only) by default, with keyword-based authorization for write operations
• Conventions Management: Auto-detects and guides setup of project conventions
• Git Branch Management: Automatically creates and switches to feature branches when you reference issues
• Action Coordination: Priority-based system ensures critical actions run first

Quick Start

npx claude-issues

This installs the workflow system into your current directory at .claude/ and .issues/.

For end users: After installation, see .issues/README.md for complete usage guide covering all commands, workflow phases, and troubleshooting.

How It Works

The system operates through hooks that intercept Claude Code events and inject context-aware guidance. Below are visual flow diagrams showing how all features work together.

User Journey Overview

flowchart TD
    Start[User starts Claude Code] --> SessionStart[SessionStart Hook]
    SessionStart --> ResetWorkflow[Reset workflowEnabled = false]
    ResetWorkflow --> Disabled[System Disabled]

    Disabled --> UserPrompt[User sends prompt]

    UserPrompt --> CheckActivation{Activation trigger?}
    CheckActivation -->|/work command| Activate
    CheckActivation -->|@issue reference| Activate
    CheckActivation -->|Neither| NoAction[No workflow actions]

    Activate[Activate System] --> CheckConventions{Conventions exist?}
    CheckConventions -->|No| InjectSetup[Inject conventions setup protocol]
    CheckConventions -->|Yes| Ready[System Ready]

    InjectSetup --> Ready
    Ready --> WorkflowActive[workflowEnabled = true]

    WorkflowActive --> UserWorking[User working]
    UserWorking --> AuthCheck{Authorization needed?}

    AuthCheck -->|Write operation| CheckMode{Mode?}
    CheckMode -->|Discussion| Block[Block + guidance]
    CheckMode -->|Action| Allow[Allow operation]

    AuthCheck -->|Read operation| Allow

    Block --> UserAuth[User says keyword]
    UserAuth --> SwitchMode[Switch to Action mode]
    SwitchMode --> Allow

    Allow --> TaskComplete{Task complete?}
    TaskComplete -->|Yes| Stop[Stop Hook]
    Stop --> Revert[Revert to Discussion mode]
    Revert --> UserWorking

    TaskComplete -->|No| UserWorking

    UserWorking --> NewSession{New session?}
    NewSession -->|Yes| SessionStart
    NewSession -->|No| UserWorking

Workflow Phases

The system guides users through structured phases when working on issues:

flowchart TD
    Start[Activate workflow on issue] --> DetectPhase[Phase Detection]

    DetectPhase --> Phase1{Has problem-statement.md?}
    Phase1 -->|No| ProblemStatement[Phase 1: Problem Statement]
    ProblemStatement --> Draft1[Create problem-statement-draft.md]
    Draft1 --> Iterate1[Iterate on draft]
    Iterate1 --> Finalize1[/finalize]
    Finalize1 --> PS[problem-statement.md created]

    Phase1 -->|Yes| Phase2{Has context-manifest.md?}
    Phase2 -->|No| ContextGathering[Phase 2: Context Gathering]
    ContextGathering --> Launch[Launch 5 parallel sub-agents]
    Launch --> Agents[architecture-mapper<br/>similarity-detector<br/>dependency-tracer<br/>test-analyzer<br/>git-investigator]
    Agents --> Merge[Merge outputs to draft]
    Merge --> Draft2[context-manifest-draft.md]
    Draft2 --> Iterate2[Review and iterate]
    Iterate2 --> Finalize2[/finalize]
    Finalize2 --> CM[context-manifest.md created]

    Phase2 -->|Yes| Phase3{Has end-state.md?}
    Phase3 -->|No| EndState[Phase 3: End State]
    EndState --> Draft3[Create end-state-draft.md]
    Draft3 --> Iterate3[Define target state & success criteria]
    Iterate3 --> Finalize3[/finalize]
    Finalize3 --> ES[end-state.md created]

    Phase3 -->|Yes| Phase4{Has solution-design/?}
    Phase4 -->|No| SolutionDesign[Phase 4: Solution Design]
    SolutionDesign --> ReadConventions[Read ALL conventions files]
    ReadConventions --> Draft4[Create solution-design-draft/ folder]
    Draft4 --> CreatePhases[Create overview.md + phases/*.md]
    CreatePhases --> PlanReview[Use plan-reviewer sub-agent]
    PlanReview --> Finalize4[/finalize]
    Finalize4 --> GenerateManifest[System generates manifest.json]
    GenerateManifest --> SD[solution-design/ created]

    Phase4 -->|Yes| Phase5{manifest.currentPhase <= totalPhases?}
    Phase5 -->|Yes| Implementation[Phase 5: Implementation]
    Implementation --> SyncManifest[Sync manifest from git]
    SyncManifest --> LoadPhase[Load current phase from manifest]
    LoadPhase --> GatherContext[Use codebase-context-gatherer]
    GatherContext --> ExecutePhase[Execute phase work items]
    ExecutePhase --> ReviewPhase[/review-phase - use review-phase-reviewer]
    ReviewPhase --> FinalizePhase[/finalize]
    FinalizePhase --> GitCommit[Create git commit: [phase:N] Phase Name]
    GitCommit --> AdvancePhase[manifest.currentPhase++]
    AdvancePhase --> Phase5

    Phase5 -->|No| Complete[Implementation complete]

    PS --> Phase2
    CM --> Phase3
    ES --> Phase4
    SD --> Phase5

Workflow Activation System

flowchart TD
    Prompt[UserPromptSubmit] --> ActivationHandler[workflow-activation-handler]
    ActivationHandler --> CheckEnabled{workflowEnabled?}

    CheckEnabled -->|true| Skip[Skip - already active]
    CheckEnabled -->|false| CheckTriggers{Check triggers}

    CheckTriggers --> Work{/work command?}
    Work -->|Yes| SetEnabled[Set workflowEnabled = true]

    CheckTriggers --> Issue{@issue reference?}
    Issue -->|Yes| SetEnabled

    CheckTriggers --> Neither[Neither trigger]
    Neither --> NoActivation[System stays disabled]

    SetEnabled --> ConventionsCheck{Conventions exist?}
    ConventionsCheck -->|No| SetupProtocol[Inject setup-conventions protocol]
    ConventionsCheck -->|Yes with /work| ActivationMsg[Show activation message]
    ConventionsCheck -->|Yes with @issue| GitBranch[Trigger git-branch-handler]

    SetupProtocol --> Done
    ActivationMsg --> Done
    GitBranch --> Done
    Done[Activation complete]

Session Lifecycle

sequenceDiagram
    participant User
    participant Claude
    participant SessionStart as SessionStart Hook
    participant Config as workflow-config.json
    participant Handlers as Workflow Handlers

    User->>Claude: Start new session
    Claude->>SessionStart: Fire SessionStart hook
    SessionStart->>Config: Read config
    Config-->>SessionStart: Current state
    SessionStart->>Config: Set workflowEnabled = false
    SessionStart-->>Claude: Reset complete

    User->>Claude: Normal prompt
    Claude->>Handlers: Fire UserPromptSubmit
    Handlers->>Config: Check workflowEnabled
    Config-->>Handlers: false (disabled)
    Handlers-->>Claude: No workflow actions

    User->>Claude: /work
    Claude->>Handlers: Fire UserPromptSubmit
    Handlers->>Config: Detect /work trigger
    Handlers->>Config: Set workflowEnabled = true
    Handlers-->>Claude: Activation message

    User->>Claude: Further prompts
    Claude->>Handlers: Fire hooks
    Handlers->>Config: Check workflowEnabled
    Config-->>Handlers: true (enabled)
    Handlers-->>Claude: Workflow guidance

Authorization System

flowchart TD
    ToolUse[Claude wants to use tool] --> PreTool[PreToolUse Hook]
    PreTool --> AuthInit[authorization-init-handler]
    AuthInit --> EnsureConfig[Ensure config exists]

    EnsureConfig --> CheckWorkflow{workflowEnabled?}
    CheckWorkflow -->|false| NoAuth[No authorization check]
    CheckWorkflow -->|true| SubAgentCheck

    SubAgentCheck[subagent-authorization-handler] --> IsTask{Task tool?}
    IsTask -->|Yes| AutoAction[Auto-switch to Action mode]
    IsTask -->|No| DraftCheck

    AutoAction --> DraftCheck[draft-authorization-handler]
    DraftCheck --> IsDraft{Draft file?}
    IsDraft -->|Yes| AllowTool[Allow tool]
    IsDraft -->|No| AuthCheck

    AuthCheck[authorization-tool-blocker] --> CheckType{Tool type?}
    CheckType -->|Write/Edit/NotebookEdit| WriteOp
    CheckType -->|Bash with >| WriteOp
    CheckType -->|Read/Grep/Glob| ReadOp

    WriteOp[Write operation] --> CheckAuthMode{Authorization mode?}
    CheckAuthMode -->|Discussion| BlockTool[Block + guidance]
    CheckAuthMode -->|Action| AllowTool

    ReadOp[Read operation] --> AllowTool

    BlockTool --> ShowGuidance[Show authorization guidance]
    ShowGuidance --> UserKeyword[User sends keyword]
    UserKeyword --> KeywordHandler[authorization-keyword-handler]
    KeywordHandler --> DetectKeyword{Keyword detected?}

    DetectKeyword -->|Yes| SwitchAction[Switch to Action mode]
    DetectKeyword -->|No| StayDiscussion[Stay in Discussion mode]

    SwitchAction --> NotifyUser[Notify user: Action mode enabled]
    NotifyUser --> AllowTool

    AllowTool --> ToolExecutes[Tool executes]
    ToolExecutes --> PostTool[PostToolUse Hook]
    PostTool --> Continue[Continue working]

    Continue --> StopHook{Stop event?}
    StopHook -->|Yes| RevertHandler[authorization-stop-handler]
    RevertHandler --> BackToDiscussion[Revert to Discussion mode]
    BackToDiscussion --> NotifyRevert[Notify user: Discussion mode]

Handler Priority System

flowchart TD
    Event[Hook Event] --> Handlers[Multiple handlers run]
    Handlers --> Propose[Each handler proposes action]

    Propose --> H1[Handler 1: action + priority]
    Propose --> H2[Handler 2: action + priority]
    Propose --> H3[Handler 3: action + priority]

    H1 --> Coordinator[ActionCoordinator.selectAction]
    H2 --> Coordinator
    H3 --> Coordinator

    Coordinator --> Sort[Sort by priority]
    Sort --> Priority{Priority levels}

    Priority --> P1[SYSTEM_SETUP = 1]
    Priority --> P2[CRITICAL = 2]
    Priority --> P3[WORKFLOW = 3]
    Priority --> P4[GUIDANCE = 4]
    Priority --> P5[DEFAULT = 5]

    P1 --> Select
    P2 --> Select
    P3 --> Select
    P4 --> Select
    P5 --> Select

    Select[Select highest priority] --> Execute[Execute selected action]
    Execute --> ApplyState[Apply state changes]
    Execute --> InjectProtocol[Inject protocol if specified]
    Execute --> InjectMessage[Inject message if specified]

    ApplyState --> SaveConfig[Save to workflow-config.json]
    InjectProtocol --> Return
    InjectMessage --> Return
    SaveConfig --> Return[Return to Claude]

Conventions Workflow

flowchart TD
    Prompt[UserPromptSubmit] --> ConventionsHandler[conventions-workflow-handler]
    ConventionsHandler --> GuardCheck{workflowEnabled?}

    GuardCheck -->|false| Skip[Skip handler]
    GuardCheck -->|true| CheckConventions{Check .issues/conventions/}

    CheckConventions --> Missing{Any missing?}
    Missing -->|Yes| ProposeAction[Propose SYSTEM_SETUP action]
    Missing -->|No| NoAction[No action]

    ProposeAction --> CoordinatorCheck[ActionCoordinator checks priority]
    CoordinatorCheck --> HighestPriority{Highest priority?}

    HighestPriority -->|Yes| InjectSetup[Inject conventions-setup-trigger.md]
    HighestPriority -->|No| Blocked[Another higher priority action wins]

    InjectSetup --> UserSees[User sees setup protocol]
    UserSees --> UserCreates[User creates conventions]
    UserCreates --> NextPrompt[Next prompt]

    NextPrompt --> ConventionsHandler
    CheckConventions --> Complete{All exist now?}
    Complete -->|Yes| SelfHealed[System self-healed]
    Complete -->|No| ProposeAction

Git Branch Auto-Creation

flowchart TD
    Prompt[User prompt with @issue] --> Detect[IssueDetector.detectIssueReference]
    Detect --> Valid{Valid reference?}

    Valid -->|No| Skip[Skip]
    Valid -->|Yes| Extract[Extract issue name]

    Extract --> GitCheck[Check current branch]
    GitCheck --> OnBranch{On feature/issue branch?}

    OnBranch -->|Yes| Silent[Silent - no action]
    OnBranch -->|No| CheckExists{Branch exists?}

    CheckExists -->|Yes| SwitchBranch[Git checkout feature/issue]
    CheckExists -->|No| CreateBranch[Git checkout -b feature/issue]

    SwitchBranch --> Notify[Notify user: switched]
    CreateBranch --> Notify[Notify user: created]

    Notify --> PreserveChanges{Uncommitted changes?}
    PreserveChanges -->|Yes| StashApply[Stash + apply after switch]
    PreserveChanges -->|No| Clean[Clean switch]

    StashApply --> Ready
    Clean --> Ready[Ready to work on issue]

Test Infrastructure

flowchart TD
    Test[Integration Test] --> Setup[TestEnvironment.setup]
    Setup --> TempDir[Create temp directory]
    TempDir --> Install[Run installer]
    Install --> CreateDirs[Create .issues/, .claude/ structure]
    CreateDirs --> CopyFiles[Copy templates/ to temp]
    CopyFiles --> SetPerms[Set executable permissions]
    SetPerms --> GitInit[Initialize git repo]
    GitInit --> DefaultConfig[Create default workflow-config.json]
    DefaultConfig --> DefaultConventions[Create default conventions]

    DefaultConventions --> Ready[Environment ready]

    Ready --> ClaudeMock[ClaudeCode mock]
    ClaudeMock --> SendPrompt[claudeCode.sendPrompt]
    SendPrompt --> FireHook[Spawn hook process]
    FireHook --> SendStdin[Send JSON to stdin]
    SendStdin --> ReadStdout[Read JSON from stdout]
    ReadStdout --> ParseResponse[Parse hook response]

    ParseResponse --> Assert[Test assertions]
    Assert --> Pass{All pass?}

    Pass -->|Yes| Teardown[TestEnvironment.teardown]
    Pass -->|No| Fail[Test fails]

    Teardown --> Cleanup[Remove temp directory]
    Cleanup --> Done[Test complete]

    Fail --> Preserve{KEEP_TEMP?}
    Preserve -->|Yes| KeepDir[Keep temp dir for debugging]
    Preserve -->|No| Cleanup

Feature Matrix

| Feature | Hook | Handler | Priority | Requires workflowEnabled | |---------|------|---------|----------|--------------------------| | Session Reset | SessionStart | session-start-handler | N/A | No | | Workflow Activation | UserPromptSubmit | workflow-activation-handler | WORKFLOW | No (activates it) | | Conventions Workflow | UserPromptSubmit | conventions-workflow-handler | SYSTEM_SETUP | Yes | | Problem Statement Protocol | UserPromptSubmit | problem-statement-protocol-handler | PHASE_PROTOCOL | Yes | | Context Gathering Protocol | UserPromptSubmit | context-gathering-protocol-handler | PHASE_PROTOCOL | Yes | | End State Protocol | UserPromptSubmit | end-state-protocol-handler | PHASE_PROTOCOL | Yes | | Solution Design Protocol | UserPromptSubmit | solution-design-protocol-handler | PHASE_PROTOCOL | Yes | | Implementation Phase Protocol | UserPromptSubmit | implementation-phase-protocol-handler | PHASE_PROTOCOL | Yes | | Git Branch Auto-Create | UserPromptSubmit | git-branch-handler | GUIDANCE | Yes | | Draft Authorization | PreToolUse | draft-authorization-handler | AUTHORIZATION | Yes | | Authorization Init | UserPromptSubmit | authorization-init-handler | N/A | No (always runs) | | Authorization Keywords | UserPromptSubmit | authorization-keyword-handler | N/A | Yes | | Authorization Tool Blocking | PreToolUse | authorization-tool-blocker | N/A | Yes | | Authorization Auto-Revert | Stop | authorization-stop-handler | N/A | Yes |

State Flow

stateDiagram-v2
    [*] --> SystemDisabled: SessionStart

    SystemDisabled --> SystemEnabled: /work or @issue

    SystemEnabled --> DiscussionMode: Default state

    DiscussionMode --> ActionMode: User keyword detected
    ActionMode --> DiscussionMode: Stop hook (auto-revert)

    DiscussionMode --> DiscussionMode: Read operations allowed
    DiscussionMode --> Blocked: Write operations blocked
    Blocked --> DiscussionMode: Show guidance

    ActionMode --> ActionMode: All operations allowed

    SystemEnabled --> SystemDisabled: New session (SessionStart)

    note right of SystemDisabled
        workflowEnabled = false
        All handlers bypassed
    end note

    note right of SystemEnabled
        workflowEnabled = true
        Handlers active
    end note

    note right of DiscussionMode
        authorization.mode = 'discussion'
        Read-only operations
    end note

    note right of ActionMode
        authorization.mode = 'action'
        Write operations allowed
    end note

Development Commands

For maintainers working on this repository:

• /prime - Initialize session with project context
• /design-feature - Plan new features
• /resolve-issue - Automated issue resolution: fetch next GitHub issue, analyze root cause, create test, fix, and verify
• /ship-feature - Complete feature validation before commit
• /handoff - Session handoff with context transfer

See .claude/commands/ for full command documentation.

Last Updated: 2025-10-02 (v0.24.0)

Maintainer Note: Update this file when shipping new features to keep flow diagrams current.