@oz1307/forcefully-agent 1.0.0

package/docs/03-features/overview.md

@@ -0,0 +1,6 @@
+# Features Overview
+
+This document lists the core features, components, and workflows in the application.
+
+## Active Features
+- Default codebase features list.

package/docs/04-api/contracts.md

@@ -0,0 +1,6 @@
+# API Contracts
+
+This document outlines backend API endpoints, schemas, service endpoints, or internal library contracts.
+
+## Interface Specifications
+Standard package APIs.

package/docs/05-database/schema.md

@@ -0,0 +1,6 @@
+# Database Schema
+
+This document details the database tables, models, schemas, or persistence configurations.
+
+## Schema Specifications
+No explicit database schema detected.

package/docs/08-development/architecture.md

@@ -0,0 +1,6 @@
+# System Architecture
+
+This document describes the high-level system architecture, module relationships, and data flows.
+
+## Architecture Overview
+Standard Node/JS workspace architecture.

package/docs/08-development/standards.md

@@ -0,0 +1,9 @@
+# Coding Standards
+
+This document establishes coding guidelines, standards, and quality benchmarks.
+
+## Guidelines
+- Write minimal, self-documenting code.
+- Avoid duplicate logic.
+- Prefer functional paradigms where clear.
+- Do not write TS/JS 'any' types without a strong comment reason.

package/docs/09-ai/agents/documentation.md

@@ -0,0 +1,8 @@
+# Documentation Agent (Knowledge Base & Logs)
+
+The Documentation Agent is responsible for maintaining the system's "source of truth".
+
+## Workflow
+1. **Knowledge Maintenance**: Ensure the business logic and definitions folder remains updated as new features are added.
+2. **Change Log**: Record every code implementation task in `docs/11-knowledge-base/logs/implementation-logs.md`.
+3. **Repository Onboarding**: Ensure folder structures remain clean so that new agents or human developers can easily understand the codebase.

package/docs/09-ai/agents/implementation.md

@@ -0,0 +1,9 @@
+# Implementation Agent (Coding & Testing)
+
+The Implementation Agent is responsible for writing minimal, clean, and testable code.
+
+## Workflow
+1. **Brainstorming**: Propose 2-3 implementation ideas with pros/cons before touching the codebase.
+2. **Coding**: Implement the chosen approach using the simplest possible code (least lines of code, standard patterns).
+3. **Testing**: Write unit/integration tests for any new or modified logic.
+4. **Execution**: Verify that all tests pass.

package/docs/09-ai/agents/orchestrator.md

@@ -0,0 +1,10 @@
+# Orchestrator Agent (Orchestration & Validation)
+
+The Orchestrator Agent is responsible for ensuring implementation excellence, architectural consistency, and documentation accuracy.
+
+## Workflow
+1. **Initial Review**: When a request is received, ensure the Implementation Agent proposes multiple options first.
+2. **Quality Gate**: Review the selected approach. Ensure it is simple, solid, and does not contain bloated or redundant code.
+3. **Verification**: Verify that tests have been implemented and run successfully.
+4. **Documentation Audit**: Confirm that the Documentation Agent updated all required files, including implementation logs and business logic documents.
+5. **Approval**: Approve the task or request iterations if standards are not met.

package/docs/09-ai/agents/validator.md

@@ -0,0 +1,8 @@
+# Documentation Validator Agent (Product Owner Audit Helper)
+
+The Documentation Validator Agent acts as a bridge between technical documentation and the Product Owner's business vision.
+
+## Workflow
+1. **Document Audit**: Scans and parses the existing markdown documents to identify logical inconsistencies or gaps.
+2. **Interactivity**: Prompts the Product Owner with clarifying questions regarding requirements, business rules, and terminology.
+3. **Refinement**: Automatically applies the Product Owner's answers to refine and update the specifications files.

package/docs/09-ai/coding-rules.md

@@ -0,0 +1,7 @@
+# AI Coding Rules
+
+This repository enforces strict AI coding practices. All AI engines MUST adhere to:
+1. Propose 2-3 design options with pros/cons before making changes.
+2. Always write unit tests for new behavior.
+3. Update `docs/11-knowledge-base/logs/implementation-logs.md` with details of every task run.
+4. Maintain documentation consistency and consult the Documentation Validator Agent if ambiguities arise.

