agile-context-engineering 0.1.0

package/bin/install.js

@@ -0,0 +1,462 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const os = require('os');
+
+const VERSION = '0.1.0';
+
+// ANSI color codes
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  magenta: '\x1b[35m',
+};
+
+// Runtime configurations
+const RUNTIMES = {
+  claude: {
+    name: 'Claude Code',
+    description: "Anthropic's Claude Code CLI",
+    globalDir: '.claude',
+    commandsDir: 'commands',
+    agentsDir: 'agents',
+    supportsLocal: true,
+  },
+  opencode: {
+    name: 'OpenCode',
+    description: 'OpenCode AI coding assistant',
+    globalDir: '.opencode',
+    commandsDir: 'commands',
+    agentsDir: 'agents',
+    supportsLocal: true,
+  },
+  gemini: {
+    name: 'Gemini CLI',
+    description: "Google's Gemini CLI",
+    globalDir: '.gemini',
+    commandsDir: 'commands',
+    agentsDir: 'agents',
+    supportsLocal: true,
+  },
+  codex: {
+    name: 'Codex CLI',
+    description: "OpenAI's Codex CLI",
+    globalDir: '.codex',
+    skillsDir: 'skills',
+    supportsLocal: false, // Codex only supports global installation
+  },
+};
+
+function log(message, color = '') {
+  console.log(`${color}${message}${colors.reset}`);
+}
+
+function banner() {
+  log(`
+  ●●●   ●●●  ●●●●●
+ ●   ●  ●    ●
+ ●●●●●  ●    ●●●●
+ ●   ●  ●    ●
+ ●   ●  ●●●  ●●●●●
+  `, colors.cyan);
+  log(`  Agile Context Engineering v${VERSION}`, colors.bright);
+  log(`  Spec-driven development for AI coding assistants\n`, colors.dim);
+}
+
+// Parse command line arguments
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const flags = {
+    claude: args.includes('--claude'),
+    opencode: args.includes('--opencode'),
+    gemini: args.includes('--gemini'),
+    codex: args.includes('--codex'),
+    all: args.includes('--all'),
+    global: args.includes('--global'),
+    local: args.includes('--local'),
+    help: args.includes('--help') || args.includes('-h'),
+    version: args.includes('--version') || args.includes('-v'),
+  };
+  return flags;
+}
+
+function showHelp() {
+  log(`
+Usage: npx agile-context-engineering [options]
+
+Options:
+  --claude      Install for Claude Code only
+  --opencode    Install for OpenCode only
+  --gemini      Install for Gemini CLI only
+  --codex       Install for Codex CLI only (global only)
+  --all         Install for all supported runtimes
+  --global      Install globally (~/.claude, ~/.gemini, etc.)
+  --local       Install locally (.claude, .opencode, etc.)
+  -h, --help    Show this help message
+  -v, --version Show version number
+
+Examples:
+  npx agile-context-engineering                    # Interactive installation
+  npx agile-context-engineering --claude --local   # Claude Code, local install
+  npx agile-context-engineering --all --global     # All runtimes, global install
+  npx agile-context-engineering --codex            # Codex CLI (always global)
+`);
+}
+
+// Create readline interface for interactive prompts
+function createPrompt() {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+}
+
+async function ask(rl, question, options) {
+  return new Promise((resolve) => {
+    log(question, colors.cyan);
+    options.forEach((opt, i) => {
+      log(`  ${i + 1}. ${opt.label}`, opt.description ? colors.bright : '');
+      if (opt.description) {
+        log(`     ${opt.description}`, colors.dim);
+      }
+    });
+    rl.question(`\n${colors.yellow}Enter choice (1-${options.length}): ${colors.reset}`, (answer) => {
+      const index = parseInt(answer) - 1;
+      if (index >= 0 && index < options.length) {
+        resolve(options[index].value);
+      } else {
+        log('Invalid choice, using default.', colors.red);
+        resolve(options[0].value);
+      }
+    });
+  });
+}
+
+async function askMultiple(rl, question, options) {
+  return new Promise((resolve) => {
+    log(question, colors.cyan);
+    options.forEach((opt, i) => {
+      log(`  ${i + 1}. ${opt.label}`, colors.bright);
+      if (opt.description) {
+        log(`     ${opt.description}`, colors.dim);
+      }
+    });
+    log(`\n  Enter numbers separated by commas (e.g., 1,2,3) or 'all'`, colors.dim);
+    rl.question(`\n${colors.yellow}Your choice: ${colors.reset}`, (answer) => {
+      if (answer.toLowerCase() === 'all') {
+        resolve(options.map(o => o.value));
+      } else {
+        const indices = answer.split(',').map(s => parseInt(s.trim()) - 1);
+        const selected = indices
+          .filter(i => i >= 0 && i < options.length)
+          .map(i => options[i].value);
+        if (selected.length === 0) {
+          log('Invalid choice, using first option.', colors.red);
+          resolve([options[0].value]);
+        } else {
+          resolve(selected);
+        }
+      }
+    });
+  });
+}
+
+// Get installation paths based on runtime and scope
+function getBasePath(runtime, scope) {
+  const home = os.homedir();
+  const cwd = process.cwd();
+  const config = RUNTIMES[runtime];
+
+  if (scope === 'local' && !config.supportsLocal) {
+    // Fallback to global for runtimes that don't support local
+    return path.join(home, config.globalDir);
+  }
+
+  return scope === 'global'
+    ? path.join(home, config.globalDir)
+    : path.join(cwd, config.globalDir);
+}
+
+// Copy directory recursively
+function copyDir(src, dest) {
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    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 for Claude Code, OpenCode, or Gemini (similar structure)
+function installStandard(runtime, scope, packageDir) {
+  const config = RUNTIMES[runtime];
+  const basePath = getBasePath(runtime, scope);
+  const commandsPath = path.join(basePath, config.commandsDir);
+  const agentsPath = path.join(basePath, config.agentsDir);
+
+  // Source directories
+  const srcCommands = path.join(packageDir, 'commands');
+  const srcAgents = path.join(packageDir, 'agents');
+
+  log(`\nInstalling ACE for ${config.name}...`, colors.cyan);
+  log(`  Target: ${basePath}`, colors.dim);
+
+  // Create directories
+  fs.mkdirSync(commandsPath, { recursive: true });
+  fs.mkdirSync(agentsPath, { recursive: true });
+
+  // Copy commands
+  if (fs.existsSync(srcCommands)) {
+    copyDir(srcCommands, commandsPath);
+    log(`  ✓ Commands installed`, colors.green);
+  }
+
+  // Copy agents
+  if (fs.existsSync(srcAgents)) {
+    copyDir(srcAgents, agentsPath);
+    log(`  ✓ Agents installed`, colors.green);
+  }
+
+  return basePath;
+}
+
+// Install for Codex CLI (different structure - uses skills with SKILL.md)
+function installCodex(packageDir) {
+  const config = RUNTIMES.codex;
+  const home = os.homedir();
+  const basePath = path.join(home, config.globalDir);
+  const skillsPath = path.join(basePath, config.skillsDir, 'ace');
+
+  // Source directories
+  const srcCommands = path.join(packageDir, 'commands');
+  const srcAgents = path.join(packageDir, 'agents');
+
+  log(`\nInstalling ACE for ${config.name}...`, colors.cyan);
+  log(`  Target: ${skillsPath}`, colors.dim);
+
+  // Create ace skill directory
+  fs.mkdirSync(skillsPath, { recursive: true });
+
+  // For Codex, we need to create a combined SKILL.md file
+  // or individual skill directories for each command
+
+  // Create main ACE skill file
+  const skillContent = generateCodexSkill(srcCommands, srcAgents);
+  fs.writeFileSync(path.join(skillsPath, 'SKILL.md'), skillContent);
+  log(`  ✓ Main skill installed`, colors.green);
+
+  // Create individual command skills
+  if (fs.existsSync(srcCommands)) {
+    const commands = fs.readdirSync(srcCommands).filter(f => f.endsWith('.md'));
+    for (const cmd of commands) {
+      const cmdName = cmd.replace('.md', '').replace('ace-', '');
+      const cmdSkillPath = path.join(basePath, config.skillsDir, `ace-${cmdName}`);
+      fs.mkdirSync(cmdSkillPath, { recursive: true });
+      fs.copyFileSync(
+        path.join(srcCommands, cmd),
+        path.join(cmdSkillPath, 'SKILL.md')
+      );
+    }
+    log(`  ✓ Command skills installed`, colors.green);
+  }
+
+  return basePath;
+}
+
+// Generate a combined skill file for Codex
+function generateCodexSkill(srcCommands, srcAgents) {
+  let content = `# ACE - Agile Context Engineering
+
+A spec-driven development system with Agile workflows.
+
+## Description
+
+ACE (Agile Context Engineering) helps you plan and execute projects using Agile methodology with epics, features, stories, and tasks.
+
+## Commands
+
+The following ACE commands are available:
+
+- \`/ace:init\` - Initialize ACE in your project
+- \`/ace:plan-project\` - Plan your project with epics and features
+- \`/ace:plan-epic\` - Break an epic into features
+- \`/ace:plan-feature\` - Break a feature into stories
+- \`/ace:plan-story\` - Create a new user story
+- \`/ace:refine-story\` - Prepare a story for execution
+- \`/ace:execute-story\` - Execute a story with atomic commits
+- \`/ace:verify-story\` - Verify a completed story
+
+## Workflow
+
+\`\`\`
+Epic → Feature → Story → Tasks
+  ↓       ↓        ↓       ↓
+Plan → Refine → Execute → Verify
+\`\`\`
+
+## Agile Hierarchy
+
+- **Epic**: Large body of work (1-3 months)
+- **Feature**: Deliverable functionality (1-2 sprints)
+- **Story**: User-facing work item (1-3 days)
+- **Task**: Atomic implementation step (30 min - 2 hours)
+
+## Getting Started
+
+1. Run \`/ace:init\` to initialize ACE in your project
+2. Run \`/ace:plan-project\` to start planning
+3. Break down work: epic → feature → story
+4. Execute and verify stories
+
+Each command has its own skill file with detailed instructions.
+`;
+
+  return content;
+}
+
+// Install commands and agents for a specific runtime
+function installForRuntime(runtime, scope, packageDir) {
+  if (runtime === 'codex') {
+    return installCodex(packageDir);
+  }
+  return installStandard(runtime, scope, packageDir);
+}
+
+// Main installation logic
+async function main() {
+  const flags = parseArgs();
+
+  if (flags.version) {
+    log(`ACE v${VERSION}`);
+    process.exit(0);
+  }
+
+  if (flags.help) {
+    banner();
+    showHelp();
+    process.exit(0);
+  }
+
+  banner();
+
+  // Determine package directory (where this script is located)
+  const packageDir = path.join(__dirname, '..');
+
+  let runtimes = [];
+  let scope = null;
+
+  // Check if non-interactive mode
+  const hasRuntimeFlag = flags.claude || flags.opencode || flags.gemini || flags.codex || flags.all;
+  const hasScopeFlag = flags.global || flags.local;
+  const isInteractive = !hasRuntimeFlag && !hasScopeFlag;
+
+  if (isInteractive) {
+    const rl = createPrompt();
+
+    // Ask for runtime selection (multiple choice)
+    runtimes = await askMultiple(rl, '\nWhich runtime(s) do you want to install ACE for?', [
+      { label: 'Claude Code', value: 'claude', description: "Anthropic's Claude Code CLI" },
+      { label: 'OpenCode', value: 'opencode', description: 'OpenCode AI coding assistant' },
+      { label: 'Gemini CLI', value: 'gemini', description: "Google's Gemini CLI" },
+      { label: 'Codex CLI', value: 'codex', description: "OpenAI's Codex CLI (global only)" },
+    ]);
+
+    // Check if any selected runtime doesn't support local
+    const hasGlobalOnly = runtimes.some(r => !RUNTIMES[r].supportsLocal);
+
+    if (hasGlobalOnly && runtimes.length === 1 && runtimes[0] === 'codex') {
+      // Only Codex selected, skip scope question
+      scope = 'global';
+      log(`\nNote: Codex CLI only supports global installation.`, colors.yellow);
+    } else {
+      // Ask for scope
+      scope = await ask(rl, '\nWhere should ACE be installed?', [
+        { label: 'Global', value: 'global', description: 'Install in home directory (~/.claude, ~/.gemini, etc.)' },
+        { label: 'Local', value: 'local', description: 'Install in current project (.claude, .opencode, etc.)' },
+      ]);
+
+      if (scope === 'local' && hasGlobalOnly) {
+        log(`\nNote: Codex CLI will be installed globally (doesn't support local).`, colors.yellow);
+      }
+    }
+
+    rl.close();
+  } else {
+    // Non-interactive mode
+    if (flags.all) {
+      runtimes = ['claude', 'opencode', 'gemini', 'codex'];
+    } else {
+      if (flags.claude) runtimes.push('claude');
+      if (flags.opencode) runtimes.push('opencode');
+      if (flags.gemini) runtimes.push('gemini');
+      if (flags.codex) runtimes.push('codex');
+    }
+
+    if (runtimes.length === 0) {
+      log('Error: No runtime specified. Use --claude, --opencode, --gemini, --codex, or --all', colors.red);
+      process.exit(1);
+    }
+
+    if (flags.global && flags.local) {
+      log('Error: Cannot specify both --global and --local', colors.red);
+      process.exit(1);
+    }
+
+    scope = flags.local ? 'local' : 'global';
+  }
+
+  // Perform installation
+  const installedPaths = [];
+
+  for (const runtime of runtimes) {
+    const installedPath = installForRuntime(runtime, scope, packageDir);
+    installedPaths.push({ runtime, name: RUNTIMES[runtime].name, path: installedPath });
+  }
+
+  // Show success message
+  log(`\n${'═'.repeat(50)}`, colors.green);
+  log(`  ACE installed successfully!`, colors.green + colors.bright);
+  log(`${'═'.repeat(50)}`, colors.green);
+
+  log(`\nInstalled locations:`, colors.cyan);
+  for (const { name, path: p } of installedPaths) {
+    log(`  ${name}: ${p}`, colors.dim);
+  }
+
+  log(`\nAvailable commands:`, colors.cyan);
+  log(`  /ace:init          Initialize ACE in your project`, colors.dim);
+  log(`  /ace:plan-project  Plan your project with epics and features`, colors.dim);
+  log(`  /ace:plan-epic     Plan an epic with features and stories`, colors.dim);
+  log(`  /ace:plan-feature  Plan a feature with stories`, colors.dim);
+  log(`  /ace:plan-story    Plan a story with tasks`, colors.dim);
+  log(`  /ace:refine-story  Refine a story for execution`, colors.dim);
+  log(`  /ace:execute-story Execute a story`, colors.dim);
+  log(`  /ace:verify-story  Verify a completed story`, colors.dim);
+
+  log(`\nGet started:`, colors.cyan);
+  log(`  1. Navigate to your project directory`, colors.dim);
+  log(`  2. Run /ace:init to initialize ACE`, colors.dim);
+  log(`  3. Run /ace:plan-project to start planning\n`, colors.dim);
+}
+
+main().catch((err) => {
+  log(`Error: ${err.message}`, colors.red);
+  process.exit(1);
+});

package/commands/ace-execute-story.md

@@ -0,0 +1,114 @@
+# /ace:execute-story - Execute a Story
+
+Execute a refined story by completing all tasks with atomic commits.
+
+## Usage
+
+```
+/ace:execute-story <story-id>
+/ace:execute-story E1-F1-S1
+```
+
+### Arguments
+
+- `story-id` - The story identifier to execute
+
+## Behavior
+
+This command executes a story by:
+- Working through each task in sequence
+- Making atomic commits per task
+- Updating task status as work progresses
+- Running tests after each significant change
+
+## Instructions for Claude
+
+<ace-execute-story>
+
+### Prerequisites
+
+1. Verify ACE is initialized
+2. Verify story is refined (has tasks)
+3. Check for blockers
+4. Ensure clean git state
+
+### Execution Process
+
+1. **Pre-flight Check**
+   ```bash
+   git status  # Ensure clean working tree
+   ```
+
+2. **For Each Task:**
+
+   a. **Read task details**
+      - Understand what to do
+      - Know the done criteria
+
+   b. **Implement the task**
+      - Make focused changes
+      - Follow existing code patterns
+      - Write/update tests as needed
+
+   c. **Verify done criteria**
+      - Run relevant tests
+      - Check acceptance criteria
+
+   d. **Commit atomically**
+      ```bash
+      git add <specific-files>
+      git commit -m "feat(E1-F1-S1-T1): <task description>"
+      ```
+
+   e. **Update task status**
+      - Mark task as completed in story file
+
+3. **After All Tasks:**
+   - Run full test suite
+   - Update story status to "Done"
+   - Update STATE.md
+
+### Commit Message Format
+
+```
+<type>(<story-task>): <description>
+
+[optional body]
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+Types:
+- `feat` - New feature
+- `fix` - Bug fix
+- `refactor` - Code refactoring
+- `test` - Adding tests
+- `docs` - Documentation
+- `chore` - Maintenance
+
+### Error Handling
+
+If a task fails:
+1. Document the issue
+2. Ask user for guidance
+3. Do NOT proceed to next task until resolved
+4. Consider creating a blocker in STATE.md
+
+### Output
+
+```
+✓ Story E1-F1-S1 executed!
+
+Completed Tasks:
+  ✓ T1: <description> (commit abc123)
+  ✓ T2: <description> (commit def456)
+  ✓ T3: <description> (commit ghi789)
+
+Tests: All passing
+
+Next steps:
+  - Run /ace:verify-story E1-F1-S1
+  - Or continue with next story
+```
+
+</ace-execute-story>