agents/ — Agentic runtime workspace

5 agent (Spec Author / Test Gen / Coder / Reviewer / Curator) chia sẻ _shared/ (env, logger, claude-client, mcp-tools).

Run modes

| Mode | GHIAK_STUB | Behavior | |---|---|---| | Stub (default for tests + smoke) | 1 | mcp-tools.ts returns fixture JSON. Anthropic client = scripted in run.ts. No network. | | Real | 0 | mcp-tools.ts → real MCP Worker fetch. Anthropic client = live API. |

Real-mode setup

Required env vars:

export GHIAK_STUB=0
export GHIAK_MCP_URL=https://ghiak-mcp.huy-tran-957.workers.dev   # deployed Worker (account subdomain)
export GHIAK_API_KEY=$(cat ~/.ghiak/key)                          # bearer token (Lead-distributed)
export ANTHROPIC_API_KEY=...                                      # team-shared
export GITHUB_TOKEN=$(gh auth token)
export GITHUB_REPOSITORY=monstar-lab-consulting/mvn-hackathon-dn-dn-beach-ghiak-agentic
export GITHUB_EVENT_NAME=issues
export GITHUB_EVENT_PATH=spec-author/test/fixtures/stub-event.json
export AGENT_NAME=spec-author

Worker URL has account subdomain huy-tran-957 (Lead's Cloudflare account). The canonical placeholder ghiak-mcp.workers.dev in execution-plan docs is a documentation shorthand — actual DNS requires the subdomain. Custom domain (e.g. mcp.ghiak.dev) planned post-Day-4.

Smoke harnesses

pnpm --filter @beach-ai/ghiak-agents smoke:stub   # offline, 15 tools fixture round-trip
pnpm --filter @beach-ai/ghiak-agents smoke:real   # live: env validate + /healthz + /mcp tools/list

smoke:real requires all env vars above. Exits non-zero on:

• GHIAK_STUB=1 (wrong mode)
• env schema invalid
• /healthz ≠ 200
• /mcp tools/list ≠ 200 (401 → bearer key hash mismatch on Worker)

Run a single agent locally

pnpm tsx spec-author/run.ts

Reads GITHUB_EVENT_PATH JSON, drives Claude agentic loop with whitelisted tools from spec-author/tools.ts. Stub mode uses scripted Claude responses (see run.ts buildStubAnthropic); real mode hits Anthropic API.

Tickets

• T-D1.C1..C6 — workspace scaffold + _shared utilities + claude-client + 15-tool registry + system prompt
• T-D2.C1..C7 — spec-author tools whitelist, stub-mode e2e, real MCP swap (C3), prompt v1.0, workflow YAML, manual e2e, feedback loop