@bamptee/aia-code 0.8.0 → 1.0.0

package/README.md

@@ -35,9 +35,10 @@ Each CLI manages its own authentication. Run `claude`, `codex`, or `gemini` once
 | `aia next <feature> [description]` | Run the next pending step automatically |
 | `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 quick <name> [description]` | Quick story/ticket: dev-plan → implement → review only |
 | `aia repo scan` | Scan codebase and generate `repo-map.json` |
 
-### Options for `run` and `next`
+### Options for `run`, `next`, and `quick`
 
 | Flag | Description |
 |------|-------------|
@@ -219,6 +220,33 @@ aia run ba-spec session-replay
 aia run tech-spec session-replay
 ```
 
+#### Initial specs (`init.md`)
+
+When you create a feature, AIA generates an `init.md` file. Edit it to add your initial specs, requirements, and constraints -- this content is injected into **every step** as context:
+
+```bash
+aia feature session-replay
+# Edit .aia/features/session-replay/init.md with your specs
+aia next session-replay
+```
+
+```markdown
+<!-- .aia/features/session-replay/init.md -->
+# session-replay
+
+## Description
+Record and replay user sessions for debugging.
+
+## Existing specs
+- Capture DOM snapshots every 500ms
+- Record network requests and console logs
+- Max session duration: 30 minutes
+
+## Constraints
+- Must work with our existing React 18 + Express stack
+- Storage budget: max 5MB per session
+```
+
 #### Using `next` (recommended)
 
 `next` automatically picks the next pending step:
@@ -253,6 +281,26 @@ aia reset tech-spec session-replay
 aia run tech-spec session-replay "Add WebSocket support and rate limiting"
 ```
 
+#### Quick mode (stories & tickets)
+
+For small stories or tickets that don't need the full 8-step pipeline, use `aia quick`. It skips brief, ba-spec, questions, tech-spec, and challenge, and runs only **dev-plan → implement → review**:
+
+```bash
+# Create feature + run 3 steps in sequence
+aia quick fix-login-bug "Fix the login timeout issue on mobile"
+
+# Or create the feature first, edit init.md, then run
+aia feature fix-login-bug
+# Edit .aia/features/fix-login-bug/init.md with details
+aia quick fix-login-bug
+```
+
+The `init.md` file serves as the sole input context for the dev-plan step. Verbose and apply flags work the same way:
+
+```bash
+aia quick add-rate-limit "Add rate limiting to the /api/upload endpoint" -v
+```
+
 ### 8. Print mode vs Agent mode
 
 By default, AIA runs in **print mode** -- the AI generates text (specs, plans, reviews) saved to `.md` files.
@@ -326,7 +374,7 @@ knowledge:
 
 ## Prompt assembly
 
-When you run a step, the prompt is built from up to 6 sections:
+When you run a step, the prompt is built from up to 7 sections:
 
 ```
 === DESCRIPTION ===
@@ -338,6 +386,9 @@ When you run a step, the prompt is built from up to 6 sections:
 === KNOWLEDGE ===
 (all .md files from the knowledge categories)
 
+=== INITIAL SPECS ===
+(content of init.md -- your initial specs and requirements)
+
 === FEATURE ===
 (outputs of all prior steps for this feature)
 
@@ -368,6 +419,7 @@ src/
     feature.js            # aia feature <name>
     run.js                # aia run <step> <feature>
     next.js               # aia next <feature>
+    quick.js              # aia quick <name> [description]
     status.js             # aia status <feature>
     reset.js              # aia reset <step> <feature>
     repo.js               # aia repo scan

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bamptee/aia-code",
-  "version": "0.8.0",
+  "version": "1.0.0",
   "description": "AI Architecture Assistant - orchestrate AI-assisted development workflows via CLI tools (Claude, Codex, Gemini)",
   "type": "module",
   "license": "MIT",

package/src/cli.js

@@ -6,6 +6,8 @@ import { registerRepoCommand } from './commands/repo.js';
 import { registerStatusCommand } from './commands/status.js';
 import { registerResetCommand } from './commands/reset.js';
 import { registerNextCommand } from './commands/next.js';
+import { registerQuickCommand } from './commands/quick.js';
+import { registerUiCommand } from './commands/ui.js';
 
 export function createCli() {
   const program = new Command();
@@ -19,9 +21,11 @@ export function createCli() {
   registerFeatureCommand(program);
   registerRunCommand(program);
   registerNextCommand(program);
+  registerQuickCommand(program);
   registerRepoCommand(program);
   registerStatusCommand(program);
   registerResetCommand(program);
+  registerUiCommand(program);
 
   return program;
 }

package/src/commands/feature.js

@@ -1,5 +1,7 @@
+import path from 'node:path';
 import chalk from 'chalk';
 import { createFeature } from '../services/feature.js';
+import { AIA_DIR } from '../constants.js';
 
 export function registerFeatureCommand(program) {
   program
@@ -8,7 +10,9 @@ export function registerFeatureCommand(program) {
     .action(async (name) => {
       try {
         await createFeature(name);
+        const initPath = path.join(AIA_DIR, 'features', name, 'init.md');
         console.log(chalk.green(`Feature "${name}" created.`));
+        console.log(chalk.gray(`Edit ${initPath} to add your initial specs and requirements.`));
       } catch (err) {
         console.error(chalk.red(err.message));
         process.exit(1);

package/src/commands/quick.js

@@ -0,0 +1,62 @@
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import path from 'node:path';
+import yaml from 'yaml';
+import { AIA_DIR, FEATURE_STEPS, QUICK_STEPS, STEP_STATUS } from '../constants.js';
+import { createFeature, validateFeatureName } from '../services/feature.js';
+import { runStep } from '../services/runner.js';
+
+async function skipEarlySteps(feature, root) {
+  const statusFile = path.join(root, AIA_DIR, 'features', feature, 'status.yaml');
+  const raw = await fs.readFile(statusFile, 'utf-8');
+  const status = yaml.parse(raw);
+
+  for (const step of FEATURE_STEPS) {
+    if (!QUICK_STEPS.includes(step)) {
+      status.steps[step] = STEP_STATUS.DONE;
+    }
+  }
+  status.current_step = QUICK_STEPS[0];
+
+  await fs.writeFile(statusFile, yaml.stringify(status), 'utf-8');
+}
+
+export function registerQuickCommand(program) {
+  program
+    .command('quick <name> [description]')
+    .description('Quick story/ticket: create feature then run dev-plan → implement → review')
+    .option('-v, --verbose', 'Show AI thinking/tool usage')
+    .option('-a, --apply', 'Force agent mode (file editing) for all steps')
+    .action(async (name, description, opts) => {
+      try {
+        validateFeatureName(name);
+
+        const root = process.cwd();
+        const featureDir = path.join(root, AIA_DIR, 'features', name);
+
+        if (!(await fs.pathExists(featureDir))) {
+          await createFeature(name, root);
+          console.log(chalk.green(`Feature "${name}" created.`));
+          const initPath = path.join(AIA_DIR, 'features', name, 'init.md');
+          console.log(chalk.gray(`Using ${initPath} as input.`));
+        }
+
+        await skipEarlySteps(name, root);
+
+        for (const step of QUICK_STEPS) {
+          console.log(chalk.cyan(`\n--- Running ${step} ---\n`));
+          await runStep(step, name, {
+            description,
+            verbose: opts.verbose,
+            apply: opts.apply,
+            root,
+          });
+        }
+
+        console.log(chalk.green(`\nQuick pipeline completed for "${name}".`));
+      } catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+      }
+    });
+}

package/src/commands/ui.js

@@ -0,0 +1,19 @@
+import { execSync } from 'node:child_process';
+import { startServer } from '../ui/server.js';
+
+function openBrowser(url) {
+  const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+  try { execSync(`${cmd} ${url}`, { stdio: 'ignore' }); } catch {}
+}
+
+export function registerUiCommand(program) {
+  program
+    .command('ui')
+    .description('Launch the local web UI to manage features and config')
+    .option('-p, --port <port>', 'Port to listen on (scans from 3100 if not specified)')
+    .action(async (opts) => {
+      const port = opts.port ? parseInt(opts.port, 10) : undefined;
+      const { port: actualPort } = await startServer(port);
+      openBrowser(`http://127.0.0.1:${actualPort}`);
+    });
+}

