Skip to content

Commit 733e558

Browse files
AitomatesAitomates
committed
docs(36-03): add docs/wiki tree (Home, Architecture, Operations, Decisions)
- Architecture.md documents landed worker fan-out vs in-progress telemetry boundary (PR #12) and critic gate (PR #14) - Operations.md verified setup/run/test/CI commands - Decisions.md indexes phase history and open PRs
1 parent 79e7f27 commit 733e558

4 files changed

Lines changed: 187 additions & 0 deletions

File tree

‎docs/wiki/Architecture.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Architecture
2+
3+
## Worker fan-out + telemetry boundary + critic gate
4+
5+
```mermaid
6+
flowchart TD
7+
subgraph Manager["Manager-led workflow (entities/repo_team/workflow.py)"]
8+
Plan[Planner<br/>gemini-2.5-pro] --> Research[Researcher<br/>gemini-2.5-flash]
9+
Research --> Impl[Implementer<br/>gemini-2.5-pro]
10+
Impl --> Review[Reviewer<br/>gemini-2.5-pro]
11+
end
12+
subgraph Boundary["Worker boundary (maf_starter/worker_boundary.py)"]
13+
WB[WorkerBoundary<br/>async dispatch, run_id, status polling]
14+
end
15+
subgraph Telemetry["Telemetry (in progress, PR #12)"]
16+
T[emit_failure_telemetry<br/>structured JSON on stderr]
17+
end
18+
subgraph Critic["Peer critic gate (in progress, PR #14)"]
19+
C[Deterministic pattern-scan<br/>engine]
20+
end
21+
subgraph Fallback["Provider fallback (maf_starter/provider_fallback.py)"]
22+
F[Gemini -> Anthropic -> local CLI]
23+
end
24+
Manager --> Boundary
25+
Impl --> Fallback
26+
Fallback -.->|on failure| Telemetry
27+
Review --> Critic
28+
Critic -.->|gates| Manager
29+
```
30+
31+
<!-- codex:generate-image prompt="A factory floor with a manager robot dispatching four numbered worker robots (Planner, Researcher, Implementer, Reviewer) through a glass boundary wall; failed work items trigger a small telemetry beacon; a fifth robot with a magnifying glass (the critic) inspects finished work at a gate before it passes through; isometric, enterprise blue/graphite palette" style="isometric, enterprise, clean" replaces="mermaid-above" -->
32+
33+
## Worker fan-out (landed on `main`)
34+
35+
`entities/repo_team/workflow.py` wires the canonical `planning -> research -> implementation ->
36+
review -> validation` sequence via `agent_framework_orchestrations.SequentialBuilder`. Each
37+
specialist is built in `maf_starter/team_factory.py` with a distinct model tier. Long-running
38+
executions are dispatched through `WorkerBoundary` (`maf_starter/worker_boundary.py`), which
39+
returns a `run_id` immediately and exposes `pending` / `running` / `done` / `error:<msg>`
40+
status polling instead of blocking HTTP ingress on the full execution path.
41+
42+
## Telemetry boundary — in progress (PR #12)
43+
44+
`main` today does not have a `maf_starter/telemetry.py` module. PR #12
45+
(`feat(28-02): structured JSON failure telemetry + CLI fallback size guards`) adds
46+
`emit_failure_telemetry(event, **fields)` — a stdlib-only, never-raising function that writes
47+
one flushed JSON line to stderr — wired into `provider_fallback.py`'s fallback middleware at
48+
`provider_failed`, `fallback_step_failed`, `fallback_succeeded`, and `fallback_exhausted`
49+
points, plus a 1MB CLI output/prompt size guard. Until merged, provider-fallback failures are
50+
still caught (existing `except Exception` boundaries in `provider_fallback.py` and
51+
`worker_boundary.py`) but not emitted as structured telemetry.
52+
53+
## Critic gate — in progress (PR #14)
54+
55+
No critic module exists on `main` yet. PR #14
56+
(`feat(29-01): deterministic peer critic pattern-scan engine`) introduces a deterministic
57+
pattern-scan reviewer intended to sit after the Reviewer specialist as an additional gate.
58+
Until merged, review is limited to the LLM-based Reviewer agent's own assessment.
59+
60+
## Provider routing and fallback (landed on `main`)
61+
62+
`maf_starter/routing_policy.py` selects a model tier by task depth; `maf_starter/
63+
provider_fallback.py` retries across the Gemini API, optional Anthropic API, and local CLI
64+
providers (`gemini.cmd`, `claude`, `codex.cmd`) on heuristic quota/rate-limit errors, recording
65+
route-attempt history.
66+
67+
## Approvals and bounded repo tools (landed on `main`)
68+
69+
`maf_starter/tools.py` enforces repo-root path boundaries and blocks writes to sensitive
70+
targets (e.g. `.env`). `maf_starter/approval_policy.py` classifies file operations and
71+
validation commands so destructive or externally visible actions pause for operator approval
72+
via the dashboard's approval surface.
73+
74+
<!-- docs-verified: e52e6aa9383a11722bbf92f95c21ff39feb3dd65 2026-07-08 -->

‎docs/wiki/Decisions.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Decisions
2+
3+
## ADR convention
4+
5+
`docs/adr/README.md` establishes the convention (sequential numbering, Context/Decision/
6+
Consequences) but **no numbered ADR files exist in the repo yet**. Decisions to date live in
7+
`.planning/phases/` plan/summary pairs instead.
8+
9+
## Phase history (`.planning/phases/`, this repo's own GSD project)
10+
11+
| Phase | Topic |
12+
|---|---|
13+
| 01 | Workspace and durable run foundation |
14+
| 02 | Manager-led orchestration core |
15+
| 03 | Specialist delegation and routing visibility |
16+
| 04 | Autonomous repo execution and validation guardrails |
17+
| 05 | Polished operator workbench |
18+
| 06 | API boundary and control-plane contract |
19+
| 07 | Worker boundary |
20+
21+
See each `.planning/phases/<NN-topic>/*-SUMMARY.md` for the detailed record.
22+
23+
## Open decisions tracked in this Phase 36 refresh
24+
25+
- **PR #11** (`feat/phase-26-coverage-gates`) — ratchets CI to a pytest-cov branch-coverage
26+
gate; open, not yet merged.
27+
- **PR #12** (`feat/phase-28-fault-injection`) — structured JSON failure telemetry + CLI
28+
fallback size guards; open, not yet merged.
29+
- **PR #13** (`ci/phase-31-workflow-hardening`) — pins third-party GitHub Actions to commit
30+
SHAs and least-privilege permissions; open, not yet merged.
31+
- **PR #14** (`feat/phase-29-peer-critic`) — deterministic peer critic pattern-scan engine;
32+
open, not yet merged. See [Architecture](./Architecture.md) for the critic-gate design this
33+
PR introduces.
34+
35+
<!-- docs-verified: e52e6aa9383a11722bbf92f95c21ff39feb3dd65 2026-07-08 -->

‎docs/wiki/Home.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# autogen Wiki
2+
3+
## Role in the CAS portfolio
4+
5+
`autogen` is the **Execution plane** of the Coding-Autopilot-System three-plane model (Control
6+
/ Execution / Governance). Built on Microsoft Agent Framework, it runs manager-led,
7+
specialist-delegated engineering work against a real repository: planning, research,
8+
implementation, review, and validation, with bounded repo tools and an approval gate for
9+
destructive actions.
10+
11+
| Plane | This repo's responsibility |
12+
|---|---|
13+
| Control | *(not this repo — see `gsd-orchestrator`)* |
14+
| Execution | Manager-led worker fan-out, bounded repo tools, provider routing/fallback, run artifacts |
15+
| Governance | *(not this repo — see `Promptimprover`, `cas-contracts`, `cas-evals`)* |
16+
17+
## Quickstart
18+
19+
- [README.md](../../README.md) — Quickstart, configuration reference, evidence posture
20+
- [Architecture](./Architecture.md) — worker fan-out, telemetry boundary (in progress), critic gate (in progress)
21+
- [Operations](./Operations.md) — verified run/test/CI commands
22+
- [Decisions](./Decisions.md) — phase history and open PRs
23+
24+
## Ecosystem links
25+
26+
Part of the [Coding-Autopilot-System](https://github.com/Coding-Autopilot-System) org:
27+
[gsd-orchestrator](https://github.com/Coding-Autopilot-System/gsd-orchestrator) (control plane) ·
28+
[Promptimprover](https://github.com/Coding-Autopilot-System/Promptimprover) (prompt governance) ·
29+
[cas-contracts](https://github.com/Coding-Autopilot-System/cas-contracts) (shared schemas) ·
30+
[cas-evals](https://github.com/Coding-Autopilot-System/cas-evals) (evidence gate)
31+
32+
<!-- docs-verified: e52e6aa9383a11722bbf92f95c21ff39feb3dd65 2026-07-08 -->

‎docs/wiki/Operations.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Operations
2+
3+
## Setup
4+
5+
```powershell
6+
git clone https://github.com/Coding-Autopilot-System/autogen.git
7+
Set-Location autogen
8+
python -m venv .venv
9+
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
10+
Copy-Item .env.example .env
11+
```
12+
13+
## Run
14+
15+
```powershell
16+
.\.venv\Scripts\python.exe main.py providers
17+
.\.venv\Scripts\python.exe main.py dashboard --host 127.0.0.1 --port 8000
18+
```
19+
20+
## Test
21+
22+
```powershell
23+
.\.venv\Scripts\python.exe -m pytest -q --tb=short
24+
```
25+
26+
Contract-compatibility gate only (consumer-side check against the pinned `cas-contracts` v1.1
27+
release):
28+
29+
```powershell
30+
.\.venv\Scripts\python.exe -m pytest tests/test_contract_compatibility.py -q --tb=short
31+
```
32+
33+
## CI (`.github/workflows/ci.yml`, matrix: ubuntu-latest + windows-latest, Python 3.12, 20-minute timeout)
34+
35+
1. `actions/checkout@v7`
36+
2. `actions/setup-python@v6` (Python 3.12, pip cache)
37+
3. `pip install -r requirements.txt`
38+
4. `pip check` — dependency consistency
39+
5. **Contract compatibility** — `tests/test_contract_compatibility.py`, fails red on pinned-contract drift
40+
6. **Run full test suite** — installs `pytest-cov`, runs `pytest --cov=. --cov-report=xml` (coverage is measured; no `--cov-fail-under` threshold is enforced on `main` yet — see [Architecture](./Architecture.md) and PR #11)
41+
7. `python -m compileall autogen_starter autogen_dashboard maf_starter main.py -q`
42+
8. `node --check autogen_dashboard/static/app.js` — legacy dashboard JS syntax check
43+
44+
A separate `.github/workflows/codeql.yml` runs CodeQL analysis (badge in the root `README.md`).
45+
46+
<!-- docs-verified: e52e6aa9383a11722bbf92f95c21ff39feb3dd65 2026-07-08 -->

0 commit comments

Comments
 (0)