<system-reminder>
As you answer the user's questions, you can use the following context:
# claudeMd
Codebase and user instructions are shown below. Be sure to adhere to these instructions. IMPORTANT: These instructions OVERRIDE any default behavior and you MUST follow them exactly as written.

Contents of /Users/psulin/.claude/CLAUDE.md (user's private global instructions for all projects):

## Rules
 - Respond concisely, correctly and accurately
 - Always add and commit files after completing a task

## Documentation Standards

### README Requirements
- Write for engineers: explain what code actually does with real CLI examples and command outputs
- No marketing fluff - if claiming functionality (e.g. "quality scoring"), explain the implementation method
- Use "Modules" section instead of "Features" to avoid redundancy with core modules listing
- Include concrete dependencies, installation steps, and actual usage examples

## Code Implementation Standards

### ABSOLUTE PROHIBITION - NO EXCEPTIONS:
🚫 **NEVER CREATE:**
- Mocks (fake objects pretending to be real)
- Stubs (hardcoded return values)
- Placeholders (temporary "TODO" implementations)
- Fallbacks (return fake data when real implementation fails)

✅ **ALWAYS DO INSTEAD:**
- Implement the real thing OR
- Fail explicitly with clear error message
- If you cannot implement, say so - DO NOT FAKE IT

### Implementation Rules:
- Research and implement the single correct solution - no fallback logic or defensive patterns
- Answer questions directly without assumptions or premature implementation
- Icons only for red X's and green checkmarks - no other icons in docs or logs
- Lean Test Strategy: Golden Master snapshots, integration workflows, unit tests only for pure functions

### Examples of VIOLATIONS (NEVER DO THIS):
```python
# ❌ WRONG - Stub/Mock/Placeholder
def _call_llm(self, prompt):
    return "def example(): return 42"  # Fake placeholder

# ✅ CORRECT - Real implementation or explicit failure
def _call_llm(self, prompt):
    raise NotImplementedError("LLM integration not yet implemented")
```

Contents of /Users/psulin/organon/CLAUDE.md (project instructions, checked into the codebase):

# Organon - Agent Instructions

## Project Initialization

**For new projects using organon:**

1. Run `organon init` to set up the `.organon/` directory structure
2. This copies reference materials from the package to `.organon/defaults/`
3. Creates `organon.yaml` in project root for project-specific configuration
4. Updates `.gitignore` to version control defaults/rules but exclude runtime data

**Directory structure created:**
```
.organon/
├── defaults/           # Reference materials (version controlled)
│   ├── organon-defaults.yaml
│   ├── organon.yaml   # Reference config
│   ├── rules/         # Reference validation rules
│   ├── templates/     # Sprint/workflow templates
│   └── definitions/   # Workflow/work-mode definitions
├── rules/             # Custom project rules (version controlled)
├── logs/              # Runtime logs (gitignored)
└── cache/             # Temp data (gitignored)
```

## Navigation Protocol

**CRITICAL:** This is your primary guide for finding information.

For any new task:
1. Check STRUCTURE.md for project layout and file locations
2. Choose work mode (conversation, one-off-task, sprint-planning, sprint-execution)
3. Read work-mode definition from `.organon/defaults/definitions/work-modes/`
4. **Call `update_workflow_context` MCP tool** at START of work to track workflow context

**Key principle:** CLAUDE.md provides navigation and standards. Details live in:
- `docs/` - User guides, developer guides, design docs, reference material
- `.organon/defaults/definitions/workflows/` - Workflow specifications (research, design, implement, etc.)

**Planning workflow sequence:**
Requirements → Research → Design (optional, UI only) → Architecture → Spec → Plan

**Document sizing:** 5-minute read test - can someone understand the document in 5 minutes? If not, sprint may be too large or you're over-documenting.

**Project documentation integration:** During architecture phase, review project-level docs (docs/design.md, docs/architecture.md) and document impact. Update project docs after implementation.

**Workflow context tracking:** Call `update_workflow_context` MCP tool when starting/switching/completing work.

## Workflow Context Tracking

**Purpose:** Automatically track agent work context for observability and efficiency analysis

**Agent responsibility:** Call `update_workflow_context` MCP tool at START of every response to keep task_description current.

### When to Update Context

Call `update_workflow_context` when:
- Starting a new task
- Switching between workflows
- Changing sprint or task focus

Parameters:
- `workflow`: conversation | one-off-task | sprint-planning | sprint-execution
- `sprint_id`: Sprint directory/task name (optional)
- `task_type`: research | design | implement | test | etc (optional)
- `task_description`: Brief description of current work (optional)

**Storage:** Context is tracked in `.organon/current-context.json` and logged to `.organon/workflow-log.jsonl` via hooks.

## Interaction Patterns

### Interactive Review

**Definition:** A back-and-forth conversation where the agent presents ONE item at a time, waits for user response, then presents the next item.

**Pattern:**
1. Present single item with summary/context
2. Wait for user decision
3. Record decision and present next item
4. Continue until all items reviewed

**Usage:**
- Use when user says "interactive review" or "review interactively"
- Use when reviewing multiple items requiring individual decisions (sprint relevance, file changes, design options)
- DO NOT dump all items at once and ask for batch decisions

**Example:**
```
User: "Let's do an interactive review of the sprint files"
Agent: [Presents first sprint with summary]
       "Decision for this sprint? (keep/archive/delete)"
User: "Keep"
Agent: [Presents second sprint with summary]
       "Decision for this sprint? (keep/archive/delete)"
```

## Work Organization

All work follows one of four work-mode types:

### Sprint Format Decision

When planning sprints, choose format based on level of task detail:

**Standard Format:**
- High-level task descriptions
- Checklist format: `- [ ] Task description`
- Example: `- [ ] Add authentication module`
- Use for: Sequential work, manual execution

**Detailed Format:**
- Explicit file operations for each task
- Rich metadata: Type, Dependencies, Files, Context
- Example:
  ```markdown
  #### Task 1.1: Add authentication module
  - **Type:** implement
  - **Dependencies:** none
  - **Files:**
    - Create: src/auth/module.py
    - Create: src/auth/__init__.py
    - Modify: src/main.py
  - **Context:** spec.md#authentication
  - **Description:** JWT-based authentication
  ```
- Use for: Complex dependencies, parallel execution, orchestration

**Key distinction:** Standard uses general descriptions; Detailed specifies exact file operations.

**Note:** All sprints use directory structure (research.md, design.md, spec.md, plan.md).

### 1. Conversation
Discussion and planning without file changes
→ `defaults/definitions/work-modes/conversation.md`

### 2. One-Off Task
Quick work (< 2 hours): bug fixes, docs updates, simple changes
→ `defaults/definitions/work-modes/one-off-task.md`

### 3. Sprint Planning

**When user requests sprint creation or planning:**

1. **Call MCP tool:** `create_sprint(number, name, status="Created")`
2. **Read work-mode definition:** The tool response tells you which file to read
3. **Follow planning sequence EXACTLY:** Requirements → Research → Design (optional, UI only) → Architecture → Spec → Plan
4. **Do NOT skip phases** even if already discussed in conversation (except Design which is optional for non-UI work)

Create implementation plan - choose format based on needs:

**Standard Format:**
→ `defaults/definitions/work-modes/sprint-planning-standard.md`
→ High-level checklist, manual execution

**Detailed Format:**
→ `defaults/definitions/work-modes/sprint-planning-detailed.md`
→ Explicit file operations, supports orchestration

Both produce plan.md in sprint directory. See Sprint Format Decision above.

### 4. Sprint Execution
Execute sprint plan - use format matching your plan:

**Standard Format:**
→ `defaults/definitions/work-modes/sprint-execution-standard.md`
→ Manual sequential execution

**Detailed Format:**
→ `defaults/definitions/work-modes/sprint-execution-detailed.md`
→ Manual or orchestrated with sub-agents, parallel execution

**Workflow types:** research, design, specify, plan, implement, test, review, document, debug, refactor
→ `defaults/definitions/workflows/` for specifications

**See also:** `docs/user-guide/workflows.md` for complete workflow system guide

## Sprint Quick Reference

**Format:** `NN_Name_Status`
- **NN**: Execution order (assigned when sprint moves to Current, not when created)
- **Status**: Created → Next → Current → Completed | Paused

**Examples:**
```
FeatureName_Created/          # Planning in progress, no number yet
FeatureName_Next/             # Queued to start, no number yet
16_FeatureName_Current/       # Started (number assigned)
16_FeatureName_Completed/     # Done
```

**See:** `docs/user-guide/sprints.md` for complete lifecycle and working guide

**Backlog:** Rough ideas not yet scoped into sprints live in `dev-docs/sprints/backlog.md`
- Dual numbering: Ordinals (1, 2, 3...) for scanning + Immutable IDs ([#001], [#002]...) for stable references
- Three sections: Quick Reference (pending), Completed (with sprint/commit), Details (full descriptions)
- MCP tools: `list_backlog_items`, `get_backlog_item` (75-85% token savings vs reading full file)
- Validation: `backlog.format` rule checks structure and dual numbering
- **See:** `docs/user-guide/backlog.md` for complete workflow guide

## Commit Conventions

**Sprint work:**
```bash
feat(sprint-16): Implement authentication
fix(sprint-16): Resolve race condition
docs(sprint-16): Update API documentation
```

**Non-sprint work:**
```bash
bugfix: Fix null pointer in parser
docs: Update README
chore: Update dependencies
```

## Implementation Standards

### ABSOLUTE PROHIBITION - NO EXCEPTIONS

**NEVER CREATE:**
- Mocks (fake objects pretending to be real)
- Stubs (hardcoded return values)
- Placeholders (temporary "TODO" implementations)
- Fallbacks (return fake data when real implementation fails)

**ALWAYS DO INSTEAD:**
- Implement the real thing OR
- Fail explicitly with clear error message
- If you cannot implement, say so - DO NOT FAKE IT

**Examples:**

```python
# ✗ WRONG - Stub/Mock/Placeholder
def _call_llm(self, prompt):
    return "def example(): return 42"  # Fake placeholder

# ✓ CORRECT - Real implementation or explicit failure
def _call_llm(self, prompt):
    raise NotImplementedError("LLM integration not yet implemented")
```

### Additional Rules

- Research and implement the single correct solution
- Answer questions directly without assumptions or premature implementation
- Icons only for ✗ (red X) and ✓ (green checkmark) - no other icons in docs or logs
- Lean testing: Golden master snapshots, integration workflows, unit tests for pure functions only
- **TEST YOUR CODE BEFORE CLAIMING IT WORKS** - Never tell the user "it should work now" without testing first

## Quick Reference

### File Locations

- **This file:** `CLAUDE.md` (agent navigation and standards)
- **Setup:** `README.md` (installation, quick start)
- **MCP Setup:** `MCP_SETUP.md` (MCP server installation and troubleshooting)
- **Workflow tracking:** `.organon/current-context.json` (tracked via MCP tool)
- **Navigation:** `STRUCTURE.md` (file organization)
- **User guides:** `docs/user-guide/` (sprints, backlog, workflows, orchestration)
- **Developer guides:** `docs/developer-guide/` (python-standards, testing)
- **CLI Reference:** `docs/reference/cli.md` (complete command documentation)
- **Design docs:** `docs/design/` (architecture, rationale)
- **Working docs:** `dev-docs/` (sprints, backlog, analysis, archive)
- **Package source:** `src/organon/`
- **Development scripts:** `scripts/llm_capture/` (LLM context capture and token analysis)
- **Package defaults:** `defaults/` (reference implementations shipped with package)
- **Project organon files:** `.organon/` (project-local organon configuration and runtime data)
  - `.organon/defaults/` - Reference materials (version controlled, copied from package on init)
  - `.organon/rules/` - Custom validation rules (version controlled)
  - `.organon/logs/`, `.organon/cache/` - Runtime data (gitignored)
- **Project config:** `organon.yaml` (project root, version controlled)


      IMPORTANT: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task.
</system-reminder>

Warmup