@bamptee/aia-code 0.2.0

package/README.md

@@ -0,0 +1,308 @@
+# AIA - AI Architecture Assistant
+
+CLI tool that orchestrates AI-assisted development workflows using a `.aia` folder convention.
+
+AIA structures your feature development into steps (brief, spec, tech-spec, etc.), builds rich prompts from project context and knowledge files, and delegates execution to AI CLI tools (Claude Code, Codex CLI, Gemini CLI) with weighted random model selection.
+
+## Quick start
+
+```bash
+npm install
+node bin/aia.js init
+```
+
+## Prerequisites
+
+AIA delegates to AI CLI tools. Install the ones you need:
+
+| Provider | CLI | Install |
+|----------|-----|---------|
+| Anthropic | `claude` (Claude Code) | `npm install -g @anthropic-ai/claude-code` |
+| OpenAI | `codex` (Codex CLI) | `npm install -g @openai/codex` |
+| Google | `gemini` (Gemini CLI) | `npm install -g @anthropic-ai/gemini-cli` |
+
+Each CLI manages its own authentication. Run `claude`, `codex`, or `gemini` once to log in before using AIA.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `aia init` | Create `.aia/` folder structure and default config |
+| `aia feature <name>` | Create a new feature workspace |
+| `aia run <step> <feature>` | Execute a step for a feature using AI |
+| `aia status <feature>` | Show the current status of a feature |
+| `aia reset <step> <feature>` | Reset a step to pending so it can be re-run |
+| `aia repo scan` | Scan codebase and generate `repo-map.json` |
+
+## Integrate into an existing project
+
+### 1. Install
+
+```bash
+cd your-project
+npm install /path/to/aia-code
+```
+
+Or add it as a dev dependency in your `package.json`:
+
+```json
+{
+  "devDependencies": {
+    "aia": "file:../aia-code"
+  }
+}
+```
+
+### 2. Initialize
+
+```bash
+npx aia init
+```
+
+This creates:
+
+```
+your-project/
+  .aia/
+    config.yaml
+    context/
+    knowledge/
+    prompts/
+    features/
+    logs/
+```
+
+### 3. Write context files
+
+These files describe your project to the AI. They are injected into every prompt.
+
+```markdown
+<!-- .aia/context/project.md -->
+# Project
+E-commerce SaaS platform built with Node.js and MongoDB.
+Stack: Express, React, Redis, PostgreSQL.
+```
+
+```markdown
+<!-- .aia/context/architecture.md -->
+# Architecture
+Microservices communicating via RabbitMQ.
+API gateway with JWT auth.
+```
+
+Reference them in `config.yaml`:
+
+```yaml
+context_files:
+  - context/project.md
+  - context/architecture.md
+```
+
+### 4. Write knowledge files
+
+Knowledge files contain reusable technical guidelines, organized by category.
+
+```
+.aia/knowledge/
+  backend/
+    nodejs.md          # Node.js patterns and conventions
+    mongo-patterns.md  # MongoDB query patterns
+    api-design.md      # REST API guidelines
+  frontend/
+    react-patterns.md  # React component patterns
+```
+
+Set the default knowledge categories in `config.yaml`:
+
+```yaml
+knowledge_default:
+  - backend
+```
+
+Each feature can override this via its `status.yaml` `knowledge` field.
+
+### 5. Write prompt templates
+
+One template per step, stored in `.aia/prompts/`:
+
+```markdown
+<!-- .aia/prompts/brief.md -->
+Write a product brief for this feature.
+Include: problem statement, target users, success metrics.
+```
+
+```markdown
+<!-- .aia/prompts/tech-spec.md -->
+Write a technical specification.
+Include: data models, API endpoints, architecture decisions, trade-offs.
+```
+
+Required templates (one per step you want to run):
+
+```
+.aia/prompts/brief.md
+.aia/prompts/ba-spec.md
+.aia/prompts/questions.md
+.aia/prompts/tech-spec.md
+.aia/prompts/challenge.md
+.aia/prompts/dev-plan.md
+.aia/prompts/review.md
+```
+
+### 6. Configure models
+
+In `config.yaml`, assign models to steps with probability weights:
+
+```yaml
+models:
+  brief:
+    - model: claude-sonnet-4-6
+      weight: 1
+
+  questions:
+    - model: claude-sonnet-4-6
+      weight: 0.5
+    - model: o3
+      weight: 0.5
+
+  tech-spec:
+    - model: gpt-4.1
+      weight: 0.6
+    - model: gemini-2.5-pro
+      weight: 0.4
+```
+
+Weights don't need to sum to 1 -- they are normalized at runtime.
+
+Supported model prefixes and the CLI used:
+
+| Prefix | CLI | Examples |
+|--------|-----|----------|
+| `claude-*` | `claude -p --model` | `claude-sonnet-4-6`, `claude-3-7-sonnet` |
+| `gpt-*`, `o[0-9]*` | `codex exec` | `gpt-4.1`, `o3`, `o4-mini` |
+| `gemini-*` | `gemini` | `gemini-2.5-pro`, `gemini-2.5-flash` |
+
+### 7. Create a feature and run steps
+
+```bash
+npx aia feature session-replay
+npx aia run brief session-replay
+npx aia status session-replay
+npx aia run tech-spec session-replay
+```
+
+Each run:
+1. Loads context files + knowledge + prior step outputs
+2. Selects a model based on weights
+3. Sends the assembled prompt to the CLI tool via stdin
+4. Streams the response to stdout in real-time
+5. Saves the output to `.aia/features/<name>/<step>.md`
+6. Updates `status.yaml` (marks step `done`, advances `current_step`)
+7. Logs execution to `.aia/logs/execution.log`
+
+To re-run a step:
+
+```bash
+npx aia reset tech-spec session-replay
+npx aia run tech-spec session-replay
+```
+
+### 8. Scan your repo
+
+```bash
+npx aia repo scan
+```
+
+Generates `.aia/repo-map.json` -- a categorized index of your source files (services, models, routes, controllers, middleware, utils, config). Useful as additional context for prompts.
+
+## Project structure
+
+```
+bin/
+  aia.js                  # CLI entrypoint
+src/
+  cli.js                  # Commander program, registers commands
+  constants.js            # Shared constants (dirs, steps, scan config)
+  models.js               # Config loader + validation, weighted model selection
+  logger.js               # Execution log writer
+  knowledge-loader.js     # Recursive markdown loader by category
+  prompt-builder.js       # Assembles full prompt from all sources
+  utils.js                # Shared filesystem helpers
+  commands/
+    init.js               # aia init
+    feature.js            # aia feature <name>
+    run.js                # aia run <step> <feature>
+    status.js             # aia status <feature>
+    reset.js              # aia reset <step> <feature>
+    repo.js               # aia repo scan
+  providers/
+    registry.js           # Model name -> provider routing
+    cli-runner.js         # Shared CLI spawn logic (stdout streaming, timeout, error handling)
+    openai.js             # codex exec
+    anthropic.js          # claude -p
+    gemini.js             # gemini
+  services/
+    scaffold.js           # .aia/ folder creation
+    config.js             # Default config generation
+    feature.js            # Feature workspace creation + validation
+    status.js             # status.yaml read/write/reset
+    runner.js             # Step execution orchestrator
+    model-call.js         # Provider dispatch
+    repo-scan.js          # Codebase scanner + categorizer
+```
+
+## Feature workflow
+
+Each feature follows a fixed pipeline:
+
+```
+brief -> ba-spec -> questions -> tech-spec -> challenge -> dev-plan -> review
+```
+
+`status.yaml` tracks progress:
+
+```yaml
+feature: session-replay
+current_step: tech-spec
+steps:
+  brief: done
+  ba-spec: done
+  questions: pending
+  tech-spec: pending
+  challenge: pending
+  dev-plan: pending
+  review: pending
+knowledge:
+  - backend
+```
+
+## Prompt assembly
+
+When you run a step, the prompt is built from four sections:
+
+```
+=== CONTEXT ===
+(content of context files from config.yaml)
+
+=== KNOWLEDGE ===
+(all .md files from the knowledge categories)
+
+=== FEATURE ===
+(outputs of all prior steps for this feature)
+
+=== TASK ===
+(content of prompts/<step>.md)
+```
+
+The full prompt is piped to the CLI tool via stdin, so there are no argument length limits.
+
+## Dependencies
+
+Only four runtime dependencies:
+
+- `commander` -- CLI framework
+- `yaml` -- YAML parse/stringify
+- `fs-extra` -- filesystem utilities
+- `chalk` -- terminal colors
+
+AI calls use `child_process.spawn` to delegate to installed CLI tools.