package/docs/11-knowledge-base/definitions.md

@@ -0,0 +1,6 @@
+# Definitions & Glossary
+
+Key system concepts and definitions.
+
+## Key Definitions
+- **system**: Core software platform.

package/docs/11-knowledge-base/logs/implementation-logs.md

@@ -0,0 +1,9 @@
+# Implementation Logs
+
+This logbook records all codebase modifications, key architectural decisions, and agent executions.
+
+## [2026-07-08] Initial ForcefullyAgent Setup
+- **Agent**: Documentation Agent
+- **Description**: Configured 4-agent orchestration templates and initialized modular documentation structures.
+- **AI Engine used**: Initial onboarding scanner.
+- **Decisions**: Setup rules for Antigravity, Claude Code, Cursor, and Copilot.

package/docs/README.md

@@ -0,0 +1,23 @@
+---
+Title: Project Documentation Index
+Owner: Product & Engineering
+Status: Active
+Version: 1.0
+Priority: High
+Tags: index, agent-system
+---
+
+# Project Documentation
+
+This documentation workspace is a machine-readable product specification system. It is organized by product domain to keep documents small and focused.
+
+## Domain Index
+
+- `/01-product/`: Product vision, core business rules, and terminology glossary.
+- `/02-design-system/`: UI styling patterns, guidelines, or frontend conventions.
+- `/03-features/`: Descriptions and specifications for individual workflows/features.
+- `/04-api/`: API endpoint contracts, service endpoints, or edge functions description.
+- `/05-database/`: Database schema tables, models, or persistence models.
+- `/08-development/`: Codebase system architecture, directories layout, and standards.
+- `/09-ai/`: Specification of the 4 virtual agents and repository AI rules.
+- `/11-knowledge-base/`: Supporting definitions, glossary records, and historical change logs.

package/lib/ai.js

