@bamptee/aia-code 0.7.0 → 0.10.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.7.0",
+  "version": "0.10.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,7 @@ 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';
 
 export function createCli() {
   const program = new Command();
@@ -19,6 +20,7 @@ export function createCli() {
   registerFeatureCommand(program);
   registerRunCommand(program);
   registerNextCommand(program);
+  registerQuickCommand(program);
   registerRepoCommand(program);
   registerStatusCommand(program);
   registerResetCommand(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/init.js

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

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/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/config.js

@@ -5,6 +5,13 @@ import { AIA_DIR } from '../constants.js';
 
 const DEFAULT_CONFIG = {
   models: {
+    brief: [
+      { model: 'claude-default', weight: 1 },
+    ],
+    'ba-spec': [
+      { model: 'claude-default', weight: 0.5 },
+      { model: 'openai-default', weight: 0.5 },
+    ],
     questions: [
       { model: 'claude-default', weight: 0.5 },
       { model: 'openai-default', weight: 0.5 },
@@ -13,6 +20,19 @@ const DEFAULT_CONFIG = {
       { model: 'claude-default', weight: 0.5 },
       { model: 'openai-default', weight: 0.5 },
     ],
+    challenge: [
+      { model: 'openai-default', weight: 1 },
+    ],
+    'dev-plan': [
+      { model: 'claude-default', weight: 0.5 },
+      { model: 'openai-default', weight: 0.5 },
+    ],
+    implement: [
+      { model: 'claude-default', weight: 1 },
+    ],
+    review: [
+      { model: 'openai-default', weight: 1 },
+    ],
   },
   knowledge_default: ['backend'],
   context_files: [

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/services/prompts.js

@@ -0,0 +1,149 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { AIA_DIR, FEATURE_STEPS } from '../constants.js';
+
+const DEFAULT_PROMPTS = {
+  brief: `You are a product manager. Write a product brief for this feature.
+
+Include:
+- Problem statement: what pain point does this solve?
+- Target users: who benefits from this feature?
+- User stories: 3-5 key user stories in "As a [user], I want [goal], so that [benefit]" format
+- Success metrics: how do we measure if this feature is successful?
+- Scope: what is in scope and out of scope for v1?
+- Open questions: list any unknowns that need clarification
+
+Keep it concise and actionable. Use the project context and knowledge to align with existing architecture.`,
+
+  'ba-spec': `You are a business analyst. Write a detailed business analysis specification based on the brief.
+
+Include:
+- Functional requirements: numbered list of what the system must do
+- Non-functional requirements: performance, security, scalability expectations
+- Business rules: validation rules, edge cases, constraints
+- Data requirements: what data is needed, where it comes from, how it flows
+- User workflows: step-by-step flows for each key user story
+- Acceptance criteria: clear, testable criteria for each requirement
+- Dependencies: external systems, APIs, or teams involved
+
+Be specific and measurable. Every requirement should be testable.`,
+
+  questions: `You are a senior architect reviewing the brief and BA spec.
+
+Generate a list of critical questions that must be answered before implementation.
+
+Organize by category:
+- Architecture: system design, integration points, data flow
+- Security: authentication, authorization, data protection
+- Performance: expected load, latency requirements, caching strategy
+- UX: user interaction details, error handling, edge cases
+- Data: migration, storage, backup, retention policies
+- Infrastructure: deployment, monitoring, scaling
+- Dependencies: third-party services, API limits, licensing
+
+For each question, explain why it matters and suggest a default answer if possible.`,
+
+  'tech-spec': `You are a senior software architect. Write a detailed technical specification.
+
+Include:
+- Architecture overview: how this feature fits into the existing system
+- Data models: schemas, relationships, indexes, migrations
+- API design: endpoints, request/response formats, status codes, authentication
+- Service layer: business logic, validation, error handling
+- Integration points: external APIs, message queues, webhooks
+- Security considerations: input validation, authorization checks, rate limiting
+- Performance considerations: caching strategy, query optimization, pagination
+- Error handling: failure modes, retry strategies, fallback behavior
+- Testing strategy: unit tests, integration tests, key scenarios to cover
+
+Use the project's existing patterns from the knowledge files. Be specific with code-level details.`,
+
+  challenge: `You are a devil's advocate reviewer. Challenge the technical specification.
+
+Your job is to find weaknesses, gaps, and risks:
+- Architectural risks: single points of failure, scaling bottlenecks, coupling issues
+- Security vulnerabilities: injection risks, auth bypass, data leaks
+- Missing edge cases: race conditions, concurrent access, data corruption
+- Performance concerns: N+1 queries, missing indexes, memory leaks
+- Operational risks: deployment complexity, rollback strategy, monitoring gaps
+- Over-engineering: unnecessary complexity, premature optimization
+- Under-engineering: missing error handling, insufficient validation
+
+For each issue found:
+1. Describe the problem
+2. Explain the potential impact
+3. Suggest a concrete fix
+
+Be constructive but thorough. It's better to catch issues now than in production.`,
+
+  'dev-plan': `You are a tech lead. Create a step-by-step implementation plan.
+
+Break the work into ordered tasks that can be implemented sequentially:
+
+For each task:
+- Title: short description
+- Files: which files to create or modify
+- Details: what exactly to implement
+- Dependencies: which previous tasks must be completed first
+- Tests: what tests to write for this task
+
+Guidelines:
+- Order tasks so each one builds on the previous
+- Start with data models and migrations
+- Then services and business logic
+- Then API routes and controllers
+- Then UI components if applicable
+- End with integration tests
+- Each task should be small enough to review in isolation
+- Include exact file paths based on the project structure`,
+
+  implement: `You are a senior developer. Implement the feature following the dev-plan exactly.
+
+Rules:
+- Follow the project's existing code patterns and conventions
+- Create all files specified in the dev-plan
+- Write clean, production-ready code
+- Include proper error handling and input validation
+- Add JSDoc comments for public functions
+- Follow the naming conventions from the knowledge files
+- Write unit tests for business logic
+- Write integration tests for API endpoints
+
+Work through the dev-plan tasks in order. For each task, create or modify the specified files.
+Do not skip any task. If a task depends on a previous one, make sure the dependency is implemented first.`,
+
+  review: `You are a senior code reviewer. Review the implementation of this feature.
+
+Evaluate:
+- Correctness: does the code match the tech spec and dev plan?
+- Code quality: readability, naming, structure, DRY principle
+- Error handling: are all failure modes covered?
+- Security: input validation, SQL injection, XSS, auth checks
+- Performance: N+1 queries, missing indexes, unnecessary computations
+- Tests: coverage, edge cases, meaningful assertions
+- Documentation: are public APIs documented?
+
+For each issue found:
+- File and line reference
+- Severity: critical / warning / suggestion
+- Description of the problem
+- Suggested fix with code example
+
+End with a summary: ship / ship with fixes / needs rework.`,
+};
+
+export async function writeDefaultPrompts(root = process.cwd()) {
+  const promptsDir = path.join(root, AIA_DIR, 'prompts');
+  await fs.ensureDir(promptsDir);
+
+  for (const step of FEATURE_STEPS) {
+    const filePath = path.join(promptsDir, `${step}.md`);
+    if (await fs.pathExists(filePath)) {
+      continue;
+    }
+    const content = DEFAULT_PROMPTS[step] ?? '';
+    if (content) {
+      await fs.writeFile(filePath, content, 'utf-8');
+    }
+  }
+}