package/bin/aia.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { createCli } from '../src/cli.js';
+
+const program = createCli();
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@bamptee/aia-code",
+  "version": "0.2.0",
+  "description": "AI Architecture Assistant - orchestrate AI-assisted development workflows via CLI tools (Claude, Codex, Gemini)",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "aia": "bin/aia.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "keywords": [
+    "ai",
+    "cli",
+    "architecture",
+    "claude",
+    "codex",
+    "gemini",
+    "orchestrator",
+    "development",
+    "workflow"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bamptee/aia-code.git"
+  },
+  "scripts": {
+    "start": "node bin/aia.js"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "fs-extra": "^11.2.0",
+    "yaml": "^2.7.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,25 @@
+import { Command } from 'commander';
+import { registerInitCommand } from './commands/init.js';
+import { registerFeatureCommand } from './commands/feature.js';
+import { registerRunCommand } from './commands/run.js';
+import { registerRepoCommand } from './commands/repo.js';
+import { registerStatusCommand } from './commands/status.js';
+import { registerResetCommand } from './commands/reset.js';
+
+export function createCli() {
+  const program = new Command();
+
+  program
+    .name('aia')
+    .description('AI Architecture Assistant')
+    .version('0.1.0');
+
+  registerInitCommand(program);
+  registerFeatureCommand(program);
+  registerRunCommand(program);
+  registerRepoCommand(program);
+  registerStatusCommand(program);
+  registerResetCommand(program);
+
+  return program;
+}

package/src/commands/feature.js

@@ -0,0 +1,17 @@
+import chalk from 'chalk';
+import { createFeature } from '../services/feature.js';
+
+export function registerFeatureCommand(program) {
+  program
+    .command('feature <name>')
+    .description('Create a new feature workspace under .aia/features/')
+    .action(async (name) => {
+      try {
+        await createFeature(name);
+        console.log(chalk.green(`Feature "${name}" created.`));
+      } catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+      }
+    });
+}

