todo-management

name	TODO Management
description	Use when the user asks to "create a todo", "list todos", "update todo", "query tasks", "check todo status", "plan implementation", or "mark todo done".
version	0.1.0

TODO Management

Overview

To interact with project TODOs, use the workflow.todo.* REPL command namespace through lib/repl-invoke.ps1 via the PowerShell.MCP wrapper. The wrapper accepts the documented params, validates them, and sends a single-line JSON request envelope to PowerShell.MCP wrapper. Direct stdio callers must use the same shape: one single-line JSON request envelope per message, not formatted YAML. The server returns a type: result or type: error envelope on stdout. Streaming commands additionally emit a sequence of type: event envelopes before the final result.

The YAML blocks in this skill illustrate the logical structure of each envelope for readability; the actual wire format is single-line JSON.

Session Log Bootstrap

Before using any workflow commands, call workflow.sessionlog.bootstrap to initialize the session log subsystem:

type: request
payload:
  requestId: req-20260409T120000Z-bootstrap-001
  method: workflow.sessionlog.bootstrap
  params: {}

This call is idempotent and should be made once per conversation context.

Usage Guidance

Use TODO data to refine or confirm the current plan after checking session/task state. Do not start with TODO enumeration when session state already identifies the active task.

Internal TODO Tracking Toggle

By default, the agent keeps transient checklist state locally and uses MCP TODOs only when the task needs durable workspace TODO tracking. To make MCP TODOs the backing store for durable plan items in a workspace:

type: request
payload:
  requestId: req-20260409T115900Z-todo-internal-enable
  method: workflow.todo.internal.enable
  params: {}

To turn it off:

type: request
payload:
  requestId: req-20260409T115901Z-todo-internal-disable
  method: workflow.todo.internal.disable
  params: {}

workflow.todo.internal.status reports the active state and whether it came from the cached setting, default behavior, or an environment override. An environment-variable override, when set, takes precedence over the cached setting for the current process: set it to 1 to force-enable internal tracking or 0 to force-disable it. The plugin defines the specific override variable name.

TODO ID Naming Conventions

Persist only IDs that conform to one of two patterns:

• ^[A-Z]+-[A-Z0-9]+-\d{3}$: three-segment uppercase kebab-case, e.g. PLAN-NAMINGCONVENTIONS-001, MCP-AUTH-042
• ^ISSUE-\d+$: GitHub-backed canonical ID, e.g. ISSUE-17

The special create-only value ISSUE-NEW instructs the server to create a GitHub issue, rewrite the stored ID to ISSUE-{number}, and return the canonical form. After the first sync, the description / body of an ISSUE-{number} TODO is immutable from the server side; subsequent update calls surface the change as a GitHub issue comment instead of overwriting the body.

When populating dependsOn, each dependency ID must also conform to these patterns.

Querying TODOs

To retrieve a filtered list of TODOs:

type: request
payload:
  requestId: req-20260409T120000Z-query-001
  method: workflow.todo.query
  params:
    keyword: authentication
    priority: high
    section: Backend
    done: false

All params fields are optional. Omit params entirely to return all TODOs. The response contains a paginated items array:

type: result
payload:
  requestId: req-20260409T120000Z-query-001
  result:
    items:
      - id: MCP-AUTH-001
        title: Implement JWT authentication
        section: Backend
        priority: high
        done: false
        estimate: 4h
        functionalRequirements: [FR-AUTH-001]
        technicalRequirements: [TR-AUTH-001]
    totalCount: 1

Valid priority values: critical, high, medium, low.

Getting a Single TODO

To fetch the full detail of one TODO by ID:

type: request
payload:
  requestId: req-20260409T120001Z-get-001
  method: workflow.todo.get
  params:
    id: MCP-AUTH-001

The result includes all fields: implementationTasks, description, technicalDetails, remaining, doneSummary, dependsOn, requirement arrays, and timestamps.

Selecting a TODO as Active Context

To set a TODO as the active working context for the session:

type: request
payload:
  requestId: req-20260409T120002Z-select-001
  method: workflow.todo.select
  params:
    id: MCP-AUTH-001

Once selected, workflow.todo.updateSelected may be used to patch fields without repeating the ID on every call.

Creating a TODO

To create a new project task:

type: request
payload:
  requestId: req-20260409T120003Z-create-001
  method: workflow.todo.create
  params:
    id: MCP-AUTH-002
    title: Add rate limiting to auth endpoints
    section: Backend
    priority: medium
    estimate: 2h
    description:
      - Implement sliding window rate limiter
      - Configure 100 requests per 15 minutes
    implementationTasks:
      - task: Create RateLimitMiddleware
        done: false
      - task: Write unit tests
        done: false
    dependsOn: [MCP-AUTH-001]
    functionalRequirements: [FR-AUTH-002]
    technicalRequirements: [TR-AUTH-002]

