🚀 Agentic Coding Framework, powered by Pheromind

[[[[ SUPPORT : https://paypal.me/GarethSimono ]]]

Initialisation : with Head Orchestrator 🎩 say :

"Start with @/Codebase\ Xray.md and then let's Just start with @/01_AI-RUN/01_Getting_Started.md "

And let it FLowCoding

Automate Your Vision into Realit - Build anything ! Transforming software / app / saas / game development with spec-driven, AI-powered agentic workflows.

↳ Just start with let's get started with '01_AI-RUN/00_Getting_Started.md' with '🎩 Head Orchestrator'

↳ Initiate Pheromind by configuring your_project_root/.swarmConfig & your_project_root/.roomodes, then activate the 🎩 @head-orchestrator with an entry-point script from the 01_AI-RUN/ directory. See "Getting Started" below.

---

🌟 Overview: What is Agentic Coding Framework, powered by Pheromind?

Welcome to the Agentic Coding Framework, powered by Pheromind – a revolutionary system designed to orchestrate fully autonomous, specification-driven software development. Pheromind acts as the intelligent swarm system and execution engine for the project lifecycle, which is itself defined by the sequence of scripts within the 01_AI-RUN/ directory. This project isn't just about generating code; it's about establishing a robust, repeatable, and high-quality process that takes your initial idea (often guided by an 01_AI-RUN/ script like 01_AI-RUN/02_AutoPilot.md) and transforms it into a functional product with AI-verifiable outcomes.

Pheromind leverages a structured, phase-by-phase approach, where specialized AI agents (defined in .roomodes) execute the instructions laid out in the 01_AI-RUN/ scripts. A central ✍️ @orchestrator-pheromone-scribe interprets natural language summaries from these executions to manage project state in the .pheromone file, while the 🧐 @uber-orchestrator delegates tasks based on this evolving state and the Master Project Plan (itself an output of an early 01_AI-RUN/ phase).

The result? Unprecedented consistency, adherence to detailed AI-verifiable specifications, and the automation of complex development workflows defined in 01_AI-RUN/, freeing human developers to focus on innovation and high-level strategy. For an ultra-detailed explanation of the Pheromind system, its agents, and core concepts, please refer to the updated ModeREADME.md. For a detailed technical breakdown of Pheromind executing the 01_AI-RUN/ workflow, refer to the updated logic.md.

🤔 Why Use Agentic Coding Framework with Pheromind?

This framework, with Pheromind as its execution engine for the 01_AI-RUN/ workflow, is built to solve key challenges in modern software development, especially when leveraging AI:

• AI-Verifiable Outcomes: Ensures every task and phase, as defined in the 01_AI-RUN/ scripts and executed by Pheromind, has a concrete, measurable, and AI-confirmable result.
• Autonomous Full-Cycle Automation: Pheromind autonomously executes the entire project lifecycle defined by the 01_AI-RUN/ scripts, from initial setup to deployment, guided by the .pheromone state.
• Swarm Intelligence & Adaptability: Specialized AI agents collaborate indirectly through the .pheromone file, allowing for dynamic task allocation as they execute the 01_AI-RUN/ workflow.
• Structured & Interpreted Communication: The ✍️ @orchestrator-pheromone-scribe translates rich natural language summaries from Task Orchestrators (reporting on 01_AI-RUN/ phase execution) into structured :signals, enabling nuanced state updates.
• Human-Centric Documentation Trail: Maintains a documentationRegistry within .pheromone, tracking all key human-readable project artifacts generated during the Pheromind-driven execution of the 01_AI-RUN/ workflow.
• Scalable & Robust Planning: The Master Project Plan, an output of an early 01_AI-RUN/ phase, allows complex projects defined by these scripts to be methodically managed by the AI swarm.
• Clear Human Oversight: While highly autonomous, Pheromind provides clear visibility into the execution of the 01_AI-RUN/ workflow through the documentationRegistry and AI-verifiable checkpoints.

✨ Core Features of Pheromind Executing the 01_AI-RUN/ Workflow

• 🧠 Pheromone-Based Swarm Intelligence: Decentralized coordination via a shared state file (.pheromone) managed by the ✍️ @orchestrator-pheromone-scribe, reflecting the progress of the 01_AI-RUN/ workflow.
• 🎯 AI-Verifiable Project Execution: All tasks within the 01_AI-RUN/ scripts are defined with AI-confirmable end results, ensuring tangible progress.
• ⚙️ Autonomous Task Orchestration: The 🧐 @uber-orchestrator delegates work to Task-Specific Orchestrators based on the Master Project Plan and current .pheromone state, following the sequence defined in an entry-point 01_AI-RUN/ script.
• 💬 Natural Language Summary Interpretation: The ✍️ @orchestrator-pheromone-scribe uses interpretationLogic from .swarmConfig to convert narrative progress reports (on 01_AI-RUN/ phase execution) into structured :signals and documentation updates.
• 📖 Comprehensive Documentation Registry: Tracks all human-readable project documents (specs, plans, code, reports generated during the 01_AI-RUN/ workflow) within .pheromone.
• 🔄 Cyclical "Boomerang Task" Lifecycle: A continuous flow of delegation (based on 01_AI-RUN/ scripts), execution, verification, reporting, and state update.
• 🛠️ Configurable Agent Behaviors & Logic: Agent roles defined in .roomodes; Scribe's interpretation logic defined in .swarmConfig, both crucial for executing the 01_AI-RUN/ workflow.
• 🔗 MCP Integration: Built to utilize Model Context Protocol (MCP) servers for extended AI capabilities during 01_AI-RUN/ execution.

⚙️ How It Works: The Pheromind Agentic Flow Executing 01_AI-RUN/ Scripts

The Agentic Coding Framework is powered by Pheromind, which acts as the execution engine and state management layer for the workflow defined by the sequence of scripts in the 01_AI-RUN/ directory. The overall 'Agentic Flow' or project lifecycle is thus defined by the specific sequence and content of these 01_AI-RUN/ scripts. These scripts typically cover phases such as:

• Initialization & Setup: (e.g., driven by 01_AI-RUN/01_Getting_Started.md)
• Idea Capture & Refinement: (e.g., driven by 01_AI-RUN/03_Idea.md)
• Market Research: (e.g., driven by 01_AI-RUN/04_Market_Research.md)
• Core Concept Definition: (e.g., driven by 01_AI-RUN/05_Core_Concept.md)
• PRD Generation: (e.g., driven by 01_AI-RUN/06_PRD_Generation.md)
• Technical Specifications & Documentation Setup: (e.g., driven by 01_AI-RUN/07_Specs_Docs.md)
• Task Management & Breakdown: (e.g., driven by 01_AI-RUN/09_Task_Manager.md)
• Implementation Cycles: (e.g., driven by 01_AI-RUN/08_Start_Building.md)
• Testing & QA: (e.g., driven by 01_AI-RUN/10_Testing.md)
• Deployment: (e.g., driven by 01_AI-RUN/11_Deployment.md)

Pheromind executes these phases by following the logic within each script. The detailed mechanism is as follows:

1. Initiation: The user activates the 🎩 @head-orchestrator with parameters including the Original_User_Directive_Payload_Path_Field pointing to an entry-point script from the 01_AI-RUN/ directory (e.g., 01_AI-RUN/02_AutoPilot.md). This script defines the overall project flow or a major phase.
2. Uber-Orchestration: The 🧐 @uber-orchestrator receives this entry-point 01_AI-RUN/ script. It uses this script as its primary guide to understand the project's phases and sequence. It then delegates major project phases (as outlined in the 01_AI-RUN/ script) to appropriate Task-Specific Orchestrators.
3. Task-Specific Orchestration & Worker Execution: Task-Specific Orchestrators receive their directives and consult their own specific 01_AI-RUN/*.md files (e.g., 01_AI-RUN/06_PRD_Generation.md for PRD generation). These scripts provide detailed instructions for the phase. The Orchestrator then breaks down these instructions into granular tasks for Worker Agents (e.g., coders, testers, spec writers). Each task is designed with an AI-verifiable end result.
4. State Management & Reporting: As Worker Agents complete tasks based on the 01_AI-RUN/ instructions, they report AI-verifiable outcomes. Task Orchestrators aggregate these and send comprehensive natural language summaries to the ✍️ @orchestrator-pheromone-scribe. The Scribe, using interpretationLogic from .swarmConfig, updates the .pheromone file with :signals reflecting the 01_AI-RUN/ phase's progress and updates the documentationRegistry. Agent roles and behaviors are defined in .roomodes.
5. Cycle Continuation: The 🎩 @head-orchestrator re-engages the 🧐 @uber-orchestrator, which consults the updated .pheromone and the entry-point 01_AI-RUN/ script to determine the next phase of the workflow to execute.

This cyclical process continues, with Pheromind agents autonomously executing the workflow defined in the 01_AI-RUN/ scripts, always focusing on AI-verifiable outcomes.

For an ultra-detailed explanation of the Pheromind system, its agents, and core concepts, please consult the updated ModeREADME.md. For a detailed technical breakdown of Pheromind executing the 01_AI-RUN/ workflow, agent interactions, and file operations, refer to the updated logic.md.

🚀 Getting Started with Pheromind for 01_AI-RUN/ Workflow Execution

Initiating a Pheromind project to execute the 01_AI-RUN/ workflow involves a specific setup:

1. Fork this Repository: This creates your project's dedicated workspace.
2. Environment Configuration:
   • Ensure your AI agent environment (e.g., Cursor, Cline, Windsurf with a compatible LLM like Claude 3.x) is operational.
   • Configure API keys for any MCP servers or external services your agents will use.
3. Define Agent Behaviors: The .roomodes File:
   • This JSON file (typically at your_project_root/.roomodes) contains the definitions for all Pheromind agents. Review and customize as needed.
4. CRITICAL - Establish the Scribe's Rulebook: The .swarmConfig File:
   • This JSON file must be created by you in your project root (e.g., your_project_root/.swarmConfig).
   • It contains the interpretationLogic that the ✍️ @orchestrator-pheromone-scribe uses to translate natural language summaries (from 01_AI-RUN/ phase executions) into structured :signals and documentationRegistry updates in .pheromone.
   • Refer to ModeREADME.md for details on its structure.
5. Select Your Entry-Point 01_AI-RUN/ Script:
   • The 01_AI-RUN/ directory contains scripts defining various project phases and workflows (e.g., 01_AI-RUN/02_AutoPilot.md for a full project lifecycle, or 01_AI-RUN/06_PRD_Generation.md for a specific phase). Choose the script that represents the starting point of the workflow you want Pheromind to execute.
6. Initiate the Pheromind Swarm:
   • Activate the 🎩 @head-orchestrator agent.
   • You must provide it with the following parameters (example values):
     • Original_User_Directive_Type_Field: "PheromindWorkflow" (or similar, indicating an 01_AI-RUN/ script execution)
     • Original_User_Directive_Payload_Path_Field: "01_AI-RUN/02_AutoPilot.md" (path to your chosen entry-point 01_AI-RUN/ script)
     • Original_Project_Root_Path_Field: "/path/to/your/project_root" (absolute path)
     • Pheromone_File_Path: ".pheromone" (path to the pheromone file, typically in project root)
   • The ✍️ @orchestrator-pheromone-scribe will bootstrap the .pheromone file if it doesn't exist.

Pheromind will then use the specified 01_AI-RUN/ script as the blueprint for its execution, with agents carrying out the instructions defined within that script and subsequent scripts it references.

For a comprehensive, step-by-step guide to Pheromind setup and initiation, please see the "Getting Started with Pheromind: An Ultra-Detailed Guide" section in updated ModeREADME.md.

📚 Key Documentation

• Pheromind System & Core Logic (Executing 01_AI-RUN/):
  • ModeREADME.md: Essential Reading. The definitive guide to the Pheromind swarm intelligence orchestration framework, its agents (defined in .roomodes), core concepts, key files (.pheromone, .swarmConfig), and how it executes the detailed project lifecycle defined by the 01_AI-RUN/ scripts.
  • logic.md: Essential Reading. Provides a detailed technical manual of Pheromind executing the 01_AI-RUN/ script-defined workflow phases, including agent interactions, file usage, and AI-verifiable outcomes.
  • workflow.md: High-level overview of the project's operational workflow, now understood as being executed by Pheromind based on 01_AI-RUN/ scripts.
• Agent & Workflow Configuration:
  • .roomodes (User-Managed): JSON definitions for all Pheromind AI agents.
  • .swarmConfig (User-Created & Managed): Critical JSON file containing interpretationLogic for the ✍️ @orchestrator-pheromone-scribe.
• Workflow Definition Scripts (01_AI-RUN/):
  • 01_AI-RUN/ (Directory): These Markdown scripts define the actual project workflow phases and logic that Pheromind executes. Pheromind agents use these scripts as their primary instructions.
    • 01_AI-RUN/01_Getting_Started.md: Defines the initial project setup and foundational document creation tasks, executed by Pheromind.
    • 01_AI-RUN/02_AutoPilot.md: Often serves as an entry-point script, outlining the high-level sequence of project phases for Pheromind to execute.
    • Other *.md files in 01_AI-RUN/ (e.g., 03_Idea.md, 06_PRD_Generation.md): Define specific project phases or tasks, providing detailed instructions for Pheromind agents.
  • 01_AI-RUN/Template/PRD_template.md: A base template used by Pheromind agents when executing PRD generation as defined in an 01_AI-RUN/ script.
• Supporting Documentation Templates (Populated by Pheromind during 01_AI-RUN/ execution):
  • 02_AI-DOCS/ (various subdirectories): Contains templates for architecture, business logic, conventions, etc. These are populated by Worker Agents as instructed by the 01_AI-RUN/ scripts and Master Project Plan, with paths tracked in the documentationRegistry of .pheromone.
  • 03_SPECS/ (various subdirectories): Contains templates for feature and bugfix specifications, populated by Worker Agents as per 01_AI-RUN/ script directives and tracked in the documentationRegistry.

🛠️ Technology Assumptions

This workflow, executed by Pheromind based on 01_AI-RUN/ scripts, suggests a default stack of:

• Frontend: Next.js (TypeScript)
• Backend/DB: Supabase
• Styling: Tailwind CSS (with Shadcn/ui inspiration)

These are recommendations and can be adapted. The Pheromind workflow heavily relies on Model Context Protocol (MCP) servers for extended AI capabilities.

🤝 Contributing / Future Vision

We envision Pheromind evolving into an even more powerful and adaptable platform for AI-driven development, executing increasingly complex workflows defined in 01_AI-RUN/. Contributions, ideas, and feedback are welcome!

• Expanding MCP integrations.
• More sophisticated AI agent personas and capabilities.
• Enhanced automated testing and validation frameworks within the 01_AI-RUN/ scripts.
• Visual tools for monitoring .pheromone state and the documentationRegistry as Pheromind executes the workflow.

---

🗺️ Roadmap: Pheromind Project Lifecycle - Executing the 01_AI-RUN/ Workflow

The Pheromind workflow is designed for comprehensive, autonomous AI-driven project execution. Pheromind acts as the execution engine, carrying out the instructions defined in the 01_AI-RUN/ scripts, guided by a Master Project Plan (itself an output of an early 01_AI-RUN/ phase) and the evolving state within the .pheromone file. Human oversight is facilitated through the documentationRegistry and AI-verifiable checkpoints. Here’s a conceptual journey:

Phase 0: Foundational Setup & Initiation (Pheromind executing 01_AI-RUN/01_Getting_Started.md & 01_AI-RUN/02_AutoPilot.md logic)

1. User: Configures the environment, defines agent behaviors in .roomodes, and critically, creates the .swarmConfig file with interpretationLogic.
2. User: Selects an entry-point 01_AI-RUN/ script (e.g., 01_AI-RUN/02_AutoPilot.md) that defines the initial project scope or overall workflow.
3. User: Activates the 🎩 @head-orchestrator with the path to this entry-point 01_AI-RUN/ script, project root, and .pheromone file.
4. Pheromind System:
   • 🎩 @head-orchestrator passes the directive (the 01_AI-RUN/ script path) to 🧐 @uber-orchestrator.
   • ✍️ @orchestrator-pheromone-scribe bootstraps .pheromone (if new project).
   • Pheromind begins executing the logic defined in the initial 01_AI-RUN/ scripts (e.g., tasks from 01_AI-RUN/01_Getting_Started.md like creating foundational documents, potentially including a Master Project Plan).

Phase 1: Strategic Planning (Pheromind executing 01_AI-RUN/ script for Master Plan)

1. 🧐 @uber-orchestrator: Following the entry-point 01_AI-RUN/ script, delegates to a Task Orchestrator (e.g., 🌟 @orchestrator-sparc-specification-master-test-plan) to execute the 01_AI-RUN/ script responsible for creating a Master Project Plan.
   • Mandate: The 01_AI-RUN/ script for this phase ensures the Master Project Plan details subsequent phases and micro-tasks, each with a specific AI-verifiable end result.
2. Task Orchestrator & Workers: Execute the relevant 01_AI-RUN/ script to produce the Master Project Plan (e.g., docs/Master_Project_Plan.md).
3. Reporting & State Update: The orchestrator reports the AI-verifiable creation of the Master Project Plan to the ✍️ @orchestrator-pheromone-scribe.
4. ✍️ @orchestrator-pheromone-scribe: Updates .pheromone with :signals (e.g., master_plan_created_verified) and adds the Master Project Plan to the documentationRegistry.

Phase 2: Iterative Development & Execution (Pheromind executing subsequent 01_AI-RUN/*.md phases)

1. 🧐 @uber-orchestrator: Guided by the Master Project Plan, current :signals in .pheromone, and the overall sequence from the entry-point 01_AI-RUN/ script, delegates the next phase (e.g., "Idea Generation" by executing 01_AI-RUN/03_Idea.md logic, "Market Research" via 01_AI-RUN/04_Market_Research.md, or "PRD Generation" using 01_AI-RUN/06_PRD_Generation.md) to a relevant Task-Specific Orchestrator.
2. Task-Specific Orchestrator: Consults the Master Project Plan and its assigned 01_AI-RUN/*.md script. This script details the tasks for its phase. The orchestrator manages Worker Agents to execute these tasks.
3. Worker Agents: Execute tasks as per the 01_AI-RUN/ script instructions, achieve AI-verifiable outcomes, and report back to their Task Orchestrator. Worker Agents also handle user validation points defined within the 01_AI-RUN/ scripts, typically by using the ask_followup_question tool to interact with the user for necessary approvals or feedback before proceeding.
4. Task-Specific Orchestrator: Aggregates worker summaries, verifies overall phase completion against AI-verifiable goals (as defined by its 01_AI-RUN/ script), and sends a comprehensive summary to the ✍️ @orchestrator-pheromone-scribe.
5. ✍️ @orchestrator-pheromone-scribe: Updates :signals in .pheromone. The documentationRegistry in .pheromone is updated with paths to generated documents like idea_document.md, market_research.md, or project_prd.md from these phases.
6. Cycle Repeats: The 🎩 @head-orchestrator re-engages the 🧐 @uber-orchestrator, which uses the updated .pheromone and the entry-point 01_AI-RUN/ script to guide the execution of the next 01_AI-RUN/ phase.

Subsequent Phases (Integration, Testing, Deployment, etc.):

• Pheromind continues to execute the workflow defined in the sequence of 01_AI-RUN/ scripts (e.g., 01_AI-RUN/08_Start_Building.md, 01_AI-RUN/10_Testing.md, 01_AI-RUN/11_Deployment.md).
• Each 01_AI-RUN/ script provides the "what" and "sequence," while Pheromind agents provide the "how," always focusing on AI-verifiable outcomes.
• The documentationRegistry in .pheromone is continuously updated with artifacts produced during the execution of these scripts.

This Pheromind lifecycle, driven by the 01_AI-RUN/ scripts, is designed to be robust and adaptable. For the most detailed explanation of this lifecycle and agent interactions, please refer to the updated ModeREADME.md and updated logic.md.