package/src/commands/init.js

@@ -0,0 +1,20 @@
+import chalk from 'chalk';
+import { createAiaStructure } from '../services/scaffold.js';
+import { writeDefaultConfig } from '../services/config.js';
+import { AIA_DIR } from '../constants.js';
+
+export function registerInitCommand(program) {
+  program
+    .command('init')
+    .description('Initialize .aia folder structure and default config')
+    .action(async () => {
+      try {
+        await createAiaStructure();
+        await writeDefaultConfig();
+        console.log(chalk.green(`Initialized ${AIA_DIR}/ project structure.`));
+      } catch (err) {
+        console.error(chalk.red(`Init failed: ${err.message}`));
+        process.exit(1);
+      }
+    });
+}

package/src/commands/repo.js

@@ -0,0 +1,29 @@
+import chalk from 'chalk';
+import { scanRepo } from '../services/repo-scan.js';
+
+export function registerRepoCommand(program) {
+  const repo = program
+    .command('repo')
+    .description('Repository intelligence tools');
+
+  repo
+    .command('scan')
+    .description('Scan the codebase and generate .aia/repo-map.json')
+    .action(async () => {
+      try {
+        const { map, total, outputPath } = await scanRepo();
+
+        const categories = Object.keys(map);
+        const matched = Object.values(map).reduce((s, f) => s + f.length, 0);
+
+        console.log(chalk.green(`Scanned ${total} files, categorized ${matched} into ${categories.length} groups.`));
+        for (const [cat, files] of Object.entries(map)) {
+          console.log(chalk.cyan(`  ${cat}: ${files.length} files`));
+        }
+        console.log(chalk.gray(`Written to ${outputPath}`));
+      } catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+      }
+    });
+}

package/src/commands/reset.js

@@ -0,0 +1,17 @@
+import chalk from 'chalk';
+import { resetStep } from '../services/status.js';
+
+export function registerResetCommand(program) {
+  program
+    .command('reset <step> <feature>')
+    .description('Reset a step to pending so it can be re-run')
+    .action(async (step, feature) => {
+      try {
+        await resetStep(feature, step);
+        console.log(chalk.green(`Step "${step}" reset to pending for feature "${feature}".`));
+      } catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+      }
+    });
+}

package/src/commands/run.js

@@ -0,0 +1,16 @@
+import chalk from 'chalk';
+import { runStep } from '../services/runner.js';
+
+export function registerRunCommand(program) {
+  program
+    .command('run <step> <feature>')
+    .description('Execute a step for a feature using the configured AI model')
+    .action(async (step, feature) => {
+      try {
+        await runStep(step, feature);
+      } catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+      }
+    });
+}

package/src/commands/status.js

