speci 0.1.0 → 0.3.0

package/README.md

@@ -81,7 +81,7 @@ speci init [options]
 
 **Options:**
 
-- `-y, --yes` - Accept all defaults without prompts
+- `-u, --update-agents` - Update agent files even if they already exist
 - `-v, --verbose` - Show detailed output
 
 **Creates:**
@@ -89,23 +89,24 @@ speci init [options]
 - `speci.config.json` - Configuration file
 - `docs/tasks/` - Task definition directory
 - `.speci-logs/` - Log file directory
+- `.github/copilot/agents/` - Copilot agent definitions
 
 **Examples:**
 
 ```bash
-# Interactive setup wizard
+# Initialize with defaults
 speci init
 
-# Quick setup with defaults
-speci init --yes
+# Update agent files to latest version
+speci init --update-agents
 
 # Short alias version
-speci i -y
+speci i
 ```
 
 ### `speci plan` (alias: `p`)
 
-Generate an implementation plan interactively using Copilot.
+Generate an implementation plan using Copilot with an initial prompt or input files.
 
 **Usage:**
 
@@ -115,21 +116,31 @@ speci plan [options]
 
 **Options:**
 
-- `-a, --agent <path>` - Use custom agent file
+- `-p, --prompt <text>` - Initial prompt describing what to plan
+- `-i, --input <files...>` - Input files for context (design docs, specs)
+- `-a, --agent <filename>` - Use custom agent file from `.github/copilot/agents/`
 - `-o, --output <path>` - Save plan to specific file
 - `-v, --verbose` - Show detailed output
 
+**Note:** At least `--prompt` or `--input` must be provided.
+
 **Examples:**
 
 ```bash
-# Start interactive planning session
-speci plan
+# Plan with an initial prompt
+speci plan -p "Build a REST API for user authentication"
+
+# Plan using a design doc as context
+speci plan -i docs/design.md
 
-# Save plan to specific file
-speci plan --output docs/plan.md
+# Combine input files with a prompt
+speci plan -i spec.md -p "Focus on the authentication module"
 
-# Use custom agent
-speci p -a custom-agent.md
+# Save plan to a specific file
+speci plan -i design.md -o docs/plan.md
+
+# Use custom agent from .github/copilot/agents/
+speci p -a my-custom-plan.agent.md -p "My feature"
 ```
 
 ### `speci task` (alias: `t`)
@@ -145,7 +156,7 @@ speci task --plan <path> [options]
 **Options:**
 
 - `-p, --plan <path>` - Path to plan file (required)
-- `-a, --agent <path>` - Use custom agent file
+- `-a, --agent <filename>` - Use custom agent file from `.github/copilot/agents/`
 - `-v, --verbose` - Show detailed output
 
 **Examples:**
@@ -172,7 +183,7 @@ speci refactor [options]
 
 - `-s, --scope <path>` - Directory or glob pattern to analyze
 - `-o, --output <path>` - Save refactoring plan to file
-- `-a, --agent <path>` - Use custom agent file
+- `-a, --agent <filename>` - Use custom agent file from `.github/copilot/agents/`
 - `-v, --verbose` - Show detailed output
 
 **Examples:**
@@ -306,15 +317,6 @@ The configuration file is created by `speci init` and can be customized:
     "logs": ".speci-logs",
     "lock": ".speci.lock"
   },
