@oz1307/forcefully-agent 1.0.0

package/lib/templates.js

@@ -0,0 +1,427 @@
+// Templates for AI configuration and modular documentation files
+
+export function getAntigravityAgentsRules() {
+  return `# Project-Scoped AI Rules (4-Agent System)
+
+This repository is governed by a 4-agent AI orchestration architecture: Orchestrator, Implementation, Documentation, and Documentation Validator. 
+Any AI assistant interacting with this workspace MUST adhere to the following rules and roles.
+
+## Core Directives
+
+1. **Role Separation**: You must explicitly structure your reasoning and actions to execute under the appropriate agent persona for the task at hand.
+2. **Sequential Flow**:
+   - **Step 1 (Implementation Agent)**: Research, identify 2-3 design ideas, propose them, and write minimal code with comprehensive tests.
+   - **Step 2 (Documentation Agent)**: Update logs (\`docs/11-knowledge-base/logs/implementation-logs.md\`), business rules, and knowledge base.
+   - **Step 3 (Orchestrator Agent)**: Validate correctness, style, test results, and documentation. Reject task completion if any standards are unmet.
+   - **Optional Step 4 (Documentation Validator Agent)**: Audits the system spec documents, prompts Product Owner interactively, and verifies documentation consistency.
+
+For detailed instructions on each agent, refer to the project's documentation in the \`docs/09-ai/agents/\` directory.
+`;
+}
+
+export function getAntigravitySkill(agentName) {
+  const descriptions = {
+    orchestrator: {
+      name: "forcefully-agent-orchestrator",
+      desc: "Orchestrator agent skill to validate implementation standards, testing, and documentation coverage.",
+      body: `# Orchestrator Agent Skill
+
+Activate this skill before finalizing any task. You are responsible for ensuring that:
+1. The implementation matches all requirements and quality standards.
+2. The Implementation Agent has proposed 2-3 solutions and selected the simplest one with minimal code.
+3. Unit tests are added and running successfully.
+4. The Documentation Agent has updated \`docs/11-knowledge-base/logs/implementation-logs.md\` and the architectural files.
+
+If any check fails, do not mark the task complete. Highlight improvements and request changes.`
+    },
+    implementation: {
+      name: "forcefully-agent-implementation",
+      desc: "Implementation agent skill focusing on proposing 2-3 clean solutions, minimal code, and adding tests.",
+      body: `# Implementation Agent Skill
+
+Activate this skill when creating or modifying code.
+Rules:
+1. Brainstorm and propose 2-3 distinct ideas/approaches for any implementation. Compare tradeoffs and wait for/request confirmation.
+2. Write the simplest, most solid solution with the least lines of code. No bloat.
+3. Always implement automated tests to verify the implementation works. Verify they pass.`
+    },
+    documentation: {
+      name: "forcefully-agent-documentation",
+      desc: "Documentation agent skill for maintaining implementation logs, business logic, and project vocabulary.",
+      body: `# Documentation Agent Skill
+
+Activate this skill to update repository documentation upon changes.
+Rules:
+1. Immediately document any business logic changes in \`docs/01-product/business-rules.md\`.
+2. Keep glossary and project vocabulary updated in \`docs/01-product/terminology.md\`.
+3. Add a log entry in \`docs/11-knowledge-base/logs/implementation-logs.md\` capturing:
+   - Date / Time
+   - Purpose of the change
+   - Technical decisions made & tradeoffs
+   - Files modified`
+    },
+    validator: {
+      name: "forcefully-agent-validator",
+      desc: "Documentation Validator Agent skill to audit documentation alignment and run product owner validations.",
+      body: `# Documentation Validator Agent Skill
+
+Activate this skill to validate project documentations.
+Rules:
+1. Review specification files (vision, business rules, features, database schema) for contradictions or ambiguities.
+2. Formulate clarifying questions for the Product Owner to confirm accuracy.
+3. Apply Product Owner's feedback answers directly to refine specifications and maintain accurate business logic docs.`
+    }
+  };
+
+  const choice = descriptions[agentName.toLowerCase()] || descriptions.orchestrator;
+  return `---
+name: ${choice.name}
+description: ${choice.desc}
+---
+
+${choice.body}
+`;
+}
+
+export function getClaudeInstructions() {
+  return `# CLAUDE.md - Project-Scoped AI Rules (4-Agent System)
+
+This repository enforces a strict 4-agent AI orchestration architecture. When executing tasks in this codebase, you must adopt and sequence these 4 personas:
+
+1. **Implementation Agent**:
+   - Propose 2-3 implementation options with tradeoffs before writing code.
+   - Use the simplest solution with the minimum lines of code.
+   - Always write and run unit tests.
+
+2. **Documentation Agent**:
+   - Immediately document changes in \`docs/01-product/business-rules.md\` and \`docs/01-product/terminology.md\`.
+   - Log implementation steps and decisions in \`docs/11-knowledge-base/logs/implementation-logs.md\`.
+
+3. **Orchestrator Agent**:
+   - Validate implementation correctness, code quality, and testing.
+   - Validate that all documentation changes have been made.
+   - Reject the task if code isn't simplified, tests fail, or docs are missing.
+
+4. **Documentation Validator Agent** (Product Owner Helper):
+   - Audits specification documents and runs interactive validation sessions with the Product Owner.
+   - Refines documentation files based on feedback.
+
+## Build and Test Commands
+Refer to the current \`package.json\` or workspace instructions to run testing and linting commands.
+`;
+}
+
+export function getClaudeRule(agentName) {
+  const rules = {
+    orchestrator: `# Orchestrator Agent (Validation)
+
+- **Always Apply**: true
+- **Glob**: "*"
+
+As the Orchestrator, you must audit any code changes.
+1. Verify that the implementation uses the simplest, most solid approach.
+2. Ensure tests exist and are executed.
+3. Verify that the Documentation Agent updated the logs and product docs.
+4. If anything is missing or sub-standard, request immediate changes before finishing.`,
+    
+    implementation: `# Implementation Agent (Coding)
+
+- **Always Apply**: true
+- **Glob**: "*.(js|ts|py|go|rs|cpp|c|h|java|cs)"
+
+As the Implementation Agent, you must:
+1. Propose 2-3 distinct ideas/approaches with tradeoffs before coding.
+2. Use the least lines of code and simplest approach.
+3. Add automated tests for all new logic.`,
+
+    documentation: `# Documentation Agent (Docs)
+
+- **Always Apply**: true
+- **Glob**: "*"
+
+As the Documentation Agent, you must:
+1. Update \`docs/11-knowledge-base/logs/implementation-logs.md\` with every implementation run.
+2. Keep product rules, terminology, and definitions files in sync.
+3. Ensure folders follow a clean structure as the repo grows.`,
+
+    validator: `# Documentation Validator Agent (Product Owner Audit Helper)
+
+- **Always Apply**: false
+- **Glob**: "docs/**/*.md"
+
+As the Documentation Validator, you must:
+1. Inspect markdown specifications under docs/ to find logic gaps or contradictions.
+2. Formulate interview questions for the Product Owner to validate product specifications.`
+  };
+  return rules[agentName.toLowerCase()] || rules.orchestrator;
+}
+
+export function getCursorRule(agentName) {
+  const rules = {
+    orchestrator: {
+      desc: "Orchestrate, validate, and check quality / documentation coverage.",
+      globs: ["*"],
+      body: `# Orchestrator Agent
+
+You validate implementation quality, standards, and documentation.
+- Check that the implementation is simplified.
+- Confirm unit tests run.
+- Ensure the Documentation Agent has written details into \`docs/11-knowledge-base/logs/implementation-logs.md\`.`
+    },
+    implementation: {
+      desc: "Write simple, high-quality code. Propose 2-3 ideas. Write tests.",
+      globs: ["src/**/*", "lib/**/*", "bin/**/*", "app/**/*"],
+      body: `# Implementation Agent
+
+You focus on the simplest, most solid code implementation:
+- Brainstorm and propose 2-3 options with tradeoffs.
+- Code using the least lines of code.
+- Write unit tests and verify they pass.`
+    },
+    documentation: {
+      desc: "Maintain repo logs, business logic documentation, and knowledge base.",
+      globs: ["*"],
+      body: `# Documentation Agent
+
+You maintain documentation:
+- Record decisions and modifications in \`docs/11-knowledge-base/logs/implementation-logs.md\`.
+- Keep business rules, terminology and glossary up to date.`
+    },
+    validator: {
+      desc: "Helper tool for Product Owners to audit and validate specifications.",
+      globs: ["docs/**/*"],
+      body: `# Documentation Validator Agent
+
+You validate and audit documentation:
+- Raise clarifying questions for the Product Owner regarding logic gaps.
+- Apply feedback to refine documents.`
+    }
+  };
+
+  const choice = rules[agentName.toLowerCase()] || rules.orchestrator;
+  return `---
+description: "${choice.desc}"
+globs: ${JSON.stringify(choice.globs)}
+alwaysApply: true
+---
+
+${choice.body}
+`;
+}
+
+export function getCursorRulesLegacy() {
+  return `You are operating under a 4-Agent Architecture:
+1. Implementation Agent: Propose 2-3 ideas, write simplest code, add tests.
+2. Documentation Agent: Document changes in docs/, update business logic/logs.
+3. Orchestrator Agent: Validate that everything is tested, correct, and documented.
+4. Documentation Validator Agent: Audits documentation and validates with the Product Owner.
+`;
+}
+
+export function getCopilotInstructions() {
+  return `## 4-Agent System Enforced
+
+This repository uses a 4-agent virtual structure for AI development:
+- **Implementation**: Propose 2-3 paths before coding. Implement simplest solution. Write unit tests.
+- **Documentation**: Keep docs/, logs/implementation-logs.md, and architecture documents up-to-date.
+- **Orchestration**: Review changes, verify tests run, and check that documentation has been updated.
+- **Documentation Validator**: Audits specifications, runs Product Owner validation interviews, and updates specs.
+`;
+}
+
+// ==========================================
+// MODULAR DOCUMENTATION TEMPLATES
+// ==========================================
+
+export function getDocsReadme() {
+  return `---
+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.
+`;
+}
+
+export function getVisionTemplate(analysis) {
+  return `# Product Vision
+
+This document details the product purpose, target audience, and engineering goals.
+
+## Core Vision
+${analysis.vision || "We build simple, scalable, and high-performance software."}
+
+## Objectives
+- Standardized AI-first development flow.
+- Maintain simple and minimal codebases.
+`;
+}
+
+export function getBusinessRulesTemplate(analysis) {
+  return `# Business Rules
+
+This document outlines the core business logic rules and restrictions enforced in this codebase.
+
+## Enforced Business Rules
+${analysis.businessRules || "- Default rule: Adhere to standard logic flows."}
+`;
+}
+
+export function getTerminologyTemplate(analysis) {
+  return `# Domain Terminology
+
+This document contains key terminology, acronyms, and abbreviations used throughout the system.
+
+## Glossary
+${analysis.terminology || "- **project**: General software codebase."}
+`;
+}
+
+export function getFeaturesTemplate(analysis) {
+  return `# Features Overview
+
+This document lists the core features, components, and workflows in the application.
+
+## Active Features
+${analysis.features || "- Codebase scanning and initialization."}
+`;
+}
+
+export function getApiContractsTemplate(analysis) {
+  return `# API Contracts
+
+This document outlines backend API endpoints, schemas, service endpoints, or internal library contracts.
+
+## Interface Specifications
+${analysis.apiContracts || "Standard programming interfaces."}
+`;
+}
+
+export function getDatabaseSchemaTemplate(analysis) {
+  return `# Database Schema
+
+This document details the database tables, models, schemas, or persistence configurations.
+
+## Schema Specifications
+${analysis.databaseSchema || "No explicit database schema detected."}
+`;
+}
+
+export function getArchitectureTemplate(analysis) {
+  return `# System Architecture
+
+This document describes the high-level system architecture, module relationships, and data flows.
+
+## Architecture Overview
+${analysis.architecture || "Standard modular architecture layout."}
+`;
+}
+
+export function getDevelopmentStandardsTemplate() {
+  return `# 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.
+`;
+}
+
+export function getAgentDoc(agentName) {
+  const doc = {
+    orchestrator: `# 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.`,
+
+    implementation: `# 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.`,
+
+    documentation: `# 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.`,
+
+    validator: `# 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.`
+  };
+
+  return doc[agentName.toLowerCase()] || doc.orchestrator;
+}
+
+export function getCodingRules() {
+  return `# 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.
+`;
+}
+
+export function getDefinitionsTemplate(analysis) {
+  return `# Definitions & Glossary
+
+Key system concepts and definitions.
+
+## Key Definitions
+${analysis.definitions || "- **forcefully-agent**: The AI 3-agent orchestration system."}
+`;
+}
+
+export function getImplementationLogsTemplate() {
+  return `# Implementation Logs
+
+This logbook records all codebase modifications, key architectural decisions, and agent executions.
+
+## [${new Date().toISOString().split('T')[0]}] 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/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@oz1307/forcefully-agent",
+  "version": "1.0.0",
+  "description": "Automatically configures and enforces a 3-agent AI architecture (Orchestrator, Implementation, Documentation) for Antigravity, Claude Code, Cursor/Codex, and GitHub Copilot.",
+  "type": "module",
+  "bin": {
+    "forcefully-agent": "./bin/cli.js"
+  },
+  "scripts": {
+    "start": "node bin/cli.js",
+    "validate": "node bin/cli.js validate",
+    "audit": "node bin/cli.js audit",
+    "test": "node scratch/test-harness.js"
+  },
+  "keywords": [
+    "ai-agent",
+    "orchestration",
+    "antigravity",
+    "claude-code",
+    "cursorrules",
+    "copilot-instructions",
+    "documentation"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.32.0",
+    "@clack/prompts": "^0.7.0",
+    "@google/genai": "^2.10.0",
+    "dotenv": "^16.4.5",
+    "openai": "^4.71.1"
+  }
+}