@@ -0,0 +1,37 @@
+import chalk from 'chalk';
+import { STEP_STATUS } from '../constants.js';
+import { loadStatus } from '../services/status.js';
+
+const STATUS_COLORS = {
+  [STEP_STATUS.DONE]: chalk.green,
+  [STEP_STATUS.IN_PROGRESS]: chalk.yellow,
+  [STEP_STATUS.ERROR]: chalk.red,
+  [STEP_STATUS.PENDING]: chalk.gray,
+};
+
+export function registerStatusCommand(program) {
+  program
+    .command('status <feature>')
+    .description('Show the current status of a feature')
+    .action(async (feature) => {
+      try {
+        const status = await loadStatus(feature);
+
+        console.log(chalk.bold(`Feature: ${status.feature}`));
+        console.log(chalk.bold(`Current step: ${status.current_step}\n`));
+
+        for (const [step, value] of Object.entries(status.steps)) {
+          const colorize = STATUS_COLORS[value] ?? chalk.white;
+          const marker = value === STEP_STATUS.DONE ? 'v' : value === STEP_STATUS.ERROR ? 'x' : '-';
+          console.log(`  ${colorize(`[${marker}] ${step}: ${value}`)}`);
+        }
+
+        if (status.knowledge?.length) {
+          console.log(chalk.gray(`\nKnowledge: ${status.knowledge.join(', ')}`));
+        }
+      } catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+      }
+    });
+}

package/src/constants.js

@@ -0,0 +1,43 @@
+export const AIA_DIR = '.aia';
+
+export const AIA_FOLDERS = [
+  'context',
+  'knowledge',
+  'prompts',
+  'features',
+  'logs',
+];
+
+export const SCAN_IGNORE = new Set([
+  'node_modules',
+  'dist',
+  '.git',
+  '.aia',
+]);
+
+export const SCAN_CATEGORIES = {
+  services: /\bservices?\b/i,
+  models: /\bmodels?\b/i,
+  routes: /\broutes?\b/i,
+  controllers: /\bcontrollers?\b/i,
+  middleware: /\bmiddleware\b/i,
+  utils: /\b(utils?|helpers?)\b/i,
+  config: /\bconfig\b/i,
+};
+
+export const FEATURE_STEPS = [
+  'brief',
+  'ba-spec',
+  'questions',
+  'tech-spec',
+  'challenge',
+  'dev-plan',
+  'review',
+];
+
+export const STEP_STATUS = {
+  PENDING: 'pending',
+  IN_PROGRESS: 'in-progress',
+  DONE: 'done',
+  ERROR: 'error',
+};

package/src/knowledge-loader.js

@@ -0,0 +1,43 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { AIA_DIR } from './constants.js';
+
+async function collectMarkdownFiles(dir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await collectMarkdownFiles(fullPath));
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+export async function loadKnowledge(categories, root = process.cwd()) {
+  const knowledgeDir = path.join(root, AIA_DIR, 'knowledge');
+  const sections = [];
+
+  for (const category of categories) {
+    const categoryDir = path.join(knowledgeDir, category);
+
+    if (!(await fs.pathExists(categoryDir))) {
+      continue;
+    }
+
+    const files = (await collectMarkdownFiles(categoryDir)).sort();
+
+    for (const filePath of files) {
+      const content = (await fs.readFile(filePath, 'utf-8')).trim();
+      if (content) {
+        sections.push(content);
+      }
+    }
+  }
+
+  return sections.join('\n\n---\n\n');
+}

package/src/logger.js

@@ -0,0 +1,28 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { AIA_DIR } from './constants.js';
+
+const LOG_FILE = 'execution.log';
+
+function formatEntry({ feature, step, model, duration }) {
+  const timestamp = new Date().toISOString().replace(/\.\d{3}Z$/, '');
+  const durationSec = (duration / 1000).toFixed(1);
+
+  return [
+    timestamp,
+    `feature=${feature}`,
+    `step=${step}`,
+    `model=${model}`,
+    `duration=${durationSec}s`,
+    '',
+  ].join('\n');
+}
+
+export async function logExecution(entry, root = process.cwd()) {
+  const logDir = path.join(root, AIA_DIR, 'logs');
+  await fs.ensureDir(logDir);
+
+  const logPath = path.join(logDir, LOG_FILE);
+  const line = formatEntry(entry);
+  await fs.appendFile(logPath, line + '\n', 'utf-8');
+}

package/src/models.js

