bmad-auto-copilot 1.0.0

package/README.md

@@ -0,0 +1,189 @@
+# bmad-auto-copilot
+
+Automated BMAD sprint development loop using **GitHub Copilot CLI**.
+
+Install into any BMAD project — runs the full story cycle automatically:
+**create-story** → **dev-story** → **code-review** → **auto-commit** → repeat.
+
+## Quick Start
+
+```bash
+# In any BMAD project directory:
+npx bmad-auto-copilot install
+
+# Run the automation:
+npx bmad-auto-copilot run
+
+# Or directly:
+./.scripts/bmad-auto/copilot/bmad-loop.sh
+```
+
+## What It Does
+
+The automation loop continuously:
+
+1. Reads `sprint-status.yaml` to determine story states
+2. Opens a **NEW Copilot CLI session** for each action (fresh context window):
+   - `backlog` stories → **SM agent** runs create-story
+   - `ready-for-dev` stories → **Dev agent** runs dev-story
+   - `review` stories → **Dev agent** runs code-review
+3. Auto-commits code after successful code reviews
+4. Repeats until all stories reach `done`
+
+Each session uses **Claude Opus 4.6** by default (configurable).
+
+## Prerequisites
+
+### 1. GitHub Copilot CLI
+
+```bash
+# macOS
+brew install copilot-cli
+
+# npm (all platforms)
+npm install -g @github/copilot
+
+# Windows
+winget install GitHub.Copilot
+```
+
+Then authenticate: `copilot` → `/login`
+
+### 2. BMAD Method
+
+Your project must have BMAD installed:
+```bash
+npx bmad-method install
+```
+
+Required files:
+- `_bmad/` directory
+- `.github/agents/bmad-agent-bmm-sm.md`
+- `.github/agents/bmad-agent-bmm-dev.md`
+- `sprint-status.yaml` (from sprint planning)
+
+## Commands
+
+### `install`
+
+```bash
+npx bmad-auto-copilot install              # Install in current directory
+npx bmad-auto-copilot install ~/my-project # Install in specific project
+npx bmad-auto-copilot install --force      # Overwrite existing installation
+```
+
+Auto-detects your BMAD output folder from `_bmad/bmm/config.yaml`.
+
+Installs to: `.scripts/bmad-auto/copilot/`
+
+### `run`
+
+```bash
+npx bmad-auto-copilot run                    # Run with defaults
+npx bmad-auto-copilot run --max 100          # Limit to 100 iterations
+npx bmad-auto-copilot run --model gpt-4.1    # Use different model
+npx bmad-auto-copilot run --verbose --dry    # Dry run with debug output
+```
+
+### `status`
+
+```bash
+npx bmad-auto-copilot status     # Check prerequisites and sprint progress
+```
+
+### `uninstall`
+
+```bash
+npx bmad-auto-copilot uninstall  # Remove from current project
+```
+
+## Direct Script Usage
+
+After installation, you can run the scripts directly:
+
+### macOS / Linux
+
+```bash
+./.scripts/bmad-auto/copilot/bmad-loop.sh              # Default
+./.scripts/bmad-auto/copilot/bmad-loop.sh 100           # 100 iterations
+./.scripts/bmad-auto/copilot/bmad-loop.sh 250 --verbose # Verbose
+./.scripts/bmad-auto/copilot/bmad-loop.sh 250 --dry     # Dry run
+```
+
+### Windows
+
+```powershell
+.\.scripts\bmad-auto\copilot\bmad-loop.ps1
+.\.scripts\bmad-auto\copilot\bmad-loop.ps1 -MaxIterations 100 -Verbose
+.\.scripts\bmad-auto\copilot\bmad-loop.ps1 -DryRun
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `COPILOT_MODEL` | `claude-opus-4.6` | AI model for all sessions |
+| `ITERATION_DELAY` | `10` | Seconds between iterations |
+
+### bmad-auto-config.yaml
+
+Auto-generated during install. Contains project-specific paths:
+
+```yaml
+project_root: "/path/to/your/project"
+output_folder: "_bmad-output"
+implementation_artifacts: "_bmad-output/implementation-artifacts"
+```
+
+## How Sessions Work
+
+Each step creates a **completely isolated Copilot CLI session**:
+
+```
+copilot --agent sm  --model claude-opus-4.6 -p <prompt> --allow-all --no-ask-user
+copilot --agent dev --model claude-opus-4.6 -p <prompt> --allow-all --no-ask-user
+```
+
+This ensures:
+- **Fresh context window** per action (no context pollution between steps)
+- **Correct agent persona** (SM for story creation, Dev for implementation/review)
+- **Consistent model** across all sessions
+
+## Installed Files
+
+```
+.scripts/bmad-auto/copilot/
+├── bmad-loop.sh              # macOS/Linux automation script
+├── bmad-loop.ps1             # Windows PowerShell script
+├── bmad-auto-config.yaml     # Project paths (auto-generated, gitignored)
+├── bmad-progress.log         # Execution log (gitignored)
+└── prompts/
+    ├── create-story.md       # SM agent prompt
+    ├── dev-story.md          # Dev agent prompt
+    └── code-review.md        # Dev agent review prompt
+```
+
+## Global Installation
+
+For frequent use across many projects:
+
+```bash
+npm install -g bmad-auto-copilot
+bmad-auto-copilot install
+bmad-auto-copilot run
+```
+
+## Safety Features
+
+- **Max iterations**: Default 250, prevents infinite loops
+- **Session isolation**: Each step = new Copilot CLI session
+- **Git check**: Only commits when there are actual changes
+- **Dry run mode**: Preview without executing
+- **Progress log**: All actions logged to `bmad-progress.log`
+- **Progress tracking**: Shows done/total story percentage
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+
+// ============================================================
+// bmad-auto-copilot CLI
+// ============================================================
+// Usage:
+//   npx bmad-auto-copilot install          Install into current BMAD project
+//   npx bmad-auto-copilot install /path    Install into specified project
+//   npx bmad-auto-copilot uninstall        Remove from current project
+//   npx bmad-auto-copilot status           Show install status
+//   npx bmad-auto-copilot run              Run the automation loop directly
+// ============================================================
+
+const { install } = require('../lib/install');
+const { uninstall } = require('../lib/uninstall');
+const { status } = require('../lib/status');
+const { run } = require('../lib/run');
+
+const HELP = `
+bmad-auto-copilot — Automated BMAD sprint loop via GitHub Copilot CLI
+
+USAGE:
+  npx bmad-auto-copilot <command> [options]
+
+COMMANDS:
+  install [path]      Install automation scripts into a BMAD project
+                      Defaults to current directory if path not given
+  uninstall [path]    Remove automation scripts from a BMAD project
+  status [path]       Check installation status and prerequisites
+  run [path]          Run the automation loop (shortcut for bmad-loop.sh)
+
+OPTIONS:
+  --model <model>     AI model (default: claude-opus-4.6)
+  --max <n>           Max iterations (default: 250)
+  --output <folder>   BMAD output folder (default: auto-detect from config)
+  --force             Overwrite existing installation
+  --help, -h          Show this help
+
+EXAMPLES:
+  npx bmad-auto-copilot install
+  npx bmad-auto-copilot install ~/projects/my-app
+  npx bmad-auto-copilot install --model claude-sonnet-4.5
+  npx bmad-auto-copilot run --max 100
+  npx bmad-auto-copilot status
+  npx bmad-auto-copilot uninstall
+
+PREREQUISITES:
+  - GitHub Copilot CLI: npm install -g @github/copilot
+  - BMAD Method installed in the target project (npx bmad-method install)
+  - Sprint planning completed (sprint-status.yaml exists)
+`;
+
+function parseArgs(args) {
+  const parsed = {
+    command: null,
+    projectPath: null,
+    model: 'claude-opus-4.6',
+    maxIterations: 250,
+    outputFolder: null,
+    force: false,
+    verbose: false,
+    dryRun: false,
+  };
+
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+
+    if (!parsed.command && !arg.startsWith('-')) {
+      parsed.command = arg;
+      i++;
+      continue;
+    }
+
+    if (!parsed.projectPath && !arg.startsWith('-') && parsed.command) {
+      parsed.projectPath = arg;
+      i++;
+      continue;
+    }
+
+    switch (arg) {
+      case '--model':
+        parsed.model = args[++i];
+        break;
+      case '--max':
+        parsed.maxIterations = parseInt(args[++i], 10);
+        break;
+      case '--output':
+        parsed.outputFolder = args[++i];
+        break;
+      case '--force':
+        parsed.force = true;
+        break;
+      case '--verbose':
+      case '-v':
+        parsed.verbose = true;
+        break;
+      case '--dry':
+      case '-d':
+        parsed.dryRun = true;
+        break;
+      case '--help':
+      case '-h':
+        parsed.command = 'help';
+        break;
+    }
+    i++;
+  }
+
+  return parsed;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  switch (args.command) {
+    case 'install':
+      await install(args);
+      break;
+    case 'uninstall':
+      await uninstall(args);
+      break;
+    case 'status':
+      await status(args);
+      break;
+    case 'run':
+      await run(args);
+      break;
+    case 'help':
+    case null:
+    case undefined:
+      console.log(HELP);
+      break;
+    default:
+      console.error(`Unknown command: ${args.command}`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(`\n[ERROR] ${err.message}`);
+  process.exit(1);
+});

package/lib/install.js

@@ -0,0 +1,221 @@
+// ============================================================
+// bmad-auto-copilot — install command
+// ============================================================
+
+const fs = require('fs');
+const path = require('path');
+const {
+  resolveProject,
+  isBmadProject,
+  detectOutputFolder,
+  getInstallPath,
+  isInstalled,
+  colors,
+} = require('./utils');
+
+/**
+ * Recursively copy a directory.
+ */
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Install automation scripts into a BMAD project.
+ */
+async function install(args) {
+  const root = resolveProject(args.projectPath);
+  const installPath = getInstallPath(root);
+
+  console.log('');
+  console.log(
+    colors.cyan('╔══════════════════════════════════════════════════════╗')
+  );
+  console.log(
+    colors.cyan('║  bmad-auto-copilot — Install                        ║')
+  );
+  console.log(
+    colors.cyan('╚══════════════════════════════════════════════════════╝')
+  );
+  console.log('');
+
+  // Validate BMAD project
+  if (!isBmadProject(root)) {
+    console.log(colors.red('[ERROR] Not a BMAD project (no _bmad/ directory)'));
+    console.log('');
+    console.log('Make sure you run this from a BMAD project root, or specify the path:');
+    console.log(colors.gray('  npx bmad-auto-copilot install /path/to/project'));
+    console.log('');
+    console.log('To set up BMAD first:');
+    console.log(colors.gray('  npx bmad-method install'));
+    process.exit(1);
+  }
+
+  console.log(colors.green(`[OK] BMAD project found: ${root}`));
+
+  // Check existing installation
+  if (isInstalled(root) && !args.force) {
+    console.log(
+      colors.yellow(
+        '[WARNING] Already installed. Use --force to overwrite.'
+      )
+    );
+    console.log(colors.gray(`  Installed at: ${installPath}`));
+    process.exit(1);
+  }
+
+  // Auto-detect output folder
+  const detected = detectOutputFolder(root);
+  const outputFolder = args.outputFolder || detected.outputFolder;
+  const implArtifacts = detected.implArtifacts;
+
+  console.log(colors.green(`[OK] Output folder: ${outputFolder}`));
+  console.log(colors.green(`[OK] Impl artifacts: ${implArtifacts}`));
+
+  // Copy template files
+  const templatesDir = path.join(__dirname, '..', 'templates');
+  console.log(colors.gray(`[COPY] Templates → ${installPath}`));
+
+  copyDir(templatesDir, installPath);
+
+  // Generate bmad-auto-config.yaml with correct paths
+  const configContent = `# Auto-generated by bmad-auto-copilot installer
+# Project-specific paths — update if you change your BMAD output folder
+
+project_root: "${root}"
+output_folder: "${outputFolder}"
+implementation_artifacts: "${implArtifacts}"
+`;
+
+  fs.writeFileSync(path.join(installPath, 'bmad-auto-config.yaml'), configContent);
+  console.log(colors.green('[OK] Generated bmad-auto-config.yaml'));
+
+  // Make shell script executable (Unix)
+  const shScript = path.join(installPath, 'bmad-loop.sh');
+  if (fs.existsSync(shScript)) {
+    try {
+      fs.chmodSync(shScript, 0o755);
+      console.log(colors.green('[OK] bmad-loop.sh marked executable'));
+    } catch (e) {
+      // Windows — chmod may not work
+      console.log(colors.gray('[SKIP] chmod not available (Windows)'));
+    }
+  }
+
+  // Check for .github/agents
+  const agentsDir = path.join(root, '.github', 'agents');
+  if (!fs.existsSync(agentsDir)) {
+    console.log(
+      colors.yellow(
+        '[WARNING] .github/agents/ not found — Copilot CLI agents may not work'
+      )
+    );
+    console.log(
+      colors.gray(
+        '  BMAD agent files (bmad-agent-bmm-sm.md, bmad-agent-bmm-dev.md) are needed'
+      )
+    );
+  } else {
+    const smAgent = path.join(agentsDir, 'bmad-agent-bmm-sm.md');
+    const devAgent = path.join(agentsDir, 'bmad-agent-bmm-dev.md');
+    if (fs.existsSync(smAgent) && fs.existsSync(devAgent)) {
+      console.log(colors.green('[OK] BMAD agents found (sm, dev)'));
+    } else {
+      console.log(
+        colors.yellow('[WARNING] Missing agent files in .github/agents/')
+      );
+      if (!fs.existsSync(smAgent))
+        console.log(colors.gray('  Missing: bmad-agent-bmm-sm.md'));
+      if (!fs.existsSync(devAgent))
+        console.log(colors.gray('  Missing: bmad-agent-bmm-dev.md'));
+    }
+  }
+
+  // Check sprint-status.yaml
+  const sprintPath = path.join(root, implArtifacts, 'sprint-status.yaml');
+  if (fs.existsSync(sprintPath)) {
+    console.log(colors.green('[OK] sprint-status.yaml found'));
+  } else {
+    console.log(
+      colors.yellow('[WARNING] sprint-status.yaml not found — run sprint planning first')
+    );
+  }
+
+  // Add to .gitignore
+  addToGitignore(root, installPath);
+
+  // Print summary
+  console.log('');
+  console.log(colors.cyan('═══════════════════════════════════════════'));
+  console.log(colors.bold('  Installation Complete!'));
+  console.log(colors.cyan('═══════════════════════════════════════════'));
+  console.log('');
+  console.log('  Installed to:');
+  console.log(colors.gray(`    ${installPath}`));
+  console.log('');
+  console.log('  Model: ' + colors.bold(args.model));
+  console.log('  Max iterations: ' + colors.bold(String(args.maxIterations)));
+  console.log('');
+  console.log(colors.bold('  Quick Start:'));
+  console.log('');
+
+  if (process.platform === 'win32') {
+    console.log(colors.gray(`    cd ${root}`));
+    console.log(
+      colors.gray('    .\\.scripts\\bmad-auto\\copilot\\bmad-loop.ps1')
+    );
+  } else {
+    console.log(colors.gray(`    cd ${root}`));
+    console.log(
+      colors.gray('    ./.scripts/bmad-auto/copilot/bmad-loop.sh')
+    );
+  }
+
+  console.log('');
+  console.log('  Or run directly:');
+  console.log(colors.gray('    npx bmad-auto-copilot run'));
+  console.log('');
+}
+
+/**
+ * Add log/config to .gitignore if needed  
+ */
+function addToGitignore(root, installPath) {
+  const gitignorePath = path.join(root, '.gitignore');
+  const relPath = path.relative(root, installPath);
+  const entries = [
+    `${relPath}/bmad-progress.log`,
+    `${relPath}/bmad-auto-config.yaml`,
+  ];
+
+  if (!fs.existsSync(gitignorePath)) return;
+
+  let content = fs.readFileSync(gitignorePath, 'utf8');
+  let added = false;
+
+  for (const entry of entries) {
+    if (!content.includes(entry)) {
+      if (!content.endsWith('\n')) content += '\n';
+      content += `${entry}\n`;
+      added = true;
+    }
+  }
+
+  if (added) {
+    fs.writeFileSync(gitignorePath, content);
+    console.log(colors.green('[OK] Updated .gitignore (log + config)'));
+  }
+}
+
+module.exports = { install };

package/lib/run.js

@@ -0,0 +1,79 @@
+// ============================================================
+// bmad-auto-copilot — run command
+// ============================================================
+
+const path = require('path');
+const { execSync, spawn } = require('child_process');
+const {
+  resolveProject,
+  getInstallPath,
+  isInstalled,
+  colors,
+} = require('./utils');
+
+/**
+ * Run the automation loop directly.
+ */
+async function run(args) {
+  const root = resolveProject(args.projectPath);
+  const installPath = getInstallPath(root);
+
+  if (!isInstalled(root)) {
+    console.log(colors.red('[ERROR] Not installed. Run first:'));
+    console.log(colors.gray('  npx bmad-auto-copilot install'));
+    process.exit(1);
+  }
+
+  const isWindows = process.platform === 'win32';
+  const scriptArgs = [];
+
+  if (isWindows) {
+    const script = path.join(installPath, 'bmad-loop.ps1');
+    scriptArgs.push(
+      'powershell',
+      [
+        '-ExecutionPolicy',
+        'Bypass',
+        '-File',
+        script,
+        '-MaxIterations',
+        String(args.maxIterations),
+        ...(args.verbose ? ['-Verbose'] : []),
+        ...(args.dryRun ? ['-DryRun'] : []),
+        ...(args.model !== 'claude-opus-4.6'
+          ? ['-Model', args.model]
+          : []),
+      ]
+    );
+  } else {
+    const script = path.join(installPath, 'bmad-loop.sh');
+    scriptArgs.push(script, [
+      String(args.maxIterations),
+      ...(args.verbose ? ['--verbose'] : []),
+      ...(args.dryRun ? ['--dry'] : []),
+    ]);
+  }
+
+  console.log(colors.cyan('[RUN] Starting BMAD auto loop...'));
+  console.log(colors.gray(`  Script: ${scriptArgs[0]}`));
+  console.log('');
+
+  // Set model env var
+  const env = { ...process.env };
+  if (args.model) {
+    env.COPILOT_MODEL = args.model;
+  }
+
+  // Spawn the loop script as a child process with inherited stdio
+  const child = spawn(scriptArgs[0], scriptArgs[1], {
+    cwd: root,
+    stdio: 'inherit',
+    env,
+  });
+
+  child.on('exit', (code) => {
+    process.exit(code || 0);
+  });
+}
+
+module.exports = { run };