DOCSEARCHbyAlgolia
Submit Docs

Pheromind Framework Documentation

repository·main·Indexed 18 days ago

https://github.com/chrisroyse/pheromind

A proprietary framework for autonomous software development using AI swarm intelligence and stigmergy. The documentation covers the Pheromind ecosystem, including agent archetypes (Master Planners, Pheromone Scribes, Specialized Executors, and Quality Verifiers), AI coding agent ADR templates, and the Universal AI & Software PRD Blueprint. It also includes details for 'source-secure' (v2.4.0), an advanced local secret scanner and security analyzer for source code with Ollama AI integration.

Tokens
16.8K
Snippets
27
Records
81
Agent score
63%

What's inside Pheromind

  1. What is Pheromind?

    main

    Pheromind is a proprietary framework designed for the autonomous management and execution of complex projects, specifically targeting the software development lifecycle. It uses emergent AI swarm intelligence to orchestrate a collection of specialized agents that collaborate to plan, build, test, and maintain software.

    Key pillars of the framework include:

    • Pheromone-Based Swarm Intelligence (Stigmergy): Agents communicate indirectly via a shared "digital scent" (information medium), enabling decentralized coordination and dynamic task allocation.
    • AI-Verifiable Methodology: Progress is measured through concrete, measurable, and programmatically verifiable outcomes rather than subjective reports.
    • Natural Language Driven Coordination: The system interprets nuanced, narrative-style information to allow for sophisticated collaboration and human-auditable trails.

  2. Implement the Testing Strategy Blueprint

    main

    All tasks must follow the FIRST framework: Fast, Independent, Repeatable, Self-Validating, and Timely.

    Testing Pyramid Distribution:

    • Unit Tests (70-80%): Fast, isolated tests using the AAA (Arrange-Act-Assert) pattern. Target 80-90% coverage for critical paths.
    • Integration Tests (15-20%): Validate component interactions, database interactions, and API contract/schema verification.
    • E2E Tests (5-10%): Minimal suite covering critical user journeys with robust selectors.

    Test Data Management:

    • Use Data Masking for sensitive info and Synthetic Generation for realistic scenarios when production data is unavailable.

  3. Implement SOLID, DRY, KISS, and YAGNI Principles

    main

    Use these design principles to build robust software architecture:

    SOLID Principles

    1. Single Responsibility: One class, one job.
    2. Open-Closed: Open for extension, closed for modification.
    3. Liskov Substitution: Subtypes must be substitutable for base types.
    4. Interface Segregation: Many client-specific interfaces are better than one general-purpose interface.
    5. Dependency Inversion: Depend on abstractions, not concretions.

    Everyday Coding Principles

    • DRY (Don't Repeat Yourself): Eliminate duplication through abstraction and reuse.
    • KISS (Keep It Simple, Stupid): Favor simple solutions over complex ones.
    • YAGNI (You Aren't Gonna Need It): Do not build features until they are actually required.

  4. Implement the Priority-Based Token Allocation framework

    main

    To prevent context overflow and ensure high-quality AI responses, follow this recommended token distribution for a 128,000 token budget:

    CategoryAllocationTarget TokensContent Included
    Task Definition & Instructions25%~32kCore requirements, acceptance criteria, implementation guidelines
    Essential Code Context40%~51kRelevant source files, API definitions, configuration files
    Dependency Information15%~19kRelated tasks, external dependencies, interface requirements
    Documentation Context10%~13kRelevant documentation, code comments, architecture notes
    Output Buffer10%~13kReserved for AI response, error handling, iterations

  5. Manage Context Windows and Token Budgets

    main

    When working with large context windows (e.g., 128k tokens), use the following allocation and prioritization strategies to prevent overflow:

    Context Window Strategy (128k Total):

    • System Instructions: 2,000 tokens
    • Task Definition: 8,000 tokens
    • Critical Dependencies: 12,000 tokens
    • Core Code Context: 50,000 tokens
    • Documentation: 15,000 tokens
    • Test Context: 10,000 tokens
    • Output Buffer: 20,000 tokens (Minimum 15,000 tokens must always be preserved)
    • Safety Buffer: 11,000 tokens

    Context Prioritization Matrix:

    • Priority 1 (Always Include): Task definition, acceptance criteria, direct code files being modified, immediate dependencies, critical error handling patterns.
    • Priority 2 (Include if Space): Related code files for reference, comprehensive documentation, extended dependencies, design patterns.
    • Priority 3 (Include if Extra Space): Historical context, peripheral documentation, nice-to-have examples.
    • Priority 4 (Omit if Necessary): Deprecated patterns, unrelated code, verbose comments, redundant documentation.

  6. Apply Microtask Principles for Task Breakdown

    main

    Break large objectives into microtasks using these criteria:

    Microtask Criteria:

    • Single responsibility: One clear objective.
    • Token bounded: Must fit within the 128k limit with a buffer.
    • Time bounded: 2-6 hours of work maximum.
    • Testable: Clear success/failure criteria.
    • Independent: Minimal external dependencies.
    • Atomic: A complete unit of work.

    Task Sizing Guidelines:

    • SIMPLE (20k-40k tokens): Single file modifications, straightforward implementations.
    • MODERATE (40k-80k tokens): Multi-file changes, new component creation, requires design decisions.
    • COMPLEX (80k-120k tokens): System-wide changes, new architecture, heavy dependencies.

    Note: Never exceed 120k tokens for a task definition to ensure a minimum 8k token response buffer.

  7. Understand the SPARC Orchestration Workflow

    main

    Once a completed Zero-Code User Blueprint is submitted, the SPARC orchestration system executes a multi-stage automated pipeline to build the program:

    1. Deep Research: Analyzes the vision, explores similar programs, and investigates technical options.
    2. Specification Writer: Converts the blueprint and research into formal requirements.
    3. GitHub Template Research: Uses the github mcp tool to find suitable templates on GitHub.
    4. Architect: Designs the system structure.
    5. Test Research: Uses the high level test deep research tool to identify optimal high-level tests.
    6. Tester: Creates all high-level tests.
    7. Iterative Development: Uses Code, TDD, Supabase Admin, MCP Integration, and Security Reviewer modes to build, test, and secure the program.
    8. System Integrator: Connects all components.
    9. Documentation Writer: Generates user guides.
    10. DevOps: Sets up infrastructure and deploys the application.
    11. Delivery: Presents the completed program based on the user's provided Success Criteria.

  8. Apply the FIRST framework for universal test quality

    main

    The FIRST principles serve as the foundation for all testing types (unit, integration, E2E). Adhering to these ensures that your test suite provides reliable and efficient feedback.

    • Fast: Tests must execute quickly. Unit tests should run in milliseconds; integration tests should take seconds to minutes.
    • Independent: Tests must be standalone. They should not depend on the execution order of other tests and should have a single, focused purpose.
    • Repeatable: Tests must be deterministic. They should yield the same results across different environments and executions. Eliminate "flaky" tests.
    • Self-Validating: The outcome (pass/fail) must be unambiguous and automated via proper assertions, requiring no human interpretation.
    • Timely: Tests should be written concurrently with or before the code they validate (shift-left testing).

  9. Optimize Testing Strategy using the Testing Pyramid

    main

    A balanced testing strategy follows the Testing Pyramid principle to optimize cost and speed:

    • Heavy Unit Testing (Base): Numerous, fast, and isolated tests.
    • Moderate Integration Testing (Middle): Validating component interactions.
    • Minimal E2E Testing (Top): Covering only critical user journeys.

    Strategic Goals:

    • Cost Efficiency: Focus on cheaper, faster tests at lower levels.
    • Speed Optimization: Maintain rapid feedback loops via efficient distribution.
    • Risk Coverage: Ensure high-risk areas receive appropriate attention.

  10. Adhere to Code Quality and Complexity Standards

    main

    To maintain a high-quality codebase, follow these specific constraints during implementation:

    Size and Complexity Constraints:

    • Functions: Target 20-50 lines. Flag functions >50 lines for review. (Exception: Complex algorithms may reach 100-200 lines with justification).
    • Files: Keep under 500 lines with 2-10 cohesive functions.
    • Cyclomatic Complexity:
      • ≤10: Maintainable.
      • 11-20: Requires a documented refactor plan.
      • >20: Blocked unless mitigation is approved.
      • >50: Untestable; must be refactored.

    Design Principles:

    • Apply SOLID (Single Responsibility, Open-Closed, Liskov Substitution, Interface Segregation, Dependency Inversion).
    • Apply DRY (Don't Repeat Yourself), KISS (Keep It Simple, Stupid), and YAGNI (You Ain't Gonna Need It).

    Security & Error Handling:

    • Validate all untrusted input and encode all output.
    • Follow the principle of Least Privilege.
    • Avoid silent failures; distinguish between recoverable and unrecoverable errors.

  11. How the Pheromind Swarm works: Agent Archetypes

    main

    The Pheromind ecosystem relies on a dynamic interplay of specialized AI agents. While the specific implementations are proprietary, the framework utilizes the following conceptual archetypes:

    • Master Planners: High-level orchestrators that interpret project goals and create master plans with verifiable milestones.
    • Pheromone Scribes (Interpreters): The core communication layer. They interpret natural language progress reports from other agents and translate them into "digital pheromone trails" that guide the collective.
    • Specialized Executors: Domain experts including Builders (writing code via TDD), Testers (executing suites), Analysts (research), and Documenters.
    • Quality Verifiers: Agents dedicated to ensuring all tasks and integrations meet stringent, AI-verifiable quality criteria.

  12. Apply Core Code Quality Principles

    main

    To ensure code is maintainable and understandable, follow these core principles:

    • Readability and Clarity: Use meaningful naming conventions for variables and functions, maintain consistent formatting/indentation, and strive for self-documenting code. Avoid deep nesting to keep logic easy to follow.
    • Single Responsibility Principle (SRP): Ensure every function, class, or module has only one reason to change. A component should do exactly one thing well to simplify testing and debugging.