gsd:docs generate bespoke architecture and diagrams

Author: Aitomates

docs/architecture.md

@@ -0,0 +1,75 @@
+# Architecture
+
+`autogen` utilizes a manager-led orchestration strategy built on top of the Microsoft Agent Framework. Its design emphasizes operator control and execution safety over pure autonomy.
+
+## Workflow Orchestration Diagram
+
+```mermaid
+flowchart TD
+    subgraph Operator[Operator / UI]
+        Dashboard[Operator Dashboard]
+        CLI[Command Line Interface]
+    end
+
+    subgraph Manager[Manager Agent]
+        Workflow[Manager-Led Workflow]
+        Approval[Approval Gate]
+        Validation[Validation Step]
+    end
+    
+    subgraph Specialists[Specialist Team]
+        Planner[Planner Agent\n(gemini-2.5-pro)]
+        Researcher[Researcher Agent\n(gemini-2.5-flash)]
+        Implementer[Implementer Agent\n(gemini-2.5-pro)]
+        Reviewer[Reviewer Agent\n(gemini-2.5-pro)]
+    end
+
+    subgraph State[Run Artifacts & State]
+        Checkpoints[Run-Scoped Checkpoints]
+        SessionStore[Durable Session Store]
+    end
+
+    subgraph Boundaries[Repo Boundaries]
+        RepoTools[Bounded Repo Tools]
+        LocalFiles[File System]
+    end
+
+    Dashboard <--> Workflow
+    CLI <--> Workflow
+
+    Workflow --> Planner
+    Planner --Handoff--> Researcher
+    Researcher --Handoff--> Implementer
+    Implementer --Handoff--> Reviewer
+    Reviewer --Handoff--> Validation
+
+    Planner --> Checkpoints
+    Researcher --> RepoTools
+    Implementer --> RepoTools
+    Reviewer --> RepoTools
+
+    RepoTools --> LocalFiles
+    RepoTools --> Approval
+    Approval -.-> Dashboard
+
+    Validation --> SessionStore
+    Checkpoints --> SessionStore
+```
+
+## Component Breakdown
+
+### Manager-Led Workflow
+The entry point (`entities/repo_team/workflow.py`) defines a canonical sequence: `planning` -> `research` -> `implementation` -> `review` -> `validation`. 
+
+### The Specialists
+Agents are built in `maf_starter/team_factory.py` with distinct models and roles:
+- **Planner**: Scopes the work, generates constraints, sets risks and assumptions.
+- **Researcher**: Gathers facts from the repository using bounded tools.
+- **Implementer**: Translates plans and research into a concrete technical change.
+- **Reviewer**: Inspects the implementation for regressions, missing tests, or weak assumptions.
+
+### Bounded Repo Operations and Approvals
+Tools restrict file accesses and enforce boundaries. Actions like file writes or executing validation commands pass through an `Approval Gate` ensuring destructive changes pause for human operator review in the dashboard.
+
+### Provider Fallback & Routing
+Built for resilience, tasks are routed across APIs (e.g., Gemini, Anthropic) or CLI fallbacks based on policy definitions.

docs/index.md

@@ -1,3 +1,20 @@
-# autogen Documentation
+# autogen Developer Documentation
 
-Welcome to the documentation for autogen.
+Welcome to the `autogen` developer documentation. `autogen` is a local-first, multi-agent engineering workbench built on the Microsoft Agent Framework (MAF).
+
+## Core Philosophy
+
+`autogen` is designed to run autonomous engineering workflows against a real repository with built-in safety, visibility, and control. It moves beyond the typical chat-bot paradigm by providing an orchestration model that coordinates multiple specialized agents under a structured, manager-led workflow.
+
+### Key Features
+- **Manager-Led Orchestration**: A structured workflow directing a planner, researcher, implementer, and reviewer.
+- **Bounded Repo Operations**: Scoped tools that enforce boundaries on read/write operations to keep destructive changes from proceeding without approval.
+- **Routed Provider Execution**: Dynamic routing across models and CLI providers depending on task requirements and availability.
+- **Durable Artifacts**: Persisted session stores, run state, diffs, and attempts to ensure traceability and reproducibility.
+- **Operator-Facing Dashboard**: A local UI for pausing, approving, and auditing workflow progression.
+
+## Getting Started
+Please refer to the repository `README.md` for the quickstart guide and environment setup.
+
+## Next Steps
+- [Architecture Overview](architecture.md) - Deep dive into the orchestration, agent interactions, and artifact stores.