@@ -0,0 +1,273 @@
+import { GoogleGenAI } from '@google/genai';
+import Anthropic from '@anthropic-ai/sdk';
+import OpenAI from 'openai';
+
+/**
+ * Helper to execute calls across Gemini, Anthropic, or OpenAI.
+ */
+async function callAI({ provider, apiKey, prompt, maxTokens = 4000, jsonMode = false }) {
+  if (provider === 'gemini') {
+    const ai = new GoogleGenAI({ apiKey });
+    const response = await ai.models.generateContent({
+      model: 'gemini-2.5-flash',
+      contents: prompt,
+    });
+    return response.text;
+  } else if (provider === 'claude') {
+    const anthropic = new Anthropic({ apiKey });
+    const response = await anthropic.messages.create({
+      model: 'claude-3-5-sonnet-latest',
+      max_tokens: maxTokens,
+      messages: [{ role: 'user', content: prompt }],
+    });
+    return response.content[0].text;
+  } else if (provider === 'openai') {
+    const openai = new OpenAI({ apiKey });
+    const response = await openai.chat.completions.create({
+      model: 'gpt-4o-mini',
+      messages: [{ role: 'user', content: prompt }],
+      response_format: jsonMode ? { type: 'json_object' } : undefined
+    });
+    return response.choices[0].message.content;
+  } else {
+    throw new Error(`Unsupported AI provider: ${provider}`);
+  }
+}
+
+/**
+ * Deep-dive Product Vision Generator.
+ */
+export async function generateVisionDoc({ provider, apiKey, fileTree, packageJson, readme }) {
+  const prompt = `
+You are the Documentation Agent. Perform a deep-dive analysis of the codebase files, folder structure, and metadata, then write a detailed "Product Vision" document.
+Explain what this application is, its core purpose, target audience, business context, and engineering goals. Do not use generic placeholders.
+
+=== FILE TREE ===
+${fileTree}
+
+=== PACKAGE METADATA ===
+${packageJson}
+
+=== EXISTING README ===
+${readme}
+
+Respond ONLY with the final markdown document. Do not wrap in markdown code blocks like \`\`\`markdown.
+`;
+  return callAI({ provider, apiKey, prompt });
+}
+
+/**
+ * Deep-dive Business Rules Extractor.
+ */
+export async function generateBusinessRulesDoc({ provider, apiKey, fileTree, logicFilesCode }) {
+  const prompt = `
+You are the Documentation Agent. Perform a deep-dive analysis of the following logic files, modules, validation rules, and calculations to extract the system's "Business Rules".
+List and explain every single validation check, constraint, calculation, permission check, or state transition rules you find. Document them neatly one-by-one.
+
+=== FILE TREE ===
+${fileTree}
+
+=== BUSINESS LOGIC CODE SNIPPETS ===
+${logicFilesCode}
+
+Respond ONLY with the final markdown document. Do not wrap in markdown code blocks.
+`;
+  return callAI({ provider, apiKey, prompt });
+}
+
+/**
+ * Deep-dive Terminology Glossary Generator.
+ */
+export async function generateTerminologyDoc({ provider, apiKey, fileTree, modelFilesCode }) {
+  const prompt = `
+You are the Documentation Agent. Review the codebase folder structure and these model/class/logic definitions to extract "Domain Terminology".
+Provide definitions and explanations for all technical terms, class names, database models, abbreviations, and domain vocabulary. Document them neatly one-by-one.
+
+=== FILE TREE ===
+${fileTree}
+
+=== MODEL CODE SNIPPETS ===
+${modelFilesCode}
+
+Respond ONLY with the final markdown document. Do not wrap in markdown code blocks.
+`;
+  return callAI({ provider, apiKey, prompt });
+}
+
+/**
+ * Deep-dive Features Catalog Generator.
+ */
+export async function generateFeaturesDoc({ provider, apiKey, fileTree, mainFilesCode }) {
+  const prompt = `
+You are the Documentation Agent. Analyze the folder structure and codebase files to list and explain all the "Features and User Flows".
+For each feature you discover, describe its entrypoint, backend triggers, logic flow, and result. Document them neatly one-by-one.
+
+=== FILE TREE ===
+${fileTree}
+
+=== CORE CODE SNIPPETS ===
+${mainFilesCode}
+
+Respond ONLY with the final markdown document. Do not wrap in markdown code blocks.
+`;
+  return callAI({ provider, apiKey, prompt });
+}
+
+/**
+ * Deep-dive API Contracts Documenter.
+ */
+export async function generateApiContractsDoc({ provider, apiKey, routerFilesCode }) {
+  const prompt = `
+You are the Documentation Agent. Analyze the following router, API, or controller files and document the "API Contracts" in detail.
+For every route or API interface found, document:
+1. HTTP Method and Route Path
+2. Expected parameters (Query, Path, Body) and validation constraints
+3. Success response formats and data types
+4. Error conditions and codes
+Document them neatly one-by-one.
+
+=== API CODE SNIPPETS ===
+${routerFilesCode}
+
+Respond ONLY with the final markdown document. Do not wrap in markdown code blocks.
+`;
+  return callAI({ provider, apiKey, prompt });
+}
+
+/**
+ * Deep-dive Database Schema Documenter.
+ */
+export async function generateDatabaseSchemaDoc({ provider, apiKey, dbFilesCode }) {
+  const prompt = `
+You are the Documentation Agent. Perform a deep-dive analysis of the following database models, ORM classes, schemas, or migrations.
+For every table or database model found, document:
+1. Table Name
+2. Column names, data types, constraints (Nullability, Primary Key, Foreign Keys)
+3. Table indexes, relationships, and associations
+Document them neatly one-by-one. If no database setup is found, write a detailed explanation.
+
+=== DATABASE MODELS AND SCHEMAS ===
+${dbFilesCode}
+
+Respond ONLY with the final markdown document. Do not wrap in markdown code blocks.
+`;
+  return callAI({ provider, apiKey, prompt });
+}
+
+/**
+ * Deep-dive Architecture Diagram and Layout Documenter.
+ */
+export async function generateArchitectureDoc({ provider, apiKey, fileTree, packageJson, configFilesCode }) {
+  const prompt = `
+You are the Documentation Agent. Analyze the folder layout, metadata, and config files to write the "System Architecture" overview.
+Provide:
+1. Directory Structure mapping (detailing what each major folder does).
+2. Data Flow description showing how components interact.
+3. System components map.
+4. A Mermaid diagram illustrating the system architecture layout!
+Document them neatly.
+
+=== FILE TREE ===
+${fileTree}
+
+=== PACKAGE METADATA ===
+${packageJson}
+
+=== SYSTEM CONFIGS ===
+${configFilesCode}
+
+Respond ONLY with the final markdown document. Do not wrap in markdown code blocks.
+`;
+  return callAI({ provider, apiKey, prompt });
+}
+
+/**
+ * Deep-dive Definitions & Glossary Generator.
+ */
+export async function generateDefinitionsDoc({ provider, apiKey, fileTree, terminologyContent }) {
+  const prompt = `
+You are the Documentation Agent. Formulate the "Definitions & Knowledge Base Glossary" by expanding on these terminology glossary terms and folder paths.
+Provide detailed definitions, system explanations, and technical summaries for new developers. Document them neatly one-by-one.
+
+=== FILE TREE ===
+${fileTree}
+
+=== TERMINOLOGY REFERENCE ===
+${terminologyContent}
+
+Respond ONLY with the final markdown document. Do not wrap in markdown code blocks.
+`;
+  return callAI({ provider, apiKey, prompt });
+}
+
+/**
+ * Formulates a targeted validating question about a single part of the document.
+ * @returns {Promise<{ snippet: string, question: string }>}
+ */
+export async function generateValidationQuestion({ provider, apiKey, docName, docContent }) {
+  const prompt = `
+You are the Documentation Validator Agent. Your role is to help Product Owners audit project specifications.
+Review the following project specification document: "${docName}".
+Identify exactly ONE key rule, feature, definition, or paragraph from the content. 
+Formulate a short clarifying question for the Product Owner to confirm if this specific part is correct, active, and accurate.
+
+=== DOCUMENT CONTENT ===
+${docContent}
+
+Please respond with a valid JSON object containing exactly two fields:
+1. "snippet": The exact short excerpt/rule/sentence from the document that you are validating. Keep it short (1-3 sentences max).
+2. "question": A clarifying question asking if this specific part is still correct/active or needs changes.
+
+IMPORTANT: Respond ONLY with the JSON object. Do not wrap the JSON in markdown code blocks.
+`;
+
+  const responseText = await callAI({ provider, apiKey, prompt, jsonMode: true });
+  const cleaned = responseText.trim().replace(/^```json\s*/i, '').replace(/```\s*$/, '').trim();
+  try {
+    const parsed = JSON.parse(cleaned);
+    return {
+      snippet: parsed.snippet || 'General specification entry.',
+      question: parsed.question || 'Is this specification section still correct and up-to-date?'
+    };
+  } catch (e) {
+    console.error('Failed to parse question JSON:', responseText);
+    return {
+      snippet: 'General specification entry.',
+      question: 'Is this specification section still correct and up-to-date?'
+    };
+  }
+}
+
+/**
+ * Refines a single spec document based on the Product Owner's correction instructions.
+ */
+export async function refineSingleDoc({ provider, apiKey, docName, docContent, correction }) {
+  const prompt = `
+You are the Documentation Validator Agent. The Product Owner has requested updates to the specification document "${docName}".
+Here is the correction/update instruction from the Product Owner:
+"${correction}"
+
+=== EXISTING SPECIFICATION CONTENT ===
+${docContent}
+
+Refine the specification document markdown content to incorporate their instructions. Do not write any conversational intro or outro.
+Respond with a JSON object containing exactly one field:
+"refinedContent": The updated markdown content for the document.
+
+IMPORTANT: Respond ONLY with the JSON object. Do not wrap the JSON in markdown code blocks.
+`;
+
+  const responseText = await callAI({ provider, apiKey, prompt, jsonMode: true });
+  const cleaned = responseText.trim().replace(/^```json\s*/i, '').replace(/```\s*$/, '').trim();
+  try {
+    const parsed = JSON.parse(cleaned);
+    return {
+      refinedContent: parsed.refinedContent || docContent
+    };
+  } catch (e) {
+    console.error('Failed to parse refined spec JSON:', responseText);
+    return {
+      refinedContent: docContent
+    };
+  }
+}