ai-development-protocol 1.0.0

package/dist/cli.js

@@ -0,0 +1,1163 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import path9 from "path";
+
+// src/core/init.ts
+import fs2 from "fs";
+import path3 from "path";
+
+// src/core/constants.ts
+import path from "path";
+var AI_DIR = ".ai";
+var CONTEXT_DIR = path.join(AI_DIR, "context");
+var DECISIONS_DIR = path.join(AI_DIR, "decisions");
+var TASKS_DIR = path.join(AI_DIR, "tasks");
+var REPORTS_DIR = path.join(AI_DIR, "reports");
+var TASKS_SUBDIRS = ["planned", "active", "completed"];
+var REPORTS_SUBDIRS = ["reviews", "security", "testing"];
+var REQUIRED_CONTEXT_FILES = [
+  "project.md",
+  "requirements.md",
+  "architecture.md",
+  "development.md",
+  "operations.md"
+];
+
+// src/utils/fs.ts
+import fs from "fs";
+import path2 from "path";
+function findProjectRoot(startDir = process.cwd()) {
+  let current = path2.resolve(startDir);
+  while (true) {
+    if (fs.existsSync(path2.join(current, ".ai"))) {
+      return current;
+    }
+    if (fs.existsSync(path2.join(current, "agent.md"))) {
+      return current;
+    }
+    if (fs.existsSync(path2.join(current, ".git"))) {
+      return current;
+    }
+    const parent = path2.dirname(current);
+    if (parent === current) {
+      return path2.resolve(startDir);
+    }
+    current = parent;
+  }
+}
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+function slugify(text) {
+  return text.toLowerCase().trim().replace(/[^\w\s-]/g, "").replace(/[\s_-]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function writeFileAtomic(filePath, content) {
+  ensureDir(path2.dirname(filePath));
+  fs.writeFileSync(filePath, content, "utf-8");
+}
+
+// src/templates/readme.ts
+function generateReadme(projectName = "Project") {
+  return `# AI Project Knowledge Base (${projectName})
+
+This directory maintains the living engineering knowledge for **${projectName}**, following the **AI Project Development Protocol (v1.0.0)**.
+
+## How This Works
+
+1. **Conversation is the Primary Interface**: The project owner interacts through natural dialogue.
+2. **AI-Maintained**: The AI agent creates, updates, and synchronizes these artifacts progressively as decisions are confirmed.
+3. **Living Knowledge**: Designed to be accumulative, preserving context, architectural decisions, and tasks without documentation drift.
+
+## Directory Structure
+
+\`\`\`text
+.ai/
+\u251C\u2500\u2500 README.md              # This guide
+\u251C\u2500\u2500 context/               # Authoritative system context
+\u2502   \u251C\u2500\u2500 project.md         # Identity, scope, state, and goals
+\u2502   \u251C\u2500\u2500 requirements.md    # Requirements, assumptions, and open questions
+\u2502   \u251C\u2500\u2500 architecture.md    # System structure, components, boundaries
+\u2502   \u251C\u2500\u2500 development.md     # Conventions, workflows, testing rules
+\u2502   \u2514\u2500\u2500 operations.md      # Deployment, environments, runbooks
+\u251C\u2500\u2500 decisions/             # Architecture Decision Records (ADRs)
+\u251C\u2500\u2500 tasks/                 # Actionable work breakdown
+\u2502   \u251C\u2500\u2500 planned/           # Ready to be started
+\u2502   \u251C\u2500\u2500 active/            # Currently in progress
+\u2502   \u2514\u2500\u2500 completed/         # Done and validated
+\u2514\u2500\u2500 reports/               # Periodic evaluation records
+    \u251C\u2500\u2500 reviews/           # Code and design reviews
+    \u251C\u2500\u2500 security/          # Security audits
+    \u2514\u2500\u2500 testing/           # Test summaries
+\`\`\`
+
+## Protocol Reference
+
+See \`agent.md\` in the project root for the complete specification.
+`;
+}
+
+// src/templates/project.ts
+function generateProjectContext(meta = {}) {
+  const name = meta.name || "My Project";
+  const purpose = meta.purpose || "To be defined through discovery.";
+  const problem = meta.problem || "To be identified through conversation.";
+  const targetUsers = meta.targetUsers || "To be determined.";
+  const valueProposition = meta.valueProposition || "To be articulated.";
+  return `# Project Identity & State
+
+## 1. Project Identity
+
+* **Project Name:** ${name}
+* **Purpose:** ${purpose}
+* **Problem:** ${problem}
+* **Target Users:** ${targetUsers}
+* **Value Proposition:** ${valueProposition}
+
+---
+
+## 2. Product Scope
+
+### Current Goals
+- [ ] Initialize project foundation and requirements discovery.
+
+### MVP Scope
+*To be defined.*
+
+### Future Possibilities
+*To be explored.*
+
+### Out of Scope
+*To be established.*
+
+---
+
+## 3. Project State
+
+* **Current Goal:** Establish problem and user requirements.
+* **Current Phase:** Level 1 \u2014 DISCOVERY
+* **Confirmed Decisions:** Initial protocol structure established.
+* **Active Work:** Initial discovery.
+* **Open Questions:** See \`requirements.md\`.
+* **Deferred Work:** None yet.
+* **Known Constraints:** None yet.
+* **Known Risks:** None identified.
+`;
+}
+
+// src/templates/requirements.ts
+function generateRequirementsContext() {
+  return `# Requirements & Discovery
+
+## 1. Functional Requirements
+
+*Each requirement should preserve rationale (Reason) and confirmation status.*
+
+*No confirmed functional requirements yet.*
+
+---
+
+## 2. Non-Functional Requirements
+
+* **Performance:** Standard expectations.
+* **Security:** Secure by default.
+* **Maintainability:** Modular and clean code standards.
+
+---
+
+## 3. Constraints & Assumptions
+
+### Constraints
+* None established.
+
+### Assumptions
+* None established.
+
+---
+
+## 4. Open Questions
+
+<!-- Questions being explored. When answered, move to confirmed decisions and remove from here. -->
+
+- What is the primary problem this project solves?
+- Who is the initial target audience?
+- What are the absolute minimum features required for the MVP?
+`;
+}
+
+// src/templates/architecture.ts
+function generateArchitectureContext() {
+  return `# Architecture & System Design
+
+## 1. System Overview
+
+*A high-level summary of the architecture once established.*
+
+---
+
+## 2. Core Components & Boundaries
+
+*To be defined.*
+
+---
+
+## 3. Technology Stack
+
+* **Runtime / Language:** To be determined.
+* **Storage / Database:** To be determined.
+* **Frameworks / Libraries:** To be determined.
+
+---
+
+## 4. Architectural Decisions Index
+
+*See \`.ai/decisions/\` for detailed ADRs.*
+
+| ID | Title | Status | Date |
+|---|---|---|---|
+| - | No ADRs created yet | - | - |
+`;
+}
+
+// src/templates/development.ts
+function generateDevelopmentContext() {
+  return `# Development Workflow & Conventions
+
+## 1. Environment & Setup
+
+*Prerequisites and commands to get started.*
+
+---
+
+## 2. Coding Conventions
+
+* Code style, linting, formatting rules, and naming conventions.
+
+---
+
+## 3. Implementation Workflow
+
+Before implementing significant features:
+1. Understand the requirement.
+2. Inspect existing implementation.
+3. Identify affected components and boundaries.
+4. Check relevant architecture and ADRs.
+5. Identify dependencies and risks.
+6. Produce a concise implementation approach.
+7. Implement cleanly.
+8. Validate (tests, build, type checks).
+
+---
+
+## 4. Testing & Validation Strategy
+
+* Test commands, coverage expectations, and verification steps.
+`;
+}
+
+// src/templates/operations.ts
+function generateOperationsContext() {
+  return `# Operations & Deployment
+
+## 1. Deployment Strategy
+
+*Target hosting, CI/CD pipelines, containerization, and release process.*
+
+---
+
+## 2. Environment Configuration
+
+*Required environment variables and secret management.*
+
+---
+
+## 3. Observability & Monitoring
+
+*Logging standards, health checks, metrics, and error alerting.*
+`;
+}
+
+// src/templates/agentBridge.ts
+function generateAgentBridge(projectName = "Project") {
+  return `# AI Coding Assistant Instructions
+
+You are the AI engineering partner for **${projectName}**, operating under the **AI Project Development Protocol** specified in \`agent.md\`.
+
+---
+
+## \u{1F680} Session Initialization (Every Fresh Session)
+
+Whenever a new conversation session starts:
+
+1. **Check Project State First**:
+   - Inspect \`.ai/context/project.md\` and \`.ai/context/requirements.md\` (or run \`npx aidp status\`).
+   - Identify: Current Phase, Current Goal, Active Tasks, and Open Questions.
+
+2. **If This Is a Brand New / Greenfield Project (Level 0 or Level 1)**:
+   - Proactively greet the project owner:
+     > *"Tell me what you're thinking about. It doesn't need to be fully defined. We'll progressively turn the idea into a product, requirements, architecture, and implementation plan."*
+   - Guide the owner through discovery: problem, target users, core workflow, and MVP boundary.
+   - Do NOT start generating large boilerplate code until the core idea and architecture are confirmed.
+
+3. **If the Project Is Already Underway (Level 2+)**:
+   - Briefly summarize where the project currently stands based on \`.ai/context/project.md\` and active tasks.
+   - Ask how the owner would like to proceed with the active or planned tasks.
+
+---
+
+## \u{1F4CB} Core Operating Rules (from \`agent.md\`)
+
+* **Conversation is the Primary Interface**: The project owner interacts through chat; you (the AI) maintain the \`.ai/\` artifacts automatically.
+* **Brainstorming vs. Decisions**: Treat exploratory ideas as proposals. Only record ADRs when the owner explicitly confirms a technical choice.
+* **Preserve Reasoning**: Every architectural choice must be recorded as an ADR with Problem, Options, Decision, and Consequences.
+* **Implementation Boundary**: Do not write production code until the owner signals clear implementation intent (e.g. *"Build it"*, *"Let's implement this"*).
+* **Validation Truth**: Always run real tests and build commands in the terminal before marking any task as complete. Never claim validation that was not run.
+`;
+}
+
+// src/core/init.ts
+import { fileURLToPath } from "url";
+function initProtocol(options = {}) {
+  const root = path3.resolve(options.targetDir || process.cwd());
+  const aiPath = path3.join(root, AI_DIR);
+  const isAlreadyInit = fs2.existsSync(aiPath);
+  const createdFiles = [];
+  const skippedFiles = [];
+  ensureDir(aiPath);
+  ensureDir(path3.join(root, CONTEXT_DIR));
+  ensureDir(path3.join(root, DECISIONS_DIR));
+  for (const sub of TASKS_SUBDIRS) {
+    ensureDir(path3.join(root, TASKS_DIR, sub));
+  }
+  for (const sub of REPORTS_SUBDIRS) {
+    ensureDir(path3.join(root, REPORTS_DIR, sub));
+  }
+  const projectName = options.projectName || path3.basename(root);
+  const bridgeContent = generateAgentBridge(projectName);
+  const files = {
+    [path3.join(root, AI_DIR, "README.md")]: generateReadme(projectName),
+    [path3.join(root, CONTEXT_DIR, "project.md")]: generateProjectContext({
+      name: projectName,
+      ...options.meta
+    }),
+    [path3.join(root, CONTEXT_DIR, "requirements.md")]: generateRequirementsContext(),
+    [path3.join(root, CONTEXT_DIR, "architecture.md")]: generateArchitectureContext(),
+    [path3.join(root, CONTEXT_DIR, "development.md")]: generateDevelopmentContext(),
+    [path3.join(root, CONTEXT_DIR, "operations.md")]: generateOperationsContext()
+  };
+  if (options.includeBridges !== false) {
+    files[path3.join(root, "AGENTS.md")] = bridgeContent;
+    files[path3.join(root, "CLAUDE.md")] = bridgeContent;
+    files[path3.join(root, ".cursorrules")] = bridgeContent;
+    files[path3.join(root, ".github", "copilot-instructions.md")] = bridgeContent;
+    const rootAgentMd = path3.join(root, "agent.md");
+    if (!fs2.existsSync(rootAgentMd) || options.force) {
+      try {
+        const sourceAgentMd = fileURLToPath(new URL("../../agent.md", import.meta.url));
+        if (fs2.existsSync(sourceAgentMd)) {
+          files[rootAgentMd] = fs2.readFileSync(sourceAgentMd, "utf-8");
+        }
+      } catch {
+      }
+    }
+  }
+  for (const [filePath, content] of Object.entries(files)) {
+    if (fs2.existsSync(filePath) && !options.force) {
+      skippedFiles.push(path3.relative(root, filePath));
+    } else {
+      writeFileAtomic(filePath, content);
+      createdFiles.push(path3.relative(root, filePath));
+    }
+  }
+  const emptyDirs = [
+    path3.join(root, DECISIONS_DIR),
+    ...TASKS_SUBDIRS.map((s) => path3.join(root, TASKS_DIR, s)),
+    ...REPORTS_SUBDIRS.map((s) => path3.join(root, REPORTS_DIR, s))
+  ];
+  for (const dir of emptyDirs) {
+    const keepPath = path3.join(dir, ".gitkeep");
+    if (!fs2.existsSync(keepPath) && fs2.readdirSync(dir).length === 0) {
+      writeFileAtomic(keepPath, "");
+    }
+  }
+  return {
+    aiPath,
+    createdFiles,
+    skippedFiles,
+    alreadyInitialized: isAlreadyInit && !options.force
+  };
+}
+
+// src/core/status.ts
+import fs6 from "fs";
+import path7 from "path";
+
+// src/core/adr.ts
+import fs3 from "fs";
+import path4 from "path";
+
+// src/templates/adr.ts
+function generateAdr(options) {
+  const padId = String(options.id).padStart(4, "0");
+  const dateStr = options.date || (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const status = options.status || "Accepted";
+  const problem = options.problem || "Describe the architectural context and problem here.";
+  const optionsList = options.options && options.options.length > 0 ? options.options.map((opt, i) => `${i + 1}. **${opt}**`).join("\n") : "1. **Option 1:** Description\n2. **Option 2:** Description";
+  const decision = options.decision || "Describe the decision made and rationale.";
+  const consequences = options.consequences || "Describe positive and negative implications.";
+  return `# ADR-${padId}: ${options.title}
+
+* **Status:** ${status}
+* **Date:** ${dateStr}
+* **Deciders:** AI & Project Owner
+
+## 1. Problem
+${problem}
+
+## 2. Options Considered
+${optionsList}
+
+## 3. Trade-offs
+*Pros and cons evaluated during discussion.*
+
+## 4. Decision
+${decision}
+
+## 5. Consequences
+${consequences}
+`;
+}
+
+// src/core/adr.ts
+function listAdrs(projectRoot = findProjectRoot()) {
+  const decisionsPath = path4.join(projectRoot, DECISIONS_DIR);
+  if (!fs3.existsSync(decisionsPath)) {
+    return [];
+  }
+  const files = fs3.readdirSync(decisionsPath).filter((f) => f.endsWith(".md") && /^\d{4}-/.test(f)).sort();
+  const records = [];
+  for (const filename of files) {
+    const filePath = path4.join(decisionsPath, filename);
+    const content = fs3.readFileSync(filePath, "utf-8");
+    const idMatch = filename.match(/^(\d{4})/);
+    const id = idMatch ? parseInt(idMatch[1], 10) : 0;
+    const formattedId = idMatch ? idMatch[1] : "0000";
+    const titleMatch = content.match(/^#\s+ADR-\d+:\s*(.+)$/m);
+    const title2 = titleMatch ? titleMatch[1].trim() : filename.replace(/^\d{4}-|\.md$/g, "");
+    const statusMatch = content.match(/\*\s*\*\*Status:\*\*\s*(.+)$/m);
+    const status = statusMatch ? statusMatch[1].trim() : "Unknown";
+    const dateMatch = content.match(/\*\s*\*\*Date:\*\*\s*(.+)$/m);
+    const date = dateMatch ? dateMatch[1].trim() : "";
+    records.push({
+      id,
+      formattedId,
+      title: title2,
+      status,
+      date,
+      filename,
+      filePath
+    });
+  }
+  return records;
+}
+function getNextAdrId(projectRoot = findProjectRoot()) {
+  const adrs = listAdrs(projectRoot);
+  if (adrs.length === 0) return 1;
+  const maxId = Math.max(...adrs.map((a) => a.id));
+  return maxId + 1;
+}
+function createAdr(options) {
+  const root = options.projectRoot || findProjectRoot();
+  const nextId = getNextAdrId(root);
+  const formattedId = String(nextId).padStart(4, "0");
+  const slug = slugify(options.title);
+  const filename = `${formattedId}-${slug}.md`;
+  const decisionsPath = path4.join(root, DECISIONS_DIR);
+  ensureDir(decisionsPath);
+  const filePath = path4.join(decisionsPath, filename);
+  const content = generateAdr({
+    ...options,
+    id: nextId
+  });
+  writeFileAtomic(filePath, content);
+  syncAdrWithArchitecture(root, {
+    formattedId,
+    title: options.title,
+    status: options.status || "Accepted",
+    date: options.date || (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
+    filename
+  });
+  return {
+    id: nextId,
+    formattedId,
+    title: options.title,
+    status: options.status || "Accepted",
+    date: options.date || (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
+    filename,
+    filePath
+  };
+}
+function syncAdrWithArchitecture(projectRoot, adr) {
+  const archFile = path4.join(projectRoot, CONTEXT_DIR, "architecture.md");
+  if (!fs3.existsSync(archFile)) return;
+  let content = fs3.readFileSync(archFile, "utf-8");
+  const tableHeaderRegex = /(\| ID \| Title \| Status \| Date \|\r?\n\|---\|---\|---\|---\|\r?\n)([\s\S]*?)(?=\r?\n#|$)/;
+  const row = `| [ADR-${adr.formattedId}](../decisions/${adr.filename}) | ${adr.title} | ${adr.status} | ${adr.date} |`;
+  if (tableHeaderRegex.test(content)) {
+    content = content.replace(tableHeaderRegex, (match, header, body) => {
+      let rows = body.split(/\r?\n/).map((r) => r.trim()).filter((r) => r.length > 0 && !r.includes("No ADRs created yet"));
+      rows.push(row);
+      return `${header}${rows.join("\n")}
+`;
+    });
+    writeFileAtomic(archFile, content);
+  }
+}
+
+// src/core/task.ts
+import fs4 from "fs";
+import path5 from "path";
+
+// src/templates/task.ts
+function generateTask(options) {
+  const status = options.status || "planned";
+  const createdDate = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const goal = options.goal || "Describe the objective of this task.";
+  const reqRef = options.requirementsRef || "Refer to requirements.md";
+  const archRef = options.architectureRef || "Refer to architecture.md";
+  const stepsList = options.steps && options.steps.length > 0 ? options.steps.map((s) => `- [ ] ${s}`).join("\n") : "- [ ] Step 1: Design and setup\n- [ ] Step 2: Implementation\n- [ ] Step 3: Tests";
+  const validationList = options.validation && options.validation.length > 0 ? options.validation.map((v) => `- [ ] ${v}`).join("\n") : "- [ ] Unit and integration tests pass\n- [ ] Working behavior validated";
+  return `# ${options.id.toUpperCase()}: ${options.title}
+
+* **Status:** ${status.toUpperCase()}
+* **Created:** ${createdDate}
+* **Category:** Implementation
+
+## Goal
+${goal}
+
+## Requirements Reference
+${reqRef}
+
+## Architecture Reference
+${archRef}
+
+## Implementation Steps
+${stepsList}
+
+## Validation Criteria
+${validationList}
+`;
+}
+
+// src/core/task.ts
+function listTasks(projectRoot = findProjectRoot()) {
+  const result = {
+    planned: [],
+    active: [],
+    completed: []
+  };
+  const tasksBase = path5.join(projectRoot, TASKS_DIR);
+  if (!fs4.existsSync(tasksBase)) {
+    return result;
+  }
+  for (const status of TASKS_SUBDIRS) {
+    const dir = path5.join(tasksBase, status);
+    if (!fs4.existsSync(dir)) continue;
+    const files = fs4.readdirSync(dir).filter((f) => f.endsWith(".md"));
+    for (const filename of files) {
+      const filePath = path5.join(dir, filename);
+      const content = fs4.readFileSync(filePath, "utf-8");
+      const titleMatch = content.match(/^#\s+([^:]+):\s*(.+)$/m);
+      const id = titleMatch ? titleMatch[1].trim() : filename.replace(/\.md$/, "");
+      const title2 = titleMatch ? titleMatch[2].trim() : filename.replace(/\.md$/, "");
+      result[status].push({
+        id,
+        title: title2,
+        status,
+        filename,
+        filePath
+      });
+    }
+  }
+  return result;
+}
+function getNextTaskId(projectRoot = findProjectRoot()) {
+  const all = listTasks(projectRoot);
+  const allTasks = [...all.planned, ...all.active, ...all.completed];
+  let maxNum = 0;
+  for (const t of allTasks) {
+    const m = t.filename.match(/task-(\d+)/i) || t.id.match(/task-(\d+)/i);
+    if (m) {
+      const num = parseInt(m[1], 10);
+      if (num > maxNum) maxNum = num;
+    }
+  }
+  return `TASK-${String(maxNum + 1).padStart(4, "0")}`;
+}
+function createTask(options) {
+  const root = options.projectRoot || findProjectRoot();
+  const id = options.id || getNextTaskId(root);
+  const status = options.status || "planned";
+  const slug = slugify(options.title);
+  const filename = `${id.toLowerCase()}-${slug}.md`;
+  const destDir = path5.join(root, TASKS_DIR, status);
+  ensureDir(destDir);
+  const filePath = path5.join(destDir, filename);
+  const content = generateTask({
+    ...options,
+    id,
+    status
+  });
+  writeFileAtomic(filePath, content);
+  return {
+    id,
+    title: options.title,
+    status,
+    filename,
+    filePath
+  };
+}
+function moveTask(taskIdOrName, newStatus, projectRoot = findProjectRoot()) {
+  const all = listTasks(projectRoot);
+  let found = null;
+  const search = taskIdOrName.toLowerCase();
+  for (const status of TASKS_SUBDIRS) {
+    const match = all[status].find(
+      (t) => t.id.toLowerCase() === search || t.filename.toLowerCase().includes(search)
+    );
+    if (match) {
+      found = match;
+      break;
+    }
+  }
+  if (!found) {
+    throw new Error(`Task matching "${taskIdOrName}" was not found.`);
+  }
+  if (found.status === newStatus) {
+    return found;
+  }
+  const oldPath = found.filePath;
+  const newDir = path5.join(projectRoot, TASKS_DIR, newStatus);
+  ensureDir(newDir);
+  const newPath = path5.join(newDir, found.filename);
+  let content = fs4.readFileSync(oldPath, "utf-8");
+  content = content.replace(/\*\s*\*\*Status:\*\*\s*(.+)$/m, `* **Status:** ${newStatus.toUpperCase()}`);
+  fs4.unlinkSync(oldPath);
+  writeFileAtomic(newPath, content);
+  return {
+    ...found,
+    status: newStatus,
+    filePath: newPath
+  };
+}
+
+// src/core/question.ts
+import fs5 from "fs";
+import path6 from "path";
+function listOpenQuestions(projectRoot = findProjectRoot()) {
+  const reqPath = path6.join(projectRoot, CONTEXT_DIR, "requirements.md");
+  if (!fs5.existsSync(reqPath)) return [];
+  const content = fs5.readFileSync(reqPath, "utf-8");
+  const sectionMatch = content.match(/## 4\. Open Questions([\s\S]*?)(?=\r?\n##|$)/);
+  if (!sectionMatch) return [];
+  const lines = sectionMatch[1].split(/\r?\n/);
+  const questions = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("- ") || trimmed.startsWith("* ")) {
+      questions.push(trimmed.slice(2).trim());
+    }
+  }
+  return questions;
+}
+function addOpenQuestion(question, projectRoot = findProjectRoot()) {
+  const reqPath = path6.join(projectRoot, CONTEXT_DIR, "requirements.md");
+  if (!fs5.existsSync(reqPath)) {
+    throw new Error(`requirements.md not found at ${reqPath}`);
+  }
+  let content = fs5.readFileSync(reqPath, "utf-8");
+  const sectionHeader = "## 4. Open Questions";
+  const idx = content.indexOf(sectionHeader);
+  if (idx === -1) {
+    content += `
+
+${sectionHeader}
+
+- ${question}
+`;
+  } else {
+    content = content.replace(/(## 4\. Open Questions[\s\S]*?)(\r?\n\r?\n##|\r?\n?$)/, (match, prefix, suffix) => {
+      return `${prefix.trimEnd()}
+- ${question}
+${suffix}`;
+    });
+  }
+  writeFileAtomic(reqPath, content);
+}
+
+// src/core/status.ts
+function getProjectStatus(projectRoot = findProjectRoot()) {
+  const projectFile = path7.join(projectRoot, CONTEXT_DIR, "project.md");
+  const isInitialized = fs6.existsSync(projectFile);
+  if (!isInitialized) {
+    return {
+      isInitialized: false,
+      name: path7.basename(projectRoot),
+      currentGoal: "Not initialized",
+      currentPhase: "Unknown",
+      adrs: [],
+      tasks: { planned: [], active: [], completed: [] },
+      openQuestions: []
+    };
+  }
+  const projectContent = fs6.readFileSync(projectFile, "utf-8");
+  const nameMatch = projectContent.match(/\*\s*\*\*Project Name:\*\*\s*(.+)$/m);
+  const name = nameMatch ? nameMatch[1].trim() : path7.basename(projectRoot);
+  const goalMatch = projectContent.match(/\*\s*\*\*Current Goal:\*\*\s*(.+)$/m);
+  const currentGoal = goalMatch ? goalMatch[1].trim() : "Unspecified";
+  const phaseMatch = projectContent.match(/\*\s*\*\*Current Phase:\*\*\s*(.+)$/m);
+  const currentPhase = phaseMatch ? phaseMatch[1].trim() : "Unknown";
+  const adrs = listAdrs(projectRoot);
+  const tasks = listTasks(projectRoot);
+  const openQuestions = listOpenQuestions(projectRoot);
+  return {
+    isInitialized: true,
+    name,
+    currentGoal,
+    currentPhase,
+    adrs,
+    tasks,
+    openQuestions
+  };
+}
+
+// src/core/validate.ts
+import fs7 from "fs";
+import path8 from "path";
+function validateProtocol(projectRoot = findProjectRoot()) {
+  const errors = [];
+  const warnings = [];
+  let checkedItems = 0;
+  const aiPath = path8.join(projectRoot, AI_DIR);
+  checkedItems++;
+  if (!fs7.existsSync(aiPath)) {
+    return {
+      valid: false,
+      errors: [`AI protocol directory '${AI_DIR}' does not exist at ${projectRoot}`],
+      warnings: [],
+      checkedItems
+    };
+  }
+  checkedItems++;
+  const readmePath = path8.join(aiPath, "README.md");
+  if (!fs7.existsSync(readmePath)) {
+    warnings.push(`Missing '${AI_DIR}/README.md' guide.`);
+  }
+  const contextPath = path8.join(projectRoot, CONTEXT_DIR);
+  checkedItems++;
+  if (!fs7.existsSync(contextPath)) {
+    errors.push(`Missing context directory at '${CONTEXT_DIR}'.`);
+  } else {
+    for (const file of REQUIRED_CONTEXT_FILES) {
+      checkedItems++;
+      const filePath = path8.join(contextPath, file);
+      if (!fs7.existsSync(filePath)) {
+        errors.push(`Missing required context file: '${path8.join(CONTEXT_DIR, file)}'.`);
+      }
+    }
+  }
+  const decisionsPath = path8.join(projectRoot, DECISIONS_DIR);
+  checkedItems++;
+  if (!fs7.existsSync(decisionsPath)) {
+    errors.push(`Missing decisions directory at '${DECISIONS_DIR}'.`);
+  } else {
+    const files = fs7.readdirSync(decisionsPath).filter((f) => f.endsWith(".md"));
+    for (const f of files) {
+      checkedItems++;
+      if (!/^\d{4}-[\w-]+\.md$/.test(f)) {
+        warnings.push(`ADR file '${f}' does not follow the naming convention: '0001-slug-title.md'.`);
+      }
+    }
+  }
+  const tasksPath = path8.join(projectRoot, TASKS_DIR);
+  checkedItems++;
+  if (!fs7.existsSync(tasksPath)) {
+    errors.push(`Missing tasks directory at '${TASKS_DIR}'.`);
+  } else {
+    for (const sub of TASKS_SUBDIRS) {
+      checkedItems++;
+      const subPath = path8.join(tasksPath, sub);
+      if (!fs7.existsSync(subPath)) {
+        errors.push(`Missing task subfolder: '${path8.join(TASKS_DIR, sub)}'.`);
+      }
+    }
+  }
+  const reportsPath = path8.join(projectRoot, REPORTS_DIR);
+  checkedItems++;
+  if (!fs7.existsSync(reportsPath)) {
+    warnings.push(`Missing reports directory at '${REPORTS_DIR}'.`);
+  } else {
+    for (const sub of REPORTS_SUBDIRS) {
+      checkedItems++;
+      const subPath = path8.join(reportsPath, sub);
+      if (!fs7.existsSync(subPath)) {
+        warnings.push(`Missing report subfolder: '${path8.join(REPORTS_DIR, sub)}'.`);
+      }
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    checkedItems
+  };
+}
+
+// src/utils/format.ts
+var isColorSupported = !process.env.NO_COLOR && (process.stdout?.isTTY ?? false);
+var colors = {
+  reset: isColorSupported ? "\x1B[0m" : "",
+  bold: isColorSupported ? "\x1B[1m" : "",
+  dim: isColorSupported ? "\x1B[2m" : "",
+  italic: isColorSupported ? "\x1B[3m" : "",
+  underline: isColorSupported ? "\x1B[4m" : "",
+  red: isColorSupported ? "\x1B[31m" : "",
+  green: isColorSupported ? "\x1B[32m" : "",
+  yellow: isColorSupported ? "\x1B[33m" : "",
+  blue: isColorSupported ? "\x1B[34m" : "",
+  magenta: isColorSupported ? "\x1B[35m" : "",
+  cyan: isColorSupported ? "\x1B[36m" : "",
+  gray: isColorSupported ? "\x1B[90m" : ""
+};
+function success(msg) {
+  return `${colors.green}\u2714${colors.reset} ${msg}`;
+}
+function info(msg) {
+  return `${colors.cyan}\u2139${colors.reset} ${msg}`;
+}
+function warn(msg) {
+  return `${colors.yellow}\u26A0${colors.reset} ${msg}`;
+}
+function error(msg) {
+  return `${colors.red}\u2716${colors.reset} ${msg}`;
+}
+function title(msg) {
+  return `${colors.bold}${colors.cyan}${msg}${colors.reset}`;
+}
+
+// src/cli.ts
+function runCli(argv) {
+  const args = argv.slice(2);
+  const command = args[0] || "help";
+  switch (command) {
+    case "init": {
+      handleInit(args.slice(1));
+      break;
+    }
+    case "status": {
+      handleStatus(args.slice(1));
+      break;
+    }
+    case "validate": {
+      handleValidate(args.slice(1));
+      break;
+    }
+    case "adr": {
+      handleAdr(args.slice(1));
+      break;
+    }
+    case "task": {
+      handleTask(args.slice(1));
+      break;
+    }
+    case "question": {
+      handleQuestion(args.slice(1));
+      break;
+    }
+    case "help":
+    case "--help":
+    case "-h":
+      printHelp();
+      break;
+    case "version":
+    case "--version":
+    case "-v":
+      console.log("aidp (AI Development Protocol CLI) v1.0.0");
+      break;
+    default:
+      console.error(error(`Unknown command: "${command}"`));
+      console.log(info("Run `aidp help` for a list of available commands."));
+      process.exit(1);
+  }
+}
+function handleInit(args) {
+  let targetDir = process.cwd();
+  let projectName;
+  let force = false;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--force" || args[i] === "-f") {
+      force = true;
+    } else if (args[i] === "--name" || args[i] === "-n") {
+      projectName = args[++i];
+    } else if (!args[i].startsWith("-")) {
+      targetDir = path9.resolve(args[i]);
+    }
+  }
+  console.log(title("Initializing AI Project Development Protocol..."));
+  const res = initProtocol({ targetDir, projectName, force });
+  if (res.createdFiles.length > 0) {
+    console.log(success(`Created ${res.createdFiles.length} file(s) in ${res.aiPath}:`));
+    for (const f of res.createdFiles) {
+      console.log(`  + ${f}`);
+    }
+  }
+  if (res.skippedFiles.length > 0) {
+    console.log(warn(`Skipped ${res.skippedFiles.length} existing file(s) (use --force to overwrite):`));
+    for (const f of res.skippedFiles) {
+      console.log(`  ~ ${f}`);
+    }
+  }
+  console.log(success("Initialization complete!"));
+}
+function handleStatus(args) {
+  const targetDir = args[0] ? path9.resolve(args[0]) : findProjectRoot();
+  const status = getProjectStatus(targetDir);
+  if (!status.isInitialized) {
+    console.log(warn(`No AI Project Development Protocol found at ${targetDir}`));
+    console.log(info("Run `aidp init` to set up the protocol."));
+    return;
+  }
+  console.log(title(`=== ${status.name} ===`));
+  console.log(`${colors.bold}Current Phase:${colors.reset}   ${status.currentPhase}`);
+  console.log(`${colors.bold}Current Goal:${colors.reset}    ${status.currentGoal}`);
+  console.log();
+  const totalTasks = status.tasks.planned.length + status.tasks.active.length + status.tasks.completed.length;
+  console.log(`${colors.bold}Tasks (${totalTasks}):${colors.reset}`);
+  console.log(`  ${colors.blue}Active (${status.tasks.active.length}):${colors.reset}`);
+  for (const t of status.tasks.active) {
+    console.log(`    * [${t.id}] ${t.title}`);
+  }
+  console.log(`  ${colors.yellow}Planned (${status.tasks.planned.length}):${colors.reset}`);
+  for (const t of status.tasks.planned) {
+    console.log(`    * [${t.id}] ${t.title}`);
+  }
+  console.log(`  ${colors.green}Completed (${status.tasks.completed.length}):${colors.reset}`);
+  for (const t of status.tasks.completed) {
+    console.log(`    * [${t.id}] ${t.title}`);
+  }
+  console.log();
+  console.log(`${colors.bold}Architectural Decisions (${status.adrs.length}):${colors.reset}`);
+  if (status.adrs.length === 0) {
+    console.log("  (None recorded yet)");
+  } else {
+    for (const adr of status.adrs) {
+      console.log(`  * ADR-${adr.formattedId}: ${adr.title} [${adr.status}] (${adr.date})`);
+    }
+  }
+  console.log();
+  console.log(`${colors.bold}Open Questions (${status.openQuestions.length}):${colors.reset}`);
+  if (status.openQuestions.length === 0) {
+    console.log("  (No open questions)");
+  } else {
+    for (const q of status.openQuestions) {
+      console.log(`  ? ${q}`);
+    }
+  }
+}
+function handleValidate(args) {
+  const targetDir = args[0] ? path9.resolve(args[0]) : findProjectRoot();
+  console.log(title("Validating AI Project Development Protocol structure..."));
+  const report = validateProtocol(targetDir);
+  if (report.warnings.length > 0) {
+    console.log(warn(`Warnings (${report.warnings.length}):`));
+    for (const w of report.warnings) {
+      console.log(`  \u26A0 ${w}`);
+    }
+  }
+  if (report.errors.length > 0) {
+    console.log(error(`Errors (${report.errors.length}):`));
+    for (const e of report.errors) {
+      console.log(`  \u2716 ${e}`);
+    }
+    console.log(error(`Validation FAILED with ${report.errors.length} error(s).`));
+    process.exit(1);
+  } else {
+    console.log(success(`Validation PASSED! Checked ${report.checkedItems} items.`));
+  }
+}
+function handleAdr(args) {
+  const sub = args[0];
+  if (sub === "list") {
+    const root = findProjectRoot();
+    const adrs = listAdrs(root);
+    console.log(title(`Architecture Decision Records (${adrs.length}):`));
+    if (adrs.length === 0) {
+      console.log(info("No ADRs found. Create one with `aidp adr new <title>`."));
+      return;
+    }
+    for (const adr of adrs) {
+      console.log(`  ADR-${adr.formattedId} [${adr.status}] - ${adr.title} (${adr.date})`);
+    }
+    return;
+  }
+  if (sub === "new") {
+    const titleParts = [];
+    let status = "Accepted";
+    for (let i = 1; i < args.length; i++) {
+      if (args[i] === "--status" && args[i + 1]) {
+        status = args[++i];
+      } else {
+        titleParts.push(args[i]);
+      }
+    }
+    const titleStr = titleParts.join(" ").trim();
+    if (!titleStr) {
+      console.error(error("Please provide a title for the ADR: `aidp adr new <title>`"));
+      process.exit(1);
+    }
+    const record = createAdr({ title: titleStr, status });
+    console.log(success(`Created ADR-${record.formattedId}: ${record.title}`));
+    console.log(info(`File saved to: ${record.filePath}`));
+    return;
+  }
+  console.error(error(`Unknown adr subcommand: "${sub}"`));
+  console.log(info("Available subcommands: `aidp adr list`, `aidp adr new <title>`"));
+  process.exit(1);
+}
+function handleTask(args) {
+  const sub = args[0];
+  if (sub === "list") {
+    const root = findProjectRoot();
+    const tasks = listTasks(root);
+    console.log(title("Project Tasks:"));
+    for (const s of ["active", "planned", "completed"]) {
+      console.log(`
+${colors.bold}${s.toUpperCase()} (${tasks[s].length}):${colors.reset}`);
+      if (tasks[s].length === 0) {
+        console.log("  (None)");
+      } else {
+        for (const t of tasks[s]) {
+          console.log(`  * [${t.id}] ${t.title}`);
+        }
+      }
+    }
+    return;
+  }
+  if (sub === "new") {
+    const titleParts = [];
+    let status = "planned";
+    let goal;
+    for (let i = 1; i < args.length; i++) {
+      if (args[i] === "--status" && args[i + 1]) {
+        status = args[++i];
+      } else if (args[i] === "--active") {
+        status = "active";
+      } else if (args[i] === "--goal" && args[i + 1]) {
+        goal = args[++i];
+      } else {
+        titleParts.push(args[i]);
+      }
+    }
+    const titleStr = titleParts.join(" ").trim();
+    if (!titleStr) {
+      console.error(error("Please provide a title for the task: `aidp task new <title>`"));
+      process.exit(1);
+    }
+    const task = createTask({ title: titleStr, status, goal });
+    console.log(success(`Created task [${task.id}] in ${task.status}: ${task.title}`));
+    console.log(info(`File saved to: ${task.filePath}`));
+    return;
+  }
+  if (sub === "move") {
+    const taskId = args[1];
+    const targetStatus = args[2];
+    if (!taskId || !targetStatus) {
+      console.error(error("Usage: `aidp task move <taskId> <planned|active|completed>`"));
+      process.exit(1);
+    }
+    if (!["planned", "active", "completed"].includes(targetStatus)) {
+      console.error(error(`Invalid status "${targetStatus}". Must be planned, active, or completed.`));
+      process.exit(1);
+    }
+    try {
+      const moved = moveTask(taskId, targetStatus);
+      console.log(success(`Moved [${moved.id}] "${moved.title}" to ${moved.status}`));
+    } catch (err) {
+      console.error(error(err.message));
+      process.exit(1);
+    }
+    return;
+  }
+  console.error(error(`Unknown task subcommand: "${sub}"`));
+  console.log(info("Available subcommands: `aidp task list`, `aidp task new <title>`, `aidp task move <id> <status>`"));
+  process.exit(1);
+}
+function handleQuestion(args) {
+  const sub = args[0];
+  if (sub === "list") {
+    const root = findProjectRoot();
+    const questions = listOpenQuestions(root);
+    console.log(title(`Open Questions (${questions.length}):`));
+    if (questions.length === 0) {
+      console.log(info("No open questions tracked."));
+      return;
+    }
+    for (const q of questions) {
+      console.log(`  ? ${q}`);
+    }
+    return;
+  }
+  if (sub === "add") {
+    const qStr = args.slice(1).join(" ").trim();
+    if (!qStr) {
+      console.error(error("Please provide a question: `aidp question add <question>`"));
+      process.exit(1);
+    }
+    addOpenQuestion(qStr);
+    console.log(success(`Added open question to requirements.md: "${qStr}"`));
+    return;
+  }
+  console.error(error(`Unknown question subcommand: "${sub}"`));
+  console.log(info("Available subcommands: `aidp question list`, `aidp question add <question>`"));
+  process.exit(1);
+}
+function printHelp() {
+  console.log(`
+${colors.bold}${colors.cyan}AI Project Development Protocol (AIDP) CLI${colors.reset}
+Version 1.0.0 \u2014 Tool-agnostic protocol automation and management
+
+${colors.bold}USAGE:${colors.reset}
+  aidp <command> [options]
+
+${colors.bold}COMMANDS:${colors.reset}
+  ${colors.green}init [path]${colors.reset}                       Scaffold the .ai/ protocol directory & context files
+      --name, -n <name>             Set project name
+      --force, -f                   Overwrite existing files
+
+  ${colors.green}status [path]${colors.reset}                     Show project state, active tasks, ADRs, questions
+  ${colors.green}validate [path]${colors.reset}                   Verify protocol directory structure & context
+
+  ${colors.green}adr list${colors.reset}                          List all Architecture Decision Records
+  ${colors.green}adr new <title> [options]${colors.reset}        Create a new numbered ADR
+      --status <status>             Status (Proposed | Accepted | Rejected | Superseded)
+
+  ${colors.green}task list${colors.reset}                         List all tasks by lifecycle status
+  ${colors.green}task new <title> [options]${colors.reset}       Create a new task specification
+      --active                      Set status to active (default: planned)
+      --goal <text>                 Set task goal
+  ${colors.green}task move <id> <status>${colors.reset}          Move task between planned | active | completed
+
+  ${colors.green}question list${colors.reset}                     List open questions from requirements.md
+  ${colors.green}question add <question>${colors.reset}           Add a new open question to requirements.md
+
+  ${colors.green}help, --help${colors.reset}                      Show this help message
+  ${colors.green}version, --version${colors.reset}                Display version number
+`);
+}
+
+// bin/cli.ts
+runCli(process.argv);
+//# sourceMappingURL=cli.js.map