@@ -0,0 +1,78 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import yaml from 'yaml';
+import chalk from 'chalk';
+import { AIA_DIR } from './constants.js';
+
+export async function loadConfig(root = process.cwd()) {
+  const configPath = path.join(root, AIA_DIR, 'config.yaml');
+
+  if (!(await fs.pathExists(configPath))) {
+    throw new Error(`Config not found: ${configPath}`);
+  }
+
+  const raw = await fs.readFile(configPath, 'utf-8');
+  const config = yaml.parse(raw);
+
+  validateConfig(config, configPath);
+
+  return config;
+}
+
+function validateConfig(config, configPath) {
+  if (!config || typeof config !== 'object') {
+    throw new Error(`Invalid config: ${configPath} must be a YAML object.`);
+  }
+
+  if (!config.models || typeof config.models !== 'object') {
+    throw new Error(`Invalid config: "models" section is required in ${configPath}.`);
+  }
+
+  for (const [step, models] of Object.entries(config.models)) {
+    if (!Array.isArray(models)) {
+      throw new Error(`Invalid config: models.${step} must be an array.`);
+    }
+    for (const entry of models) {
+      if (!entry.model || typeof entry.model !== 'string') {
+        throw new Error(`Invalid config: each entry in models.${step} must have a "model" string.`);
+      }
+      if (typeof entry.weight !== 'number' || entry.weight <= 0) {
+        throw new Error(`Invalid config: each entry in models.${step} must have a positive "weight".`);
+      }
+    }
+  }
+}
+
+export function selectByWeight(models) {
+  if (models.length === 1) {
+    return models[0].model;
+  }
+
+  const totalWeight = models.reduce((sum, m) => sum + m.weight, 0);
+  const roll = Math.random() * totalWeight;
+
+  let cumulative = 0;
+  for (const entry of models) {
+    cumulative += entry.weight;
+    if (roll < cumulative) {
+      return entry.model;
+    }
+  }
+
+  return models[models.length - 1].model;
+}
+
+export async function resolveModel(step, root = process.cwd()) {
+  const config = await loadConfig(root);
+  const models = config.models?.[step];
+
+  if (!models || models.length === 0) {
+    throw new Error(`No models configured for step "${step}".`);
+  }
+
+  const selected = selectByWeight(models);
+
+  console.log(chalk.cyan(`[AI] step=${step} model=${selected}`));
+
+  return selected;
+}

package/src/prompt-builder.js

@@ -0,0 +1,97 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import yaml from 'yaml';
+import { AIA_DIR, FEATURE_STEPS } from './constants.js';
+import { loadConfig } from './models.js';
+import { loadKnowledge } from './knowledge-loader.js';
+import { readIfExists } from './utils.js';
+
+async function loadContextFiles(config, root) {
+  const files = config.context_files ?? [];
+  const sections = [];
+
+  for (const file of files) {
+    const content = await readIfExists(path.join(root, AIA_DIR, file));
+    if (content) {
+      sections.push(content);
+    }
+  }
+
+  return sections.join('\n\n');
+}
+
+async function loadFeatureFiles(feature, step, root) {
+  const stepIndex = FEATURE_STEPS.indexOf(step);
+  if (stepIndex === -1) {
+    throw new Error(`Unknown step "${step}".`);
+  }
+
+  const featureDir = path.join(root, AIA_DIR, 'features', feature);
+  if (!(await fs.pathExists(featureDir))) {
+    throw new Error(`Feature "${feature}" not found.`);
+  }
+
+  const priorSteps = FEATURE_STEPS.slice(0, stepIndex);
+  const sections = [];
+
+  for (const s of priorSteps) {
+    const content = await readIfExists(path.join(featureDir, `${s}.md`));
+    if (content) {
+      sections.push(content);
+    }
+  }
+
+  return sections.join('\n\n');
+}
+
+async function resolveKnowledgeCategories(feature, config, root) {
+  const statusPath = path.join(root, AIA_DIR, 'features', feature, 'status.yaml');
+  const raw = await readIfExists(statusPath);
+
+  if (raw) {
+    const status = yaml.parse(raw);
+    if (status?.knowledge?.length) {
+      return status.knowledge;
+    }
+  }
+
+  return config.knowledge_default ?? [];
+}
+
+async function loadPromptTemplate(step, root) {
+  const templatePath = path.join(root, AIA_DIR, 'prompts', `${step}.md`);
+  const content = await readIfExists(templatePath);
+  if (!content) {
+    throw new Error(`Prompt template not found: prompts/${step}.md`);
+  }
+  return content;
+}
+
+export async function buildPrompt(feature, step, root = process.cwd()) {
+  const config = await loadConfig(root);
+
+  const [context, knowledgeCategories, featureContent, task] = await Promise.all([
+    loadContextFiles(config, root),
+    resolveKnowledgeCategories(feature, config, root),
+    loadFeatureFiles(feature, step, root),
+    loadPromptTemplate(step, root),
+  ]);
+
+  const knowledge = await loadKnowledge(knowledgeCategories, root);
+
+  const parts = [];
+
+  parts.push('=== CONTEXT ===\n');
+  parts.push(context || '(no context files)');
+
+  parts.push('\n\n=== KNOWLEDGE ===\n');
+  parts.push(knowledge || '(no knowledge)');
+
+  parts.push('\n\n=== FEATURE ===\n');
+  parts.push(featureContent || '(no prior steps)');
+
+  parts.push('\n\n=== TASK ===\n');
+  parts.push(task);
+
+  return parts.join('\n');
+}

