execute

---

name: execute description: Execute a single sub-task with context priming. Supports both Linear and Jira backends via progressive disclosure. Use when ready to implement a refined issue, when the user mentions "execute", "implement", or "work on" an issue. invocation: /execute

<objective> Execute EXACTLY ONE sub-task from a refined issue, then STOP. This skill is designed to run in a loop where each invocation completes one sub-task.

Key behavior:

• Find ONE ready sub-task (no unresolved blockers)
• Implement it completely
• Verify with tests/typecheck/lint
• Commit and push
• Update issue status
• Report completion and STOP IMMEDIATELY

CRITICAL: After completing one sub-task (or determining none are ready), you MUST stop and end your response. Do NOT continue to the next sub-task. The calling loop will invoke you again for the next sub-task. </objective>

<one_subtask_rule> THIS SKILL EXECUTES EXACTLY ONE SUB-TASK PER INVOCATION

The workflow for each invocation:

1. Find the next ready sub-task
2. If none ready -> output STATUS and STOP
3. If found -> implement, verify, commit, push
4. Update issue status
5. Output completion STATUS and STOP

NEVER:

• Process multiple sub-tasks in one invocation
• Ask "should I continue to the next task?"
• Loop through remaining sub-tasks
• Suggest running the skill again

The loop script handles iteration. This skill handles ONE task. </one_subtask_rule>

<context_input> The mobius loop provides issue context via environment variable and local files.

The skill receives context through:

1. MOBIUS_CONTEXT_FILE environment variable - path to the context JSON file
2. Local files at .mobius/issues/{parentId}/

Context file structure (at MOBIUS_CONTEXT_FILE path):

{
  "parent": {
    "id": "uuid",
    "identifier": "MOB-161",
    "title": "Parent issue title",
    "description": "Full description with acceptance criteria",
    "gitBranchName": "branch-name",
    "status": "Backlog",
    "labels": ["Feature"],
    "url": "https://linear.app/..."
  },
  "subTasks": [
    {
      "id": "uuid",
      "identifier": "MOB-177",
      "title": "Sub-task title",
      "description": "Full description with acceptance criteria",
      "status": "pending",
      "gitBranchName": "branch-name",
      "blockedBy": [{"id": "uuid", "identifier": "MOB-176"}],
      "blocks": [{"id": "uuid", "identifier": "MOB-182"}]
    }
  ],
  "metadata": {
    "fetchedAt": "2026-01-28T12:00:00Z",
    "updatedAt": "2026-01-28T12:00:00Z",
    "backend": "linear"
  }
}

Reading context:

# Context file path from environment
CONTEXT_FILE="$MOBIUS_CONTEXT_FILE"

# Or read directly from project-local storage
cat .mobius/issues/MOB-161/parent.json
cat .mobius/issues/MOB-161/tasks/MOB-177.json

Sub-task status values: pending, in_progress, done

Backend detection: The metadata.backend field indicates whether the issue is from Linear or Jira. This affects status transition names but the skill should treat the context data uniformly. </context_input>

<structured_output> This skill MUST output structured data for the mobius loop to parse.

At the END of your response, output a YAML or JSON block with the execution result. The mobius loop parses this to execute status updates, add comments, and determine next actions.

Output format (YAML preferred for readability):

---
status: SUBTASK_COMPLETE  # Required: one of the valid status values
timestamp: "2026-01-28T12:00:00Z"  # Required: ISO-8601 timestamp
subtaskId: "MOB-177"  # Required for subtask statuses
parentId: "MOB-161"  # Required for parent-level statuses

# For SUBTASK_COMPLETE:
commitHash: "abc1234"
filesModified:
  - "src/lib/feature.ts"
  - "src/lib/feature.test.ts"
verificationResults:
  typecheck: PASS
  tests: PASS
  lint: PASS
  subtaskVerify: PASS  # or N/A if no verify block

# For SUBTASK_PARTIAL:
progressMade:
  - "Implemented core function"
  - "Added type definitions"
remainingWork:
  - "Add unit tests"
  - "Fix lint errors"

# For ALL_BLOCKED:
blockedCount: 3
waitingOn:
  - "MOB-176"
  - "MOB-175"

# For VERIFICATION_FAILED:
errorType: "tests"  # typecheck | tests | lint | subtask_verify
errorOutput: "Test failed: expected 2 but got 3"
attemptedFixes:
  - "Updated expected value"
  - "Fixed calculation logic"
uncommittedFiles:
  - "src/lib/feature.ts"
---

Valid status values:

Status	When to use
SUBTASK_COMPLETE	Sub-task fully implemented, verified, committed
SUBTASK_PARTIAL	Partial progress made, continuing next loop
ALL_COMPLETE	All sub-tasks of parent are done
ALL_BLOCKED	Remaining sub-tasks are blocked
NO_SUBTASKS	Parent has no sub-tasks
VERIFICATION_FAILED	Tests/typecheck/lint failed after retries

Critical requirements:

1. Output MUST be valid YAML or JSON
2. Output MUST appear at the END of your response
3. Output MUST include status and timestamp fields
4. Include all required fields for the specific status type

Example complete output:

