feat: interactive GitHub issues wizard (ralph-starter github)

README.md

@@ -469,10 +469,11 @@ This creates:
 | `ralph-starter` | Launch interactive wizard |
 | `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 github` | Interactive GitHub issues wizard |
 | `ralph-starter linear` | Interactive Linear issues wizard |
 | `ralph-starter notion` | Interactive Notion pages wizard |
+| `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/sources/github.md

@@ -35,6 +35,28 @@ Required scopes:
 - `repo` (for private repositories)
 - `public_repo` (for public repositories only)
 
+## Interactive Wizard
+
+The easiest way to get started:
+
+```bash
+ralph-starter github
+```
+
+This will:
+1. Check your authentication (prompt for token if needed)
+2. Let you browse repositories and select issues
+3. Multi-select which issues to work on
+4. Start the build loop automatically
+
+You can also pass options:
+
+```bash
+ralph-starter github --commit --pr --validate
+```
+
+If you prefer the CLI flags approach, use `ralph-starter run --from github` (see below).
+
 ## Usage
 
 ```bash

src/cli.ts

@@ -8,6 +8,7 @@ import { checkCommand } from './commands/check.js';
 import { configCommand } from './commands/config.js';
 import { figmaCommand } from './commands/figma.js';
 import { fixCommand } from './commands/fix.js';
+import { githubCommand } from './commands/github.js';
 import { initCommand } from './commands/init.js';
 import { integrationsCommand } from './commands/integrations.js';
 import { linearCommand } from './commands/linear.js';
@@ -189,6 +190,28 @@ program
     });
   });
 
+// ralph-starter github - Build from GitHub issues wizard
+program
+  .command('github')
+  .description('Build from GitHub issues with an interactive wizard')
+  .option('--commit', 'Auto-commit after tasks')
+  .option('--push', 'Push to remote')
+  .option('--pr', 'Create PR when done')
+  .option('--validate', 'Run validation', true)
+  .option('--no-validate', 'Skip validation')
+  .option('--max-iterations <n>', 'Max loop iterations')
+  .option('--agent <name>', 'Agent to use')
+  .action(async (options) => {
+    await githubCommand({
+      commit: options.commit,
+      push: options.push,
+      pr: options.pr,
+      validate: options.validate,
+      maxIterations: options.maxIterations ? parseInt(options.maxIterations, 10) : undefined,
+      agent: options.agent,
+    });
+  });
+
 // ralph-starter linear - Linear issues wizard
 program
   .command('linear')

src/commands/github.ts