package/src/providers/anthropic.js

@@ -0,0 +1,11 @@
+import { runCli } from './cli-runner.js';
+
+export async function generate(prompt, model) {
+  const args = ['-p'];
+  if (model) {
+    args.push('--model', model);
+  }
+  args.push('-');
+
+  return runCli('claude', args, { stdin: prompt });
+}

package/src/providers/cli-runner.js

@@ -0,0 +1,53 @@
+import { spawn } from 'node:child_process';
+
+const DEFAULT_TIMEOUT_MS = 300_000;
+
+export function runCli(command, args, { stdin: stdinData, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env, FORCE_COLOR: '0' },
+    });
+
+    const chunks = [];
+    let stderr = '';
+
+    child.stdout.on('data', (data) => {
+      const text = data.toString();
+      process.stdout.write(text);
+      chunks.push(text);
+    });
+
+    child.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    const timer = setTimeout(() => {
+      child.kill('SIGTERM');
+      reject(new Error(`CLI timed out after ${timeoutMs / 1000}s: ${command} ${args.join(' ')}`));
+    }, timeoutMs);
+
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      if (err.code === 'ENOENT') {
+        reject(new Error(`CLI not found: "${command}". Make sure it is installed and in your PATH.`));
+      } else {
+        reject(err);
+      }
+    });
+
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      if (code !== 0) {
+        reject(new Error(`${command} exited with code ${code}:\n${stderr.trim()}`));
+      } else {
+        resolve(chunks.join(''));
+      }
+    });
+
+    if (stdinData) {
+      child.stdin.write(stdinData);
+      child.stdin.end();
+    }
+  });
+}

package/src/providers/gemini.js

@@ -0,0 +1,11 @@
+import { runCli } from './cli-runner.js';
+
+export async function generate(prompt, model) {
+  const args = [];
+  if (model) {
+    args.push('-m', model);
+  }
+  args.push('-');
+
+  return runCli('gemini', args, { stdin: prompt });
+}

package/src/providers/openai.js

@@ -0,0 +1,11 @@
+import { runCli } from './cli-runner.js';
+
+export async function generate(prompt, model) {
+  const args = ['exec'];
+  if (model) {
+    args.push('-c', `model="${model}"`);
+  }
+  args.push('-');
+
+  return runCli('codex', args, { stdin: prompt });
+}

package/src/providers/registry.js

@@ -0,0 +1,38 @@
+import * as openai from './openai.js';
+import * as anthropic from './anthropic.js';
+import * as gemini from './gemini.js';
+
+const MODEL_ALIASES = {
+  'claude-default':  { provider: anthropic, model: null },
+  'openai-default':  { provider: openai,    model: null },
+  'codex-default':   { provider: openai,    model: null },
+  'gemini-default':  { provider: gemini,    model: null },
+};
+
+const MODEL_PREFIXES = [
+  { test: (m) => m.startsWith('gpt-') || /^o[0-9]/.test(m), provider: openai },
+  { test: (m) => m.startsWith('claude-'),                    provider: anthropic },
+  { test: (m) => m.startsWith('gemini-'),                    provider: gemini },
+];
+
+export function resolveModelAlias(model) {
+  if (!model || typeof model !== 'string') {
+    throw new Error('Model name must be a non-empty string.');
+  }
+
+  const alias = MODEL_ALIASES[model];
+  if (alias) {
+    return { provider: alias.provider, model: alias.model };
+  }
+
+  const match = MODEL_PREFIXES.find((entry) => entry.test(model));
+  if (!match) {
+    throw new Error(`No provider found for model "${model}".`);
+  }
+
+  return { provider: match.provider, model };
+}
+
+export function getProvider(model) {
+  return resolveModelAlias(model).provider;
+}

package/src/services/config.js

@@ -0,0 +1,33 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import yaml from 'yaml';
+import { AIA_DIR } from '../constants.js';
+
+const DEFAULT_CONFIG = {
+  models: {
+    questions: [
+      { model: 'claude-default', weight: 0.5 },
+      { model: 'openai-default', weight: 0.5 },
+    ],
+    'tech-spec': [
+      { model: 'claude-default', weight: 0.5 },
+      { model: 'openai-default', weight: 0.5 },
+    ],
+  },
+  knowledge_default: ['backend'],
+  context_files: [
+    'context/project.md',
+    'context/architecture.md',
+  ],
+};
+
+export async function writeDefaultConfig(root = process.cwd()) {
+  const configPath = path.join(root, AIA_DIR, 'config.yaml');
+
+  if (await fs.pathExists(configPath)) {
+    return;
+  }
+
+  const content = yaml.stringify(DEFAULT_CONFIG);
+  await fs.writeFile(configPath, content, 'utf-8');
+}

