feat: add --github-order flag to control issue execution order

README.md

@@ -179,8 +179,11 @@ Titles must be unique.
 ```bash
 ralphy --github owner/repo
 ralphy --github owner/repo --github-label "ready"
+ralphy --github owner/repo --github-label "task" --github-order 2,3,4,5,6
 ```
 
+Use `--github-order` to execute issues in a specific order. Without it, issues are processed in the order returned by the GitHub API (newest first). The flag takes comma-separated issue numbers — only those issues will be executed, in the exact order specified.
+
 ## Parallel Execution
 
 ```bash
@@ -300,6 +303,7 @@ ralphy --parallel --sandbox
 | `--json FILE` | JSON task file |
 | `--github REPO` | use GitHub issues |
 | `--github-label TAG` | filter issues by label |
+| `--github-order 2,3,4` | execute issues in this order |
 | `--sync-issue N` | sync PRD progress to GitHub issue #N |
 | `--model NAME` | override model for any engine |
 | `--sonnet` | shortcut for `--claude --model sonnet` |

cli/src/cli/args.ts

@@ -49,6 +49,7 @@ export function createProgram(): Command {
 		.option("--json <file>", "JSON task file")
 		.option("--github <repo>", "GitHub repo for issues (owner/repo)")
 		.option("--github-label <label>", "Filter GitHub issues by label")
+		.option("--github-order <issues>", "Execute GitHub issues in this order (comma-separated issue numbers, e.g. 2,3,4,5,6)")
 		.option("--sync-issue <number>", "Sync PRD file to GitHub issue body on each iteration")
 		.option("--no-commit", "Don't auto-commit changes")
 		.option("--browser", "Enable browser automation (agent-browser)")
@@ -152,6 +153,9 @@ export function parseArgs(args: string[]): {
 		prdIsFolder,
 		githubRepo: opts.github || "",
 		githubLabel: opts.githubLabel || "",
+		githubOrder: opts.githubOrder
+			? opts.githubOrder.split(",").map((n: string) => Number.parseInt(n.trim(), 10))
+			: undefined,
 		syncIssue: opts.syncIssue ? Number.parseInt(opts.syncIssue, 10) || undefined : undefined,
 		autoCommit: opts.commit !== false,
 		browserEnabled: opts.browser === true ? "true" : opts.browser === false ? "false" : "auto",

cli/src/cli/commands/run.ts

@@ -71,6 +71,7 @@ export async function runLoop(options: RuntimeOptions): Promise<void> {
 		filePath: options.prdFile,
 		repo: options.githubRepo,
 		label: options.githubLabel,
+		order: options.githubOrder,
 	});
 	const taskSource = new CachedTaskSource(innerTaskSource);
 

cli/src/config/types.ts

@@ -101,6 +101,8 @@ export interface RuntimeOptions {
 	githubRepo: string;
 	/** GitHub issue label filter */
 	githubLabel: string;
+	/** Ordered list of GitHub issue numbers to execute in sequence */
+	githubOrder?: number[];
 	/** GitHub issue number to sync PRD with on each iteration */
 	syncIssue?: number;
 	/** Auto-commit changes */

cli/src/tasks/github.ts

@@ -25,9 +25,10 @@ export class GitHubTaskSource implements TaskSource {
 	private owner: string;
 	private repo: string;
 	private label?: string;
+	private order?: number[];
 	private cache: GitHubCache | null = null;
 
-	constructor(repoPath: string, label?: string) {
+	constructor(repoPath: string, label?: string, order?: number[]) {
 		// Parse owner/repo format
 		const [owner, repo] = repoPath.split("/");
 		if (!owner || !repo) {
@@ -37,6 +38,7 @@ export class GitHubTaskSource implements TaskSource {
 		this.owner = owner;
 		this.repo = repo;
 		this.label = label;
+		this.order = order;
 
 		// Use GITHUB_TOKEN from environment
 		this.octokit = new Octokit({
@@ -75,13 +77,28 @@ export class GitHubTaskSource implements TaskSource {
 			per_page: 100,
 		});
 
-		const tasks = issues.map((issue) => ({
+		let tasks = issues.map((issue) => ({
 			id: `${issue.number}:${issue.title}`,
 			title: issue.title,
 			body: issue.body || undefined,
 			completed: false,
 		}));
 
+		// Sort by specified order if provided
+		if (this.order && this.order.length > 0) {
+			const orderMap = new Map(this.order.map((num, idx) => [num, idx]));
+			tasks = tasks
+				.filter((t) => {
+					const issueNum = Number.parseInt(t.id.split(":")[0], 10);
+					return orderMap.has(issueNum);
+				})
+				.sort((a, b) => {
+					const aNum = Number.parseInt(a.id.split(":")[0], 10);
+					const bNum = Number.parseInt(b.id.split(":")[0], 10);
+					return (orderMap.get(aNum) ?? 0) - (orderMap.get(bNum) ?? 0);
+				});
+		}
+
 		// Update cache (preserve closed count if we have it)
 		this.cache = {
 			openIssues: tasks,

cli/src/tasks/index.ts

@@ -21,6 +21,8 @@ interface TaskSourceOptions {
 	repo?: string;
 	/** Label filter for GitHub source */
 	label?: string;
+	/** Ordered list of issue numbers to execute in sequence */
+	order?: number[];
 }
 
 /**
@@ -56,7 +58,7 @@ export function createTaskSource(options: TaskSourceOptions): TaskSource {
 			if (!options.repo) {
 				throw new Error("repo is required for github task source");
 			}
-			return new GitHubTaskSource(options.repo, options.label);
+			return new GitHubTaskSource(options.repo, options.label, options.order);
 
 		default:
 			throw new Error(`Unknown task source type: ${options.type}`);