---
status: SUBTASK_COMPLETE
timestamp: "2026-01-28T16:45:00Z"
subtaskId: "MOB-177"
parentId: "MOB-161"
commitHash: "f2ccd9e"
filesModified:
  - ".claude/skills/execute/SKILL.md"
verificationResults:
  typecheck: PASS
  tests: PASS
  lint: PASS
  subtaskVerify: PASS
---

</structured_output>

<context> This skill is the execution phase of the issue workflow:

1. define - Creates well-defined issues with acceptance criteria
2. refine - Breaks issues into single-file-focused sub-tasks with dependencies
3. execute (this skill) - Implements ONE sub-task, then stops

Loop-Based Execution Model: This skill is designed to be called repeatedly by a loop script (e.g., mobius loop). Each invocation:

1. Finds the NEXT ready sub-task
2. Executes it completely
3. Reports completion
4. STOPS (does not continue to next sub-task)

The loop script will call this skill again for the next sub-task. This ensures:

• Fresh context for each sub-task
• Clear boundaries between tasks
• Predictable execution behavior
• Easy progress monitoring

Each sub-task is designed to:

• Target a single file (or source + test pair)
• Fit within one context window
• Have clear acceptance criteria
• Have explicit blocking relationships </context>

<checkpoint_system> Checkpoint system enables recovery from interruptions by saving structured state after each major phase.

Checkpoints are only used for non-trivial tasks (estimated >5 minutes or involving multiple verification cycles). Skip checkpoints for simple single-file changes.

<checkpoint_definitions>

Checkpoint 1: Context Priming Complete

Phase: After loading parent issue, finding ready subtask, and loading dependency context Marker: CHECKPOINT:PRIMED Saves:

• Parent issue ID and title
• Selected subtask ID and title
• Target file path
• Completed dependency summaries (not full content)
• Key patterns identified for implementation Recovery: Skip context loading, proceed directly to implementation

Checkpoint 2: Implementation Complete

Phase: After implementing changes but before verification Marker: CHECKPOINT:IMPLEMENTED Saves:

• List of modified files
• Summary of changes made (not full diffs)
• Staged files ready for verification
• Implementation approach taken Recovery: Skip implementation, proceed to verification

Checkpoint 3: Verification Complete

Phase: After all verification passes, ready to commit Marker: CHECKPOINT:VERIFIED Saves:

• Verification results (typecheck, tests, lint)
• Files ready to commit
• Draft commit message Recovery: Skip verification, proceed directly to commit </checkpoint_definitions>

<checkpoint_thresholds> When to create checkpoints:

• Task description > 5 sentences
• Multiple acceptance criteria (>3)
• Target file > 200 lines
• Previous attempt was interrupted (detected via existing checkpoint)

When to skip checkpoints:

• Simple single-criterion tasks
• Small file changes (<50 lines)
• Tasks marked as "quick fix" or "trivial" </checkpoint_thresholds>

<save_checkpoint> Add checkpoint comment to issue after completing each phase.

Checkpoints are written to the local context and queued for sync. The checkpoint data is included in the structured output.

Checkpoint comment format (structured for parsing):

## Checkpoint: {CHECKPOINT_MARKER}

**Timestamp**: {ISO-8601 timestamp}
**Agent**: {agent-id or session-id if available}

### State Summary
{phase-specific state data as key-value pairs}

### Files Involved
- `{file1}` - {status: read/modified/staged}
- `{file2}` - {status: read/modified/staged}

### Next Phase
{description of what the next phase should do}

---
CHECKPOINT:{MARKER}:{subtask-id}:{timestamp}

Example checkpoint comments:

## Checkpoint: PRIMED

**Timestamp**: 2024-01-15T14:30:00Z
**Agent**: execute-loop-1

### State Summary
- parent_id: PROJ-100
- subtask_id: PROJ-125
- target_file: src/contexts/ThemeContext.tsx
- change_type: Create
- dependencies_loaded: PROJ-124

### Files Involved
- `src/types/theme.ts` - read (from dependency)

### Next Phase
Implement ThemeContext provider with light/dark/system modes

---
CHECKPOINT:PRIMED:PROJ-125:2024-01-15T14:30:00Z

Important:

• Append new checkpoints; never delete previous ones (audit trail)
• Include machine-parseable marker line at the end
• Keep state summaries concise - metadata only, not full content </save_checkpoint>

<resume_from_checkpoint> Detect and resume from interrupted work at the start of execution.

Detection steps:

1. After loading the subtask, list recent comments
2. Search for comments containing CHECKPOINT: marker
3. Parse the most recent checkpoint marker line

Checkpoint marker format:

CHECKPOINT:{MARKER}:{subtask-id}:{timestamp}

Resume logic by marker:

Marker	Resume Action
PRIMED	Skip context loading, read state summary, proceed to implementation
IMPLEMENTED	Skip implementation, verify files from state, proceed to verification
VERIFIED	Skip verification, use saved commit message, proceed to commit

Resume validation: Before resuming, validate the checkpoint is still valid:

1. Check that mentioned files still exist
2. Verify git status matches expected state (staged files, no unexpected changes)
3. If validation fails, discard checkpoint and start fresh

Resume comment (add when resuming):

## Resuming from Checkpoint