package/src/constants.js

@@ -36,6 +36,8 @@ export const FEATURE_STEPS = [
   'review',
 ];
 
+export const QUICK_STEPS = ['dev-plan', 'implement', 'review'];
+
 export const APPLY_STEPS = new Set([
   'implement',
 ]);

package/src/prompt-builder.js

@@ -44,6 +44,11 @@ async function loadFeatureFiles(feature, step, root) {
   return sections.join('\n\n');
 }
 
+async function loadInitSpecs(feature, root) {
+  const filePath = path.join(root, AIA_DIR, 'features', feature, 'init.md');
+  return readIfExists(filePath);
+}
+
 async function loadPreviousOutput(feature, step, root) {
   const filePath = path.join(root, AIA_DIR, 'features', feature, `${step}.md`);
   return readIfExists(filePath);
@@ -75,9 +80,10 @@ async function loadPromptTemplate(step, root) {
 export async function buildPrompt(feature, step, { description, root = process.cwd() } = {}) {
   const config = await loadConfig(root);
 
-  const [context, knowledgeCategories, featureContent, previousOutput, task] = await Promise.all([
+  const [context, knowledgeCategories, initSpecs, featureContent, previousOutput, task] = await Promise.all([
     loadContextFiles(config, root),
     resolveKnowledgeCategories(feature, config, root),
+    loadInitSpecs(feature, root),
     loadFeatureFiles(feature, step, root),
     loadPreviousOutput(feature, step, root),
     loadPromptTemplate(step, root),
@@ -99,6 +105,11 @@ export async function buildPrompt(feature, step, { description, root = process.c
   parts.push('\n\n=== KNOWLEDGE ===\n');
   parts.push(knowledge || '(no knowledge)');
 
+  if (initSpecs) {
+    parts.push('\n\n=== INITIAL SPECS ===\n');
+    parts.push(initSpecs);
+  }
+
   parts.push('\n\n=== FEATURE ===\n');
   parts.push(featureContent || '(no prior steps)');
 

package/src/services/feature.js

@@ -5,6 +5,7 @@ import { AIA_DIR, FEATURE_STEPS } from '../constants.js';
 
 const FEATURE_FILES = [
   'status.yaml',
+  'init.md',
   ...FEATURE_STEPS.map((s) => `${s}.md`),
 ];
 
@@ -18,6 +19,23 @@ export function validateFeatureName(name) {
   }
 }
 
+function buildInitMd(name) {
+  return `# ${name}
+
+<!-- Describe your feature here. This file is injected into every step as context. -->
+<!-- Add any initial specs, requirements, mockups, or notes you already have. -->
+
+## Description
+
+
+## Existing specs
+
+
+## Constraints
+
+`;
+}
+
 function buildStatusYaml(name) {
   const steps = {};
   for (const step of FEATURE_STEPS) {
@@ -45,7 +63,9 @@ export async function createFeature(name, root = process.cwd()) {
 
   for (const file of FEATURE_FILES) {
     const filePath = path.join(featureDir, file);
-    const content = file === 'status.yaml' ? buildStatusYaml(name) : '';
+    let content = '';
+    if (file === 'status.yaml') content = buildStatusYaml(name);
+    else if (file === 'init.md') content = buildInitMd(name);
     await fs.writeFile(filePath, content, 'utf-8');
   }
 }

package/src/ui/api/config.js

@@ -0,0 +1,81 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import yaml from 'yaml';
+import { AIA_DIR } from '../../constants.js';
+import { json, error } from '../router.js';
+
+export function registerConfigRoutes(router) {
+  // Get config
+  router.get('/api/config', async (req, res, { root }) => {
+    const configPath = path.join(root, AIA_DIR, 'config.yaml');
+    if (!(await fs.pathExists(configPath))) {
+      return error(res, 'config.yaml not found', 404);
+    }
+    const content = await fs.readFile(configPath, 'utf-8');
+    json(res, { content, parsed: yaml.parse(content) });
+  });
+
+  // Save config
+  router.put('/api/config', async (req, res, { root, parseBody }) => {
+    const body = await parseBody();
+    const configPath = path.join(root, AIA_DIR, 'config.yaml');
+    await fs.writeFile(configPath, body.content, 'utf-8');
+    json(res, { ok: true });
+  });
+
+  // List context files
+  router.get('/api/context', async (req, res, { root }) => {
+    const dir = path.join(root, AIA_DIR, 'context');
+    if (!(await fs.pathExists(dir))) return json(res, []);
+    const files = await fs.readdir(dir);
+    json(res, files.filter(f => f.endsWith('.md')));
+  });
+
+  // Read context file
+  router.get('/api/context/:filename', async (req, res, { params, root }) => {
+    const filePath = path.join(root, AIA_DIR, 'context', params.filename);
+    if (!(await fs.pathExists(filePath))) return error(res, 'Not found', 404);
+    const content = await fs.readFile(filePath, 'utf-8');
+    json(res, { filename: params.filename, content });
+  });
+
+  // Save context file
+  router.put('/api/context/:filename', async (req, res, { params, root, parseBody }) => {
+    const body = await parseBody();
+    const filePath = path.join(root, AIA_DIR, 'context', params.filename);
+    await fs.writeFile(filePath, body.content, 'utf-8');
+    json(res, { ok: true });
+  });
+
+  // List knowledge categories
+  router.get('/api/knowledge', async (req, res, { root }) => {
+    const dir = path.join(root, AIA_DIR, 'knowledge');
+    if (!(await fs.pathExists(dir))) return json(res, []);
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    const categories = [];
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const files = await fs.readdir(path.join(dir, entry.name));
+        categories.push({ name: entry.name, files: files.filter(f => f.endsWith('.md')) });
+      }
+    }
+    json(res, categories);
+  });
+
+  // Read knowledge file
+  router.get('/api/knowledge/:category/:filename', async (req, res, { params, root }) => {
+    const filePath = path.join(root, AIA_DIR, 'knowledge', params.category, params.filename);
+    if (!(await fs.pathExists(filePath))) return error(res, 'Not found', 404);
+    const content = await fs.readFile(filePath, 'utf-8');
+    json(res, { filename: params.filename, category: params.category, content });
+  });
+
+  // Save knowledge file
+  router.put('/api/knowledge/:category/:filename', async (req, res, { params, root, parseBody }) => {
+    const body = await parseBody();
+    const filePath = path.join(root, AIA_DIR, 'knowledge', params.category, params.filename);
+    await fs.ensureDir(path.dirname(filePath));
+    await fs.writeFile(filePath, body.content, 'utf-8');
+    json(res, { ok: true });
+  });
+}

package/src/ui/api/constants.js

@@ -0,0 +1,8 @@
+import { FEATURE_STEPS, STEP_STATUS, QUICK_STEPS } from '../../constants.js';
+import { json } from '../router.js';
+
+export function registerConstantsRoutes(router) {
+  router.get('/api/constants', (req, res) => {
+    json(res, { FEATURE_STEPS, STEP_STATUS, QUICK_STEPS });
+  });
+}

package/src/ui/api/features.js

@@ -0,0 +1,98 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { AIA_DIR } from '../../constants.js';
+import { loadStatus, updateStepStatus, resetStep } from '../../services/status.js';
+import { createFeature, validateFeatureName } from '../../services/feature.js';
+import { runStep } from '../../services/runner.js';
+import { json, error } from '../router.js';
+
+export function registerFeatureRoutes(router) {
+  // List all features
+  router.get('/api/features', async (req, res, { root }) => {
+    const featuresDir = path.join(root, AIA_DIR, 'features');
+    if (!(await fs.pathExists(featuresDir))) {
+      return json(res, []);
+    }
+    const entries = await fs.readdir(featuresDir, { withFileTypes: true });
+    const features = [];
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        try {
+          const status = await loadStatus(entry.name, root);
+          features.push({ name: entry.name, ...status });
+        } catch {
+          features.push({ name: entry.name, error: true });
+        }
+      }
+    }
+    json(res, features);
+  });
+
+  // Get a single feature
+  router.get('/api/features/:name', async (req, res, { params, root }) => {
+    try {
+      const status = await loadStatus(params.name, root);
+      const featureDir = path.join(root, AIA_DIR, 'features', params.name);
+      const files = await fs.readdir(featureDir);
+      json(res, { name: params.name, ...status, files });
+    } catch (err) {
+      error(res, err.message, 404);
+    }
+  });
+
+  // Read a feature file
+  router.get('/api/features/:name/files/:filename', async (req, res, { params, root }) => {
+    const filePath = path.join(root, AIA_DIR, 'features', params.name, params.filename);
+    if (!(await fs.pathExists(filePath))) {
+      return error(res, 'File not found', 404);
+    }
+    const content = await fs.readFile(filePath, 'utf-8');
+    json(res, { filename: params.filename, content });
+  });
+
+  // Save a feature file
+  router.put('/api/features/:name/files/:filename', async (req, res, { params, root, parseBody }) => {
+    const body = await parseBody();
+    const filePath = path.join(root, AIA_DIR, 'features', params.name, params.filename);
+    await fs.writeFile(filePath, body.content, 'utf-8');
+    json(res, { ok: true });
+  });
+
+  // Create a new feature
+  router.post('/api/features', async (req, res, { root, parseBody }) => {
+    const body = await parseBody();
+    try {
+      validateFeatureName(body.name);
+      await createFeature(body.name, root);
+      json(res, { ok: true, name: body.name }, 201);
+    } catch (err) {
+      error(res, err.message, 400);
+    }
+  });
+
+  // Run a step (blocking - returns when done)
+  router.post('/api/features/:name/run/:step', async (req, res, { params, root, parseBody }) => {
+    const body = await parseBody();
+    try {
+      const output = await runStep(params.step, params.name, {
+        description: body.description,
+        verbose: false,
+        apply: body.apply || false,
+        root,
+      });
+      json(res, { ok: true, output });
+    } catch (err) {
+      error(res, err.message, 400);
+    }
+  });
+
+  // Reset a step
+  router.post('/api/features/:name/reset/:step', async (req, res, { params, root }) => {
+    try {
+      await resetStep(params.name, params.step, root);
+      json(res, { ok: true });
+    } catch (err) {
+      error(res, err.message, 400);
+    }
+  });
+}

package/src/ui/api/index.js

@@ -0,0 +1,11 @@
+import { registerFeatureRoutes } from './features.js';
+import { registerConfigRoutes } from './config.js';
+import { registerLogRoutes } from './logs.js';
+import { registerConstantsRoutes } from './constants.js';
+
+export function registerApiRoutes(router, root) {
+  registerFeatureRoutes(router);
+  registerConfigRoutes(router);
+  registerLogRoutes(router);
+  registerConstantsRoutes(router);
+}

package/src/ui/api/logs.js

@@ -0,0 +1,15 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { AIA_DIR } from '../../constants.js';
+import { json } from '../router.js';
+
+export function registerLogRoutes(router) {
+  router.get('/api/logs', async (req, res, { root }) => {
+    const logPath = path.join(root, AIA_DIR, 'logs', 'execution.log');
+    if (!(await fs.pathExists(logPath))) {
+      return json(res, { content: '' });
+    }
+    const content = await fs.readFile(logPath, 'utf-8');
+    json(res, { content });
+  });
+}

package/src/ui/public/components/config-view.js

@@ -0,0 +1,160 @@
+import React from 'react';
+import { api } from '/main.js';
+
+function YamlEditor({ title, loadFn, saveFn }) {
+  const [content, setContent] = React.useState('');
+  const [loading, setLoading] = React.useState(true);
+  const [saving, setSaving] = React.useState(false);
+  const [dirty, setDirty] = React.useState(false);
+  const [msg, setMsg] = React.useState(null);
+
+  React.useEffect(() => {
+    loadFn().then(c => setContent(c)).catch(() => setContent('')).finally(() => setLoading(false));
+  }, []);
+
+  async function save() {
+    setSaving(true);
+    setMsg(null);
+    try {
+      await saveFn(content);
+      setDirty(false);
+      setMsg({ type: 'ok', text: 'Saved.' });
+    } catch (e) {
+      setMsg({ type: 'err', text: e.message });
+    }
+    setSaving(false);
+  }
+
+  if (loading) return React.createElement('p', { className: 'text-slate-500 text-sm' }, 'Loading...');
+
+  return React.createElement('div', { className: 'space-y-2' },
+    React.createElement('div', { className: 'flex items-center justify-between' },
+      React.createElement('h3', { className: 'text-sm font-semibold text-slate-300' }, title),
+      React.createElement('div', { className: 'flex gap-2 items-center' },
+        dirty && React.createElement('span', { className: 'text-xs text-amber-400' }, 'unsaved'),
+        msg && React.createElement('span', { className: `text-xs ${msg.type === 'ok' ? 'text-emerald-400' : 'text-red-400'}` }, msg.text),
+        React.createElement('button', {
+          onClick: save,
+          disabled: saving || !dirty,
+          className: 'bg-aia-accent/20 text-aia-accent border border-aia-accent/30 rounded px-3 py-1 text-xs hover:bg-aia-accent/30 disabled:opacity-40',
+        }, saving ? '...' : 'Save'),
+      ),
+    ),
+    React.createElement('textarea', {
+      value: content,
+      onChange: e => { setContent(e.target.value); setDirty(true); },
+      spellCheck: false,
+      className: 'w-full h-72 bg-slate-900 border border-aia-border rounded p-3 text-sm text-slate-300 font-mono resize-y focus:border-aia-accent focus:outline-none',
+    })
+  );
+}
+
+function FileList({ title, files, selectedFile, onSelect }) {
+  if (!files.length) return null;
+  return React.createElement('div', { className: 'space-y-1' },
+    React.createElement('h4', { className: 'text-xs font-semibold text-slate-400 uppercase tracking-wider' }, title),
+    ...files.map(f =>
+      React.createElement('button', {
+        key: f,
+        onClick: () => onSelect(f),
+        className: `block w-full text-left px-2 py-1 text-sm rounded ${selectedFile === f ? 'bg-aia-accent/20 text-aia-accent' : 'text-slate-400 hover:text-slate-200 hover:bg-slate-800'}`,
+      }, f)
+    )
+  );
+}
+
+export function ConfigView() {
+  const [contextFiles, setContextFiles] = React.useState([]);
+  const [knowledgeCategories, setKnowledgeCategories] = React.useState([]);
+  const [selectedFile, setSelectedFile] = React.useState(null);
+  const [selectedType, setSelectedType] = React.useState(null); // 'context' | 'knowledge'
+  const [selectedCategory, setSelectedCategory] = React.useState(null);
+  const [logs, setLogs] = React.useState('');
+  const [showLogs, setShowLogs] = React.useState(false);
+
+  React.useEffect(() => {
+    api.get('/context').then(setContextFiles).catch(() => {});
+    api.get('/knowledge').then(setKnowledgeCategories).catch(() => {});
+  }, []);
+
+  function selectContext(f) {
+    setSelectedFile(f);
+    setSelectedType('context');
+    setSelectedCategory(null);
+  }
+
+  function selectKnowledge(cat, f) {
+    setSelectedFile(f);
+    setSelectedType('knowledge');
+    setSelectedCategory(cat);
+  }
+
+  async function loadLogs() {
+    try {
+      const data = await api.get('/logs');
+      setLogs(data.content || '(empty)');
+      setShowLogs(true);
+    } catch {}
+  }
+
+  return React.createElement('div', { className: 'space-y-6' },
+    React.createElement('h1', { className: 'text-xl font-bold text-slate-100' }, 'Configuration'),
+
+    // config.yaml
+    React.createElement(YamlEditor, {
+      title: 'config.yaml',
+      loadFn: async () => (await api.get('/config')).content,
+      saveFn: async (content) => api.put('/config', { content }),
+    }),
+
+    // Sidebar + editor for context/knowledge
+    React.createElement('div', { className: 'grid grid-cols-4 gap-4' },
+      // Sidebar
+      React.createElement('div', { className: 'col-span-1 space-y-4' },
+        React.createElement(FileList, {
+          title: 'Context',
+          files: contextFiles,
+          selectedFile: selectedType === 'context' ? selectedFile : null,
+          onSelect: selectContext,
+        }),
+        ...knowledgeCategories.map(cat =>
+          React.createElement(FileList, {
+            key: cat.name,
+            title: `Knowledge / ${cat.name}`,
+            files: cat.files,
+            selectedFile: selectedType === 'knowledge' && selectedCategory === cat.name ? selectedFile : null,
+            onSelect: f => selectKnowledge(cat.name, f),
+          })
+        ),
+        React.createElement('button', {
+          onClick: loadLogs,
+          className: 'text-xs text-slate-500 hover:text-slate-300 mt-4',
+        }, 'View execution logs'),
+      ),
+
+      // Editor
+      React.createElement('div', { className: 'col-span-3' },
+        selectedFile && selectedType === 'context' && React.createElement(YamlEditor, {
+          key: `ctx-${selectedFile}`,
+          title: `context/${selectedFile}`,
+          loadFn: async () => (await api.get(`/context/${selectedFile}`)).content,
+          saveFn: async (content) => api.put(`/context/${selectedFile}`, { content }),
+        }),
+        selectedFile && selectedType === 'knowledge' && React.createElement(YamlEditor, {
+          key: `kn-${selectedCategory}-${selectedFile}`,
+          title: `knowledge/${selectedCategory}/${selectedFile}`,
+          loadFn: async () => (await api.get(`/knowledge/${selectedCategory}/${selectedFile}`)).content,
+          saveFn: async (content) => api.put(`/knowledge/${selectedCategory}/${selectedFile}`, { content }),
+        }),
+        !selectedFile && !showLogs && React.createElement('p', { className: 'text-slate-500 text-sm' }, 'Select a file to edit.'),
+        showLogs && React.createElement('div', { className: 'space-y-2' },
+          React.createElement('div', { className: 'flex items-center justify-between' },
+            React.createElement('h3', { className: 'text-sm font-semibold text-slate-300' }, 'Execution Logs'),
+            React.createElement('button', { onClick: () => setShowLogs(false), className: 'text-xs text-slate-500 hover:text-slate-300' }, 'Close'),
+          ),
+          React.createElement('pre', { className: 'bg-slate-900 border border-aia-border rounded p-3 text-xs text-slate-400 overflow-auto max-h-96' }, logs),
+        ),
+      ),
+    ),
+  );
+}

package/src/ui/public/components/dashboard.js

@@ -0,0 +1,109 @@
+import React from 'react';
+import { api } from '/main.js';
+
+const STATUS_CLASSES = {
+  done: 'step-done',
+  pending: 'step-pending',
+  'in-progress': 'step-in-progress',
+  error: 'step-error',
+};
+
+function StepBadge({ step, status }) {
+  return React.createElement('span', {
+    className: `inline-block px-2 py-0.5 text-xs rounded border ${STATUS_CLASSES[status] || 'step-pending'}`,
+  }, step);
+}
+
+function FeatureCard({ feature }) {
+  const steps = feature.steps || {};
+  const doneCount = Object.values(steps).filter(s => s === 'done').length;
+  const totalCount = Object.keys(steps).length;
+
+  return React.createElement('a', {
+    href: `#/features/${feature.name}`,
+    className: 'block bg-aia-card border border-aia-border rounded-lg p-4 hover:border-aia-accent/50 transition-colors',
+  },
+    React.createElement('div', { className: 'flex items-center justify-between mb-3' },
+      React.createElement('h3', { className: 'text-slate-100 font-semibold' }, feature.name),
+      React.createElement('span', { className: 'text-xs text-slate-500' },
+        `${doneCount}/${totalCount} steps`
+      ),
+    ),
+    feature.current_step && React.createElement('p', { className: 'text-xs text-slate-400 mb-3' },
+      'Current: ', React.createElement('span', { className: 'text-aia-accent' }, feature.current_step)
+    ),
+    React.createElement('div', { className: 'flex flex-wrap gap-1.5' },
+      ...Object.entries(steps).map(([step, status]) =>
+        React.createElement(StepBadge, { key: step, step, status })
+      )
+    )
+  );
+}
+
+function NewFeatureForm({ onCreated }) {
+  const [name, setName] = React.useState('');
+  const [err, setErr] = React.useState('');
+  const [loading, setLoading] = React.useState(false);
+
+  async function handleSubmit(e) {
+    e.preventDefault();
+    setErr('');
+    setLoading(true);
+    try {
+      await api.post('/features', { name });
+      setName('');
+      onCreated();
+    } catch (e) {
+      setErr(e.message);
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return React.createElement('form', { onSubmit: handleSubmit, className: 'flex gap-2 items-start' },
+    React.createElement('div', null,
+      React.createElement('input', {
+        type: 'text',
+        value: name,
+        onChange: e => setName(e.target.value),
+        placeholder: 'feature-name',
+        className: 'bg-aia-card border border-aia-border rounded px-3 py-1.5 text-sm text-slate-200 placeholder-slate-500 focus:border-aia-accent focus:outline-none',
+      }),
+      err && React.createElement('p', { className: 'text-red-400 text-xs mt-1' }, err),
+    ),
+    React.createElement('button', {
+      type: 'submit',
+      disabled: loading || !name,
+      className: 'bg-aia-accent/20 text-aia-accent border border-aia-accent/30 rounded px-3 py-1.5 text-sm hover:bg-aia-accent/30 disabled:opacity-40',
+    }, loading ? '...' : '+ New Feature')
+  );
+}
+
+export function Dashboard() {
+  const [features, setFeatures] = React.useState([]);
+  const [loading, setLoading] = React.useState(true);
+
+  async function load() {
+    try {
+      const data = await api.get('/features');
+      setFeatures(data);
+    } catch {}
+    setLoading(false);
+  }
+
+  React.useEffect(() => { load(); }, []);
+
+  return React.createElement('div', null,
+    React.createElement('div', { className: 'flex items-center justify-between mb-6' },
+      React.createElement('h1', { className: 'text-xl font-bold text-slate-100' }, 'Features'),
+      React.createElement(NewFeatureForm, { onCreated: load }),
+    ),
+    loading
+      ? React.createElement('p', { className: 'text-slate-500' }, 'Loading...')
+      : features.length === 0
+        ? React.createElement('p', { className: 'text-slate-500' }, 'No features yet. Create one to get started.')
+        : React.createElement('div', { className: 'grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4' },
+            ...features.map(f => React.createElement(FeatureCard, { key: f.name, feature: f }))
+          )
+  );
+}

package/src/ui/public/components/feature-detail.js

@@ -0,0 +1,193 @@
+import React from 'react';
+import { api } from '/main.js';
+
+const STATUS_CLASSES = {
+  done: 'step-done',
+  pending: 'step-pending',
+  'in-progress': 'step-in-progress',
+  error: 'step-error',
+};
+
+const STATUS_ICONS = { done: '\u2713', pending: '\u00b7', 'in-progress': '\u25b6', error: '\u2717' };
+
+function StepPill({ step, status, active, onClick }) {
+  return React.createElement('button', {
+    onClick,
+    className: `px-3 py-1.5 text-xs rounded border transition-all ${STATUS_CLASSES[status] || 'step-pending'} ${active ? 'ring-2 ring-aia-accent ring-offset-1 ring-offset-aia-bg' : 'hover:brightness-125'}`,
+  }, `${STATUS_ICONS[status] || ''} ${step}`);
+}
+
+function FileEditor({ name, filename, onSaved }) {
+  const [content, setContent] = React.useState('');
+  const [loading, setLoading] = React.useState(true);
+  const [saving, setSaving] = React.useState(false);
+  const [dirty, setDirty] = React.useState(false);
+
+  React.useEffect(() => {
+    setLoading(true);
+    setDirty(false);
+    api.get(`/features/${name}/files/${filename}`)
+      .then(data => setContent(data.content))
+      .catch(() => setContent(''))
+      .finally(() => setLoading(false));
+  }, [name, filename]);
+
+  async function save() {
+    setSaving(true);
+    try {
+      await api.put(`/features/${name}/files/${filename}`, { content });
+      setDirty(false);
+      if (onSaved) onSaved();
+    } catch {}
+    setSaving(false);
+  }
+
+  if (loading) return React.createElement('p', { className: 'text-slate-500 text-sm' }, 'Loading...');
+
+  return React.createElement('div', { className: 'flex flex-col gap-2' },
+    React.createElement('div', { className: 'flex items-center justify-between' },
+      React.createElement('span', { className: 'text-sm text-slate-400' }, filename),
+      React.createElement('div', { className: 'flex gap-2' },
+        dirty && React.createElement('span', { className: 'text-xs text-amber-400' }, 'unsaved'),
+        React.createElement('button', {
+          onClick: save,
+          disabled: saving || !dirty,
+          className: 'bg-aia-accent/20 text-aia-accent border border-aia-accent/30 rounded px-3 py-1 text-xs hover:bg-aia-accent/30 disabled:opacity-40',
+        }, saving ? 'Saving...' : 'Save'),
+      ),
+    ),
+    React.createElement('textarea', {
+      value: content,
+      onChange: e => { setContent(e.target.value); setDirty(true); },
+      spellCheck: false,
+      className: 'w-full h-96 bg-slate-900 border border-aia-border rounded p-3 text-sm text-slate-300 font-mono resize-y focus:border-aia-accent focus:outline-none',
+    })
+  );
+}
+
+function RunPanel({ name, step, onDone }) {
+  const [description, setDescription] = React.useState('');
+  const [apply, setApply] = React.useState(false);
+  const [running, setRunning] = React.useState(false);
+  const [result, setResult] = React.useState(null);
+  const [error, setError] = React.useState(null);
+
+  async function run() {
+    setRunning(true);
+    setResult(null);
+    setError(null);
+    try {
+      const data = await api.post(`/features/${name}/run/${step}`, { description, apply });
+      setResult('Step completed.');
+      if (onDone) onDone();
+    } catch (e) {
+      setError(e.message);
+    }
+    setRunning(false);
+  }
+
+  async function reset() {
+    try {
+      await api.post(`/features/${name}/reset/${step}`);
+      if (onDone) onDone();
+    } catch (e) {
+      setError(e.message);
+    }
+  }
+
+  return React.createElement('div', { className: 'bg-slate-900 border border-aia-border rounded p-4 space-y-3' },
+    React.createElement('h4', { className: 'text-sm font-semibold text-slate-300' }, `Run: ${step}`),
+    React.createElement('input', {
+      type: 'text',
+      value: description,
+      onChange: e => setDescription(e.target.value),
+      placeholder: 'Optional description...',
+      className: 'w-full bg-aia-card border border-aia-border rounded px-3 py-1.5 text-sm text-slate-200 placeholder-slate-500 focus:border-aia-accent focus:outline-none',
+    }),
+    React.createElement('div', { className: 'flex items-center gap-4' },
+      React.createElement('label', { className: 'flex items-center gap-2 text-xs text-slate-400 cursor-pointer' },
+        React.createElement('input', {
+          type: 'checkbox',
+          checked: apply,
+          onChange: e => setApply(e.target.checked),
+          className: 'rounded',
+        }),
+        'Agent mode (--apply)'
+      ),
+      React.createElement('button', {
+        onClick: run,
+        disabled: running,
+        className: 'bg-emerald-500/20 text-emerald-400 border border-emerald-500/30 rounded px-4 py-1.5 text-sm hover:bg-emerald-500/30 disabled:opacity-40',
+      }, running ? 'Running...' : 'Run Step'),
+      React.createElement('button', {
+        onClick: reset,
+        disabled: running,
+        className: 'text-slate-500 hover:text-slate-300 text-xs',
+      }, 'Reset'),
+    ),
+    running && React.createElement('p', { className: 'text-amber-400 text-xs animate-pulse' }, 'Step is running... This may take a few minutes.'),
+    result && React.createElement('p', { className: 'text-emerald-400 text-xs' }, result),
+    error && React.createElement('p', { className: 'text-red-400 text-xs' }, error),
+  );
+}
+
+export function FeatureDetail({ name }) {
+  const [feature, setFeature] = React.useState(null);
+  const [loading, setLoading] = React.useState(true);
+  const [activeFile, setActiveFile] = React.useState('init.md');
+  const [activeStep, setActiveStep] = React.useState(null);
+
+  async function load() {
+    try {
+      const data = await api.get(`/features/${name}`);
+      setFeature(data);
+    } catch {}
+    setLoading(false);
+  }
+
+  React.useEffect(() => { load(); }, [name]);
+
+  if (loading) return React.createElement('p', { className: 'text-slate-500' }, 'Loading...');
+  if (!feature) return React.createElement('p', { className: 'text-red-400' }, `Feature "${name}" not found.`);
+
+  const steps = feature.steps || {};
+
+  return React.createElement('div', { className: 'space-y-6' },
+    // Header
+    React.createElement('div', { className: 'flex items-center gap-3' },
+      React.createElement('a', { href: '#/', className: 'text-slate-500 hover:text-slate-300' }, '\u2190'),
+      React.createElement('h1', { className: 'text-xl font-bold text-slate-100' }, name),
+      feature.current_step && React.createElement('span', { className: 'text-xs bg-aia-accent/20 text-aia-accent px-2 py-0.5 rounded' }, feature.current_step),
+    ),
+
+    // Pipeline
+    React.createElement('div', { className: 'flex flex-wrap gap-2' },
+      ...Object.entries(steps).map(([step, status]) =>
+        React.createElement(StepPill, {
+          key: step,
+          step,
+          status,
+          active: activeStep === step,
+          onClick: () => { setActiveStep(step); setActiveFile(`${step}.md`); },
+        })
+      )
+    ),
+
+    // Run panel
+    activeStep && React.createElement(RunPanel, { name, step: activeStep, onDone: load }),
+
+    // File tabs
+    React.createElement('div', { className: 'flex gap-1 border-b border-aia-border' },
+      ...(feature.files || []).filter(f => f.endsWith('.md') || f.endsWith('.yaml')).map(f =>
+        React.createElement('button', {
+          key: f,
+          onClick: () => setActiveFile(f),
+          className: `px-3 py-1.5 text-xs border-b-2 transition-colors ${activeFile === f ? 'border-aia-accent text-aia-accent' : 'border-transparent text-slate-500 hover:text-slate-300'}`,
+        }, f)
+      )
+    ),
+
+    // Editor
+    activeFile && React.createElement(FileEditor, { key: `${name}-${activeFile}`, name, filename: activeFile, onSaved: load }),
+  );
+}

package/src/ui/public/index.html

@@ -0,0 +1,44 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>AIA - AI Architecture Assistant</title>
+  <script src="https://cdn.tailwindcss.com"></script>
+  <script>
+    tailwind.config = {
+      theme: {
+        extend: {
+          colors: {
+            'aia-bg': '#0f172a',
+            'aia-card': '#1e293b',
+            'aia-border': '#334155',
+            'aia-accent': '#38bdf8',
+          }
+        }
+      }
+    }
+  </script>
+  <script type="importmap">
+  {
+    "imports": {
+      "react": "https://esm.sh/react@19?dev",
+      "react-dom/client": "https://esm.sh/react-dom@19/client?dev",
+      "react/jsx-runtime": "https://esm.sh/react@19/jsx-runtime?dev"
+    }
+  }
+  </script>
+  <style>
+    body { font-family: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, monospace; }
+    .step-done { @apply bg-emerald-500/20 text-emerald-400 border-emerald-500/30; }
+    .step-pending { @apply bg-slate-700/50 text-slate-400 border-slate-600; }
+    .step-in-progress { @apply bg-amber-500/20 text-amber-400 border-amber-500/30; }
+    .step-error { @apply bg-red-500/20 text-red-400 border-red-500/30; }
+    textarea { tab-size: 2; }
+  </style>
+</head>
+<body class="bg-aia-bg text-slate-200 min-h-screen">
+  <div id="root"></div>
+  <script type="module" src="/main.js"></script>
+</body>
+</html>

package/src/ui/public/main.js

@@ -0,0 +1,72 @@
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { Dashboard } from '/components/dashboard.js';
+import { FeatureDetail } from '/components/feature-detail.js';
+import { ConfigView } from '/components/config-view.js';
+
+// --- API client ---
+export const api = {
+  async get(path) {
+    const res = await fetch(`/api${path}`);
+    if (!res.ok) throw new Error((await res.json()).error || res.statusText);
+    return res.json();
+  },
+  async post(path, body = {}) {
+    const res = await fetch(`/api${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) throw new Error((await res.json()).error || res.statusText);
+    return res.json();
+  },
+  async put(path, body = {}) {
+    const res = await fetch(`/api${path}`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) throw new Error((await res.json()).error || res.statusText);
+    return res.json();
+  },
+};
+
+// --- Simple hash router ---
+function useHashRoute() {
+  const [route, setRoute] = React.useState(window.location.hash || '#/');
+  React.useEffect(() => {
+    const handler = () => setRoute(window.location.hash || '#/');
+    window.addEventListener('hashchange', handler);
+    return () => window.removeEventListener('hashchange', handler);
+  }, []);
+  return route;
+}
+
+function parseRoute(hash) {
+  if (hash.startsWith('#/features/')) {
+    return { page: 'feature', name: decodeURIComponent(hash.slice('#/features/'.length)) };
+  }
+  if (hash === '#/config') return { page: 'config' };
+  return { page: 'dashboard' };
+}
+
+// --- App ---
+function App() {
+  const hash = useHashRoute();
+  const { page, name } = parseRoute(hash);
+
+  return React.createElement('div', { className: 'min-h-screen' },
+    React.createElement('nav', { className: 'border-b border-aia-border px-6 py-3 flex items-center gap-6' },
+      React.createElement('a', { href: '#/', className: 'text-aia-accent font-bold text-lg hover:text-sky-300' }, 'AIA'),
+      React.createElement('a', { href: '#/', className: 'text-slate-400 hover:text-slate-200 text-sm' }, 'Features'),
+      React.createElement('a', { href: '#/config', className: 'text-slate-400 hover:text-slate-200 text-sm' }, 'Config'),
+    ),
+    React.createElement('main', { className: 'max-w-6xl mx-auto p-6' },
+      page === 'dashboard' ? React.createElement(Dashboard) :
+      page === 'feature' ? React.createElement(FeatureDetail, { name }) :
+      page === 'config' ? React.createElement(ConfigView) : null
+    )
+  );
+}
+
+createRoot(document.getElementById('root')).render(React.createElement(App));

package/src/ui/router.js

@@ -0,0 +1,47 @@
+export function createRouter() {
+  const routes = [];
+
+  function add(method, pattern, handler) {
+    const keys = [];
+    const regex = new RegExp(
+      '^' + pattern.replace(/:([^/]+)/g, (_, key) => { keys.push(key); return '([^/]+)'; }) + '$'
+    );
+    routes.push({ method, regex, keys, handler });
+  }
+
+  function match(method, pathname) {
+    for (const route of routes) {
+      if (route.method !== method) continue;
+      const m = pathname.match(route.regex);
+      if (m) {
+        const params = {};
+        route.keys.forEach((key, i) => { params[key] = decodeURIComponent(m[i + 1]); });
+        return { handler: route.handler, params };
+      }
+    }
+    return null;
+  }
+
+  return { add, match, get: (p, h) => add('GET', p, h), post: (p, h) => add('POST', p, h), put: (p, h) => add('PUT', p, h), delete: (p, h) => add('DELETE', p, h) };
+}
+
+export async function parseBody(req) {
+  return new Promise((resolve, reject) => {
+    let body = '';
+    req.on('data', chunk => { body += chunk; });
+    req.on('end', () => {
+      try { resolve(body ? JSON.parse(body) : {}); }
+      catch (e) { reject(new Error('Invalid JSON body')); }
+    });
+    req.on('error', reject);
+  });
+}
+
+export function json(res, data, status = 200) {
+  res.writeHead(status, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*' });
+  res.end(JSON.stringify(data));
+}
+
+export function error(res, message, status = 500) {
+  json(res, { error: message }, status);
+}

package/src/ui/server.js

@@ -0,0 +1,105 @@
+import { createServer } from 'node:http';
+import { createConnection } from 'node:net';
+import { createReadStream, existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRouter, parseBody, json, error } from './router.js';
+import { registerApiRoutes } from './api/index.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const MIME_TYPES = {
+  '.html': 'text/html',
+  '.js': 'application/javascript',
+  '.css': 'text/css',
+  '.json': 'application/json',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.ico': 'image/x-icon',
+};
+
+function serveStatic(res, filePath) {
+  const ext = path.extname(filePath);
+  const mime = MIME_TYPES[ext] || 'application/octet-stream';
+
+  if (!existsSync(filePath)) {
+    // SPA fallback: serve index.html for non-API, non-file routes
+    const indexPath = path.join(__dirname, 'public', 'index.html');
+    if (existsSync(indexPath)) {
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      createReadStream(indexPath).pipe(res);
+      return;
+    }
+    res.writeHead(404);
+    res.end('Not found');
+    return;
+  }
+
+  res.writeHead(200, { 'Content-Type': mime });
+  createReadStream(filePath).pipe(res);
+}
+
+function isPortFree(port) {
+  return new Promise((resolve) => {
+    const socket = createConnection({ port, host: '127.0.0.1' });
+    socket.once('connect', () => { socket.destroy(); resolve(false); });
+    socket.once('error', () => { resolve(true); });
+  });
+}
+
+async function findFreePort(start = 3100, maxAttempts = 50) {
+  for (let port = start; port < start + maxAttempts; port++) {
+    if (await isPortFree(port)) return port;
+  }
+  throw new Error(`No free port found between ${start} and ${start + maxAttempts - 1}`);
+}
+
+export async function startServer(preferredPort, root = process.cwd()) {
+  const port = preferredPort ?? await findFreePort();
+
+  const router = createRouter();
+  registerApiRoutes(router, root);
+
+  const server = createServer(async (req, res) => {
+    // CORS preflight
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204, {
+        'Access-Control-Allow-Origin': '*',
+        'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
+        'Access-Control-Allow-Headers': 'Content-Type',
+      });
+      res.end();
+      return;
+    }
+
+    const url = new URL(req.url, `http://${req.headers.host}`);
+    const pathname = url.pathname;
+
+    // API routes
+    if (pathname.startsWith('/api/')) {
+      const matched = router.match(req.method, pathname);
+      if (matched) {
+        try {
+          await matched.handler(req, res, { params: matched.params, query: Object.fromEntries(url.searchParams), root, parseBody: () => parseBody(req) });
+        } catch (err) {
+          error(res, err.message, 500);
+        }
+      } else {
+        error(res, 'Not found', 404);
+      }
+      return;
+    }
+
+    // Static files
+    let filePath = path.join(__dirname, 'public', pathname === '/' ? 'index.html' : pathname);
+    serveStatic(res, filePath);
+  });
+
+  return new Promise((resolve, reject) => {
+    server.on('error', reject);
+    server.listen(port, '127.0.0.1', () => {
+      console.log(`AIA UI running at http://127.0.0.1:${port}`);
+      resolve({ server, port });
+    });
+  });
+}