Hatch: multi-agent harness design docs

.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "hatch",
+  "owner": {
+    "name": "Finolabs",
+    "url": "https://github.com/fioenix/overclaud"
+  },
+  "plugins": [
+    {
+      "name": "hatch",
+      "source": "./hatch/plugin",
+      "description": "Embedded harness for a coding-agent squad: shared chat (= comms + backlog) and a knowledge base over MCP."
+    }
+  ]
+}

.github/workflows/hatch.yml

@@ -0,0 +1,31 @@
+name: hatch CI
+
+on:
+  push:
+    branches: ["**"]
+    paths: ["hatch/**", ".github/workflows/hatch.yml"]
+  pull_request:
+    paths: ["hatch/**", ".github/workflows/hatch.yml"]
+
+jobs:
+  build-test:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: hatch
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.24"
+          cache-dependency-path: hatch/go.sum
+      - name: Verify modules tidy
+        run: |
+          go mod tidy
+          git diff --exit-code go.mod go.sum
+      - name: Lint (vet + gofmt)
+        run: make lint
+      - name: Test
+        run: make test
+      - name: Build
+        run: make build

CODE_OF_CONDUCT.md

@@ -0,0 +1,45 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainers at **tangduyphuong@gmail.com**. All complaints will
+be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

CONTRIBUTING.md

@@ -40,6 +40,29 @@ If the skill setup flow doesn't work correctly, open an issue with:
 - What you expected vs what happened
 - Any error messages
 
+## Contributing to Hatch (the `hatch/` Go project)
+
+Hatch is the multi-agent orchestrator CLI. To develop:
+
+```bash
+cd hatch
+./scripts/onboard.sh   # build + a runnable demo (mock agent)
+make test              # unit + integration tests
+make lint              # go vet + gofmt check (CI enforces both)
+make build             # bin/hatch + bin/hatch-mock
+```
+
+Standards for Go changes:
+
+- [ ] `make lint` and `make test` pass (CI runs them on every PR)
+- [ ] `go mod tidy` leaves `go.mod`/`go.sum` unchanged
+- [ ] New behavior has a test; security-relevant paths are sanitized
+- [ ] No secrets in code/config; credentials come from env vars only
+- [ ] Keep packages small and documented; match the surrounding style
+
+See `hatch/docs/` for the design and `SECURITY.md` for trust boundaries.
+
 ## Code of Conduct
 
-Be kind. Be helpful. Skip the drama.
+See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). In short: be kind, be helpful,
+skip the drama.

README.md

@@ -2,6 +2,8 @@
 
 Optimize how Claude works for you — across every surface.
 
+> **Đang nâng cấp lên đa-agent → [Hatch](hatch/README.md).** overclaud (single-agent) đang được nâng thành một harness điều phối **nhiều coding agent** (Claude Code, Codex, Kiro, Antigravity) trên cùng một repo, tối ưu token, theo quy trình kiểu Agile. overclaud hiện tại trở thành compiler backend cho Claude bên trong Hatch. Sản phẩm thuộc hệ sinh thái **Finolabs**. Xem bộ thiết kế ở [`hatch/`](hatch/README.md).
+
 Claude reads your instructions every message, but most users either don't set them up, put everything in one place, or waste tokens on vague guidance. **overclaud** fixes that.
 
 ## What This Is
@@ -129,9 +131,13 @@ overclaud/
 │       ├── layers.md               # Complete layer architecture
 │       ├── token-optimization.md   # Token efficiency techniques
 │       └── common-mistakes.md      # Anti-patterns to avoid