**Previous checkpoint**: {MARKER} at {timestamp}
**Validation**: PASSED
**Skipping phases**: {list of skipped phases}

Continuing from {phase name}...

When NOT to resume:

• Checkpoint is >24 hours old
• Files mentioned in checkpoint were modified outside this workflow
• Subtask description has changed since checkpoint
• User explicitly requests fresh start </resume_from_checkpoint> </checkpoint_system>

<quick_start> <invocation> Pass an issue ID (either parent or subtask):

/execute PROJ-123    # Parent issue - finds next ready subtask
/execute PROJ-124    # Subtask - executes this specific task

When running in parallel mode, each agent receives a specific subtask ID to prevent race conditions. </invocation>

<workflow> 1. **Detect backend** - Read backend from config (linear or jira) 2. **Detect issue type** - Check if passed ID is a subtask (has parent) or parent issue 3. **Load parent issue** - Get high-level context and acceptance criteria 4. **Find ready sub-task** - If parent was passed, find first ready subtask (skip if subtask was passed) 5. **Mark In Progress** - Move sub-task to "In Progress" immediately before starting work 6. **Prime context** - Load completed dependent tasks for implementation context 7. **Implement changes** - Execute the single-file-focused work 8. **Verify standard** - Run tests, typecheck, and lint 9. **Fix if needed** - Attempt automatic fixes on verification failures 10. **Verify sub-task** - Execute `### Verify` command from sub-task if present (with safety checks) 11. **Commit and push** - Create commit with conventional message, push 12. **Update local context** - Update `.mobius/issues/{parentId}/` files with new status 13. **Write iteration data** - Append iteration entry to `.mobius/issues/{parentId}/execution/iterations.json` 14. **Update status** - Move sub-task to "Done" if all criteria met 15. **Report completion** - Show what was done and what's next </workflow> </quick_start>

<context_priming_phase> <detect_issue_type> FIRST: Determine if the passed issue ID is a subtask or a parent issue.

Read from the context file provided via MOBIUS_CONTEXT_FILE environment variable.

Check the context structure:

1. If context contains a specific subtask to execute -> This is a SUBTASK

   • The context file will have the subtask pre-selected
   • Skip the "find ready subtask" phase entirely
   • Use this subtask directly for implementation

2. If context contains parent with multiple subtasks -> Find ready subtask

   • Continue with the "find ready subtask" flow below
   • This is the fallback for backward compatibility

Why this matters: When running in parallel mode (mobius loop PROJ-123 --parallel=3), each agent receives a specific subtask ID to prevent race conditions. The orchestrator assigns tasks upfront, so each agent should execute exactly the task it was given. </detect_issue_type>

<load_parent_issue> Read the parent issue from the context file:

# Read from context file
cat "$MOBIUS_CONTEXT_FILE" | jq '.parent'

Extract:

• Goal: What the overall feature/fix achieves (from description)
• Acceptance criteria: High-level success conditions
• Context: Any technical notes or constraints
• Related issues: For broader understanding </load_parent_issue>

<find_ready_subtask> Skip this section if executing a specific subtask (context has pre-selected subtask).

Read all sub-tasks from the context file:

cat "$MOBIUS_CONTEXT_FILE" | jq '.subTasks[]'

For each sub-task, check:

1. Status is not "done" or "canceled"
2. All blocking issues (in blockedBy array) have status "done"

Select the FIRST sub-task where all blockers are resolved.

STOP CONDITIONS (output structured status and end immediately):

1. All sub-tasks are Done: Output structured status with status: ALL_COMPLETE

2. All remaining sub-tasks are blocked: Output structured status with status: ALL_BLOCKED

3. No sub-tasks exist: Output structured status with status: NO_SUBTASKS

If any stop condition is met, output the structured status and STOP. Do not continue. </find_ready_subtask>

<mark_in_progress> IMMEDIATELY after selecting a sub-task to work on, note it as "In Progress" in your structured output.

The mobius loop will handle the actual status update via SDK after parsing your output.

Why this matters: Moving to "In Progress" immediately ensures:

• Other agents (in parallel mode) won't pick up the same task
• The TUI/dashboard shows accurate real-time status
• If the agent crashes or times out, the task remains "In Progress" for the next loop </mark_in_progress>

<load_dependency_context> For each completed blocker of the selected sub-task, fetch the issue details.

Extract from each completed dependency:

• What was implemented: Summary of changes
• Files modified: To understand current state
• Patterns used: To maintain consistency
• Any notes: Implementation decisions or gotchas

Compile into a context brief for the current task. </load_dependency_context>

<context_brief_format> Build context brief for implementation:

# Execution Context

## Parent Issue: {ID} - {Title}
{Parent description and acceptance criteria}

## Current Sub-task: {ID} - {Title}
**Target file**: {file path}
**Change type**: {Create/Modify}
{Sub-task description and acceptance criteria}

## Completed Dependencies
### {Dep-1 ID}: {Title}
- Modified: {files}
- Summary: {what was done}

### {Dep-2 ID}: {Title}
- Modified: {files}
- Summary: {what was done}

## Implementation Notes
- Follow patterns from: {relevant completed tasks}
- Key imports needed: {based on dependency analysis}
- Test file: {expected test location}

