gsd:docs write architecture and workflow state machine diagrams

Author: Aitomates

docs/architecture.md

@@ -0,0 +1,51 @@
+# Architecture
+
+The heart of the `gsd-orchestrator` is a durable State Machine built around the `WorkflowState` enumeration. It decomposes the massive complexity of an autonomous coding task into discrete, verifyable phases.
+
+## Workflow State Machine
+
+The orchestrator guarantees that no code is pushed to a PR without passing through `TestGenerating` and `Validating`.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Idle
+
+    Idle --> Triaging : Issue Received
+    Triaging --> Analyzing : Issue Classified
+    Analyzing --> Branching : Action Plan Approved
+    
+    Branching --> Editing : Branch Created
+    Editing --> TestGenerating : Files Modified
+    
+    TestGenerating --> Validating : xUnit Tests Written
+    
+    Validating --> Committing : Tests Passed
+    Validating --> Editing : Tests Failed (Feedback Loop)
+    
+    Committing --> PrCreating : Commits Hashed
+    PrCreating --> Reviewing : PR Opened
+    
+    Reviewing --> Documenting : PR Approved by Agent
+    Reviewing --> Editing : PR Rejected (Feedback Loop)
+    
+    Documenting --> Done : Docs Generated
+
+    state Failed {
+        [*] --> Recoverable
+        [*] --> TerminalStopReason
+    }
+
+    Analyzing --> Failed : Ambiguity
+    Validating --> Failed : BudgetExhausted
+```
+
+## Validation & SDLC Status
+
+Beyond linear states, the Orchestrator maps operations to Software Development Life Cycle (SDLC) batches:
+- `Discovery` (Triaging, Analyzing)
+- `Design`
+- `Change` (Branching, Editing, TestGenerating)
+- `Assurance` (Validating, Reviewing)
+- `Closure` (Committing, PrCreating, Documenting)
+
+If a phase reaches `ValidationStatus.Block`, the engine triggers a `TerminalStopReason` (e.g., `PolicyDenied`, `DestructiveAction`), rolling back the branch and alerting the human operator.

docs/index.md

@@ -1,3 +1,17 @@
-# gsd-orchestrator Documentation
+# GSD Orchestrator
 
-Welcome to the documentation for gsd-orchestrator.
+**GSD Orchestrator** is a highly resilient, state-driven workflow engine built on .NET 10. It is designed to autonomously translate GitHub Issues into tested, validated, and documented Pull Requests via an AI-native Control Plane (the Coding Autopilot System).
+
+## Key Capabilities
+
+1. **State Machine Durability:** The entire Issue-to-PR pipeline is governed by an explicit state machine, ensuring tasks can be interrupted and resumed without losing context.
+2. **AI Verification Loops:** Uses explicit `SdlcBatch` and `SdlcPhaseStatus` checkpoints to ensure code is validated, tested, and reviewed by autonomous personas before merging.
+3. **Multi-Agent Orchestration:** Delegates specific tasks to specialized AI Personas (e.g., `sdet-expert`, `python-expert`, `azure-architect`) using the `GLOBAL_AGENTS.md` router framework.
+
+## Project Structure
+
+- `src/GsdOrchestrator/Workflows`: Contains the core `.NET 10` State Machine and all transition handlers.
+- `src/GsdOrchestrator/Mcp`: The Model Context Protocol (MCP) dispatchers that interact with the local filesystem and GitHub API.
+- `src/GsdOrchestrator/Checkpointing`: State serialization logic for workflow durability.
+
+To dive deeper into how the states are processed, see the [Architecture Guide](architecture.md).