Project FLOCK: System Plan

1. Core Principle: Decoupled Architecture

The system is designed to be platform-agnostic. Its logic is separated into two parts:

• The Core Engine: A platform-agnostic brain built with the FLOCK agent framework. It understands problems and code but knows nothing about GitHub.
• The GitHub Adapter: The code and configuration responsible for all interaction with GitHub, such as reading issues, creating branches, and opening Pull Requests. This adapter is triggered by GitHub Actions.

This design ensures the Core Engine can be reused with other platforms (e.g., GitLab) by simply creating a new adapter.

---

2. The Workflow

The process is executed in three distinct phases.

Phase 1: Analysis & Planning

Goal: Understand the problem and create a high-quality plan.

1. Trigger: A new GitHub Issue is created, starting the GitHub Actions workflow.
2. Parse Issue (Issue Parser Agent): The issue's title and body are analyzed to produce a clean summary and categorize the task (e.g., bug, feature).
3. Analyze Repo (Repo Reader Agent): The agent scans the codebase to find the most relevant files needed to solve the problem, drastically narrowing the scope.
4. Generate Solution (Solution Generator Agent): Using the problem summary and relevant files, the agent creates a step-by-step, natural-language plan to solve the issue. This plan is reviewed for logical soundness before proceeding.

---

Phase 2: Execution & Validation

Goal: Write and test code in a temporary, isolated environment.

5. Code & Validate (Writer Agent & Validator):
   • The Writer Agent executes the plan, writing code changes to files in the local workspace.
   • A Validator automatically runs linters and unit tests against the new code.
   • Refinement Loop: If validation fails, the error is fed back to the Writer Agent to attempt a fix. This loop repeats until the code passes or a retry limit is hit.
   • Crucially, no branch is created in the repository at this stage. If the agent cannot produce a valid solution, the process stops here to avoid clutter.

---

Phase 3: Delivery

Goal: Deliver the validated solution as a clean Pull Request.

6. Branch & Commit (GitHub Adapter):
   • Only after the code is validated, a new branch (e.g., flock-fix/issue-123) is created from the local workspace.
   • The validated changes are committed and the branch is pushed to the repository.
7. Create Pull Request (GitHub Adapter):
   • A Pull Request is automatically created, linking back to the original issue.
   • The PR description is pre-filled with the agent's plan and a summary of changes.
   • A comment is posted on the issue, notifying participants that a PR is ready for human review.

The system's work is now complete, awaiting human approval to merge.