Systematic issue tracking and workflow system for Claude Code
npm install claude-issuesA workflow orchestration system for Claude Code that provides structured guidance through systematic issue-based development.
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
``bash`
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.
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.
`mermaid
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
`
The system guides users through structured phases when working on issues:
`mermaid
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
similarity-detector
dependency-tracer
test-analyzer
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
`
`mermaid
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]
`
`mermaid
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
`
`mermaid
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]
`
`mermaid
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]
`
`mermaid
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
`
`mermaid
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]
`
`mermaid
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 | 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 |
---
`mermaid
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
`
---
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.