-  "agents": {
-    "plan": null,
-    "task": null,
-    "refactor": null,
-    "impl": null,
-    "review": null,
-    "fix": null,
-    "tidy": null
-  },
   "copilot": {
     "permissions": "allow-all",
     "model": null,
@@ -334,18 +336,19 @@ The configuration file is created by `speci init` and can be customized:
 
 Environment variables can override configuration file settings:
 
-| Variable                 | Config Path           | Description                        |
-| ------------------------ | --------------------- | ---------------------------------- |
-| `SPECI_PROGRESS_PATH`    | `paths.progress`      | Path to PROGRESS.md file           |
-| `SPECI_TASKS_PATH`       | `paths.tasks`         | Path to tasks directory            |
-| `SPECI_LOG_PATH`         | `paths.logs`          | Path to log directory              |
-| `SPECI_LOCK_PATH`        | `paths.lock`          | Path to lock file                  |
-| `SPECI_COPILOT_MODEL`    | `copilot.model`       | Copilot model to use               |
-| `SPECI_MAX_ITERATIONS`   | `loop.maxIterations`  | Maximum loop iterations            |
-| `SPECI_ENABLE_AUTO_FIX`  | `loop.enableAutoFix`  | Enable automatic gate fix attempts |
-| `SPECI_MAX_FIX_ATTEMPTS` | `gate.maxFixAttempts` | Maximum fix attempts               |
-| `SPECI_DEBUG`            | N/A                   | Enable debug logging (1 or true)   |
-| `NO_COLOR`               | N/A                   | Disable colored output             |
+| Variable                 | Config Path           | Description                                   |
+| ------------------------ | --------------------- | --------------------------------------------- |
+| `SPECI_PROGRESS_PATH`    | `paths.progress`      | Path to PROGRESS.md file                      |
+| `SPECI_TASKS_PATH`       | `paths.tasks`         | Path to tasks directory                       |
+| `SPECI_LOG_PATH`         | `paths.logs`          | Path to log directory                         |
+| `SPECI_LOCK_PATH`        | `paths.lock`          | Path to lock file                             |
+| `SPECI_COPILOT_MODEL`    | `copilot.model`       | Copilot model to use                          |
+| `SPECI_MAX_ITERATIONS`   | `loop.maxIterations`  | Maximum loop iterations                       |
+| `SPECI_ENABLE_AUTO_FIX`  | `loop.enableAutoFix`  | Enable automatic gate fix attempts            |
+| `SPECI_MAX_FIX_ATTEMPTS` | `gate.maxFixAttempts` | Maximum fix attempts                          |
+| `SPECI_DEBUG`            | N/A                   | Enable debug logging (1 or true)              |
+| `SPECI_NO_ANIMATION`     | N/A                   | Disable banner animation (any value disables) |
+| `NO_COLOR`               | N/A                   | Disable colored output                        |
 
 ## Error Codes
 
@@ -363,13 +366,13 @@ speci uses structured error codes for clear diagnostics:
 
 ### Input Errors (ERR-INP-\*)
 
-| Code       | Message                   | Solution                                |
-| ---------- | ------------------------- | --------------------------------------- |
-| ERR-INP-01 | Required argument missing | Check command usage with `--help`       |
-| ERR-INP-02 | Agent file not found      | Verify agent path or use bundled agents |
-| ERR-INP-03 | Config file is malformed  | Fix JSON syntax in speci.config.json    |
-| ERR-INP-04 | Config validation failed  | Check config against schema             |
-| ERR-INP-05 | Plan file not found       | Provide valid path with `--plan`        |
+| Code       | Message                   | Solution                                                   |
+| ---------- | ------------------------- | ---------------------------------------------------------- |
+| ERR-INP-01 | Required argument missing | Check command usage with `--help`                          |
+| ERR-INP-02 | Agent file not found      | Run `speci init` or add agent to `.github/copilot/agents/` |
+| ERR-INP-03 | Config file is malformed  | Fix JSON syntax in speci.config.json                       |
+| ERR-INP-04 | Config validation failed  | Check config against schema                                |
+| ERR-INP-05 | Plan file not found       | Provide valid path with `--plan`                           |
 
 ### State Errors (ERR-STA-\*)
 

package/bin/speci.ts

@@ -8,6 +8,7 @@
 
 import { Command } from 'commander';
 import { renderBanner, VERSION } from '../lib/ui/banner.js';
+import { animateBanner, shouldAnimate } from '../lib/ui/banner-animation.js';
 import { init } from '../lib/commands/init.js';
 import { plan } from '../lib/commands/plan.js';
 import { task } from '../lib/commands/task.js';
@@ -20,9 +21,19 @@ import { setVerbose, debug } from '../lib/utils/logger.js';
 
 /**
  * Display the application banner
+ *
+ * Conditionally animates the banner when appropriate conditions are met.
+ * Returns a Promise when animation is enabled, or void when displaying static banner.
+ *
+ * @param options - Optional configuration for banner display
  */
-function displayBanner(): void {
-  console.log('\n' + renderBanner({ showVersion: true }) + '\n');
+function displayBanner(options?: { color?: boolean }): Promise<void> | void {
+  if (shouldAnimate(options)) {
+    console.log();
+    return animateBanner().then(() => console.log());
+  } else {
+    console.log('\n' + renderBanner({ showVersion: true }) + '\n');
+  }
 }
 
 const program = new Command();
@@ -34,7 +45,7 @@ program
   .description('Speci CLI - AI-powered implementation loop orchestrator')
   .option('-v, --verbose', 'Enable verbose output')
   .option('--no-color', 'Disable colored output')
-  .hook('preAction', (_thisCommand) => {
+  .hook('preAction', async (_thisCommand) => {
     // Enable verbose mode if --verbose flag is set
     const opts = _thisCommand.opts();
     if (opts.verbose) {
@@ -53,7 +64,10 @@ program
       args.includes('--version') ||
       args.includes('-V');
     if (!isHelpOrVersion) {
-      displayBanner();
+      const result = displayBanner({ color: opts.color });
+      if (result instanceof Promise) {
+        await result;
+      }
     }
   });
 
@@ -63,6 +77,7 @@ program
   .alias('i')
   .description('Initialize Speci in current project')
   .option('-y, --yes', 'Accept all defaults')
+  .option('-u, --update-agents', 'Update agent files even if they exist')
   .option('-v, --verbose', 'Show detailed output')
   .addHelpText(
     'after',
@@ -71,6 +86,7 @@ Examples:
   $ speci init              Interactive setup wizard
   $ speci init --yes        Quick setup with defaults
   $ speci i -y              Force initialize with defaults
+  $ speci init -u           Update agent files to latest version
 `
   )
   .action(init);
@@ -80,6 +96,11 @@ program
   .command('plan')
   .alias('p')
   .description('Generate implementation plan interactively')
+  .option('-p, --prompt <text>', 'Initial prompt describing what to plan')
+  .option(
+    '-i, --input <files...>',
+    'Input files for context (design docs, specs)'
+  )
   .option('-a, --agent <path>', 'Use custom agent file')
   .option('-o, --output <path>', 'Output plan to file')
   .option('-v, --verbose', 'Show detailed output')
@@ -87,9 +108,11 @@ program
     'after',
     `
 Examples:
-  $ speci plan                         Start interactive planning session
-  $ speci plan --output docs/plan.md   Save plan to specific file
-  $ speci p -a custom-agent.md         Use custom agent
+  $ speci plan -p "Build a REST API"              Plan with initial prompt
+  $ speci plan -i docs/design.md                  Plan using design doc as context
+  $ speci plan -i spec.md -p "Focus on auth"      Combine input files with prompt
+  $ speci plan -i design.md -o docs/plan.md       Save plan to specific file
+  $ speci p -a custom-agent.md -p "My feature"    Use custom agent
 `
   )
   .action(plan);
@@ -220,9 +243,14 @@ program.on('command:*', (operands) => {
 
 // Show banner and help when no arguments provided
 if (process.argv.length <= 2) {
-  displayBanner();
-  program.help();
+  (async () => {
+    const result = displayBanner({ color: program.opts().color });
+    if (result instanceof Promise) {
+      await result;
+    }
+    program.help();
+  })();
+} else {
+  // Parse command line arguments (only when a command is provided)
+  program.parse(process.argv);
 }
-
-// Parse command line arguments
-program.parse(process.argv);

package/lib/commands/init.ts

@@ -1,126 +1,35 @@
 /**
  * Init Command Module
  *
- * Provides interactive project setup for new Speci users.
+ * Provides a project setup for new Speci users.
  * Creates speci.config.json, directory structure, and initial files.
- * Uses Node.js readline for zero-dependency interactive prompts.
  */
 
-import { createInterface } from 'node:readline';
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
-import { resolve, basename } from 'node:path';
+import {
+  existsSync,
+  mkdirSync,
+  writeFileSync,
+  copyFileSync,
+  readdirSync,
+  statSync,
+} from 'node:fs';
+import { join, relative } from 'node:path';
 import { log } from '../utils/logger.js';
 import { renderBanner } from '../ui/banner.js';
 import { colorize } from '../ui/colors.js';
-import { getDefaults, type SpeciConfig } from '../config.js';
+import {
+  getDefaults,
+  getAgentsTemplatePath,
+  GITHUB_AGENTS_DIR,
+  type SpeciConfig,
+} from '../config.js';
 
 /**
  * Options for the init command
  */
 export interface InitOptions {
-  yes?: boolean; // Skip prompts, use defaults
   verbose?: boolean; // Show detailed output
-}
-
-/**
- * Prompt user for input with default value
- * @param question - Question to ask
- * @param defaultValue - Default value if no input provided
- * @returns User's answer or default value
- */
-async function prompt(question: string, defaultValue: string): Promise<string> {
-  const rl = createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
-
-  return new Promise((resolve) => {
-    const styled = `${colorize(question, 'sky400')} ${colorize(`(${defaultValue})`, 'dim')}: `;
-    rl.question(styled, (answer) => {
-      rl.close();
-      resolve(answer.trim() || defaultValue);
-    });
-  });
-}
-
-/**
- * Validate path to ensure it's safe (no path traversal outside project)
- * @param input - Path to validate
- * @returns Validated path
- * @throws Error if path attempts to escape project directory
- */
-function validatePath(input: string): string {
-  const normalized = resolve(process.cwd(), input);
-  const projectRoot = process.cwd();
-
-  // Check if normalized path starts with project root
-  if (!normalized.startsWith(projectRoot)) {
-    throw new Error(
-      `Invalid path: ${input} attempts to escape project directory`
-    );
-  }
-
-  return input;
-}
-
-/**
- * Gather configuration through interactive prompts
- * @returns Partial config with user answers
- */
-async function gatherConfig(): Promise<Partial<SpeciConfig>> {
-  // Project name is prompted but not used in config (for future enhancement)
-  await prompt('Project name', basename(process.cwd()));
-
-  const progressPath = validatePath(
-    await prompt('Progress file path', 'docs/PROGRESS.md')
-  );
-
-  const tasksPath = validatePath(
-    await prompt('Tasks directory path', 'docs/tasks')
-  );
-
-  const logsPath = validatePath(
-    await prompt('Logs directory path', '.speci-logs')
-  );
-
-  const gateCommands = await prompt(
-    'Gate commands (comma-separated)',
-    'npm run lint, npm run typecheck, npm test'
-  );
-
-  return {
-    paths: {
-      progress: progressPath,
-      tasks: tasksPath,
-      logs: logsPath,
-      lock: '.speci-lock',
-    },
-    gate: {
-      commands: gateCommands.split(',').map((cmd) => cmd.trim()),
-      maxFixAttempts: 3,
-    },
-  };
-}
-
-/**
- * Merge user config with defaults
- * @param userConfig - Partial config from user
- * @returns Full config merged with defaults
- */
-function mergeWithDefaults(userConfig: Partial<SpeciConfig>): SpeciConfig {
-  const defaults = getDefaults();
-
-  return {
-    ...defaults,
-    paths: {
-      ...defaults.paths,
-      ...userConfig.paths,
-    },
-    gate: {
-      ...defaults.gate,
-      ...userConfig.gate,
-    },
-  };
+  updateAgents?: boolean; // Force update agent files even if they exist
 }
 
 /**
@@ -132,11 +41,13 @@ function checkExistingFiles(config: SpeciConfig): {
   configExists: boolean;
   tasksExists: boolean;
   logsExists: boolean;
+  agentsExist: boolean;
 } {
   return {
     configExists: existsSync('speci.config.json'),
     tasksExists: existsSync(config.paths.tasks),
     logsExists: existsSync(config.paths.logs),
+    agentsExist: existsSync(GITHUB_AGENTS_DIR),
   };
 }
 
@@ -144,26 +55,27 @@ function checkExistingFiles(config: SpeciConfig): {
  * Display summary of actions to be taken
  * @param config - Config to display
  * @param existing - Existing files flags
+ * @param updateAgents - Whether to force update agent files
  */
 function displayActionSummary(
   config: SpeciConfig,
-  existing: ReturnType<typeof checkExistingFiles>
+  existing: ReturnType<typeof checkExistingFiles>,
+  updateAgents: boolean = false
 ): void {
-  console.log();
-  log.info('The following actions will be performed:');
-  console.log();
-
   if (existing.configExists) {
     log.warn('  speci.config.json already exists (will skip)');
   } else {
-    console.log(colorize('  ✓ Create speci.config.json', 'success'));
+    console.log(colorize('    speci.config.json will be created', 'success'));
   }
 
   if (existing.tasksExists) {
     log.warn(`  ${config.paths.tasks}/ already exists (will skip)`);
   } else {
     console.log(
-      colorize(`  ✓ Create ${config.paths.tasks}/ directory`, 'success')
+      colorize(
+        `    ${config.paths.tasks}/ directory will be created`,
+        'success'
+      )
     );
   }
 
@@ -171,7 +83,26 @@ function displayActionSummary(
     log.warn(`  ${config.paths.logs}/ already exists (will skip)`);
   } else {
     console.log(
-      colorize(`  ✓ Create ${config.paths.logs}/ directory`, 'success')
+      colorize(`    ${config.paths.logs}/ directory will be created`, 'success')
+    );
+  }
+
+  if (existing.agentsExist) {
+    if (updateAgents) {
+      console.log(
+        colorize(
+          `    ${GITHUB_AGENTS_DIR}/ directory will be updated`,
+          'success'
+        )
+      );
+    } else {
+      log.warn(
+        `  ${GITHUB_AGENTS_DIR}/ already exists (will skip, use --update-agents to overwrite)`
+      );
+    }
+  } else {
+    console.log(
+      colorize(`    ${GITHUB_AGENTS_DIR}/ directory will be updated`, 'success')
     );
   }
 
@@ -237,17 +168,97 @@ async function createFiles(
   }
 }
 
+/**
+ * Recursively copy a directory
+ * @param src - Source directory path
+ * @param dest - Destination directory path
+ * @returns Number of files copied
+ */
+function copyDirectoryRecursive(src: string, dest: string): number {
+  let fileCount = 0;
+
+  // Create destination directory
+  mkdirSync(dest, { recursive: true, mode: 0o755 });
+
+  // Read source directory contents
+  const entries = readdirSync(src);
+
+  for (const entry of entries) {
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    const stat = statSync(srcPath);
+
+    if (stat.isDirectory()) {
+      // Recursively copy subdirectories
+      fileCount += copyDirectoryRecursive(srcPath, destPath);
+    } else if (stat.isFile()) {
+      // Copy file
+      copyFileSync(srcPath, destPath);
+      const relativePath = relative(getAgentsTemplatePath(), srcPath);
+      log.debug(`Copied: ${relativePath}`);
+      fileCount++;
+    }
+  }
+
+  return fileCount;
+}
+
+/**
+ * Copy agent files to .github/copilot/agents/
+ * This allows copilot CLI to use --agent flag with agent names
+ * Recursively copies entire agents template directory including subagents
+ * @param existing - Existing files flags
+ * @param forceUpdate - Force update even if agents exist
+ */
+async function copyAgentFiles(
+  existing: ReturnType<typeof checkExistingFiles>,
+  forceUpdate: boolean = false
+): Promise<void> {
+  if (existing.agentsExist && !forceUpdate) {
+    log.debug(`Skipping agent files copy: ${GITHUB_AGENTS_DIR} already exists`);
+    return;
+  }
+
+  try {
+    const templateDir = getAgentsTemplatePath();
+
+    if (!existsSync(templateDir)) {
+      throw new Error(`Agent templates directory not found: ${templateDir}`);
+    }
+
+    // Recursively copy entire agents directory
+    const fileCount = copyDirectoryRecursive(templateDir, GITHUB_AGENTS_DIR);
+
+    const action = existing.agentsExist ? 'Updated' : 'Copied';
+    log.success(
+      `${action} ${fileCount} agent files inside ${GITHUB_AGENTS_DIR}/`
+    );
+  } catch (error) {
+    throw new Error(
+      `Failed to copy agent files: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
 /**
  * Display success message and next steps
  */
 function displaySuccess(): void {
-  console.log();
-  log.success('Speci initialization complete!');
   console.log();
   log.info('Next steps:');
-  console.log(colorize('  1. Add tasks to docs/tasks/', 'dim'));
-  console.log(colorize('  2. Update docs/PROGRESS.md with your tasks', 'dim'));
-  console.log(colorize('  3. Run: speci status', 'dim'));
+  console.log(colorize('  1. Generate your plan with: speci plan', 'dim'));
+  console.log(
+    colorize(
+      '  2. Generate your tasks and PROGRESS.md with: speci tasks',
+      'dim'
+    )
+  );
+  console.log(
+    colorize(
+      '  3. After a manual check start the implementation loop: speci run',
+      'dim'
+    )
+  );
   console.log();
 }
 
@@ -264,19 +275,14 @@ export async function init(options: InitOptions = {}): Promise<void> {
     log.info('Initializing Speci in current directory...');
     console.log();
 
-    // Gather configuration (prompts or defaults)
-    const userConfig = options.yes
-      ? { paths: getDefaults().paths, gate: getDefaults().gate }
-      : await gatherConfig();
-
-    // Merge with defaults
-    const config = mergeWithDefaults(userConfig);
+    // Use default configuration
+    const config = getDefaults();
 
     // Check existing files
     const existing = checkExistingFiles(config);
 
     // Display action summary
-    displayActionSummary(config, existing);
+    displayActionSummary(config, existing, options.updateAgents);
 
     // Create directories
     await createDirectories(config, existing);
@@ -284,6 +290,9 @@ export async function init(options: InitOptions = {}): Promise<void> {
     // Create files
     await createFiles(config, existing);
 
+    // Copy agent files to .github/copilot/agents/
+    await copyAgentFiles(existing, options.updateAgents);
+
     // Display success and next steps
     displaySuccess();
   } catch (error) {