feat: unified task management across GitHub & Linear

README.md

@@ -453,6 +453,7 @@ This creates:
 | `ralph-starter run [task]` | Run an autonomous coding loop |
 | `ralph-starter fix [task]` | Fix build errors, lint issues, or design problems |
 | `ralph-starter auto` | Batch-process issues from GitHub/Linear |
+| `ralph-starter task <action>` | Manage tasks across GitHub and Linear (list, create, update, close, comment) |
 | `ralph-starter integrations <action>` | Manage integrations (list, help, test, fetch) |
 | `ralph-starter plan` | Create implementation plan from specs |
 | `ralph-starter init` | Initialize Ralph Playbook in a project |

docs/docs/cli/task.md

@@ -0,0 +1,181 @@
+---
+sidebar_position: 3
+title: task
+description: Manage tasks across GitHub and Linear
+keywords: [cli, task, command, github, linear, issues, unified, assignee]
+---
+
+# ralph-starter task
+
+Unified task management across GitHub and Linear. Issues stay where they are -- ralph-starter detects the platform from the ID format and routes operations accordingly.
+
+## Synopsis
+
+```bash
+ralph-starter task list [options]
+ralph-starter task create --title "..." [options]
+ralph-starter task update <id> [options]
+ralph-starter task close <id> [options]
+ralph-starter task comment <id> "message" [options]
+```
+
+## Description
+
+The `task` command provides a single interface for managing issues on both GitHub and Linear. Instead of switching between `gh issue` and Linear's UI, you can:
+
+- **List** tasks from both platforms in a unified table
+- **Create** issues on either platform
+- **Update** status, priority, or assignee
+- **Close** issues with optional comments
+- **Comment** on issues
+
+### Smart ID Detection
+
+ralph-starter automatically detects which platform an issue belongs to based on the ID format:
+
+| Format | Platform | Example |
+|--------|----------|---------|
+| `#123` or `123` | GitHub | `ralph-starter task close #42` |
+| `TEAM-123` | Linear | `ralph-starter task update ENG-42 --status "In Progress"` |
+
+You can always override detection with `--source github` or `--source linear`.
+
+## Actions
+
+### `task list`
+
+List tasks from all configured integrations.
+
+```bash
+# List from all sources
+ralph-starter task list
+
+# List from GitHub only
+ralph-starter task list --source github --project owner/repo
+
+# List from Linear only
+ralph-starter task list --source linear
+
+# Filter by label and status
+ralph-starter task list --label "bug" --status "open" --limit 10
+```
+
+### `task create`
+
+Create a new issue on GitHub or Linear.
+
+```bash
+# Create on GitHub (default)
+ralph-starter task create --title "Add dark mode" --project owner/repo
+
+# Create on Linear
+ralph-starter task create --title "Add dark mode" --source linear --priority P1
+
+# Create with assignee and labels
+ralph-starter task create --title "Fix auth bug" --source github \
+  --project owner/repo --assignee octocat --label "bug,urgent"
+```
+
+### `task update`
+
+Update an existing issue.
+
+```bash
+# Update status on Linear (auto-detected from ID)
+ralph-starter task update ENG-42 --status "In Progress"
+
+# Assign a task
+ralph-starter task update ENG-42 --assignee ruben
+
+# Update priority
+ralph-starter task update ENG-42 --priority P0
+
+# Update a GitHub issue
+ralph-starter task update #123 --assignee octocat --project owner/repo
+```
+
+### `task close`
+
+Close an issue with an optional comment.
+
+```bash
+# Close a Linear issue
+ralph-starter task close ENG-42
+
+# Close with a comment
+ralph-starter task close #123 --comment "Fixed in PR #456" --project owner/repo
+```
+
+### `task comment`
+
+Add a comment to an issue.
+
+```bash
+ralph-starter task comment ENG-42 "Working on this now"
+ralph-starter task comment #123 "Needs design review" --project owner/repo
+```
+
+## Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--source <source>` | Filter by source: `github`, `linear`, or `all` | `all` (list) / `github` (create) |
+| `--project <name>` | Project filter (`owner/repo` for GitHub, team name for Linear) | - |
+| `--label <name>` | Filter by label or set labels (comma-separated) | - |
+| `--status <status>` | Filter by status or set status on update | - |
+| `--limit <n>` | Max tasks to fetch | `50` |
+| `--title <title>` | Task title (for create) | - |
+| `--body <body>` | Task description (for create) | - |
+| `--priority <p>` | Priority: `P0`, `P1`, `P2`, `P3` | - |
+| `--assignee <name>` | Assign to team member (GitHub username or Linear display name) | - |
+| `--comment <text>` | Comment text (for close/update) | - |
+
+## Assignee Resolution
+
+### GitHub
+
+Pass a GitHub username directly:
+
+```bash
+ralph-starter task update #123 --assignee octocat --project owner/repo
+```
+
+### Linear
+
+ralph-starter resolves display names, full names, and email prefixes to Linear user IDs:
+
+```bash
+# Match by display name
+ralph-starter task update ENG-42 --assignee "Ruben"
+
+# Match by email prefix
+ralph-starter task update ENG-42 --assignee "ruben"
+```
+
+Matching is case-insensitive. If no match is found, ralph-starter shows available team members.
+
+## Prerequisites
+
+At least one integration must be configured:
+
+```bash
+# GitHub (via GitHub CLI)
+gh auth login
+
+# Linear (via API key)
+ralph-starter config set linear.apiKey lin_api_xxxxxxxxxxxx
+```
+
+Check integration status:
+
+```bash
+ralph-starter integrations list
+```
+
+## See Also
+
+- [`ralph-starter auto`](auto.md) -- Batch-process tasks autonomously
+- [`ralph-starter integrations`](integrations.md) -- Manage integrations
+- [`ralph-starter auth`](auth.md) -- Authenticate with services
+- [GitHub Source](../sources/github.md) -- GitHub integration details
+- [Linear Source](../sources/linear.md) -- Linear integration details

