Refine

Refinement is only complete after documentation artifacts are finalized: task JSON files, context.json, and the handoff summary used by /execute and /verify.

Hard rules:

• Do not edit application/source code while running /refine
• Do not run build/test/lint except lightweight checks needed to validate refinement artifacts
• Do not create commits/branches/PRs from /refine
• Only allowed writes are refinement artifacts under .mobius/issues/{id}/ (tasks/*.json, context.json, optional parent cache)

If the user asks to refine and implement in one request:

1. Complete refinement and write sub-task artifacts after approval
2. Stop
3. Recommend /execute {id} or mobius loop {id} for implementation

1. Deeply researches the codebase to understand existing patterns, dependencies, and affected areas
2. Decomposes work into single-file-focused tasks that Claude can complete in one session
3. Identifies dependencies between tasks to establish blocking relationships
4. Writes sub-tasks locally as JSON files in .mobius/issues/{id}/tasks/ with proper blocking order

Sub-tasks are ALWAYS local files, regardless of backend mode. The backend only determines where the parent issue is fetched from. Sub-tasks are designed for autonomous execution - each should be completable without needing to reference other sub-tasks or gather additional context.

Auto-detection from issue ID:

• Linear format: MOB-123, VRZ-456 (typically 2-4 letter prefix)
• Jira format: PROJ-123 (typically longer project key)
• Local format: LOC-001, LOC-002 (auto-incremented local IDs)

If the format is ambiguous, use AskUserQuestion:

Question: "Which backend are you using?"

Options:

1. Linear - Fetch parent from Linear, write sub-tasks locally
2. Jira - Fetch parent from Jira, write sub-tasks locally
3. Local - Read parent from local file, write sub-tasks locally

Store the selection to use appropriate tools throughout the skill.

Default: If not specified, default to linear.

Important: Regardless of backend, sub-tasks are ALWAYS written as local JSON files to .mobius/issues/{id}/tasks/. The backend only affects how the parent issue is loaded.

If issue ID doesn't match expected format, warn user before proceeding:

The issue ID "{id}" doesn't match the expected format ({backend} pattern).
Did you mean to use a different backend, or is this a valid issue ID?

The backend determines where the parent issue is loaded from:

For backend: local - read from local file:

cat .mobius/issues/{issue-id}/parent.json

The local parent.json file is created by /define in local mode and contains:

• Title and description: What needs to be implemented
• Acceptance criteria: Checklist of requirements
• Labels: Bug/Feature/Improvement for context
• Priority: Urgency level for task ordering

If parent.json does not exist, report the error:

No local parent file found at .mobius/issues/{issue-id}/parent.json
Run /define {issue-id} first to create the issue spec, or check the issue ID.

For backend: linear — use linearis issues read CLI:

# Fetch issue details as JSON
linearis issues read MOB-123

Extract from the response:

• Title and description: What needs to be implemented
• Acceptance criteria: Checklist of requirements (look for checkbox patterns in description)
• Labels: Bug/Feature/Improvement for context
• Priority: Urgency level for task ordering
• Team/Project: For sub-task inheritance
• Existing relationships: blockedBy, blocks, relatedTo
• URL: For reference in sub-tasks

For backend: jira — use acli jira workitem show:

# Fetch issue details
acli jira workitem show PROJ-123

Extract from the response:

• Summary and description: What needs to be implemented
• Issue type: Bug/Story/Task for context
• Priority: Urgency level
• Project key: For sub-task inheritance
• Issue links: blocks, is blocked by relationships

After loading (all backends): Write or update the local parent file for use by later skills:

mkdir -p .mobius/issues/{parent-id}

Write tool:
  file_path: .mobius/issues/{parent-id}/parent.json
  content: {parent issue JSON}

If CLI command fails (linear/jira backends):

1. Report the error to the user
2. If CLI not found, show install instructions:
   • Linear: npm install -g linearis
   • Jira: See https://developer.atlassian.com/cloud/acli/
3. Check if the issue ID is valid
4. Verify API permissions/authentication
5. Offer to retry or use a different issue ID

Sub-tasks are ALWAYS written locally to .mobius/issues/{id}/tasks/ — never pushed to Linear/Jira. This applies to ALL backend modes (local, linear, jira).

Directory setup: Before writing files, ensure the tasks directory exists:

mkdir -p .mobius/issues/{parent-id}/tasks

File naming: Sub-task files use task-{NNN}.json format with zero-padded 3-digit numbers:

• task-001.json, task-002.json, ..., task-010.json
• Verification gate uses: task-VG.json

Creation order: Write sub-tasks in dependency order (leaf tasks first):

1. Write tasks with no blockers first
2. Use task-{NNN} identifiers for blocking references
3. Write dependent tasks with blockedBy referencing earlier task identifiers

Sub-task JSON schema:

{
  "id": "task-001",
  "taskType": "general",
  "title": "[{parent-id}] {sub-task title}",
  "description": "## Summary\n{Brief description}\n\n## Context\nPart of {parent-id}: {parent title}\n\n## Target File(s)\n`{file-path}` ({Create/Modify})\n\n## Action\n{Specific implementation guidance}\n\n## Avoid\n- Do NOT {anti-pattern} because {reason}\n\n## Acceptance Criteria\n- [ ] {Criterion 1}\n  * **Verification**: {how to verify}\n- [ ] {Criterion 2}\n\n## Verify Command\n```bash\n{executable verification command}\n```",
  "status": "pending",
  "blockedBy": [],
  "blocks": ["task-002", "task-003"],
  "labels": ["{inherited-labels}"],
  "parentId": "{parent-id}"
}

Required field: Every implementation sub-task JSON MUST include taskType with one of: frontend, backend, general.

Task-type assignment guidance:

• Use frontend for UI/presentation work (components, styling, client interactions)
• Use backend for server/runtime/core logic work (API, data, execution internals)
• Use general for cross-cutting or neutral orchestration/docs/infra work
• Never emit free-form values outside frontend|backend|general

Write each sub-task using the Write tool:

Write tool:
  file_path: .mobius/issues/{parent-id}/tasks/task-001.json
  content: {JSON content}

Verification Gate creation (always the last file):

{
  "id": "task-VG",
  "title": "[{parent-id}] Verification Gate",
  "description": "Runs verify to validate implementation meets acceptance criteria.\n\n**Blocked by**: ALL implementation sub-tasks\n**Action**: Run `/verify {parent-id}` after all implementation tasks complete\n\n### Aggregated Verify Commands\n1. task-001: Define types\n   ```bash\n   cd /path && bun run typecheck\n   ```\n2. task-002: Implement service\n   ```bash\n   cd /path && bun test service.test.ts\n   ```\n3. task-003: Add hook\n   ```bash\n   cd /path && bun run typecheck\n   ```",
  "status": "pending",
  "blockedBy": ["task-001", "task-002", "task-003"],
  "blocks": [],
  "labels": [],
  "parentId": "{parent-id}"
}

Write as: .mobius/issues/{parent-id}/tasks/task-VG.json

Also update the context file after writing all tasks:

Edit tool:
  file_path: .mobius/issues/{parent-id}/context.json
  # Update subTasks array with all created task references

Or if no context.json exists, create one:

{
  "parent": {
    "id": "{parent-uuid}",
    "identifier": "{parent-id}",
    "title": "{parent title}",
    "description": "{parent description}",
    "status": "In Progress",
    "labels": ["{labels}"],
    "url": "{parent url}"
  },
  "subTasks": [
    {
      "id": "task-001",
      "identifier": "task-001",
      "taskType": "general",
      "title": "[{parent-id}] {sub-task title}",
      "status": "pending",
      "blockedBy": [],
      "blocks": ["task-002"]
    }
  ],
  "metadata": {
    "backend": "{linear|jira|local}",
    "fetchedAt": "{ISO-8601 timestamp}",
    "updatedAt": "{ISO-8601 timestamp}"
  }
}

Error handling:

• If file write fails (e.g., permission error), report and ask user to check directory permissions
• If directory creation fails, offer to create .mobius/ manually
• All writes are atomic per-file so partial failure is safe

/refine MOB-123    # Linear issue (parent fetched from Linear, sub-tasks written locally)
/refine PROJ-456   # Jira issue (parent fetched from Jira, sub-tasks written locally)
/refine LOC-001    # Local issue (parent read from local file, sub-tasks written locally)

Or invoke programmatically:

Skill: refine
Args: MOB-123

For backend: local - read from local file:

cat .mobius/issues/{issue-id}/parent.json

Extract from the JSON: title, description, acceptance criteria, labels, priority.

For backend: linear — use linearis issues read CLI:

# Fetch issue details as JSON
linearis issues read {issue-id}  # e.g., "MOB-123"

Extract from response:

• Title and description: What needs to be implemented
• Acceptance criteria: Checklist of requirements (look for - [ ] patterns in description)
• Labels: Bug/Feature/Improvement for context
• Priority: Urgency level for task ordering
• Team: For sub-task inheritance (use same team for all sub-tasks)
• Existing relationships: blockedBy, blocks (to maintain)
• URL: For linking back to parent

For backend: jira — use acli jira workitem show:

# Fetch issue details
acli jira workitem show PROJ-123

Extract from response:

• Summary and description: What needs to be implemented
• Issue type: Bug/Story/Task for context
• Priority: Urgency level for task ordering
• Project key: For sub-task inheritance (use same project for all sub-tasks)
• Issue links: blocks, is blocked by (to maintain)
• URL: For linking back to parent

After loading (all backends): Save parent data locally for use by execute/verify skills:

mkdir -p .mobius/issues/{parent-id}

Write tool:
  file_path: .mobius/issues/{parent-id}/parent.json
  content: {parent issue JSON}

Task tool:
  subagent_type: Explore
  prompt: |
    Analyze the codebase to understand how to implement: {issue title and description}

    Research:
    1. Find all files that will need modification
    2. Understand existing patterns in similar areas
    3. Identify dependencies between affected files
    4. Note any shared utilities, types, or services involved
    5. Find test files that will need updates

    For each file, note:
    - What changes are needed
    - What it imports/exports that affects other files
    - Whether it has corresponding test files

    Provide a comprehensive analysis of the implementation approach.

Set thoroughness to "very thorough" for complex issues.

• Affected files: Complete list with change type (create/modify)
• Dependency graph: Which files import from which
• Shared resources: Types, utilities, services used across files
• Test requirements: Which test files need updates
• Pattern notes: Existing conventions to follow

Process:

1. Review the Explore agent's file list and dependency graph
2. Group files into work units following the single-file principle (one file or tightly-coupled pair per unit)
3. For each work unit, note:
   • Target file(s): The primary file (and optional test pair)
   • Rough scope: Create / Modify / Delete, approximate change size
   • Related areas: Nearby files the subagent should examine for patterns and context
   • Dependency hints: Which other work units this one likely depends on or enables

Output: A list of work unit briefs, each feeding into a Phase 3 subagent.

Example work unit brief:

Work Unit 3: Create useTheme hook
  Target: src/hooks/useTheme.ts (Create)
  Related: src/hooks/useAuth.ts (pattern reference), src/contexts/ThemeContext.tsx (dependency)
  Scope: ~40 lines, new hook consuming ThemeContext
  Depends on: Work Unit 2 (ThemeContext)
  Enables: Work Units 4, 5, 6 (components consuming the hook)

Example (7 work units):

• Batch 1: Work Units 1, 2, 3 (parallel)
• Batch 2: Work Units 4, 5, 6 (parallel)
• Batch 3: Work Unit 7 (final)

Task tool:
  subagent_type: feature-dev:code-architect
  prompt: |
    You are writing a sub-task description for an implementation breakdown.

    ## Parent Issue
    Title: {parent issue title}
    Description: {parent issue description}
    Acceptance Criteria: {acceptance criteria from parent}

    ## Architecture Context (from Phase 1 exploration)
    {Paste the Explore agent's analysis output — affected files, patterns, dependency graph, conventions}

    ## Your Assigned Work Unit
    Target file(s): {target file path(s)} ({Create/Modify})
    Rough scope: {approximate change description}
    Related areas to examine: {nearby files for pattern reference}
    Dependency hints: Depends on {work unit N}, enables {work unit M}

    ## Your Task
    Analyze the target file(s) and related areas deeply. Then produce a complete sub-task description using this exact template:

    ## Summary
    {1-2 sentences: what this sub-task accomplishes}

    ## Context
    Part of {parent-id}: {parent title}

    ## Target File(s)
    `{file-path}` ({Create/Modify})

    ## Task Type
    {Exactly one of: frontend | backend | general}

    ## Action
    {2-4 sentences of specific implementation guidance}
    - Use {library/pattern} following `{existing example file}`
    - Handle {error case} by {specific handling}
    - Return {exact output shape}

    ## Avoid
    - Do NOT {anti-pattern 1} because {reason}
    - Do NOT {anti-pattern 2} because {reason}

    ## Acceptance Criteria
    - [ ] {Criterion 1}
      * **Verification**: {how to verify}
    - [ ] {Criterion 2}
      * **Verification**: {how to verify}

    ## Verify Command
    ```bash
    {executable verification command}
    ```

    ## Dependencies
    - **Blocked by**: {work unit numbers this depends on, or "None"}
    - **Enables**: {work unit numbers this unblocks}

    IMPORTANT: Be specific. Reference actual file paths, function names, and patterns you find in the codebase. Do not use generic placeholders.

On failure:

• If a subagent returns incomplete or malformed output, retry once with a clarifying note
• If retry also fails, the main agent writes the sub-task description manually using Phase 1 exploration data
• Log which work units required fallback for debugging

On success:

• Store the write-up keyed by work unit number
• Pass all collected write-ups to Phase 4 (aggregation)

For subagent pattern details, batching strategy, and rationale, see .claude/skills/refine/parallel-research.md.

• Task fits within one context window
• Clear scope prevents scope creep
• Easy to verify completion
• Enables parallel work on unrelated files

## Sub-task: [Number] - [Brief title]

**Target file(s)**: `path/to/file.ts` (and `path/to/file.test.ts` if applicable)
**Change type**: Create | Modify | Delete

### Action
[2-4 sentences of specific implementation guidance]
- Use {library/pattern} following `src/existing/example.ts`
- Handle {error case} by {specific handling}
- Return {exact output shape}

### Avoid
- Do NOT {anti-pattern 1} because {reason}
- Do NOT {anti-pattern 2} because {reason}

### Verify
```bash
{executable command that proves completion}

Done

• {Measurable outcome 1}
• {Measurable outcome 2}
• {Measurable outcome 3}

Blocked by: [Sub-task numbers, or "None"] Enables: [Sub-task numbers this unblocks]

Use the "Avoid" section when research phase identified pitfalls specific to this task.
</task_structure_full>
</task_structure>

<ordering_principles>
Determine blocking order based on functional requirements:

1. **Foundation first**: Types, interfaces, schemas before implementations
2. **Dependencies flow down**: If A imports from B, B must be done first
3. **Tests with implementation**: Pair test files with their source files in same task
4. **UI last**: Components after their dependencies (services, hooks, types)
5. **Verification last**: The verification gate is ALWAYS the final sub-task

**Parallelization opportunities**:
- Independent services can run in parallel
- Unrelated UI components can run in parallel
- Tests for different features can run in parallel
</ordering_principles>

<aggregation_phase>
**Phase 4**: Collect all sub-task write-ups from Phase 3 subagents and assemble the final breakdown.

**Aggregation steps**:
1. **Collect write-ups** — Gather all sub-task descriptions from Phase 3 subagents (keyed by work unit number)
2. **Assign ordering numbers** — Use dependency hints from subagent outputs combined with ordering principles to assign sequential order numbers
3. **Establish blockedBy relationships** — Convert dependency hints into formal `blockedBy` references using assigned order numbers
4. **Verify no circular dependencies** — Walk the dependency graph to confirm it is a DAG (directed acyclic graph)
5. **Aggregate verify commands** — For each sub-task write-up from Phase 3 subagents, extract the `### Verify Command` bash code block and collect into a numbered list for the Verification Gate description:
   - Format each entry as: `{N}. {task-id}: {title}\n   ```bash\n   {verify command}\n   ```\n`
   - If a sub-task has no verify command, note: `{N}. {task-id}: {title}\n   (no verify command specified)`
   - Insert the collected list into the VG description's `### Aggregated Verify Commands` section
6. **Identify parallel groups** — Group tasks that share no mutual dependencies for concurrent execution
7. **Add verification gate** — Append the verification gate sub-task blocked by ALL implementation tasks, with the aggregated verify commands from step 5 included in its description
8. **Quality checks**:
    - Each sub-task targets a single file (or tightly-coupled pair)
    - No duplicate target files across sub-tasks
    - Every implementation sub-task includes `taskType` with allowed values `frontend|backend|general`
    - All template sections are complete (Summary, Context, Target Files, Action, Avoid, Acceptance Criteria, Verify Command)
   - Verify commands are executable (not pseudocode)
   - Acceptance criteria are measurable
   - Verification Gate description includes aggregated verify commands from all sub-tasks
</aggregation_phase>

<verification_gate>
**ALWAYS include a Verification Gate as the final sub-task.** This is required for every refined issue.

The verification gate:
- Has title: `[{parent-id}] Verification Gate` (MUST contain "Verification Gate" for mobius routing)
- Is blocked by ALL implementation sub-tasks
- When executed by mobius, routes to `/verify` instead of `/execute`
- Validates all acceptance criteria are met before the parent can be completed

**Template**:
```markdown
## Sub-task: [Final] - Verification Gate

**Target**: Validate implementation against acceptance criteria
**Change type**: Verification (no code changes)

### Action
This task triggers the verify skill to validate all implementation sub-tasks meet the parent issue's acceptance criteria.

### Aggregated Verify Commands
{List of each implementation sub-task's verify command, numbered by sub-task}

### Done
- [ ] All sub-task verify commands pass
- [ ] All tests pass
- [ ] All acceptance criteria verified
- [ ] No critical issues found by code review agents

**Blocked by**: [ALL implementation sub-task IDs]
**Enables**: Parent issue completion

• Targets 1 file (or source + test pair)
• Has 2-4 acceptance criteria
• Can be described in 2-3 sentences
• Takes roughly 50-200 lines of changes
• Doesn't require reading many other files to understand

Split if:

• File needs multiple unrelated changes
• Description exceeds 5 sentences
• More than 5 acceptance criteria
• Changes span unrelated concerns in the file

Combine if:

• Two files are always modified together
• Changes are trivially small (< 10 lines each)
• One file is just re-exporting from another

1. Wave 1: Foundation - Types, interfaces, schemas (max 3 tasks)
2. Wave 2: Core Logic - Services, API endpoints (max 3 tasks)
3. Wave 3: UI/Presentation - Components, forms (max 3 tasks)
4. Wave 4: Integration - Routing, E2E tests (remaining tasks)

Batching rules:

• Group related changes in same wave (e.g., service + its tests)
• Foundation tasks always in first wave
• Integration/E2E tasks always in final wave

See <examples> section for complete wave-based breakdown example.

Present the complete breakdown:

# Implementation Breakdown: {Issue ID} - {Issue Title}

## Overview
- **Total sub-tasks**: {count}
- **Parallelizable groups**: {count}
- **Critical path**: {list of sequential dependencies}
- **Estimated scope**: {total files affected}

## Dependency Graph

[1] Types/Interfaces └─► [2] Service implementation ├─► [3] Hook implementation │ └─► [5] Component A └─► [4] Repository updates └─► [6] Component B

Parallel groups:

• Group 1: [1]
• Group 2: [2]
• Group 3: [3], [4]
• Group 4: [5], [6]

## Sub-tasks

### 1. Define TypeScript types for {feature}
**File**: `src/types/feature.ts`
**Blocked by**: None
**Enables**: 2, 3, 4

[Full sub-task details...]

### 2. Implement {feature} service
**File**: `src/lib/services/featureService.ts`
**Blocked by**: 1
**Enables**: 3, 4

[Full sub-task details...]

[Continue for all sub-tasks...]

Question: "How would you like to proceed with this breakdown?"

Options:

1. Create all sub-tasks - Breakdown looks correct, create in issue tracker
2. Adjust scope - Some tasks need to be split or combined
3. Change ordering - Blocking relationships need adjustment
4. Add context - I have additional information to include
5. Start over - Need a different approach entirely

For each sub-task, use AskUserQuestion to verify:

Scope validation:

Question: "Is the scope for sub-task {N} ({title}) correct?"
Options:
1. **Correct** - Scope is well-defined
2. **Too broad** - Should be split into smaller tasks
3. **Too narrow** - Can be combined with another task
4. **Needs clarification** - Requirements are unclear

Edge case validation:

Question: "What should happen if {operation} fails in sub-task {N}?"
Options:
1. **Throw error** - Fail fast with clear error message
2. **Return fallback** - Use default value and continue
3. **Retry** - Attempt operation again with backoff
4. **Not applicable** - This operation cannot fail

Acceptance criteria validation:

Question: "How should we verify sub-task {N} is complete?"
Options:
1. **Automated test** - Unit/integration test in CI
2. **Manual verification** - Human checks specific behavior
3. **Type checking** - TypeScript compilation succeeds
4. **All of the above** - Multiple verification methods

• Adjust scope: Ask which specific tasks to modify, then present revised breakdown
• Change ordering: Present dependency graph and ask which relationships to change
• Add context: Incorporate new information and re-analyze affected tasks

Loop back to presentation after each refinement until user approves.

Creation sequence:

1. Ensure directory exists: mkdir -p .mobius/issues/{parent-id}/tasks
2. Write leaf tasks first (tasks with no blockers) as task-001.json, task-002.json, etc.
3. Write dependent tasks with blockedBy referencing earlier task-{NNN} identifiers
4. Write Verification Gate last as task-VG.json with all implementation task IDs as blockers
5. Write context.json with full parent + subTasks array for execute/verify skills
6. Validate documentation consistency (task files and context.json contain matching IDs/status/dependencies)
7. Report progress as each file is written

Example creation flow:

Writing sub-task 1/4: "Define TypeScript types"...
  -> Wrote .mobius/issues/MOB-100/tasks/task-001.json

Writing sub-task 2/4: "Implement feature service" (blocked by task-001)...
  -> Wrote .mobius/issues/MOB-100/tasks/task-002.json

Writing sub-task 3/4: "Add useFeature hook" (blocked by task-001)...
  -> Wrote .mobius/issues/MOB-100/tasks/task-003.json

Writing Verification Gate (blocked by task-001, task-002, task-003)...
  -> Wrote .mobius/issues/MOB-100/tasks/task-VG.json

Writing context.json...
  -> Wrote .mobius/issues/MOB-100/context.json

All sub-tasks written successfully!

Before ending /refine, confirm all refinement artifacts are complete and consistent:

1. Every planned task has a corresponding task-{NNN}.json (plus task-VG.json)
2. context.json contains the same task set, dependency relationships, and metadata timestamp updates
3. The handoff summary clearly identifies ready-first tasks and dependency order

If any artifact is missing or inconsistent, fix the files first and only then report "Breakdown Complete".

This summary is the final documentation handoff. It should be complete enough for /execute to start without additional clarification.

## Breakdown Complete: {parent issue ID}

**Sub-tasks created**: {count}
**Verification gate**: Included
**Location**: `.mobius/issues/{parent-id}/tasks/`

| ID | Title | Blocked By | File |
|----|-------|------------|------|
| task-001 | Define types | - | `tasks/task-001.json` |
| task-002 | Implement service | task-001 | `tasks/task-002.json` |
| task-003 | Add hook | task-001 | `tasks/task-003.json` |
| task-VG | Verification Gate | task-001, task-002, task-003 | `tasks/task-VG.json` |

**Ready to start**: task-001
**Parallel opportunities**: After task-001, task-002 and task-003 can run simultaneously

**Dependency Graph**:
```mermaid
graph TD
    A[task-001: Define types] --> B[task-002: Implement service]
    A --> C[task-003: Add hook]
    B --> D[task-VG: Verification Gate]
    C --> D

Run mobius loop {parent-id} to begin execution, or /execute {parent-id} for a single task.

</completion_summary>

<post_creation_comment>
Optionally post the dependency graph as a comment on the parent issue (backend modes only):

**For `backend: linear`** — use `linearis comments create`:

```bash
COMMENT_BODY=$(cat <<'COMMENT'
## Sub-task Breakdown

| ID | Title | Blocked By |
|----|-------|------------|
| task-001 | Define types | - |
| task-002 | Implement service | task-001 |
| task-003 | Add hook | task-001 |
| task-VG | Verification Gate | task-001, task-002, task-003 |

**Ready to start**: task-001
**Local files**: `.mobius/issues/{parent-id}/tasks/`
COMMENT
)

linearis comments create {parent-issue-id} --body "$COMMENT_BODY"

For backend: jira — use acli jira workitem comment add:

COMMENT_BODY=$(cat <<'COMMENT'
## Sub-task Breakdown

| ID | Title | Blocked By |
|----|-------|------------|
| task-001 | Define types | - |
| task-002 | Implement service | task-001 |
| task-003 | Add hook | task-001 |
| task-VG | Verification Gate | task-001, task-002, task-003 |

**Ready to start**: task-001
**Local files**: `.mobius/issues/{parent-id}/tasks/`
COMMENT
)

acli jira workitem comment add --issue "{parent-issue-key}" --body "$COMMENT_BODY"

For backend: local: No comment posted (no remote issue tracker). The summary is displayed to the user in the terminal.

1. Issue not found:

   • Verify the issue ID is correct
   • Check if the issue exists in the tracker
   • Try with the full identifier (e.g., "MOB-123" not just "123")

2. Permission denied:

   • CLI may not be authenticated or may lack access to this issue
   • Check API token permissions in Linear/Jira settings
   • Verify the issue is not in a restricted project

3. CLI not installed:

   • Linearis CLI (linearis) not found — install via: npm install -g linearis
   • Jira CLI (acli) not found — see: https://developer.atlassian.com/cloud/acli/
   • Fall back to asking user to provide issue details manually

Recovery: Ask user if they want to retry, use a different issue ID, or provide details manually.

1. Directory creation failed:

   • .mobius/ directory may not be writable
   • Check file system permissions
   • Offer to create the directory manually

2. File write failed:

   • Disk may be full
   • Path may be invalid
   • Report which files were successfully written and which failed

3. Partial write:

   • Some task files may have been written before the failure
   • Report which files exist and which are missing
   • Offer to retry the failed writes

Recovery options via AskUserQuestion:

Question: "Sub-task file creation failed. How would you like to proceed?"
Options:
1. **Retry failed** - Attempt to write failed task files again
2. **Check permissions** - Verify .mobius/ directory is writable
3. **Cancel** - Don't write any more task files

Exploration findings:

• Need theme types in src/types/theme.ts
• ThemeProvider context in src/contexts/ThemeContext.tsx
• useTheme hook in src/hooks/useTheme.ts
• Settings toggle in src/components/settings/ThemeToggle.tsx
• Update 3 components that have hardcoded colors

Breakdown:

## Sub-task: 1 - Define theme types

**Target file(s)**: `src/types/theme.ts`
**Change type**: Create

### Action
Create TypeScript type definitions for the theme system. Define `Theme` type with light/dark/system modes, `ThemeContextValue` interface with current theme and toggle function.
- Follow existing type patterns in `src/types/` directory
- Export all types for use by ThemeProvider and useTheme hook

### Avoid
- Do NOT include implementation logic in types file because types should be pure declarations
- Do NOT use `any` type because it defeats type safety

### Verify
```bash
grep -q "export type Theme" src/types/theme.ts && \
grep -q "export interface ThemeContextValue" src/types/theme.ts && \
echo "PASS"

Done

• Theme type exported with 'light' | 'dark' | 'system' values
• ThemeContextValue interface exported with theme and setTheme properties
• File compiles without TypeScript errors

Blocked by: None Enables: 2, 3

Sub-task: 2 - Create ThemeProvider context

Target file(s): src/contexts/ThemeContext.tsx Change type: Create

Action

Create React context provider for theme state management. Import types from sub-task 1, implement localStorage persistence, and detect system preference.

• Follow existing context patterns in src/contexts/ directory
• Use useEffect for system preference detection via matchMedia

Avoid

• Do NOT call hooks conditionally because it violates React rules
• Do NOT forget SSR safety check for localStorage because window may not exist

Verify

grep -q "createContext" src/contexts/ThemeContext.tsx && \
grep -q "ThemeProvider" src/contexts/ThemeContext.tsx && \
echo "PASS"

Done

• ThemeContext created with proper default value
• ThemeProvider component exports and wraps children
• Theme persisted to localStorage on change
• System preference detected on mount

Blocked by: 1 Enables: 3

Sub-task: 3 - Implement useTheme hook

Target file(s): src/hooks/useTheme.ts Change type: Create Blocked by: 2 Enables: 4, 5, 6, 7

Sub-task: 4 - Add ThemeToggle component

Target file(s): src/components/settings/ThemeToggle.tsx Change type: Create Blocked by: 3

Sub-task: 5-7 - Update existing components

Files: Header.tsx, Sidebar.tsx, Card.tsx (modify) Blocked by: 3

Sub-task: 8 - Verification Gate

Target: Validate implementation against acceptance criteria Change type: Verification (no code changes)

Action

This task triggers the verify skill to validate all implementation sub-tasks meet the parent issue's acceptance criteria.

Done

• All tests pass
• All acceptance criteria verified
• No critical issues found by code review agents

Blocked by: 1, 2, 3, 4, 5, 6, 7 Enables: Parent issue completion

**Dependency graph**:

[1] Types ─► [2] ThemeProvider ─► [3] useTheme hook │ ┌──────────────────┼──────────────────┐ ▼ ▼ ▼ [4] [5] [6] ThemeToggle Header.tsx Sidebar.tsx │ │ │ └──────────────────┼──────────────────┘ ▼ [8] Verification Gate

**Parallel groups**:
- [1] → [2] → [3] (sequential foundation)
- [4], [5], [6], [7] can all run in parallel after [3]
- [8] runs after ALL other tasks complete

**After user approval, write local task files**:

```bash
# Ensure directory exists
mkdir -p .mobius/issues/MOB-100/tasks

# Step 1: Write leaf task (no blockers)
Write tool:
  file_path: .mobius/issues/MOB-100/tasks/task-001.json
  content: {
    "id": "task-001",
    "title": "[MOB-100] Define theme types",
    "description": "## Summary\nCreate TypeScript type definitions...

…(truncated)