@oz1307/forcefully-agent 1.0.0

package/bin/cli.js

@@ -0,0 +1,672 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import dotenv from 'dotenv';
+import * as p from '@clack/prompts';
+import {
+  generateVisionDoc,
+  generateBusinessRulesDoc,
+  generateTerminologyDoc,
+  generateFeaturesDoc,
+  generateApiContractsDoc,
+  generateDatabaseSchemaDoc,
+  generateArchitectureDoc,
+  generateDefinitionsDoc,
+  generateValidationQuestion,
+  refineSingleDoc
+} from '../lib/ai.js';
+import * as templates from '../lib/templates.js';
+
+// Load existing environment variables
+dotenv.config();
+const localAgentsEnv = path.join(process.cwd(), '.env.agents');
+if (fs.existsSync(localAgentsEnv)) {
+  dotenv.config({ path: localAgentsEnv, override: true });
+}
+
+const IGNORE_DIRS = new Set([
+  'node_modules',
+  '.git',
+  '.agents',
+  '.claude',
+  '.cursor',
+  'dist',
+  'build',
+  'out',
+  'docs',
+  'coverage',
+  '.nyc_output',
+  'package-lock.json',
+  'yarn.lock',
+  'pnpm-lock.yaml'
+]);
+
+const INTERESTING_EXTS = new Set([
+  '.js', '.ts', '.jsx', '.tsx', '.py', '.go', '.rs', '.rb', '.php', '.java', '.cs', '.json', '.md'
+]);
+
+/**
+ * Scan the repository recursively to build a file tree.
+ */
+function scanRepository(dir, baseDir = dir, depth = 0) {
+  let fileTree = '';
+  let fileCount = 0;
+  let folderCount = 0;
+
+  function recurse(currentDir, currentDepth) {
+    if (currentDepth > 4 || fileCount > 150) return;
+
+    let files;
+    try {
+      files = fs.readdirSync(currentDir);
+    } catch (e) {
+      return;
+    }
+
+    for (const file of files) {
+      if (IGNORE_DIRS.has(file)) continue;
+
+      const fullPath = path.join(currentDir, file);
+      let stat;
+      try {
+        stat = fs.statSync(fullPath);
+      } catch (e) {
+        continue;
+      }
+
+      const indent = '  '.repeat(currentDepth);
+
+      if (stat.isDirectory()) {
+        fileTree += `${indent}📁 ${file}/\n`;
+        folderCount++;
+        recurse(fullPath, currentDepth + 1);
+      } else {
+        fileTree += `${indent}📄 ${file}\n`;
+        fileCount++;
+      }
+    }
+  }
+
+  recurse(dir, depth);
+  return { fileTree, fileCount, folderCount };
+}
+
+/**
+ * Gathers content snippets from files matching specific keywords.
+ */
+function gatherSnippetContext(baseDir, keywords, excludeDirs = IGNORE_DIRS) {
+  let content = '';
+  let count = 0;
+
+  function recurse(currentDir) {
+    if (count >= 6) return;
+
+    let files;
+    try {
+      files = fs.readdirSync(currentDir);
+    } catch (e) {
+      return;
+    }
+
+    for (const file of files) {
+      if (excludeDirs.has(file)) continue;
+
+      const fullPath = path.join(currentDir, file);
+      let stat;
+      try {
+        stat = fs.statSync(fullPath);
+      } catch (e) {
+        continue;
+      }
+
+      if (stat.isDirectory()) {
+        recurse(fullPath);
+      } else {
+        const ext = path.extname(file).toLowerCase();
+        if (INTERESTING_EXTS.has(ext) && stat.size < 50000) {
+          const lowerName = file.toLowerCase();
+          const matches = keywords.some(keyword => lowerName.includes(keyword));
+          if (matches) {
+            try {
+              const fileContent = fs.readFileSync(fullPath, 'utf8');
+              const relative = path.relative(baseDir, fullPath);
+              // Grab first 150 lines
+              const lines = fileContent.split('\n').slice(0, 150).join('\n');
+              content += `\n--- File: ${relative} ---\n${lines}\n`;
+              count++;
+              if (count >= 6) return;
+            } catch (e) {
+              // Ignore
+            }
+          }
+        }
+      }
+    }
+  }
+
+  recurse(baseDir);
+  return content;
+}
+
+/**
+ * Ensures a directory exists.
+ */
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+/**
+ * Writes a file.
+ */
+function writeFile(filePath, content) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, content, 'utf8');
+}
+
+/**
+ * Appends api key to .env.agents and updates .gitignore.
+ */
+function saveApiKeyToEnv(provider, apiKey) {
+  const envFile = path.join(process.cwd(), '.env.agents');
+  const varName = `${provider.toUpperCase()}_API_KEY`;
+  
+  let envContent = '';
+  if (fs.existsSync(envFile)) {
+    envContent = fs.readFileSync(envFile, 'utf8');
+  }
+
+  const lines = envContent.split('\n').filter(line => !line.trim().startsWith(varName));
+  lines.push(`${varName}=${apiKey}`);
+  fs.writeFileSync(envFile, lines.join('\n').trim() + '\n', 'utf8');
+
+  // Update .gitignore
+  const gitignoreFile = path.join(process.cwd(), '.gitignore');
+  let gitignoreContent = '';
+  if (fs.existsSync(gitignoreFile)) {
+    gitignoreContent = fs.readFileSync(gitignoreFile, 'utf8');
+  }
+
+  if (!gitignoreContent.includes('.env.agents')) {
+    fs.writeFileSync(gitignoreFile, gitignoreContent.trim() + '\n.env.agents\n', 'utf8');
+  }
+}
+
+/**
+ * Common helper to resolve AI configuration from env or prompt.
+ */
+async function resolveAIConfig(message = 'Choose an AI service to scan and onboard your codebase:') {
+  let provider = process.env.FORCEFULLY_PROVIDER;
+  let apiKey = '';
+
+  if (process.env.GEMINI_API_KEY) {
+    provider = 'gemini';
+    apiKey = process.env.GEMINI_API_KEY;
+  } else if (process.env.ANTHROPIC_API_KEY) {
+    provider = 'claude';
+    apiKey = process.env.ANTHROPIC_API_KEY;
+  } else if (process.env.OPENAI_API_KEY) {
+    provider = 'openai';
+    apiKey = process.env.OPENAI_API_KEY;
+  }
+
+  if (provider && apiKey) {
+    p.note(`Found existing credentials for: ${provider} via environment variables or .env.agents.`, 'Credentials Info');
+    return { provider, apiKey };
+  }
+
+  const selectedProvider = await p.select({
+    message,
+    options: [
+      { value: 'gemini', label: 'Google Gemini (gemini-2.5-flash)' },
+      { value: 'claude', label: 'Anthropic Claude (claude-3-5-sonnet)' },
+      { value: 'openai', label: 'OpenAI (gpt-4o-mini)' }
+    ]
+  });
+
+  if (p.isCancel(selectedProvider)) {
+    p.cancel('Setup cancelled.');
+    process.exit(0);
+  }
+
+  provider = selectedProvider;
+  const envVar = `${provider.toUpperCase()}_API_KEY`;
+
+  const inputKey = await p.password({
+    message: `Enter your ${envVar}:`,
+    validate: (value) => {
+      if (!value || value.trim().length === 0) return 'API key is required.';
+    }
+  });
+
+  if (p.isCancel(inputKey)) {
+    p.cancel('Setup cancelled.');
+    process.exit(0);
+  }
+
+  apiKey = inputKey;
+
+  const saveEnv = await p.confirm({
+    message: 'Would you like to save this key to a local .env.agents file (automatically added to .gitignore)?',
+    initialValue: true
+  });
+
+  if (p.isCancel(saveEnv)) {
+    p.cancel('Setup cancelled.');
+    process.exit(0);
+  }
+
+  if (saveEnv) {
+    saveApiKeyToEnv(provider, apiKey);
+    p.log.success('Saved API Key to .env.agents and updated .gitignore');
+  }
+
+  return { provider, apiKey };
+}
+
+async function main() {
+  console.clear();
+  p.intro('🚀 ForcefullyAgent Initializer');
+
+  // Step 1: Resolve AI provider and API Key
+  const { provider, apiKey } = await resolveAIConfig();
+
+  // Step 2: Codebase Scanning
+  const scanSpinner = p.spinner();
+  scanSpinner.start('Scanning repository structure and source files...');
+  const cwd = process.cwd();
+  const { fileTree, fileCount, folderCount } = scanRepository(cwd);
+  
+  // Read package metadata and readme if present
+  let packageJsonContent = '{}';
+  try {
+    const pkgPath = path.join(cwd, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      packageJsonContent = fs.readFileSync(pkgPath, 'utf8');
+    }
+  } catch (e) {}
+
+  let readmeContent = '';
+  try {
+    const readmePath = path.join(cwd, 'README.md');
+    if (fs.existsSync(readmePath)) {
+      readmeContent = fs.readFileSync(readmePath, 'utf8');
+    }
+  } catch (e) {}
+
+  // Gather specific code file types for deep-dive analysis
+  const dbFilesCode = gatherSnippetContext(cwd, ['model', 'schema', 'db', 'migration', 'database', 'table', 'orm']);
+  const routerFilesCode = gatherSnippetContext(cwd, ['route', 'router', 'api', 'controller', 'handler', 'endpoint']);
+  const logicFilesCode = gatherSnippetContext(cwd, ['service', 'logic', 'helper', 'utils', 'lib', 'util', 'core']);
+  const mainFilesCode = gatherSnippetContext(cwd, ['index', 'main', 'app', 'server']);
+
+  scanSpinner.stop(`Scan complete. Analyzed ${fileCount} files. Deep-scanned database models, routes, and logic scripts.`);
+
+  // Step 3: Write Rule Configurations
+  const configSpinner = p.spinner();
+  configSpinner.start('Writing AI agent rule files...');
+
+  writeFile(path.join(cwd, '.agents', 'AGENTS.md'), templates.getAntigravityAgentsRules());
+  writeFile(path.join(cwd, '.agents', 'skills', 'orchestrator', 'SKILL.md'), templates.getAntigravitySkill('orchestrator'));
+  writeFile(path.join(cwd, '.agents', 'skills', 'implementation', 'SKILL.md'), templates.getAntigravitySkill('implementation'));
+  writeFile(path.join(cwd, '.agents', 'skills', 'documentation', 'SKILL.md'), templates.getAntigravitySkill('documentation'));
+  writeFile(path.join(cwd, '.agents', 'skills', 'validator', 'SKILL.md'), templates.getAntigravitySkill('validator'));
+
+  writeFile(path.join(cwd, 'CLAUDE.md'), templates.getClaudeInstructions());
+  writeFile(path.join(cwd, '.claude', 'rules', 'orchestrator.md'), templates.getClaudeRule('orchestrator'));
+  writeFile(path.join(cwd, '.claude', 'rules', 'implementation.md'), templates.getClaudeRule('implementation'));
+  writeFile(path.join(cwd, '.claude', 'rules', 'documentation.md'), templates.getClaudeRule('documentation'));
+  writeFile(path.join(cwd, '.claude', 'rules', 'validator.md'), templates.getClaudeRule('validator'));
+
+  writeFile(path.join(cwd, '.cursorrules'), templates.getCursorRulesLegacy());
+  writeFile(path.join(cwd, '.cursor', 'rules', 'orchestrator.mdc'), templates.getCursorRule('orchestrator'));
+  writeFile(path.join(cwd, '.cursor', 'rules', 'implementation.mdc'), templates.getCursorRule('implementation'));
+  writeFile(path.join(cwd, '.cursor', 'rules', 'documentation.mdc'), templates.getCursorRule('documentation'));
+  writeFile(path.join(cwd, '.cursor', 'rules', 'validator.mdc'), templates.getCursorRule('validator'));
+
+  writeFile(path.join(cwd, '.github', 'copilot-instructions.md'), templates.getCopilotInstructions());
+
+  configSpinner.stop('AI agent rule files written.');
+  p.log.success('✔ Generated agent rule configurations.');
+
+  // Step 4: Multi-Doc Deep-Dive AI Generation
+  const docSpinner = p.spinner();
+  docSpinner.start('Connecting to AI to generate deep-dive documentation files one by one...');
+
+  // Helper to generate docs sequentially using AI or templates fallback
+  async function generateDoc(docPath, generateFunc, args, fallbackContent) {
+    docSpinner.message(`Generating deep-dive ${path.basename(docPath)}...`);
+    try {
+      const content = await generateFunc(args);
+      if (content && content.trim().length > 10) {
+        writeFile(docPath, content);
+        return content;
+      }
+    } catch (e) {
+      // Fallback
+    }
+    writeFile(docPath, fallbackContent);
+    return fallbackContent;
+  }
+
+  // Pre-scaffold README
+  writeFile(path.join(cwd, 'docs', 'README.md'), templates.getDocsReadme());
+
+  const dummyAnalysisResult = {
+    vision: 'Product vision detailed analysis.',
+    businessRules: '- Analyzed business rules list.',
+    terminology: '- Glossary definitions.',
+    features: '- Discovered system features list.',
+    apiContracts: 'System API endpoints list.',
+    databaseSchema: 'System database models catalog.',
+    architecture: 'Folder and architectural structure.',
+    definitions: '- Support dictionary rules.'
+  };
+
+  // vision.md
+  await generateDoc(
+    path.join(cwd, 'docs', '01-product', 'vision.md'),
+    generateVisionDoc,
+    { provider, apiKey, fileTree, packageJson: packageJsonContent, readme: readmeContent },
+    templates.getVisionTemplate(dummyAnalysisResult)
+  );
+
+  // business-rules.md
+  await generateDoc(
+    path.join(cwd, 'docs', '01-product', 'business-rules.md'),
+    generateBusinessRulesDoc,
+    { provider, apiKey, fileTree, logicFilesCode },
+    templates.getBusinessRulesTemplate(dummyAnalysisResult)
+  );
+
+  // terminology.md
+  const terminologyContent = await generateDoc(
+    path.join(cwd, 'docs', '01-product', 'terminology.md'),
+    generateTerminologyDoc,
+    { provider, apiKey, fileTree, modelFilesCode: dbFilesCode },
+    templates.getTerminologyTemplate(dummyAnalysisResult)
+  );
+
+  // overview.md
+  await generateDoc(
+    path.join(cwd, 'docs', '03-features', 'overview.md'),
+    generateFeaturesDoc,
+    { provider, apiKey, fileTree, mainFilesCode },
+    templates.getFeaturesTemplate(dummyAnalysisResult)
+  );
+
+  // contracts.md
+  await generateDoc(
+    path.join(cwd, 'docs', '04-api', 'contracts.md'),
+    generateApiContractsDoc,
+    { provider, apiKey, routerFilesCode },
+    templates.getApiContractsTemplate(dummyAnalysisResult)
+  );
+
+  // schema.md
+  await generateDoc(
+    path.join(cwd, 'docs', '05-database', 'schema.md'),
+    generateDatabaseSchemaDoc,
+    { provider, apiKey, dbFilesCode },
+    templates.getDatabaseSchemaTemplate(dummyAnalysisResult)
+  );
+
+  // architecture.md
+  await generateDoc(
+    path.join(cwd, 'docs', '08-development', 'architecture.md'),
+    generateArchitectureDoc,
+    { provider, apiKey, fileTree, packageJson: packageJsonContent, configFilesCode: mainFilesCode },
+    templates.getArchitectureTemplate(dummyAnalysisResult)
+  );
+
+  // definitions.md
+  await generateDoc(
+    path.join(cwd, 'docs', '11-knowledge-base', 'definitions.md'),
+    generateDefinitionsDoc,
+    { provider, apiKey, fileTree, terminologyContent },
+    templates.getDefinitionsTemplate(dummyAnalysisResult)
+  );
+
+  // Scaffolding standards and agent pages
+  writeFile(path.join(cwd, 'docs', '08-development', 'standards.md'), templates.getDevelopmentStandardsTemplate());
+  writeFile(path.join(cwd, 'docs', '09-ai', 'agents', 'orchestrator.md'), templates.getAgentDoc('orchestrator'));
+  writeFile(path.join(cwd, 'docs', '09-ai', 'agents', 'implementation.md'), templates.getAgentDoc('implementation'));
+  writeFile(path.join(cwd, 'docs', '09-ai', 'agents', 'documentation.md'), templates.getAgentDoc('documentation'));
+  writeFile(path.join(cwd, 'docs', '09-ai', 'agents', 'validator.md'), templates.getAgentDoc('validator'));
+  writeFile(path.join(cwd, 'docs', '09-ai', 'coding-rules.md'), templates.getCodingRules());
+  writeFile(path.join(cwd, 'docs', '11-knowledge-base', 'logs', 'implementation-logs.md'), templates.getImplementationLogsTemplate());
+
+  docSpinner.stop('Multi-doc deep-dive documentation files generated.');
+  p.log.success('✔ Scaffolded and generated detailed repository specification documents under docs/.');
+
+  p.outro('🎉 ForcefullyAgent has been successfully configured! Any AI assistant (Antigravity, Claude Code, Cursor, or Copilot) will now automatically operate under the 4-agent orchestration protocol.');
+}
+
+async function validateSetup() {
+  p.intro('🔍 ForcefullyAgent Configuration Validator');
+
+  const cwd = process.cwd();
+  const filesToCheck = [
+    { path: '.agents/AGENTS.md', label: 'Antigravity Rules (AGENTS.md)' },
+    { path: '.agents/skills/orchestrator/SKILL.md', label: 'Antigravity Orchestrator Skill' },
+    { path: '.agents/skills/implementation/SKILL.md', label: 'Antigravity Implementation Skill' },
+    { path: '.agents/skills/documentation/SKILL.md', label: 'Antigravity Documentation Skill' },
+    { path: '.agents/skills/validator/SKILL.md', label: 'Antigravity Validator Skill' },
+    { path: 'CLAUDE.md', label: 'Claude Instructions (CLAUDE.md)' },
+    { path: '.claude/rules/orchestrator.md', label: 'Claude Orchestrator Rule' },
+    { path: '.claude/rules/implementation.md', label: 'Claude Implementation Rule' },
+    { path: '.claude/rules/documentation.md', label: 'Claude Documentation Rule' },
+    { path: '.claude/rules/validator.md', label: 'Claude Validator Rule' },
+    { path: '.cursorrules', label: 'Cursor Rules Legacy (.cursorrules)' },
+    { path: '.cursor/rules/orchestrator.mdc', label: 'Cursor Orchestrator Rule' },
+    { path: '.cursor/rules/implementation.mdc', label: 'Cursor Implementation Rule' },
+    { path: '.cursor/rules/documentation.mdc', label: 'Cursor Documentation Rule' },
+    { path: '.cursor/rules/validator.mdc', label: 'Cursor Validator Rule' },
+    { path: '.github/copilot-instructions.md', label: 'Copilot Instructions' },
+    { path: 'docs/README.md', label: 'Docs Index (README.md)' },
+    { path: 'docs/01-product/vision.md', label: 'Product Vision' },
+    { path: 'docs/01-product/business-rules.md', label: 'Product Business Rules' },
+    { path: 'docs/01-product/terminology.md', label: 'Product Terminology Glossary' },
+    { path: 'docs/03-features/overview.md', label: 'Features Overview' },
+    { path: 'docs/04-api/contracts.md', label: 'API Endpoint Contracts' },
+    { path: 'docs/05-database/schema.md', label: 'Database Schema Details' },
+    { path: 'docs/08-development/architecture.md', label: 'Development Architecture' },
+    { path: 'docs/08-development/standards.md', label: 'Development Standards' },
+    { path: 'docs/09-ai/agents/orchestrator.md', label: 'Agent Orchestrator Specification' },
+    { path: 'docs/09-ai/agents/implementation.md', label: 'Agent Implementation Specification' },
+    { path: 'docs/09-ai/agents/documentation.md', label: 'Agent Documentation Specification' },
+    { path: 'docs/09-ai/agents/validator.md', label: 'Agent Validator Specification' },
+    { path: 'docs/09-ai/coding-rules.md', label: 'AI Coding Rules' },
+    { path: 'docs/11-knowledge-base/definitions.md', label: 'Knowledge Base Definitions' },
+    { path: 'docs/11-knowledge-base/logs/implementation-logs.md', label: 'Implementation Logs' }
+  ];
+
+  let missingCount = 0;
+  const s = p.spinner();
+  s.start('Validating agent and documentation configurations...');
+
+  const results = [];
+  for (const item of filesToCheck) {
+    const fullPath = path.join(cwd, item.path);
+    const exists = fs.existsSync(fullPath);
+    if (!exists) {
+      missingCount++;
+    }
+    results.push({ ...item, exists });
+  }
+
+  s.stop('Validation checks complete.');
+
+  for (const item of results) {
+    if (item.exists) {
+      p.log.success(`[PASS] ${item.label} matches target path: ${item.path}`);
+    } else {
+      p.log.error(`[FAIL] ${item.label} is missing! Expected at: ${item.path}`);
+    }
+  }
+
+  if (missingCount === 0) {
+    p.outro('🎉 Configuration validation SUCCESSful! All 4-agent orchestration rules and documentation folders are correctly configured.');
+    process.exit(0);
+  } else {
+    p.log.warn(`Validation failed with ${missingCount} missing file(s).`);
+    p.outro('❌ Verification FAILED. Please run `npx forcefully-agent` to regenerate the missing configurations.');
+    process.exit(1);
+  }
+}
+
+/**
+ * Runs the interactive Documentation Validator structured validation loop for Product Owners.
+ */
+async function runAudit() {
+  console.clear();
+  p.intro('⚖️ Documentation Validator Agent (Interactive Spec Audit)');
+
+  const cwd = process.cwd();
+  
+  const filesMap = {
+    vision: { path: 'docs/01-product/vision.md', label: 'Product Vision' },
+    businessRules: { path: 'docs/01-product/business-rules.md', label: 'Business Rules' },
+    terminology: { path: 'docs/01-product/terminology.md', label: 'Terminology Glossary' },
+    features: { path: 'docs/03-features/overview.md', label: 'Features Overview' }
+  };
+
+  for (const key in filesMap) {
+    const fullPath = path.join(cwd, filesMap[key].path);
+    if (!fs.existsSync(fullPath)) {
+      p.log.error(`Required specification document is missing: ${filesMap[key].path}`);
+      p.outro('❌ Audit cancelled. Run npx forcefully-agent first to initialize specifications.');
+      process.exit(1);
+    }
+  }
+
+  const { provider, apiKey } = await resolveAIConfig('Choose AI provider to audit documents:');
+
+  while (true) {
+    const selection = await p.select({
+      message: 'Which part of the documentation would you like to validate?',
+      options: [
+        { value: 'vision', label: '1. Product Vision (vision.md)' },
+        { value: 'businessRules', label: '2. Business Rules (business-rules.md)' },
+        { value: 'terminology', label: '3. Terminology Glossary (terminology.md)' },
+        { value: 'features', label: '4. Features Overview (overview.md)' },
+        { value: 'exit', label: '5. [Exit Audit]' }
+      ]
+    });
+
+    if (p.isCancel(selection) || selection === 'exit') {
+      break;
+    }
+
+    const docTarget = filesMap[selection];
+    const fullPath = path.join(cwd, docTarget.path);
+    const docContent = fs.readFileSync(fullPath, 'utf8');
+
+    // Generate validation question and snippet using AI
+    const qSpinner = p.spinner();
+    qSpinner.start(`Analyzing ${docTarget.label} to select validation target...`);
+    let snippet = '';
+    let question = '';
+    try {
+      const result = await generateValidationQuestion({ provider, apiKey, docName: docTarget.label, docContent });
+      snippet = result.snippet;
+      question = result.question;
+      qSpinner.stop('Validation target formulated.');
+    } catch (e) {
+      qSpinner.stop('Failed to analyze document.');
+      p.log.error(e.message);
+      continue;
+    }
+
+    // Display the selected targeted snippet instead of the full file
+    p.note(snippet, `Target Snippet from ${docTarget.label}`);
+
+    // Prompt user for confirmation/corrections on this snippet
+    const answer = await p.text({
+      message: `${question}\n\nIs this correct? (Press Enter or type "yes" to confirm, or type your corrections to edit it):`,
+      placeholder: 'Press enter to confirm...'
+    });
+
+    if (p.isCancel(answer)) {
+      continue;
+    }
+
+    const isConfirmed = !answer || answer.trim() === '' || ['yes', 'correct', 'looks good', 'ok', 'y'].includes(answer.trim().toLowerCase());
+
+    if (isConfirmed) {
+      p.log.success(`✔ Specification validated: ${docTarget.path} is accurate. No changes needed.`);
+      
+      const logsPath = path.join(cwd, 'docs/11-knowledge-base/logs/implementation-logs.md');
+      let existingLogs = '';
+      if (fs.existsSync(logsPath)) {
+        existingLogs = fs.readFileSync(logsPath, 'utf8');
+      }
+      const newLogEntry = `
+## [${new Date().toISOString().split('T')[0]}] Specification Validation Audit
+- **Agent**: Documentation Validator Agent
+- **Document**: ${docTarget.path} (${docTarget.label})
+- **Segment Audited**: ${snippet}
+- **Result**: Segment validated as up-to-date by Product Owner. No refinement required.
+`;
+      writeFile(logsPath, existingLogs.trim() + '\n' + newLogEntry);
+    } else {
+      // Process PO corrections and refine doc using AI
+      const rSpinner = p.spinner();
+      rSpinner.start('Processing corrections and refining specifications...');
+      try {
+        const { refinedContent } = await refineSingleDoc({
+          provider,
+          apiKey,
+          docName: docTarget.label,
+          docContent,
+          correction: `Regarding the segment "${snippet}", apply the following feedback: ${answer}`
+        });
+        rSpinner.stop('Feedback processed.');
+
+        writeFile(fullPath, refinedContent);
+        p.log.success(`✔ Refinement complete: ${docTarget.path} updated successfully.`);
+
+        const logsPath = path.join(cwd, 'docs/11-knowledge-base/logs/implementation-logs.md');
+        let existingLogs = '';
+        if (fs.existsSync(logsPath)) {
+          existingLogs = fs.readFileSync(logsPath, 'utf8');
+        }
+        const newLogEntry = `
+## [${new Date().toISOString().split('T')[0]}] Specification Refinement Audit
+- **Agent**: Documentation Validator Agent
+- **Document**: ${docTarget.path} (${docTarget.label})
+- **Segment Audited**: ${snippet}
+- **Product Owner Feedback**: ${answer}
+- **Result**: Specification file refined and updated based on feedback.
+`;
+        writeFile(logsPath, existingLogs.trim() + '\n' + newLogEntry);
+      } catch (e) {
+        rSpinner.stop('Refinement failed.');
+        p.log.error(e.message);
+      }
+    }
+    console.log('\n');
+  }
+
+  p.outro('🎉 Specification audit session closed. All validation records are logged and active.');
+}
+
+if (process.argv.includes('validate')) {
+  validateSetup().catch((err) => {
+    console.error('Fatal error running validation:', err);
+    process.exit(1);
+  });
+} else if (process.argv.includes('audit')) {
+  runAudit().catch((err) => {
+    console.error('Fatal error running documentation audit:', err);
+    process.exit(1);
+  });
+} else {
+  main().catch((err) => {
+    console.error('Fatal error running ForcefullyAgent:', err);
+    process.exit(1);
+  });
+}

package/docs/01-product/business-rules.md

@@ -0,0 +1,6 @@
+# Business Rules
+
+This document outlines the core business logic rules and restrictions enforced in this codebase.
+
+## Enforced Business Rules
+- Scaffolding default business rules.

package/docs/01-product/terminology.md

@@ -0,0 +1,6 @@
+# Domain Terminology
+
+This document contains key terminology, acronyms, and abbreviations used throughout the system.
+
+## Glossary
+- **project**: General software codebase.

package/docs/01-product/vision.md

@@ -0,0 +1,10 @@
+# Product Vision
+
+This document details the product purpose, target audience, and engineering goals.
+
+## Core Vision
+Product vision. Default scaffolded.
+
+## Objectives
+- Standardized AI-first development flow.
+- Maintain simple and minimal codebases.