package/src/services/feature.js

@@ -0,0 +1,57 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import yaml from 'yaml';
+import { AIA_DIR, FEATURE_STEPS } from '../constants.js';
+
+const FEATURE_FILES = [
+  'status.yaml',
+  'brief.md',
+  'ba-spec.md',
+  'questions.md',
+  'tech-spec.md',
+  'challenge.md',
+  'dev-plan.md',
+  'review.md',
+];
+
+const FEATURE_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export function validateFeatureName(name) {
+  if (!name || !FEATURE_NAME_RE.test(name)) {
+    throw new Error(
+      `Invalid feature name "${name}". Use lowercase alphanumeric with hyphens (e.g. session-replay).`,
+    );
+  }
+}
+
+function buildStatusYaml(name) {
+  const steps = {};
+  for (const step of FEATURE_STEPS) {
+    steps[step] = 'pending';
+  }
+
+  return yaml.stringify({
+    feature: name,
+    current_step: 'brief',
+    steps,
+    knowledge: ['backend'],
+  });
+}
+
+export async function createFeature(name, root = process.cwd()) {
+  validateFeatureName(name);
+
+  const featureDir = path.join(root, AIA_DIR, 'features', name);
+
+  if (await fs.pathExists(featureDir)) {
+    throw new Error(`Feature "${name}" already exists.`);
+  }
+
+  await fs.ensureDir(featureDir);
+
+  for (const file of FEATURE_FILES) {
+    const filePath = path.join(featureDir, file);
+    const content = file === 'status.yaml' ? buildStatusYaml(name) : '';
+    await fs.writeFile(filePath, content, 'utf-8');
+  }
+}

package/src/services/model-call.js

@@ -0,0 +1,11 @@
+import chalk from 'chalk';
+import { resolveModelAlias } from '../providers/registry.js';
+
+export async function callModel(model, prompt) {
+  const resolved = resolveModelAlias(model);
+  const displayName = resolved.model ?? `${model} (CLI default)`;
+
+  console.log(chalk.yellow(`[AI] Calling ${displayName}...`));
+
+  return resolved.provider.generate(prompt, resolved.model);
+}

package/src/services/repo-scan.js

@@ -0,0 +1,59 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { AIA_DIR, SCAN_IGNORE, SCAN_CATEGORIES } from '../constants.js';
+
+const CODE_EXTENSIONS = new Set([
+  '.js', '.mjs', '.cjs',
+  '.ts', '.mts', '.cts',
+  '.jsx', '.tsx',
+  '.json',
+]);
+
+async function walk(dir, root) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    if (SCAN_IGNORE.has(entry.name)) continue;
+
+    const fullPath = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push(...await walk(fullPath, root));
+    } else if (entry.isFile() && CODE_EXTENSIONS.has(path.extname(entry.name))) {
+      files.push(path.relative(root, fullPath));
+    }
+  }
+
+  return files;
+}
+
+function categorize(files) {
+  const map = {};
+
+  for (const file of files) {
+    for (const [category, pattern] of Object.entries(SCAN_CATEGORIES)) {
+      if (pattern.test(file)) {
+        (map[category] ??= []).push(file);
+        break;
+      }
+    }
+  }
+
+  for (const key of Object.keys(map)) {
+    map[key].sort();
+  }
+
+  return map;
+}
+
+export async function scanRepo(root = process.cwd()) {
+  const files = (await walk(root, root)).sort();
+  const map = categorize(files);
+
+  const outputPath = path.join(root, AIA_DIR, 'repo-map.json');
+  await fs.ensureDir(path.dirname(outputPath));
+  await fs.writeJson(outputPath, map, { spaces: 2 });
+
+  return { map, total: files.length, outputPath };
+}

package/src/services/runner.js