Required fields: id, title, section, priority. All other fields are optional.

To create a GitHub-backed TODO and let the server assign a canonical ISSUE-{number} ID:

type: request
payload:
  requestId: req-20260409T120004Z-create-issue-001
  method: workflow.todo.create
  params:
    id: ISSUE-NEW
    title: Capture sync regression in token refresh
    section: Issues
    priority: high

The result item.id will contain the assigned ISSUE-{number} value.

Updating a TODO

To modify fields of an existing TODO:

type: request
payload:
  requestId: req-20260409T120005Z-update-001
  method: workflow.todo.update
  params:
    id: MCP-AUTH-001
    remaining: Integration tests still needed
    implementationTasks:
      - task: Create TokenService
        done: true
      - task: Create JwtValidator
        done: true
      - task: Add integration tests
        done: false

Only include fields to change. To mark a TODO complete, set done: true and supply a doneSummary:

type: request
payload:
  requestId: req-20260409T120006Z-update-done-001
  method: workflow.todo.update
  params:
    id: MCP-AUTH-001
    done: true
    doneSummary: JWT authentication implemented and all tests passing

To update the currently selected TODO without repeating the ID:

type: request
payload:
  requestId: req-20260409T120007Z-updatesel-001
  method: workflow.todo.updateSelected
  params:
    remaining: Need to add OpenAPI annotations

Deleting a TODO

To remove a TODO permanently:

type: request
payload:
  requestId: req-20260409T120008Z-delete-001
  method: workflow.todo.delete
  params:
    id: MCP-AUTH-002

Streaming Status Analysis

To request an AI-driven status analysis of a TODO, showing blockers and dependency state:

type: request
payload:
  requestId: req-20260409T120009Z-status-001
  method: workflow.todo.streamStatus
  params:
    id: MCP-AUTH-001

The server emits a sequence of progress events followed by a completion event:

type: event
payload:
  event: workflow.todo.streamStatus
  data:
    eventType: status.progress
    sequence: 1
    timestamp: 2026-04-09T12:00:09Z
    message: Analyzing TODO dependencies...
    progress: 25
---
type: event
payload:
  event: workflow.todo.streamStatus
  data:
    eventType: status.complete
    sequence: 4
    timestamp: 2026-04-09T12:00:12Z
    todoId: MCP-AUTH-001
    status: ready
    blockers: []
    dependencies: [MCP-AUTH-002]

Streaming Plan Generation

To generate an implementation plan for a TODO and stream the result:

type: request
payload:
  requestId: req-20260409T120010Z-plan-001
  method: workflow.todo.streamPlan
  params:
    id: MCP-AUTH-001

Events follow the same eventType: plan.progress / eventType: plan.complete pattern as status streaming. The completion event includes a structured plan document.

Streaming Implementation Execution

To execute an AI-driven implementation run for a TODO and stream progress:

type: request
payload:
  requestId: req-20260409T120011Z-implement-001
  method: workflow.todo.streamImplement
  params:
    id: MCP-AUTH-001

Implementation events carry eventType: implement.progress and a final eventType: implement.complete with a results summary. Handle cancellation by sending a cancellation request; the stream emits a eventType: status.cancelled terminal event.

Analyzing Requirements for a TODO

To trigger requirements analysis and surface missing FR/TR traceability:

type: request
payload:
  requestId: req-20260409T120012Z-analyze-001
  method: workflow.todo.analyzeRequirements
  params:
    id: MCP-AUTH-001

The result lists any detected requirement gaps and suggests FR/TR IDs to associate with the TODO.

Error Handling

Error envelopes include a structured code field:

type: error
payload:
  requestId: req-20260409T120003Z-create-001
  code: invalid_todo_id
  message: TODO ID does not conform to canonical format
  details:
    providedId: mcp-auth-001
    expectedFormat: "^[A-Z]+-[A-Z0-9]+-\\d{3}$"

Common error codes:

• todo_not_found: no TODO with the specified ID
• todo_already_exists: a TODO with the same ID already exists
• invalid_todo_id: ID violates naming convention
• no_selection: updateSelected called with no active selection
• stream_error: a streaming operation failed mid-stream

Implementation Notes

• Use Invoke-McpPlugin.ps1 from lib/repl-invoke.ps1 to build and send envelopes via PowerShell.MCP wrapper.
• The requestId must match ^req-\d{8}T\d{6}Z-[a-z0-9]+(?:-[a-z0-9]+)*$ for every envelope.
• All streaming operations may be cancelled by closing stdin or sending a cancellation request; the REPL guarantees a final cancellation event before closing the stream.
• After marking a TODO done, record the action in the active session log turn using workflow.sessionlog.appendActions with type: edit and the TODO ID as context.