feat: unified task management across GitHub & Linear

[rubenmarcus]

Summary

• ralph-starter task command — unified CLI for managing issues across GitHub and Linear (list, create, update, close, comment)
• Smart ID routing — #123 routes to GitHub, ENG-42 routes to Linear automatically
• --assignee flag — assign tasks with user resolution (Linear matches by name/displayName/email)
• WritableIntegration interface — extends read-only integrations with bidirectional task management
• OpenClaw agent support — added to agent adapter pattern alongside Claude Code, Cursor, Codex, OpenCode
• MCP ralph_task tool — task management available in Claude Desktop/Code
• batch-fetcher refactored — delegates to WritableIntegration instead of hard-coded CLI calls
• Bug fix — resolveIssueId now uses issue(id:) which accepts both UUIDs and identifiers

Documentation

• New CLI reference: docs/docs/cli/task.md
• README: added task to commands table
• Sidebar: added cli/task to CLI Reference section
• Source docs: added Task Management sections to GitHub and Linear pages

Test plan

• pnpm build passes
• pnpm test — 171 tests pass
• pnpm lint — no new warnings
• Dogfooded: bulk-assigned 9 Linear issues (ENG-1442–ENG-1450) to team member via ralph-starter task update
• Verify ralph-starter task list --source linear shows issues
• Verify ralph-starter task create --source linear --title "Test" --priority P1 creates issue
• Verify docs build: cd docs && pnpm build

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[github-actions]

⚠️ Bundle Size Analysis

Metric	Value
Base	1848.54 KB
PR	1920.48 KB
Diff	71.94 KB (3.00%)

Bundle breakdown

156K	dist/auth
28K	dist/automation
4.0K	dist/cli.d.ts
4.0K	dist/cli.d.ts.map
16K	dist/cli.js
12K	dist/cli.js.map
492K	dist/commands
28K	dist/config
4.0K	dist/index.d.ts
4.0K	dist/index.d.ts.map
4.0K	dist/index.js
4.0K	dist/index.js.map
560K	dist/integrations
84K	dist/llm
732K	dist/loop
188K	dist/mcp
32K	dist/presets
92K	dist/setup
36K	dist/skills
392K	dist/sources
76K	dist/ui
84K	dist/utils
336K	dist/wizard

[github-actions]

🔗 Docs Preview

Preview URL: https://feat-unified-task-management.ralph-starter-docs.pages.dev

This preview was deployed from the latest commit on this PR.

[greptile-apps]

Greptile Summary

This PR adds a unified ralph-starter task CLI command for managing issues across GitHub and Linear, along with a WritableIntegration interface that extends the existing read-only integration pattern with bidirectional task management (create, update, close, comment). It also adds OpenClaw agent support and exposes task management via the MCP ralph_task tool.

• WritableIntegration interface added to src/integrations/base.ts with createTask, updateTask, closeTask, addComment, and listTasks methods. Both GitHubIntegration and LinearIntegration implement the new interface.
• Smart ID routing in the task command: #123 routes to GitHub, ENG-42 routes to Linear automatically.
• Linear listTasks generates incorrect URLs — constructs https://linear.app/issue/{identifier} instead of querying the actual url field from the GraphQL API (which requires the workspace slug). Other Linear methods correctly query url.
• GitHub updateTask silently ignores status changes — handles labels, assignee, and comment but drops any --status input without error.
• batch-fetcher.ts refactoring is incomplete — Linear tasks now use WritableIntegration, but GitHub tasks still use raw execa calls. The completeTask function mixes integration calls with direct CLI invocation and has a potential empty-string bug on the -R flag.
• OpenClaw agent added alongside Claude Code, Cursor, Codex, and OpenCode with appropriate detection and invocation support.
• DTOs (TaskCreateInput, TaskUpdateInput, TaskReference, TaskCommandOptions) use interface instead of type, which diverges from the project's convention.

Confidence Score: 3/5

• Functional issues in Linear URL generation and GitHub status handling should be addressed before merging, but are unlikely to cause data loss.
• Score of 3 reflects two logic bugs (incorrect Linear URLs, silently ignored GitHub status updates), an incomplete refactoring in batch-fetcher with a potential runtime error on empty project strings, and style convention deviations. The core architecture is sound, agent support and MCP tool are well-implemented, and documentation is thorough.
• Pay close attention to src/integrations/linear/source.ts (incorrect URLs), src/integrations/github/source.ts (missing status handling), and src/loop/batch-fetcher.ts (incomplete refactoring with empty-string bug).

Important Files Changed

Filename	Overview
src/commands/task.ts	New unified task command dispatcher. Clean routing logic with smart ID detection. Minor style issue (interface vs type).
src/integrations/base.ts	Adds WritableIntegration interface and type guard. Well-designed extension of the existing Integration pattern. DTOs should use type per project convention.
src/integrations/github/source.ts	Implements WritableIntegration for GitHub via gh CLI. updateTask silently ignores status changes, which is a functional gap.
src/integrations/linear/source.ts	Implements WritableIntegration for Linear via GraphQL. listTasks constructs incorrect Linear URLs missing the workspace slug. Resolver helpers are well-structured.
src/loop/batch-fetcher.ts	Refactored to use WritableIntegration, but incompletely: GitHub fetch still uses raw execa, and completeTask mixes integration calls with direct CLI calls. Empty-string project bug on label removal.
src/mcp/tools.ts	Adds ralph_task MCP tool with proper Zod schema validation. Duplicates integration-loading logic from task.ts but correctly handles all actions.
src/loop/agents.ts	Adds OpenClaw agent support with appropriate type, detection, and invocation config. Clean addition following existing patterns.

Sequence Diagram

sequenceDiagram
    participant CLI as ralph-starter task
    participant TC as TaskCommand
    participant WI as WritableIntegration
    participant GH as GitHubIntegration
    participant LI as LinearIntegration
    participant GHA as GitHub API (gh CLI)
    participant LIA as Linear GraphQL API

    CLI->>TC: taskCommand(action, args, options)
    TC->>TC: detectSource(id) — #123→GitHub, ENG-42→Linear

    alt list tasks
        TC->>WI: getIntegrations(source)
        WI-->>TC: [GitHub, Linear]
        TC->>GH: listTasks(options)
        GH->>GHA: gh issue list --json
        GHA-->>GH: issues[]
        GH-->>TC: TaskReference[]
        TC->>LI: listTasks(options)
        LI->>LIA: query GetIssues
        LIA-->>LI: issues[]
        LI-->>TC: TaskReference[]
        TC->>CLI: printTaskTable(allTasks)
    end

    alt create/update/close
        TC->>WI: getIntegrations(detected source)
        WI-->>TC: [integration]
        TC->>WI: createTask / updateTask / closeTask
        alt GitHub
            WI->>GHA: gh issue create/edit/close
            GHA-->>WI: result
        else Linear
            WI->>LIA: mutation (IssueCreate/Update)
            LIA-->>WI: result
        end
        WI-->>TC: TaskReference
        TC->>CLI: display result
    end

Loading

_{Last reviewed commit: 190cd26}

[greptile-apps]

_{14 files reviewed, 5 comments}

_{Edit Code Review Agent Settings | Greptile}