@@ -0,0 +1,46 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import chalk from 'chalk';
+import { AIA_DIR, FEATURE_STEPS, STEP_STATUS } from '../constants.js';
+import { resolveModel } from '../models.js';
+import { buildPrompt } from '../prompt-builder.js';
+import { callModel } from './model-call.js';
+import { loadStatus, updateStepStatus } from './status.js';
+import { logExecution } from '../logger.js';
+
+export async function runStep(step, feature, root = process.cwd()) {
+  if (!FEATURE_STEPS.includes(step)) {
+    throw new Error(`Unknown step "${step}". Valid steps: ${FEATURE_STEPS.join(', ')}`);
+  }
+
+  const status = await loadStatus(feature, root);
+
+  if (status.steps[step] === STEP_STATUS.DONE) {
+    throw new Error(
+      `Step "${step}" already done for feature "${feature}". Use "aia reset ${step} ${feature}" to re-run.`,
+    );
+  }
+
+  await updateStepStatus(feature, step, STEP_STATUS.IN_PROGRESS, root);
+
+  try {
+    const model = await resolveModel(step, root);
+    const prompt = await buildPrompt(feature, step, root);
+
+    const start = performance.now();
+    const output = await callModel(model, prompt);
+    const duration = performance.now() - start;
+
+    const outputPath = path.join(root, AIA_DIR, 'features', feature, `${step}.md`);
+    await fs.writeFile(outputPath, output, 'utf-8');
+
+    await updateStepStatus(feature, step, STEP_STATUS.DONE, root);
+    await logExecution({ feature, step, model, duration }, root);
+
+    console.log(chalk.green(`Step "${step}" completed for feature "${feature}".`));
+    return output;
+  } catch (err) {
+    await updateStepStatus(feature, step, STEP_STATUS.ERROR, root);
+    throw err;
+  }
+}

package/src/services/scaffold.js

@@ -0,0 +1,9 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { AIA_DIR, AIA_FOLDERS } from '../constants.js';
+
+export async function createAiaStructure(root = process.cwd()) {
+  for (const folder of AIA_FOLDERS) {
+    await fs.ensureDir(path.join(root, AIA_DIR, folder));
+  }
+}

package/src/services/status.js

@@ -0,0 +1,70 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import yaml from 'yaml';
+import { AIA_DIR, FEATURE_STEPS, STEP_STATUS } from '../constants.js';
+
+function statusPath(feature, root) {
+  return path.join(root, AIA_DIR, 'features', feature, 'status.yaml');
+}
+
+function validateStatus(status, feature) {
+  if (!status || typeof status !== 'object') {
+    throw new Error(`Corrupted status.yaml for feature "${feature}".`);
+  }
+  if (!status.steps || typeof status.steps !== 'object') {
+    throw new Error(`Missing "steps" in status.yaml for feature "${feature}".`);
+  }
+}
+
+export async function loadStatus(feature, root = process.cwd()) {
+  const filePath = statusPath(feature, root);
+
+  if (!(await fs.pathExists(filePath))) {
+    throw new Error(`Feature "${feature}" not found.`);
+  }
+
+  const raw = await fs.readFile(filePath, 'utf-8');
+  const status = yaml.parse(raw);
+
+  validateStatus(status, feature);
+
+  return status;
+}
+
+export async function updateStepStatus(feature, step, value, root = process.cwd()) {
+  const status = await loadStatus(feature, root);
+
+  status.steps[step] = value;
+
+  const stepIndex = FEATURE_STEPS.indexOf(step);
+  const nextStep = FEATURE_STEPS[stepIndex + 1] ?? null;
+  if (value === STEP_STATUS.DONE && nextStep) {
+    status.current_step = nextStep;
+  }
+
+  const content = yaml.stringify(status);
+  await fs.writeFile(statusPath(feature, root), content, 'utf-8');
+}
+
+export async function resetStep(feature, step, root = process.cwd()) {
+  if (!FEATURE_STEPS.includes(step)) {
+    throw new Error(`Unknown step "${step}". Valid steps: ${FEATURE_STEPS.join(', ')}`);
+  }
+
+  const status = await loadStatus(feature, root);
+
+  status.steps[step] = STEP_STATUS.PENDING;
+
+  const firstPending = FEATURE_STEPS.find((s) => status.steps[s] !== STEP_STATUS.DONE);
+  if (firstPending) {
+    status.current_step = firstPending;
+  }
+
+  const content = yaml.stringify(status);
+  await fs.writeFile(statusPath(feature, root), content, 'utf-8');
+
+  const outputPath = path.join(root, AIA_DIR, 'features', feature, `${step}.md`);
+  if (await fs.pathExists(outputPath)) {
+    await fs.writeFile(outputPath, '', 'utf-8');
+  }
+}

package/src/utils.js

@@ -0,0 +1,8 @@
+import fs from 'fs-extra';
+
+export async function readIfExists(filePath) {
+  if (await fs.pathExists(filePath)) {
+    return (await fs.readFile(filePath, 'utf-8')).trim();
+  }
+  return '';
+}