/github-clone

description: Clone GitHub repositories to local workspace. Activate when user wants to clone, add, get, pull down, or fetch a repo/repository. Supports single repo (--repo owner/repo, URL, or SSH) or org-level bulk cloning (--org). Use after init to add repos. Already-cloned repos are automatically skipped.

Clone GitHub Repositories Command

You are a GitHub repository cloning expert. Help users clone repositories from GitHub organizations to their local workspace.

Activation & Parameter Extraction

**Activate this skill** when the user's intent involves any of:

• "clone a repo", "clone this repo", "clone owner/repo"
• "add a repository", "add repo X to the workspace"
• "get a repo", "get me owner/repo", "pull down a repo"
• "fetch repo X", "I need repo X cloned"
• Any message containing a GitHub URL (https://github.com/..., git@github.com:...) with clone intent
• Any `owner/repo` shorthand when the context is about adding repos to the workspace

**Extract `--repo` from natural language**: When the user mentions a specific repository identifier in their prompt, extract it as the `--repo` value. Examples:

• "clone anton-abyzov/vskill" → `--repo "anton-abyzov/vskill"`
• "add https://github.com/foo/bar to the workspace" → `--repo "https://github.com/foo/bar"`
• "get git@github.com:org/project.git" → `--repo "git@github.com:org/project.git"`
• "I need the foo/bar repo" → `--repo "foo/bar"`

**Extract `--org` from natural language**: When the user mentions an organization without a specific repo:

• "clone all repos from mycompany" → `--org "mycompany"`
• "get the acme-corp repos" → `--org "acme-corp"`

**Detect `--dry-run`**: "preview", "what would happen", "show me what would be cloned" → add `--dry-run`

Purpose

This command clones GitHub repositories **after** initial SpecWeave setup (`specweave init`). Use when:

• **Adding a single repo** with `--repo owner/repo` (any URL format supported)
• User skipped cloning during init
• **Resuming interrupted cloning** (already-cloned repos are skipped!)
• Adding repositories from organization
• Selective cloning with pattern filtering
• Retrying after partial failures

CRITICAL: NEVER-STOP BEHAVIOR

**This command NEVER stops on individual repo failures!**

• Each repo failure is logged but cloning continues
• Already-cloned repos are automatically skipped (resume = re-run!)
• Final status: `completed` (all success) or `completed_with_warnings` (some failed)
• Failed repos are listed in result.json for easy retry

Command Syntax

# Clone a single repo (owner/repo shorthand)
sw-github:clone --repo "owner/repo"

# Clone a single repo (full URL)
sw-github:clone --repo "https://github.com/owner/repo"

# Clone a single repo (SSH URL)
sw-github:clone --repo "git@github.com:owner/repo.git"

# Clone a single repo (bare host)
sw-github:clone --repo "github.com/owner/repo"

# Single repo dry-run (validate only)
sw-github:clone --repo "owner/repo" --dry-run

# Interactive mode (prompts for everything)
sw-github:clone

# Clone from specific org
sw-github:clone --org "mycompany"

# With pattern filter (glob)
sw-github:clone --pattern "api-*"

# Regex pattern
sw-github:clone --pattern "regex:^frontend-.*$"

# Dry-run (preview only)
sw-github:clone --dry-run

# Resume/retry - just run again! Already cloned repos are skipped
sw-github:clone

**Flag precedence**: When `--repo` is provided, `--org` and `--pattern` are ignored.

Your Task

When the user runs this command:

Step 0: Single Repo Mode (--repo)

If the user provided `--repo`, bypass org-level cloning entirely:

import { cloneSingleGitHubRepo } from '../../../src/cli/helpers/init/github-repo-cloning.js';
import { readEnvFile, parseEnvFile } from '../../../src/utils/env-file.js';

if (args.repo) {
  // Resolve token
  let pat = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
  if (!pat) {
    const envContent = readEnvFile(projectPath);
    if (envContent) {
      const parsed = parseEnvFile(envContent);
      pat = parsed.GH_TOKEN || parsed.GITHUB_TOKEN;
    }
  }

  const result = await cloneSingleGitHubRepo({
    repoIdentifier: args.repo,
    projectPath,
    pat,
    dryRun: args.dryRun,
  });

  if (result.error) {
    console.log(chalk.red(`❌ ${result.error}`));
  } else if (result.alreadyCloned) {
    console.log(chalk.green(`✅ ${result.owner}/${result.repo} already cloned.`));
  } else if (result.cloned) {
    console.log(chalk.green(`\n✅ Cloning ${result.owner}/${result.repo} started!`));
    console.log(chalk.cyan(`   sw:jobs → Check progress`));
  } else if (args.dryRun) {
    console.log(chalk.cyan(`🔎 DRY RUN: Would clone ${result.owner}/${result.repo}`));
  }

  return; // Skip all remaining steps
}

**Supported input formats for `--repo`:**

• `owner/repo` — shorthand (assumes github.com, uses HTTPS with PAT)
• `github.com/owner/repo` — bare host (uses HTTPS with PAT)
• `https://github.com/owner/repo` — full HTTPS URL (uses HTTPS with PAT)
• `git@github.com:owner/repo.git` — SSH URL (uses SSH key, no PAT needed)

**Token requirement:** HTTPS/shorthand formats require `GH_TOKEN` or `GITHUB_TOKEN`. SSH format uses SSH key authentication and does not require a token.

---

Step 1: Check Prerequisites

import { readEnvFile, parseEnvFile } from '../../../src/utils/env-file.js';
import chalk from 'chalk';

const projectPath = process.cwd();

// Check for GitHub token
const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;

if (!token) {
  // Try .env file
  const envContent = readEnvFile(projectPath);
  if (envContent) {
    const parsed = parseEnvFile(envContent);
    if (parsed.GH_TOKEN || parsed.GITHUB_TOKEN) {
      // Token found in .env
    } else {
      console.log(chalk.red('❌ No GitHub token found.'));
      console.log(chalk.gray('   Set GH_TOKEN or GITHUB_TOKEN environment variable.'));
      console.log(chalk.gray('   Or add to .env file: GH_TOKEN=ghp_xxxx'));
      return;
    }
  } else {
    con