@oz1307/forcefully-agent 1.0.0

package/.agents/AGENTS.md

@@ -0,0 +1,15 @@
+# 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.

package/.agents/skills/documentation/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: forcefully-agent-documentation
+description: Documentation agent skill for maintaining implementation logs, business logic, and project vocabulary.
+---
+
+# 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

package/.agents/skills/implementation/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: forcefully-agent-implementation
+description: Implementation agent skill focusing on proposing 2-3 clean solutions, minimal code, and adding tests.
+---
+
+# 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.

package/.agents/skills/orchestrator/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: forcefully-agent-orchestrator
+description: Orchestrator agent skill to validate implementation standards, testing, and documentation coverage.
+---
+
+# 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.

package/.agents/skills/validator/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: forcefully-agent-validator
+description: Documentation Validator Agent skill to audit documentation alignment and run product owner validations.
+---
+
+# 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.

package/.claude/rules/documentation.md

@@ -0,0 +1,9 @@
+# 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.

package/.claude/rules/implementation.md

@@ -0,0 +1,9 @@
+# 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.

package/.claude/rules/orchestrator.md

@@ -0,0 +1,10 @@
+# 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.

package/.claude/rules/validator.md

@@ -0,0 +1,8 @@
+# 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.

package/.cursor/rules/documentation.mdc

@@ -0,0 +1,11 @@
+---
+description: "Maintain repo logs, business logic documentation, and knowledge base."
+globs: ["*"]
+alwaysApply: true
+---
+
+# 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.

package/.cursor/rules/implementation.mdc

@@ -0,0 +1,12 @@
+---
+description: "Write simple, high-quality code. Propose 2-3 ideas. Write tests."
+globs: ["src/**/*","lib/**/*","bin/**/*","app/**/*"]
+alwaysApply: true
+---
+
+# 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.

package/.cursor/rules/orchestrator.mdc

@@ -0,0 +1,12 @@
+---
+description: "Orchestrate, validate, and check quality / documentation coverage."
+globs: ["*"]
+alwaysApply: true
+---
+
+# 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`.

package/.cursor/rules/validator.mdc

@@ -0,0 +1,11 @@
+---
+description: "Helper tool for Product Owners to audit and validate specifications."
+globs: ["docs/**/*"]
+alwaysApply: true
+---
+
+# Documentation Validator Agent
+
+You validate and audit documentation:
+- Raise clarifying questions for the Product Owner regarding logic gaps.
+- Apply feedback to refine documents.

package/.cursorrules

@@ -0,0 +1,5 @@
+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.

package/.github/copilot-instructions.md

@@ -0,0 +1,7 @@
+## 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.

package/CLAUDE.md

@@ -0,0 +1,24 @@
+# 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.

package/README.md