</context_brief_format> </context_priming_phase>

<implementation_phase> <read_target_file> Before making changes, read the target file(s):

• If Create: Check directory exists, understand sibling file patterns
• If Modify: Read current file content completely

Also read:

• Related type definitions (from completed dependencies)
• Test file if it exists
• Any files imported by the target </read_target_file>

<implement_changes> Execute the implementation following:

1. Match existing patterns - Use same style as similar files
2. Single file focus - Only modify the target file(s) specified
3. Meet acceptance criteria - Each criterion should be addressed
4. Add/update tests - If target is source file, update corresponding test

Use Edit tool for modifications, Write tool for new files.

Implementation checklist:

• All acceptance criteria addressed
• Follows existing code patterns
• Proper imports added
• Types are correct
• Test coverage for new code </implement_changes>

<scope_discipline> Stay within scope:

• Only modify files specified in the sub-task
• Don't refactor unrelated code
• Don't add features not in acceptance criteria
• Don't fix unrelated issues discovered during work

If you discover issues outside scope:

• Note them for later
• Don't fix them now
• Can mention in completion report </scope_discipline> </implementation_phase>

<tdd_option> Test-Driven Development workflow is optional and should be used when explicitly requested or when sub-tasks have highly testable acceptance criteria.

<when_to_use> Use TDD when ANY of these apply:

1. Explicit directive: Sub-task description contains "Use TDD" or "TDD workflow"
2. Complex business logic: Algorithm implementations, data transformations, validation rules
3. Refactoring existing code: When changing implementation while preserving behavior
4. Bug fixes with reproducible steps: Write test that reproduces bug first
5. Well-defined input/output: Functions with clear contracts and edge cases

Skip TDD when:

• Simple configuration changes
• UI/layout modifications without logic
• Adding imports or wiring up existing components
• Documentation-only changes
• Sub-task explicitly says "Do NOT use TDD"

Detection heuristic: If sub-task has >3 specific, testable acceptance criteria (not just "implement X"), consider TDD. </when_to_use>

<tdd_workflow> When TDD is appropriate, follow the red-green-refactor cycle instead of the standard implementation flow:

Red Phase: Write Failing Tests First

1. Analyze acceptance criteria - Convert each criterion to a test case
2. Create/update test file - Write tests that define expected behavior
3. Run tests to confirm failure - Tests MUST fail (proves tests are meaningful)
4. Commit failing tests (optional) - Some teams prefer this for traceability

# Example: Run tests to verify they fail
just test-file {test-file-pattern}
# Expected: Tests should FAIL at this point

Red phase checklist:

• Each acceptance criterion has a corresponding test
• Tests cover edge cases mentioned in sub-task
• Tests are isolated and independent
• Tests fail for the right reason (missing implementation, not syntax errors)

Green Phase: Implement Minimal Code to Pass

1. Focus on passing tests - Write just enough code to make tests green
2. Don't optimize prematurely - Correctness first, elegance later
3. Run tests after each change - Verify progress incrementally
4. All tests must pass before proceeding

# Verify tests pass
just test-file {test-file-pattern}
# Expected: All tests should PASS

Green phase checklist:

• All previously failing tests now pass
• No new test failures introduced
• Implementation addresses acceptance criteria
• Code compiles without type errors

Refactor Phase: Improve Code Quality

1. Clean up implementation - Remove duplication, improve naming
2. Maintain passing tests - Run tests after each refactor step
3. Apply code patterns - Match existing codebase conventions
4. Don't add new behavior - Only restructure existing code

# Verify tests still pass after refactoring
just test-file {test-file-pattern}
# Expected: All tests should still PASS

Refactor phase checklist:

• Code follows project patterns and conventions
• No code duplication
• Clear naming and structure
• All tests still pass
• Typecheck passes </tdd_workflow>

<tdd_vs_standard_flow> When to use each approach:

Scenario	Approach	Why
"Use TDD" in description	TDD	Explicit request
Algorithm implementation	TDD	Complex logic benefits from test-first
Bug fix with repro steps	TDD	Test captures the bug
UI component wiring	Standard	Tests come after implementation
Config/env changes	Standard	Not meaningfully testable
>3 testable criteria	Consider TDD	High specificity suggests test-first value

Switching mid-task: If you start with standard flow and realize TDD would help, you can switch. Write tests for remaining criteria, verify they fail, then continue with green-refactor. </tdd_vs_standard_flow>

<tdd_commit_strategy> Commit points in TDD workflow:

Option A: Single commit at end (recommended for small sub-tasks)

• Complete full red-green-refactor cycle
• Single commit with all changes

Option B: Multiple commits (for larger sub-tasks)

• Commit 1: Failing tests (optional, documents intent)
• Commit 2: Passing implementation + refactored code

Commit message for TDD:

feat(scope): implement feature using TDD

Red: Added tests for {criteria}
Green: Implemented {functionality}
Refactor: {what was cleaned up}

Implements: {sub-task-id}
Part-of: {parent-issue-id}

</tdd_commit_strategy>

<tdd_anti_patterns> Avoid these TDD mistakes:

• Testing implementation details: Test behavior, not internal structure

  • BAD: expect(obj._privateMethod).toBeCalled()
  • GOOD: expect(result).toEqual(expectedOutput)