@@ -0,0 +1,299 @@
+/**
+ * ralph-starter github — Interactive GitHub issues wizard
+ *
+ * Guides the user through selecting GitHub issues to work on:
+ * 1. Authenticate (gh CLI or token)
+ * 2. Browse repos + issues or paste a URL
+ * 3. Select issues (multi-select)
+ * 4. Delegate to run command
+ */
+
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { askBrowseOrUrl, askForUrl, ensureCredentials } from '../integrations/wizards/shared.js';
+import { type RunCommandOptions, runCommand } from './run.js';
+
+export type GitHubWizardOptions = {
+  commit?: boolean;
+  push?: boolean;
+  pr?: boolean;
+  validate?: boolean;
+  maxIterations?: number;
+  agent?: string;
+};
+
+type GitHubRepo = {
+  name: string;
+  owner: { login: string };
+  description: string;
+};
+
+type GitHubIssue = {
+  number: number;
+  title: string;
+  labels: Array<{ name: string }>;
+};
+
+type GitHubLabel = {
+  name: string;
+};
+
+/** Check if gh CLI is available and authenticated */
+async function isGhCliAvailable(): Promise<boolean> {
+  try {
+    const { execa } = await import('execa');
+    await execa('gh', ['auth', 'status']);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Fetch user's repos via gh CLI */
+async function fetchReposViaCli(limit = 30): Promise<GitHubRepo[]> {
+  const { execa } = await import('execa');
+  const result = await execa('gh', [
+    'repo',
+    'list',
+    '--json',
+    'name,owner,description',
+    '--limit',
+    String(limit),
+    '--sort',
+    'updated',
+  ]);
+  return JSON.parse(result.stdout);
+}
+
+/** Fetch open issues for a repo via gh CLI */
+async function fetchIssuesViaCli(
+  owner: string,
+  repo: string,
+  label?: string,
+  limit = 30
+): Promise<GitHubIssue[]> {
+  const { execa } = await import('execa');
+  const args = [
+    'issue',
+    'list',
+    '-R',
+    `${owner}/${repo}`,
+    '--json',
+    'number,title,labels',
+    '--limit',
+    String(limit),
+    '--state',
+    'open',
+  ];
+  if (label) {
+    args.push('--label', label);
+  }
+  const result = await execa('gh', args);
+  return JSON.parse(result.stdout);
+}
+
+/** Fetch labels for a repo via gh CLI */
+async function fetchLabelsViaCli(owner: string, repo: string): Promise<GitHubLabel[]> {
+  const { execa } = await import('execa');
+  const result = await execa('gh', [
+    'label',
+    'list',
+    '-R',
+    `${owner}/${repo}`,
+    '--json',
+    'name',
+    '--limit',
+    '50',
+  ]);
+  return JSON.parse(result.stdout);
+}
+
+/** Parse a GitHub URL into owner/repo and optional issue number */
+function parseGitHubUrl(url: string): { owner: string; repo: string; issue?: number } | null {
+  // Match: https://github.com/owner/repo/issues/123
+  const issueMatch = url.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)/);
+  if (issueMatch) {
+    return {
+      owner: issueMatch[1],
+      repo: issueMatch[2].replace(/\.git$/, ''),
+      issue: parseInt(issueMatch[3], 10),
+    };
+  }
+
+  // Match: https://github.com/owner/repo
+  const repoMatch = url.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+)/);
+  if (repoMatch) {
+    return {
+      owner: repoMatch[1],
+      repo: repoMatch[2].replace(/\.git$/, '').replace(/\/$/, ''),
+    };
+  }
+
+  return null;
+}
+
+export async function githubCommand(options: GitHubWizardOptions): Promise<void> {
+  console.log();
+  console.log(chalk.cyan.bold('  GitHub Issues'));
+  console.log(chalk.dim('  Build from GitHub issues interactively'));
+  console.log();
+
+  // Step 1: Ensure credentials
+  await ensureCredentials('github', 'GitHub', {
+    credKey: 'token',
+    consoleUrl: 'https://github.com/settings/tokens',
+    envVar: 'GITHUB_TOKEN',
+    checkCliAuth: isGhCliAvailable,
+  });
+
+  // Step 2: Browse or URL?
+  const mode = await askBrowseOrUrl('GitHub');
+
+  if (mode === 'url') {
+    const url = await askForUrl('GitHub', /^https?:\/\/github\.com\//);
+    const parsed = parseGitHubUrl(url);
+    if (!parsed) {
+      console.log(
+        chalk.red('  Could not parse GitHub URL. Expected format: github.com/owner/repo')
+      );
+      return;
+    }
+
+    const runOpts: RunCommandOptions = {
+      from: 'github',
+      project: `${parsed.owner}/${parsed.repo}`,
+      issue: parsed.issue,
+      auto: true,
+      commit: options.commit ?? false,
+      push: options.push,
+      pr: options.pr,
+      validate: options.validate ?? true,
+      maxIterations: options.maxIterations,
+      agent: options.agent,
+    };
+
+    await runCommand(undefined, runOpts);
+    return;
+  }
+
+  // Browse mode
+  // Step 3: Fetch and select repository
+  console.log(chalk.dim('  Fetching your repositories...'));
+  let repos: GitHubRepo[];
+  try {
+    repos = await fetchReposViaCli();
+  } catch (err) {
+    console.log(chalk.red('  Failed to fetch repositories. Check your authentication.'));
+    console.log(chalk.dim(`  Error: ${err instanceof Error ? err.message : String(err)}`));
+    return;
+  }
+
+  if (repos.length === 0) {
+    console.log(chalk.yellow('  No repositories found.'));
+    return;
+  }
+
+  const { selectedRepo } = await inquirer.prompt([
+    {
+      type: 'select',
+      name: 'selectedRepo',
+      message: 'Select a repository:',
+      choices: repos.map((r) => ({
+        name: `${r.owner.login}/${r.name}${r.description ? chalk.dim(` — ${r.description.slice(0, 60)}`) : ''}`,
+        value: `${r.owner.login}/${r.name}`,
+      })),
+    },
+  ]);
+
+  const [owner, repo] = selectedRepo.split('/');
+
+  // Step 4: Optional label filter
+  let selectedLabel: string | undefined;
+  try {
+    const labels = await fetchLabelsViaCli(owner, repo);
+    if (labels.length > 0) {
+      const { labelChoice } = await inquirer.prompt([
+        {
+          type: 'select',
+          name: 'labelChoice',
+          message: 'Filter by label?',
+          choices: [
+            { name: 'All issues (no filter)', value: '__none__' },
+            ...labels.map((l) => ({ name: l.name, value: l.name })),
+          ],
+        },
+      ]);
+      if (labelChoice !== '__none__') {
+        selectedLabel = labelChoice;
+      }
+    }
+  } catch {
+    // Labels fetch failed, skip filter
+  }
+
+  // Step 5: Fetch and select issues
+  console.log(chalk.dim(`  Fetching open issues for ${owner}/${repo}...`));
+  let issues: GitHubIssue[];
+  try {
+    issues = await fetchIssuesViaCli(owner, repo, selectedLabel);
+  } catch (err) {
+    console.log(chalk.red('  Failed to fetch issues.'));
+    console.log(chalk.dim(`  Error: ${err instanceof Error ? err.message : String(err)}`));
+    return;
+  }
+
+  if (issues.length === 0) {
+    console.log(
+      chalk.yellow(
+        `  No open issues found${selectedLabel ? ` with label "${selectedLabel}"` : ''}.`
+      )
+    );
+    return;
+  }
+
+  const { selectedIssues } = await inquirer.prompt([
+    {
+      type: 'checkbox',
+      name: 'selectedIssues',
+      message: 'Select issues to work on:',
+      choices: issues.map((issue) => {
+        const labelTags =
+          issue.labels.length > 0
+            ? ` ${chalk.dim(`[${issue.labels.map((l) => l.name).join(', ')}]`)}`
+            : '';
+        return {
+          name: `#${issue.number} — ${issue.title}${labelTags}`,
+          value: issue.number,
+        };
+      }),
+      validate: (input: number[]) => (input.length > 0 ? true : 'Please select at least one issue'),
+    },
+  ]);
+
+  // Step 6: Run for each selected issue
+  console.log();
+  console.log(
+    chalk.green(
+      `  Starting build for ${selectedIssues.length} issue${selectedIssues.length > 1 ? 's' : ''}...`
+    )
+  );
+  console.log();
+
+  for (const issueNumber of selectedIssues) {
+    const runOpts: RunCommandOptions = {
+      from: 'github',
+      project: `${owner}/${repo}`,
+      issue: issueNumber,
+      label: selectedLabel,
+      auto: true,
+      commit: options.commit ?? false,
+      push: options.push,
+      pr: options.pr,
+      validate: options.validate ?? true,
+      maxIterations: options.maxIterations,
+      agent: options.agent,
+    };
+
+    await runCommand(undefined, runOpts);
+  }
+}