@@ -0,0 +1,122 @@
+# ForcefullyAgent 🚀 (`forcefully-agent`)
+
+> **Enforce a high-performance, 4-Agent AI framework in any codebase. Automatically. Forcefully.**
+
+`forcefully-agent` is an open-source command-line tool that automatically configures and restricts AI coding assistants (**Claude Code**, **Antigravity**, **Cursor/Codex**, and **GitHub Copilot**) to work as a coordinated team of four specialized virtual agents. 
+
+No complex configs, no manual onboarding. Just run one command and watch your AI assistants transform into a structured engineering team.
+
+---
+
+## 🎭 The 4-Agent Virtual Team
+
+By injecting localized workspace rules and context-aware triggers, this package forces your AI tools to cycle through four specialized personas:
+
+```mermaid
+graph TD
+    A[Dev Task Received] --> B[💻 Implementation Agent]
+    B -->|Proposes 2-3 paths, keeps code minimal, runs tests| C[📝 Documentation Agent]
+    C -->|Updates modular specs, business rules & implementation logs| D[⚖️ Orchestrator Agent]
+    D -->|Reviews changes against style standards & validates tests/docs| E{Approved?}
+    E -->|No: Request Improvements| B
+    E -->|Yes| F[Task Completed]
+    
+    G[Product Owner Audit] -.-> H[🔍 Documentation Validator Agent]
+    H -.->|Interviews Product Owner & refines specs| C
+```
+
+### 1. 💻 The Implementation Agent
+* **Convention Over Code**: Focuses on writing the simplest, most solid logic with the absolute minimum lines of code.
+* **Paths & Tradeoffs**: Always brainstorms and proposes **2-3 implementation paths** with tradeoffs before writing a single line.
+* **Test-Driven**: Automatically drafts unit tests and verifies code correctness.
+
+### 2. 📝 The Documentation Agent
+* **Modular Knowledge**: Scaffolds a complete product specification layout upon initialization.
+* **Chronological Logs**: Automatically updates business logic, domain vocabularies, and writes structured records of decisions to `implementation-logs.md`.
+
+### 3. ⚖️ The Orchestrator Agent
+* **Quality Gate**: Validates that all changes follow standard conventions, are fully covered by unit tests, and documented.
+* **Revision Gate**: Rejects subpar solutions and instructs the AI loop to revise its work until all quality standards are met.
+
+### 🔍 4. The Documentation Validator Agent
+* **Product Owner Audit Helper**: Serves as a bridge between technical files and the Product Owner's business vision.
+* **Targeted Snippet Reviews**: Scans markdown documents, selects exactly one key specification rule or statement, displays it in a clean terminal card, and prompts the PO with a focused confirmation question.
+
+---
+
+## ⚡ The Developer Advantages (Why Use It?)
+
+### 🪙 1. Massive Token Efficiency & Cost Reduction
+Normal AI rules files (like cursorrules or massive system instructions) get injected into *every single chat prompt*, draining your tokens and raising costs. 
+`forcefully-agent` utilizes **context-aware modular rule structures** (`.claude/rules/`, `.cursor/rules/`, and `.agents/skills/`). The IDE only loads the rules relevant to the files you are currently editing, cutting token overhead and saving you money on API costs.
+
+### 📁 2. Scalable Numbered Document Folder Structure
+Scaffolds a professional, structured document root under `docs/` inspired by enterprise-level engineering directories. Keeping files small and topic-focused prevents documents from growing into bloated, unreadable files.
+
+### ⚙️ 3. Deep-Dive Codebase Onboarding (8-Stage Sequential Generation)
+Instead of drafting weak placeholders, the initializer does a targeted, multi-stage code scan (grouping database ORM models, routes/endpoints files, and core logic components) and calls the AI in **8 sequential document-specific steps**. This results in rich, highly comprehensive specifications, detailed database schema columns, API endpoint contracts, and visual Mermaid architecture diagrams immediately.
+
+### 🔑 4. Zero-Prompt API Key Persistence
+Once you select your AI provider and input your credentials, they are saved locally to a git-ignored `.env.agents` file. The CLI automatically loads this file on subsequent runs, completely bypassing key prompts.
+
+### ⚖️ 5. Zero-Friction Quality Assurance (For Developers & POs)
+The interactive audit loop allows Product Owners to validate the documentation step-by-step. Since the agent only displays a single target snippet at a time, the PO doesn't have to read through giant directories. They just read one card, hit Enter to approve, or type corrections to rewrite files automatically.
+
+---
+
+## 🚀 Getting Started
+
+### 1. Initialize Agents & Generate Deep-Dive Specs
+Initialize your project instantly using `npx`:
+```bash
+npx forcefully-agent
+```
+*(Securely prompts for credentials on first run, saves to `.env.agents`, performs a deep scan, and writes rules and modular documentation files).*
+
+### 2. Run Product Specifications Audit (Frictionless Validation)
+Product Owners can run an interactive audit validation loop to review specs and apply revisions in real-time:
+```bash
+npx forcefully-agent audit
+```
+* **Select Domain**: Choose the documentation category you wish to review (Vision, Business Rules, Glossary, Features).
+* **Targeted Excerpt Card**: The tool presents exactly one key segment or rule selected by the AI (no reading of long files required).
+* **Easy Confirm / Edit**: 
+  * Press **Enter** (or type `yes`) to confirm it is correct (specification is marked validated and logged).
+  * Type your changes (e.g., *"We no longer support USA stocks, only European stocks."*) to have the AI refine the spec file on disk instantly.
+
+### 3. Running Configuration Validation
+Check if your codebase agent configs and documentation are in place and haven't been modified:
+```bash
+npx forcefully-agent validate
+```
+
+---
+
+## 📂 Generated Workspace Layout
+
+Running the tool creates the following configuration and documentation blueprint:
+
+```text
+├── .agents/                    # Antigravity project rules and skills
+├── .claude/rules/              # Claude Code workspace rules
+├── .cursor/rules/              # Cursor context-aware MDC rules
+├── CLAUDE.md                   # Claude global instructions
+├── .cursorrules                # Legacy Cursor fallback instructions
+├── .github/
+│   └── copilot-instructions.md # GitHub Copilot workspace settings
+└── docs/                       # Numbered modular documentation workspace
+    ├── README.md               # Overview & Machine-readable spec index
+    ├── 01-product/             # Product vision, business rules, and glossary
+    ├── 03-features/            # Scoped features specifications
+    ├── 04-api/                 # Endpoint specs and interface contracts
+    ├── 05-database/            # Persistence schemas and table details
+    ├── 08-development/         # High-level architecture and coding standards
+    ├── 09-ai/                  # Virtual agent definition cards and prompting guides
+    └── 11-knowledge-base/      # Domain definitions and implementation change logs
+```
+
+---
+
+## 📄 License
+
+MIT