• Writing tests that can't fail: Tests must be meaningful

  • BAD: expect(true).toBe(true)
  • GOOD: expect(calculate(input)).toBe(expectedResult)

• Skipping the refactor phase: Refactoring is essential for maintainability

  • BAD: Green tests → commit immediately
  • GOOD: Green tests → refactor → verify still green → commit

• Over-testing: Don't test framework behavior or trivial code

  • BAD: Testing that React renders a div
  • GOOD: Testing that component displays correct data

• Forcing TDD on unsuitable tasks: Not everything benefits from test-first

  • BAD: TDD for a CSS color change
  • GOOD: Standard flow for styling, TDD for logic </tdd_anti_patterns> </tdd_option>

<verification_phase> <full_validation> Run all three verification steps:

1. Type checking:

just typecheck

2. Tests:

just test-file {pattern matching target file}

Or if new functionality spans multiple test files:

just test

3. Lint (if available):

just lint
# or
bun run lint

</full_validation>

<handle_failures> If any verification fails:

Attempt automatic fix:

1. Read the error output carefully
2. Identify the root cause
3. Apply targeted fix to resolve the issue
4. Re-run the failing verification
5. Repeat up to 3 times

Common fixes:

• Type errors: Add missing types, fix type mismatches
• Test failures: Update test expectations, fix logic errors
• Lint errors: Apply auto-fix if available, manual fix otherwise

If fix attempts fail after 3 tries:

• Stop execution immediately
• Do NOT ask user questions (this skill runs in an automated loop)
• Output failure status and terminate:

STATUS: VERIFICATION_FAILED

## Sub-task Failed: {sub-task-id}

### Error Summary
{type of failure: typecheck/tests/lint}

### Last Error Output

{truncated error output, last 50 lines}

### Attempted Fixes
1. {fix attempt 1}
2. {fix attempt 2}
3. {fix attempt 3}

### Files Modified (uncommitted)
- {file1}
- {file2}

The loop will stop. Review the errors and either:
- Fix manually and run `/execute {parent-id}` again
- Or rollback with `git checkout -- .`

CRITICAL: After outputting this failure report, STOP. Do not continue trying. </handle_failures>

<verification_success> All checks must pass before proceeding:

## Verification Results
- Typecheck: PASS
- Tests: PASS (X tests, Y assertions)
- Lint: PASS

Ready for sub-task verify command (if present).

</verification_success>

<subtask_verify_command> After standard verification passes, check for and execute a ### Verify command from the sub-task description.

<parse_verify_block> Extract the verify command from the sub-task description:

1. Look for ### Verify section in the sub-task description
2. Extract the bash code block immediately following the header
3. The command is the content between ```bash and ``` markers

Example sub-task description:

### Verify

```bash
grep -q "export function" src/utils/helpers.ts && \
npm test -- --grep "helpers" && \
echo "PASS: Helper function verified"

**Extraction result**: The bash command to execute.
</parse_verify_block>

<verify_command_safety>
**CRITICAL**: Before executing any verify command, check for dangerous patterns.

**Block these patterns** (do NOT execute, report as unsafe):
- `rm -rf` or `rm -r` with wildcards or root paths
- `sudo` commands
- Commands writing to system paths (`/etc`, `/usr`, `/var`)
- `chmod 777` or overly permissive permission changes
- `curl | bash` or `wget | sh` piping to shell
- `dd if=` disk operations
- `mkfs` or filesystem formatting
- `:(){:|:&};:` or other fork bombs
- `> /dev/` device writes
- Commands containing `$()` or backticks with destructive operations

**Safety check implementation**:
```bash
# Patterns to block (regex)
DANGEROUS_PATTERNS=(
  "rm\s+(-[rf]+\s+)*(/|~|\*|\.\.|\\$)"
  "sudo\s+"
  "chmod\s+777"
  "curl.*\|\s*(ba)?sh"
  "wget.*\|\s*(ba)?sh"
  "dd\s+if="
  "mkfs"
  ">\s*/dev/"
  ":\(\)\s*\{.*\}.*;"
)

If a dangerous pattern is detected:

## Verify Command Blocked

**Reason**: Command contains potentially dangerous pattern: `{pattern}`
**Command**: `{command}`

The verify command was not executed for safety reasons.
Proceeding to commit phase without sub-task verification.

**Note**: Review the verify command in the sub-task description.

</verify_command_safety>

<execute_verify_command> If the verify command passes safety checks, execute it:

# Execute the extracted verify command
{extracted_verify_command}

Timeout: Verify commands have a 60-second timeout to prevent hanging.

On success (exit code 0):

## Sub-task Verify Command
- Command: `{command_summary}`
- Result: PASS
- Output: {last few lines of output}

Verify command passed. Ready to commit.

On failure (non-zero exit code): The verify command failure triggers an implementation review loop:

1. Read the error output to understand what failed
2. Review the implementation against the sub-task requirements
3. Attempt to fix the issue (similar to handling test failures)
4. Re-run the verify command
5. Repeat up to 3 times

If verify command still fails after 3 attempts:

STATUS: VERIFICATION_FAILED