-└── guides/
-    ├── layering-strategy.md        # What goes where — decision guide
-    └── contributing-templates.md   # How to contribute new templates
+├── guides/
+│   ├── layering-strategy.md        # What goes where — decision guide
+│   └── contributing-templates.md   # How to contribute new templates
+└── hatch/                          # Multi-agent upgrade (design docs)
+    ├── README.md                   # Hatch — multi-agent harness overview
+    ├── docs/                       # 00-vision … 08-roadmap
+    └── spec/                       # registry / ticket / ledger schemas
 ```
 
 ## Contributing

SECURITY.md

@@ -21,3 +21,31 @@ overclaud is an instruction optimization skill. It:
 ## Hook Security
 
 The auto-suggest hook processes `$TOOL_INPUT` through `jq` (JSON parser) before any string operations. User input never appears in the hook's output. The output is a hardcoded JSON system message.
+
+## Hatch (the orchestrator in `hatch/`)
+
+Hatch is a **local, file-based** tool: state lives in `.hatch/` and the repo;
+there is no server and no telemetry. It does, however, execute programs, so the
+following are deliberate **trust boundaries** — treat a `.hatch/` workspace and
+its `registry.yaml`/`workflow.yaml` as trusted, code-reviewed inputs (like a
+`Makefile` or CI config):
+
+- **Gate commands.** `workflow.yaml` gates of `type: command` run via `sh -c`
+  (e.g. `make test`). Anyone who can commit `workflow.yaml` can run commands on
+  a machine that runs `hatch gate`/`move`. Review workflow changes in PRs.
+- **Agent execution.** The orchestrator spawns the agent CLIs named in
+  `registry.yaml` (`exec`, no shell — arguments are passed directly, not
+  interpolated into a shell string). Only list agents you trust.
+- **Credentials.** Agent API keys are read from the environment at spawn time
+  (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `KIRO_API_KEY`) and
+  are **never** written to the repo, ledger, or config. Never commit secrets;
+  `registry.yaml` references env var names only.
+- **Transcripts.** Raw agent stdout/stderr is captured to `.hatch/runs/` and the
+  ledger summary. If an agent prints a secret, it lands there — output redaction
+  is currently out of scope (tracked in `hatch/docs/17-pre-implementation.md`).
+  Keep `.hatch/runs/` out of public artifacts if your agents echo sensitive data.
+- **Path safety.** Ticket ids, channel names and run targets are sanitized
+  before being used as path segments to prevent traversal; `hatch validate`
+  rejects unsafe ticket ids.
+
+Report Hatch vulnerabilities the same way as above (subject "hatch security").

hatch/.gitignore

@@ -0,0 +1,7 @@
+# Build artifacts. Note: patterns must be anchored so they don't match the
+# cmd/hatch source directory.
+/bin/
+/hatch
+/demo-workspace/
+*.out
+*.test

hatch/ARCHITECTURE.md

@@ -0,0 +1,93 @@
+# Architecture
+
+Hatch follows a **Lean Hexagonal** (ports & adapters) design: a pure domain at
+the center, use-case services that depend on **ports** (interfaces), and
+infrastructure as **adapters** behind those ports. "Lean" = we only introduce a
+port where it buys decoupling or testability; we don't abstract things we will
+never swap (the filesystem *is* the database, by design).
+
+## The dependency rule
+
+Dependencies point **inward**. Inner layers never import outer ones.
+
+```
+   driving adapters            cmd/hatch, internal/cli, internal/tui, cmd/hatch-mock
+        │ wire + call
+        ▼
+   use cases (application)     wf · compile · metrics · ceremony · orchestrator · docs · config
+        │ depend on
+        ▼
+   ports (interfaces)          wf.Board · wf.Ledger · gate.Runner · orchestrator.Adapter
+        ▲ implemented by
+        │
+   adapters (infrastructure)   store · bus · gate.ShellRunner · orchestrator(claude/codex/…/mock)
+                               presence · oncall · mux · mdfront · paths
+        │ all built on
+        ▼
+   domain (pure)               model   (entities + value objects, zero IO imports)
+```
+
+## Layers
+
+| Layer | Packages | Rule |
+|---|---|---|
+| **Domain** | `internal/model` | Pure data + invariants (tickets, registry, workflow, ledger entries, **messages**). Imports nothing from the project. |
+| **Use cases** | `internal/wf`, `compile`, `metrics`, `ceremony`, `orchestrator`, `docs`, `config` | Orchestrate the domain via **ports**; no direct knowledge of *how* IO happens. |
+| **Ports** | `internal/port` (`Board`, `Ledger`, `Bus`, `OnCall`) + `gate.Runner`, `orchestrator.Adapter` | Interfaces the use-case layer depends on; adapters satisfy them. |
+| **Adapters** | `internal/store` (filesystem board/ledger/KB), `bus` (filesystem messaging), `gate.ShellRunner` (exec), `orchestrator` per-kind agent adapters + `mock`, `mux` (tmux/zellij), `presence`, `oncall`, `mdfront`, `paths` | Implement ports / wrap the outside world. |
+| **Driving adapters** | `cmd/hatch`, `internal/cli`, `internal/tui`, `cmd/hatch-mock` | The composition root: parse input, wire concrete adapters into use cases. |
+
+## Ports in practice
+
+The ports live in **`internal/port`** (`Board`, `Ledger`, `Bus`, `OnCall`),
+plus consumer-local ports where they belong to one boundary (`gate.Runner`,
+`orchestrator.Adapter`). Infrastructure packages provide adapters that satisfy
+them, asserted at compile time (`var _ port.Board = (*store.Board)(nil)`).
+
+- **`wf.Engine`** — the workflow engine holds `port.Board/Ledger/Bus/OnCall`
+  and exposes `Move`/`Escalate` as methods. It imports **no infrastructure**
+  (only `port` + `model` + `config` + `gate`). `engineFor(ws)` in the CLI wires
+  the concrete adapters.
+- **`orchestrator.Orchestrator`** — holds `port.Ledger` + `port.Bus`; `Run`/
+  `Execute` are methods. The agent boundary itself is `orchestrator.Adapter`
+  (Claude/Codex/agy/Kiro + `mock` test adapter) — textbook ports & adapters.
+- **`gate.Runner`** — gate command execution sits behind a port; `ShellRunner`
+  is the production adapter, fakes are used in tests (no real `sh`).
+- **`metrics.Compute(port.Ledger)`** and **`ceremony.Service{Board, Ledger,
+  Bus, KB}`** — the reporting use cases read through ports too. To make this
+  clean, the messaging value types (`Message`, `SearchOpts`, message kinds) live
+  in the **domain** (`model`); `bus` re-exports them as aliases for terse call
+  sites, and `port.Bus.Search` / `port.KB.List` return domain types — so no
+  adapter type ever leaks into a port.
+
+### Every use case is port-based
+
+The whole use-case layer — `wf`, `orchestrator`, `gate`, `metrics`,
+`ceremony` — depends only on `internal/port` (+ `model`/`config`). None import
+`internal/store` or `internal/bus`. Concrete adapters are wired exclusively at
+the composition root (`internal/cli` helpers `engineFor`, `orch`,
+`ceremonyService`; the TUI builds them inline). The remaining direct adapter use
+in `cli`/`tui` is the composition root itself, which is expected to know
+concretes.
+
+## Where we stay Lean (intentional non-ports)
+
+We do **not** hide these behind interfaces, because there is one real
+implementation and swapping it is a non-goal:
+
+- The filesystem layout (`paths`) and markdown encoding (`mdfront`) — the
+  storage format is the product; the adapters (`store`, `bus`) are built on them.
+- `presence` is read by the CLI's capacity-aware assignment (`pickAgent`), which
+  is part of the composition root — no port needed there.
+
+If a second backend ever appears (e.g. a server-backed store), the seams above
+(`store` behind `wf.Board`/`wf.Ledger`) are where a new adapter slots in without
+touching the engine.
+
+## Testing reflects the architecture
+
+- Domain + use cases are unit-tested with fakes through ports (`gate` with a
+  fake `Runner`; `wf` with the real `store` satisfying the interfaces).
+- `orchestrator` is exercised end-to-end with the **mock** agent adapter.
+- `internal/cli` has a full lifecycle integration test driving the real command
+  tree (init → compile → ticket → run → logs → report).

hatch/HANDOFF.md

@@ -0,0 +1,114 @@
+# HANDOFF — tiếp tục phát triển Hatch ở local
+
+Tài liệu bàn giao để dev tiếp Hatch trên máy của bạn. Đọc cùng:
+`docs/20-embedded-harness-pivot.md` (mô hình hiện hành), `ARCHITECTURE.md`
+(Lean Hexagonal), `docs/architecture-diagram.md` (sơ đồ).
+
+## 1. Hatch là gì (sau pivot)
+
+Hatch là **embedded harness** cho một squad coding-agent làm trên một repo:
+**coding agent là entrypoint và tự lái**; Hatch cung cấp **chat dùng chung
+(= giao tiếp + backlog, thread = task)** và **Knowledge Base**, phơi cho agent
+qua **MCP server**. Hatch **không** spawn/điều khiển agent. `hatch board`/
+`chat`/`status` chỉ là **view read-only**. Quy trình/phân vai là **protocol
+được compile** vào `CLAUDE.md`/`AGENTS.md`/`GEMINI.md`/`.kiro` (prose), không
+phải engine cưỡng chế.
+
+> Docs `00–19` mô tả thiết kế **trước pivot** (Hatch tự lái). Khi mâu thuẫn,
+> **doc 20 thắng** và hành vi CLI thực tế là chuẩn.
+
+## 2. Build / test / run
+
+Yêu cầu: **Go 1.24+** (go.mod khai `go 1.25.0`), **git**.
+
+```bash
+cd hatch
+make build           # → bin/hatch (+ bin/hatch-mock, chỉ dùng cho legacy)
+make lint            # go vet + kiểm gofmt
+make test            # toàn bộ test (build mặc định)
+make install         # go install ./cmd/hatch → $(go env GOPATH)/bin
+./scripts/onboard.sh # build + demo trong ./demo-workspace (không cần agent thật)
+```
+
+Hai cấu hình build — **luôn chạy cả hai trước khi push**:
+
+```bash
+go build ./...                 && go test ./...                 # default (sản phẩm)
+go build -tags hatch_legacy ./... && go test -tags hatch_legacy ./...  # + operator đã archive
+```
+
+## 3. Trạng thái hiện tại (đã xong)
+
+- **MCP server** `hatch mcp --as <agent>` (stdio) — tools: whoami, chat_open,
+  chat_post, chat_read, chat_inbox, chat_search, chat_channels, kb_add,
+  kb_search. `--as` rỗng → `$HATCH_AGENT` → agent kind=claude đầu tiên.
+  (`internal/mcpserver/`, `internal/cli/mcp.go`)
+- **compile** tiêm protocol (workflow prose + chat etiquette + DoD self-check
+  + khối orchestrator cho lead) vào surfaces; đăng ký MCP per-agent.
+  (`internal/compile/render.go`, `mcp.go`)
+- **Claude plugin** `hatch/plugin/` (MCP + skill `hatch-chat` + `/hatch`) +
+  `.claude-plugin/marketplace.json` ở repo root.
+- **board/chat/status read-only** (`internal/tui/`, `internal/cli/status.go`).
+- **`hatch init --client cc|codex|agy|kiro`** — wire MCP cho từng client
+  (`internal/cli/client.go`).
+- **Workspace phân tầng**: `~/.hatch` global + `.hatch` local override; output
+  compile luôn vào repo hiện tại. (`internal/paths/`, `config.Workspace.Out()`)
+- **Operator tự-lái archived** sau tag `hatch_legacy` (run/plan/watch/tick,
+  orchestrator, workflow-engine, ceremonies, ask/convene, pair/mob, presence,
+  oncall, cost/budget, workload/perf, report).
+
+## 4. CẦN VERIFY Ở LOCAL (chưa kiểm được trên remote)
+
+Đây là việc đầu tiên nên làm — môi trường remote không có agent CLI thật:
+
+1. **MCP handshake thật** với từng agent:
+   - Claude Code: cài plugin (`/plugin marketplace add fioenix/overclaud` →
+     `/plugin install hatch@hatch`) hoặc dựa `.mcp.json`; gọi thử tool
+     `whoami`, `chat_open`, `chat_inbox`. Kiểm 2 agent (vd claude + codex) cùng
+     thấy một chat: agent A `chat_open @codex …`, agent B `chat_inbox` thấy.
+   - Codex: `hatch init --client codex` (cần `codex` trên PATH → nó gọi
+     `codex mcp add hatch -- hatch mcp --as codex`). Xác nhận `~/.codex/
+     config.toml` có `[mcp_servers.hatch]` và Codex gọi được tool.
+   - **agy (Antigravity CLI)**: `hatch init --client agy` ghi
+     `~/.gemini/config/mcp_config.json`. **Cần xác nhận runtime path đúng** với
+     bản agy bạn cài (có migration; xem `google-antigravity/antigravity-cli#60`).
+     Lưu ý bug stdout non-TTY (#76) có thể ảnh hưởng.
+   - Kiro: `.kiro/settings/mcp.json`.
+2. **`hatch doctor`** với agent thật đã đăng nhập (chỉ gọi lệnh auth của từng
+   CLI, KHÔNG quét thư mục creds — giữ nguyên nguyên tắc này).
+3. **Orchestrator ≠ Claude**: gán `conductor` cho codex/agy trong
+   `registry.yaml`, `hatch compile`, kiểm khối orchestrator vào đúng
+   AGENTS.md/GEMINI.md và agent đó thật sự điều phối qua chat.
+
+## 5. Kiến trúc & nơi sửa
+
+Lean Hexagonal (xem `ARCHITECTURE.md`):
+- `internal/model/` — domain types (Message, KBEntry, Registry, Workflow…).
+- `internal/port/` — interfaces (Board/Ledger/Bus/KB…).
+- Adapters: `internal/bus/` (chat), `internal/store/` (kb/ledger/board),
+  `internal/compile/` (SSOT→surfaces+MCP), `internal/mcpserver/` (MCP).
+- Driving: `internal/cli/` (Cobra), `internal/tui/` (Bubble Tea), `cmd/hatch/`.
+- SSOT mẫu + template: `internal/scaffold/templates/`.
+
+Thêm một MCP tool: sửa `internal/mcpserver/server.go` (+ struct ở `types.go`).
+Đổi nội dung compiled: `internal/compile/render.go`. Thêm client: `resolveClientKind`
++ `setupClient` trong `internal/cli/client.go`.
+
+## 6. Hạn chế & ý tưởng kế tiếp
+
+- **agy path** dựa trên tài liệu, chưa chạy binary thật → verify (#4).
+- **compile manifest** lưu trong SSOT; khi global SSOT dùng cho NHIỀU repo,
+  `compile --check` chỉ nhớ outputs repo cuối — chấp nhận tạm; nếu cần, đưa
+  manifest về theo output-root.
+- **Plugin** mới có cho Claude; Codex/Kiro/agy dựa surfaces (đủ dùng).
+- `cmd/hatch-mock` chỉ phục vụ legacy orchestrator — cân nhắc gỡ khỏi
+  `make build` mặc định.
+- Ý tưởng: `hatch doctor` đọc/thử `~/.gemini/config/mcp_config.json` &
+  `~/.codex/config.toml` để báo trạng thái đăng ký MCP per-client; pixel-game
+  visualize cho `hatch chat` (đã nêu trong tầm nhìn).
+
+## 7. Git
+
+- Branch: `claude/agents-control-tower-bo6w3f` (PR #1, draft).
+- Quy ước: dev trên branch này; chạy `make lint && make test` (+ legacy) trước
+  khi push; `go mod tidy` nếu đổi deps (CI có check tidy).