docs/docs/sources/github.md

@@ -175,6 +175,26 @@ Verify your authentication:
 ralph-starter source test github
 ```
 
+## Task Management
+
+Beyond fetching specs, you can create, update, and close GitHub issues directly from the CLI:
+
+```bash
+# List open issues
+ralph-starter task list --source github --project owner/repo
+
+# Create an issue
+ralph-starter task create --title "Add dark mode" --project owner/repo --assignee octocat
+
+# Update an issue
+ralph-starter task update #42 --assignee octocat --project owner/repo
+
+# Close an issue
+ralph-starter task close #42 --comment "Fixed in PR #100" --project owner/repo
+```
+
+See [`ralph-starter task`](/docs/cli/task) for full details.
+
 ## Tips
 
 1. **Use labels effectively** - Create a "ready-to-build" or "ralph" label for issues that are well-specified

docs/docs/sources/linear.md

@@ -136,6 +136,31 @@ Create these labels in Linear:
 2. Add comments with build progress
 3. Close issues when build succeeds
 
+## Task Management
+
+Beyond fetching specs, you can create, update, close, and assign Linear issues from the CLI:
+
+```bash
+# List issues from Linear
+ralph-starter task list --source linear
+
+# Create an issue on a specific team
+ralph-starter task create --title "Add dark mode" --source linear --priority P1
+
+# Assign an issue (resolves display name to user ID automatically)
+ralph-starter task update ENG-42 --assignee ruben
+
+# Update status
+ralph-starter task update ENG-42 --status "In Progress"
+
+# Close an issue
+ralph-starter task close ENG-42 --comment "Shipped in v1.2"
+```
+
+Assignee resolution is case-insensitive and matches against display name, full name, and email prefix. If no match is found, ralph-starter shows available team members.
+
+See [`ralph-starter task`](/docs/cli/task) for full details.
+
 ## Tips
 
 1. **Write detailed issues** - Linear's rich markdown support is perfect for detailed specs

docs/sidebars.ts

@@ -46,6 +46,7 @@ const sidebars: SidebarsConfig = {
         'cli/config',
         'cli/source',
         'cli/auto',
+        'cli/task',
         'cli/auth',
         'cli/setup',
         'cli/check',

src/cli.ts

@@ -16,6 +16,7 @@ import { runCommand } from './commands/run.js';
 import { setupCommand } from './commands/setup.js';
 import { skillCommand } from './commands/skill.js';
 import { sourceCommand } from './commands/source.js';
+import { taskCommand } from './commands/task.js';
 import { templateCommand } from './commands/template.js';
 import { startMcpServer } from './mcp/server.js';
 import { formatPresetsHelp, getPresetNames } from './presets/index.js';
@@ -61,7 +62,7 @@ program
   .option('--docker', 'Run in Docker sandbox (coming soon)')
   .option('--prd <file>', 'Read tasks from a PRD markdown file')
   .option('--max-iterations <n>', 'Maximum loop iterations (auto-calculated if not specified)')
-  .option('--agent <name>', 'Specify agent (claude-code, cursor, codex, opencode)')
+  .option('--agent <name>', 'Specify agent (claude-code, cursor, codex, opencode, openclaw)')
   .option('--from <source>', 'Fetch spec from source (file, url, github, todoist, linear, notion)')
   .option('--project <name>', 'Project/repo name for --from integrations')
   .option('--label <name>', 'Label filter for --from integrations')
@@ -275,6 +276,24 @@ program
     });
   });
 
+// ralph-starter task - Manage tasks across GitHub and Linear
+program
+  .command('task [action] [args...]')
+  .description('Manage tasks across GitHub and Linear (list, create, update, close, comment)')
+  .option('--source <source>', 'Source: github, linear, or all (default: all)')
+  .option('--project <name>', 'Project filter (owner/repo for GitHub, team name for Linear)')
+  .option('--label <name>', 'Filter by label')
+  .option('--status <status>', 'Filter by status or set status on update')
+  .option('--limit <n>', 'Max tasks to fetch (default: 50)', '50')
+  .option('--title <title>', 'Task title (for create)')
+  .option('--body <body>', 'Task description (for create)')
+  .option('--priority <p>', 'Priority: P0, P1, P2, P3')
+  .option('--comment <text>', 'Comment text (for close/update)')
+  .option('--assignee <name>', 'Assign to team member (GitHub username or Linear display name)')
+  .action(async (action: string | undefined, args: string[], options) => {
+    await taskCommand(action, args, options);
+  });
+
 // ralph-starter pause - Pause a running session
 program
   .command('pause')
@@ -324,7 +343,7 @@ program
   .option('--pr', 'Create a pull request when done')
   .option('--validate', 'Run tests/lint/build after each iteration')
   .option('--max-iterations <n>', 'Maximum loop iterations')
-  .option('--agent <name>', 'Specify agent (claude-code, cursor, codex, opencode)')
+  .option('--agent <name>', 'Specify agent (claude-code, cursor, codex, opencode, openclaw)')
   .action(async (action: string | undefined, args: string[], options) => {
     await templateCommand(action, args, options);
   });