## Sub-task Failed: {sub-task-id}

### Error Summary
Sub-task verify command failed after 3 attempts

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

Last Error Output

{error output}

Attempted Fixes

1. {fix attempt 1}
2. {fix attempt 2}
3. {fix attempt 3}

Files Modified (uncommitted)

• {file1}
• {file2}

The loop will stop. Review the verify command and implementation.

**CRITICAL**: After outputting this failure report, STOP.
</execute_verify_command>

<verify_command_fallback>
**If no `### Verify` section exists** in the sub-task description:

- This is normal and expected for older sub-tasks
- Proceed directly to commit phase after standard verification passes
- Include note in completion report:

```markdown
## Verification Results
- Typecheck: PASS
- Tests: PASS
- Lint: PASS
- Sub-task verify: N/A (no verify block in sub-task)

Ready to commit.

Fallback behavior ensures:

• Backward compatibility with existing sub-tasks
• Standard tests/typecheck/lint still required
• No failure if verify block is missing </verify_command_fallback> </subtask_verify_command> </verification_phase>

<commit_phase> <commit_message> Create conventional commit message:

Format:

{type}({scope}): {description}

{body with details}

Implements: {sub-task-id}
Part-of: {parent-issue-id}

Type mapping:

• New file created -> feat
• Bug fix -> fix
• Modification/enhancement -> feat or refactor
• Test only -> test
• Types only -> types

Example:

feat(theme): add ThemeContext provider

- Create ThemeProvider with light/dark/system modes
- Persist theme preference to localStorage
- Add useTheme hook for consuming context

Implements: PROJ-125
Part-of: PROJ-100

</commit_message>

<git_operations> Execute git operations:

# Stage only the files we modified
git add {target-file} {test-file-if-applicable}

# Commit with conventional message
git commit -m "{commit message}"

# Push to current branch
git push

Important:

• Only stage files explicitly modified for this sub-task
• Don't use git add -A or git add .
• Verify staged files match expected scope before commit </git_operations>

<commit_verification> After push, verify:

git log -1 --oneline
git status

Confirm:

• Commit created successfully
• Push completed without errors
• Working directory is clean </commit_verification> </commit_phase>

<status_update_phase> <update_local_context> CRITICAL: After successful commit, update the local context files.

The local context files must be updated so that mobius sync can push changes to Linear/Jira.

Files to update:

1. Task-specific file: .mobius/issues/{parentId}/tasks/{subtaskId}.json

   • Change "status": "pending" or "status": "in_progress" to "status": "done"

2. Main context file: .mobius/issues/{parentId}/context.json

   • Find the subtask in the subTasks array by identifier
   • Change its "status" to "done"
   • Update metadata.updatedAt to current ISO-8601 timestamp

Example using Edit tool:

# Update task file
Edit .mobius/issues/MOB-161/tasks/MOB-184.json
  old_string: "status": "pending"
  new_string: "status": "done"

# Update context.json - find the subtask entry and update status
Edit .mobius/issues/MOB-161/context.json
  old_string: [find the subtask block with matching identifier and "status": "pending"]
  new_string: [same block with "status": "done"]

# Update the updatedAt timestamp
Edit .mobius/issues/MOB-161/context.json
  old_string: "updatedAt": "2026-01-28T19:05:00.000Z"
  new_string: "updatedAt": "{current ISO-8601 timestamp}"

Why this matters:

• The mobius sync command reads local context files and pushes changes to Linear/Jira
• Without updating these files, the status change won't propagate to the issue tracker
• The structured YAML output alone is not sufficient - local files MUST be updated

For partial completion (SUBTASK_PARTIAL):

• Update status to "in_progress" instead of "done"
• Still update the updatedAt timestamp </update_local_context>

<iteration_tracking> After updating local context, write iteration data to the execution log.

Each sub-task execution is tracked as an iteration in .mobius/issues/{parentId}/execution/iterations.json. This file accumulates data across loop invocations to provide a full execution history.

Iteration data structure:

{
  "iterations": [
    {
      "subtaskId": "MOB-177",
      "startedAt": "2026-01-28T14:30:00Z",
      "completedAt": "2026-01-28T14:45:00Z",
      "commitHash": "abc1234",
      "duration": "PT15M",
      "status": "complete",
      "filesModified": ["src/lib/feature.ts", "src/lib/feature.test.ts"],
      "verificationResults": {
        "typecheck": "PASS",
        "tests": "PASS",
        "lint": "PASS",
        "subtaskVerify": "PASS"
      }
    }
  ]
}

Writing iteration data:

1. Read existing .mobius/issues/{parentId}/execution/iterations.json (create if missing)
2. Append a new entry to the iterations array with:
   • subtaskId: The sub-task identifier (e.g., "MOB-177")
   • startedAt: ISO-8601 timestamp when execution began
   • completedAt: ISO-8601 timestamp when execution finished
   • commitHash: The git commit hash (or null if no commit)
   • duration: ISO-8601 duration (e.g., "PT15M" for 15 minutes)
   • status: One of "complete", "partial", "failed"
   • filesModified: Array of modified file paths
   • verificationResults: Object with typecheck/tests/lint/subtaskVerify results
3. Write the updated JSON back to the file

Ensure the execution directory exists:

mkdir -p .mobius/issues/{parentId}/execution

For failed iterations, still record the entry with status: "failed" and include error details:

{
  "subtaskId": "MOB-178",
  "startedAt": "2026-01-28T15:00:00Z",
  "completedAt": "2026-01-28T15:20:00Z",
  "commitHash": null,
  "duration": "PT20M",
  "status": "failed",
  "filesModified": ["src/lib/feature.ts"],
  "verificationResults": {
    "typecheck": "PASS",
    "tests": "FAIL",
    "lint": "PASS",
    "subtaskVerify": "N/A"
  },
  "error": "Test failed: expected 2 but got 3"
}

Why this matters:

• Provides full execution history for debugging and analysis
• Enables timing analysis across the loop lifecycle
• Powers the summary generation at loop completion
• Tracks retry patterns and common failure modes </iteration_tracking>

<update_subtask_status_done> After successful commit with all acceptance criteria met, include status update in your structured output.

The mobius loop will execute the actual status transition via SDK based on your output.

Criteria for moving to "Done":

• All acceptance criteria from the sub-task are implemented
• All verification checks pass (typecheck, tests, lint)
• Changes are committed and pushed
• Local context files updated (see update_local_context above)
• No outstanding work remains for this sub-task </update_subtask_status_done>

<add_completion_comment> Include completion details in your structured output. The mobius loop will create the comment via SDK.

The structured output should include:

status: SUBTASK_COMPLETE
subtaskId: "MOB-177"
commitHash: "abc123"
filesModified:
  - "src/file1.ts"
  - "src/file2.ts"
verificationResults:
  typecheck: PASS
  tests: PASS
  lint: PASS
  subtaskVerify: PASS

</add_completion_comment>

<partial_completion_handling> If the agent must wrap up before completing all work (context limits, time constraints, or blocking issues discovered), keep the task "In Progress" and add a detailed progress comment:

## Partial Progress - Continuing Next Loop

**Progress Made**:
- {what was accomplished}
- {files modified so far}

**Remaining Work**:
- {what still needs to be done}
- {specific acceptance criteria not yet met}

**Current State**:
- Committed: {yes/no - if yes, include commit hash}
- Verification: {status of typecheck/tests/lint}

**Blockers/Issues Discovered** (if any):
- {any issues that need attention}

**Next Steps**:
- {what the next loop iteration should focus on}

CRITICAL: Do NOT move to "Done" if:

• Some acceptance criteria are not yet implemented
• Tests are failing
• There are uncommitted changes that need more work
• The implementation is incomplete

Leave the task "In Progress" so the next loop iteration can continue the work. </partial_completion_handling> </status_update_phase>

<completion_report> <report_format> After successful execution, report and STOP:

# Sub-task Completed

STATUS: SUBTASK_COMPLETE

## {Sub-task ID}: {Title}
**Status**: Moved to Done
**Commit**: {hash} on {branch}

### Files Modified
- `{file1}` - {change summary}
- `{file2}` - {change summary}

### Acceptance Criteria
- [x] Criterion 1
- [x] Criterion 2
- [x] Criterion 3

### Verification
- Typecheck: PASS
- Tests: PASS
- Lint: PASS
- Sub-task verify: {PASS/N/A}

---

## Progress
**Completed**: {X of Y sub-tasks}
**Ready next**: {list of now-unblocked sub-tasks, or "none" if all blocked/done}
**Still blocked**: {count of sub-tasks still waiting}

---
EXECUTION_COMPLETE: {sub-task-id}

CRITICAL: After outputting this report, STOP IMMEDIATELY. Do not:

• Start working on the next sub-task
• Ask if the user wants to continue
• Suggest what to do next
• Make any further tool calls

The loop script will invoke this skill again for the next sub-task. </report_format>

<partial_completion_report> If wrapping up with incomplete work, output this report instead:

# Sub-task Partial Progress

STATUS: SUBTASK_PARTIAL

## {Sub-task ID}: {Title}
**Status**: In Progress (continuing next loop)
**Commit**: {hash if any, or "uncommitted changes"}

### Progress Made
- {what was accomplished}
- {files modified}

### Remaining Work
- [ ] {uncompleted criterion 1}
- [ ] {uncompleted criterion 2}

### Current State
- Typecheck: {PASS/FAIL/NOT_RUN}
- Tests: {PASS/FAIL/NOT_RUN}
- Lint: {PASS/FAIL/NOT_RUN}
- Sub-task verify: {PASS/FAIL/NOT_RUN/N/A}

### Why Stopping
{reason - e.g., "context limit reached", "blocking issue discovered", "time constraint"}

### Notes for Next Loop
{specific guidance for continuation}

---
EXECUTION_PARTIAL: {sub-task-id}

This status keeps the task "In Progress" for the next loop iteration to continue. </partial_completion_report>

<discovered_issues> If issues were discovered during implementation but not addressed:

### Out-of-Scope Issues Discovered
- {Issue 1}: {brief description} in {file}
- {Issue 2}: {brief description} in {file}

Consider creating separate issues for these.

</discovered_issues> </completion_report>

<examples> <execution_example> **Input**: `/execute PROJ-100`

Flow:

1. Detect backend from config (e.g., linear)

2. Load PROJ-100 (parent: "Add dark mode support")

3. Find sub-tasks:

   • PROJ-124: Define types (Done)
   • PROJ-125: Create ThemeProvider (blockedBy: PROJ-124) <- Ready
   • PROJ-126: Add useTheme hook (blockedBy: PROJ-125) - Blocked
   • PROJ-127: Update Header (blockedBy: PROJ-126) - Blocked

4. Select PROJ-125 (first ready task)

5. Immediately mark PROJ-125 as "In Progress" and add start comment

6. Load context from PROJ-124:

   • Created src/types/theme.ts
   • Exports: Theme, ThemeMode, ThemeContextValue

7. Implement PROJ-125:

   • Create src/contexts/ThemeContext.tsx
   • Import types from completed dependency
   • Follow existing context patterns in codebase

8. Verify:

   • just typecheck -> PASS
   • just test-file ThemeContext -> PASS
   • just lint -> PASS

9. Commit and push:

   feat(theme): create ThemeProvider context
   
   - Add ThemeProvider component with light/dark/system modes
   - Persist preference to localStorage
   - Detect system preference changes
   
   Implements: PROJ-125
   Part-of: PROJ-100
   

10. Update status:

    • PROJ-125 -> "Done" (all criteria met)
    • Add completion comment with commit hash and acceptance criteria

11. Report and STOP:

    STATUS: SUBTASK_COMPLETE
    
    ## PROJ-125: Create ThemeProvider
    **Status**: Moved to Done
    Completed: 2 of 4 sub-tasks
    Ready next: PROJ-126
    
    EXECUTION_COMPLETE: PROJ-125
    

12. STOP - Do not continue to PROJ-126. The loop will invoke again. </execution_example>

    </examples>

<anti_patterns> Don't continue to next sub-task (MOST IMPORTANT):

• BAD: "Sub-task A complete. Now let me work on sub-task B..."
• BAD: "Should I continue to the next sub-task?"
• BAD: Processing multiple sub-tasks in one invocation
• GOOD: Complete ONE sub-task, output STATUS, STOP

Don't skip context priming:

• BAD: Jump straight into coding without understanding dependencies
• GOOD: Load parent issue and completed blockers first

Don't expand scope:

• BAD: Fix unrelated issues discovered during work
• GOOD: Note them and stay focused on the sub-task

Don't skip verification:

• BAD: Commit without running tests
• GOOD: Full validation (tests, typecheck, lint) before every commit

Don't commit unrelated files:

• BAD: git add -A to stage everything
• GOOD: Stage only files specified in sub-task

Don't ignore failures:

• BAD: Push despite test failures
• GOOD: Fix issues or output VERIFICATION_FAILED and stop

Don't forget status updates:

• BAD: Complete work but leave sub-task in Backlog
• GOOD: Update status and add completion comment

Don't skip local context updates:

• BAD: Only output structured YAML without updating .mobius/issues/ files
• BAD: Commit and push but forget to update task JSON files
• GOOD: Update both task-specific JSON and main context.json after commit
• GOOD: Update metadata.updatedAt timestamp when modifying context

Don't misuse status transitions:

• BAD: Leave task in Backlog while working on it
• BAD: Move to Done before all acceptance criteria are met
• BAD: Move to Done when tests are failing
• GOOD: Move to "In Progress" immediately when starting work
• GOOD: Move to "Done" only after successful commit with all criteria met
• GOOD: Keep "In Progress" with progress comment if wrapping up incomplete

Don't ask user questions:

• BAD: Using AskUserQuestion during automated loop execution
• GOOD: Make reasonable decisions or output failure STATUS and stop </anti_patterns>

<success_criteria> A successful execution achieves:

• Backend detected from config
• Parent issue context loaded and understood
• Correct ready sub-task selected (no unresolved blockers)
• Sub-task moved to "In Progress" immediately when starting work
• Context from completed dependencies incorporated
• Implementation addresses all acceptance criteria
• Only specified files modified (scope discipline)
• Typecheck passes
• Tests pass
• Lint passes
• Sub-task verify command passes (if present in description)
• Commit created with conventional message
• Changes pushed to remote
• Local context files updated (.mobius/issues/{parentId}/ task and context.json)
• Sub-task moved to "Done" (if fully complete)
• Or: Sub-task kept "In Progress" with progress comment (if partial)
• Completion report output with STATUS marker
• STOPPED after one sub-task (no continuation) </success_criteria>

<termination_signals> The skill outputs these status markers for loop script parsing:

Status	Meaning	Loop Action
STATUS: SUBTASK_COMPLETE	Sub-task fully implemented, moved to Done	Continue loop
STATUS: SUBTASK_PARTIAL	Partial progress made, stays In Progress	Continue loop
STATUS: ALL_COMPLETE	All sub-tasks are done	Exit loop
STATUS: ALL_BLOCKED	Remaining sub-tasks are blocked	Exit loop
STATUS: NO_SUBTASKS	No sub-tasks exist	Exit loop
STATUS: VERIFICATION_FAILED	Tests/typecheck failed after retries	Exit loop

Each invocation outputs exactly ONE status and then terminates. </termination_signals>