Plan For Phase 2

The **Crystal Agents** framework you’ve built is perfectly positioned for this transition. With your 16GB laptop acting as the “Brain” (Orchestrator) and your VPS serving as the “Hands” (Execution Environment), you have a professional-grade hybrid architecture.

Below is the **Product Requirements Document (PRD)** tailored to your specific hardware and “Human-in-the-Loop” (HITL) workflow.

-–

# PRD: Crystal Agents - Autonomous Git Workflow

## 1. Objective

Enable an autonomous, multi-agent coding workflow where a local Orchestrator (Laptop) delegates tasks to remote agents (VPS) to perform Git operations (branching, coding, pushing) and presents the final Pull Request (PR) for human approval via Telegram/Dashboard.

## 2. System Architecture & Component Mapping

| Component | Host | Specification | Responsibility |

| :— | :— | :— | :— |

| **CEO Router** | Laptop | 16GB RAM / i3 | Local Qwen 3.5-4B parsing Telegram commands and routing to workflows. |

| **Worker Agents** | VPS | 4 vCPU / 8GB RAM | OpenCode/Antigravity executing Git tasks and cloud-model API calls. |

| **Connectivity** | Tailscale | Virtual Mesh | Secure, low-latency communication between Laptop (client) and VPS (server). |

| **Gateway** | Telegram | API | Primary interaction layer for instructions and approval gates. |

## 3. The “Autonomous Night Shift” Workflow

1. **Instruction:** User sends /task fix-login-bug via Telegram.

2. **Orchestration:** Local Qwen 3.5 analyzes the task and checks current VPS health.

3. **Handoff:** Orchestrator triggers a background job on the VPS using the feature-spec workflow.

4. **Execution:** VPS Worker (OpenCode) pulls the repo, creates branch ai/fix-login-bug, performs edits, and runs tests.

5. **Persistence:** VPS pushes the branch and creates a **Draft PR** on GitHub.

6. **Review Loop:** Orchestrator notifies Telegram/Dashboard: *“Task complete. Branch pushed. Ready for your review.”*.

-–

## 4. Interaction Model: “Who am I talking to?”

Since you have multiple agents, you should avoid “talking” to them individually. Instead, use the **CEO Router** pattern found in your orchestrator.ceo\_router.

### A. Telegram Interaction (Primary)

* **The Router Approach:** You talk to **one** bot. The bot uses your local Qwen model to decide which agent needs to hear the message.

* **Routing Logic:** * If you say: *“Review the last PR,”* the Router sends the context to the **Review Agent**.

* If you say: *“How is the server doing?”* the Router calls the **Health Check script**.

* **Agent Selection via Commands:** Use Telegram’s native slash menu:

* /task \[prompt] – Routes to CEO Router for automatic agent selection.

* /dev \[prompt] – Forces the message to the **Dev Agent** (OpenCode).

* /status – Pulls a report from logs/scheduler\_history.jsonl.

### B. Dashboard Interaction (Monitoring & Manual Start)

* **Textbox UI:** Add a “Global Input” box on the http://\[VPS-IP]:8000/ home page.

* **Functionality:** This box should mirror the Telegram input, allowing you to start workflows or provide feedback to “Paused” jobs (approvals) without using the terminal.

-–

## 5. Security & Safety Gates

* **Approval Gates:** Any Git push or merge action must hit the approvals.jsonl logic. The agent will pause until you click “Approve” on the dashboard or reply “Yes” in Telegram.

* **Allowlisted Roots:** Ensure allowed\_script\_roots in config.json includes your Git workspace to prevent agents from straying into system folders.

* **Token Budgeting:** Set max\_tokens in config.json to prevent runaway cloud model costs during autonomous cycles.

-–

## 6. Success Metrics (The “Morning Report”)

The Orchestrator must generate a daily\_summary.md that answers:

* What branches were created?

* How many cloud credits were spent?

* Are all scheduled health checks currently passing?

**Next Step Recommendation:** Update your config/config.json to include the telegram.chat\_id and ensure your allowed\_script\_roots includes your GitHub repo folder on the VPS.