Template
mathiasandClaude Opus 4.8
c6f8ea477b
The template carried the old multi-tool/agentsquad-era CAD-executor scaffold. Refresh it to the consolidated single-harness reality (hyperguild#75/#76): Claude Code + hyperguild, session-based, brain + gitea MCP. No dispatch automation added (out of scope — dispatch stays manual until real friction warrants it). Removed (multi-tool + dead generator + deployed-agent-era): - .aider.conf.yml, .aider.conventions.md, .cursorrules - .context/ (mcp.json, PROJECT.md, system-prompt.txt) - agent-policy.yaml (k8s NetworkPolicy scaffold) - scripts/context-sync.sh (generated the above from .context/PROJECT.md — now input-less) + its context:sync* Taskfile tasks Added / updated: - .mcp.json (root, hyperguild-shaped: brain + gitea, Bearer env tokens) - CLAUDE.md / AGENTS.md / README.md → single-harness workflow (issue → hyperguild session → PR → report-back comment → brain capture) - AGENT_BOUNDARIES.md kept (harness-agnostic egress/scope guidance); repointed its two references to the removed agent-policy.yaml Left alone: cd.yml, Dockerfile, Taskfile (build/test), go.mod, cmd/, internal/, pkg/, .claude/. No dangling refs to removed files (verified). Refs infra#178. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
79 lines
3.2 KiB
Markdown
79 lines
3.2 KiB
Markdown
# Agent boundaries — __PROJECT_NAME__
|
|
|
|
Operational scope for this agent. Read before extending tools, adding endpoints,
|
|
or wiring new data sources. Defaults are conservative; widen explicitly.
|
|
|
|
## Network scope
|
|
|
|
Egress is allow-listed. The agent MAY reach:
|
|
|
|
| Endpoint | Purpose | Protocol | Default port |
|
|
|--------------------------------|----------------------------------|----------|--------------|
|
|
| `llm-api.d-ma.be` (LiteLLM) | Model inference | HTTPS | 443 |
|
|
| `brain-mcp.d-ma.be` | Knowledge base (BM25 + synth) | HTTPS | 443 |
|
|
| `gitea-mcp.d-ma.be` | Repo/issue/PR ops | HTTPS | 443 |
|
|
| `jaeger.d-ma.be` | OTLP trace export | HTTP | 4318 |
|
|
| In-cluster DNS (`kube-dns`) | Service discovery | UDP | 53 |
|
|
|
|
Egress MUST be blocked to:
|
|
|
|
- Public Slack / Discord / Telegram / email
|
|
- Third-party LLM APIs (OpenAI, Anthropic, Google) unless explicitly added below
|
|
- Public package registries from runtime (proxy through build only)
|
|
- Customer/client domains not listed in the engagement scope
|
|
|
|
Add new endpoints by editing this table in the same commit that wires them, and enforce them
|
|
with whatever egress mechanism the deployment uses (e.g. a k8s NetworkPolicy in the project's
|
|
own deploy manifests).
|
|
|
|
## File scope
|
|
|
|
Read scope:
|
|
|
|
- Mounted ConfigMaps and Secrets under `/etc/__PROJECT_NAME__/`
|
|
- Working dir under `/var/lib/__PROJECT_NAME__/` (ephemeral)
|
|
- `/tmp` for streaming artifacts (size-capped via emptyDir)
|
|
|
|
Write scope:
|
|
|
|
- `/var/lib/__PROJECT_NAME__/` only
|
|
- `/tmp` only
|
|
- Never `/`, `/etc`, `/var/log`, host paths, or sibling pod volumes
|
|
|
|
Persistent state MUST live in PostgreSQL (`postgres.d-ma.be`) or object storage —
|
|
not the pod filesystem.
|
|
|
|
## Approved operations
|
|
|
|
The agent MAY:
|
|
|
|
- Issue LLM inference requests via the LiteLLM adapter
|
|
- Query the brain MCP for prior art / postmortems
|
|
- Read repos, issues, and PRs via gitea-mcp
|
|
- Emit OTLP spans for `invoke_agent`, `generate_content`, and any custom tool spans
|
|
- Write to its own k8s logs (stdout/stderr; structured `slog`)
|
|
|
|
The agent MUST NOT, without explicit opt-in in code review:
|
|
|
|
- Write to gitea (open PR, push branch, comment) — requires `--write` flag and audit log
|
|
- Execute shell commands in non-sandboxed contexts
|
|
- Mutate k8s resources (no kubectl/Helm/Flux operations from runtime)
|
|
- Forward LLM outputs to external systems before redaction
|
|
- Hold conversation logs longer than the session TTL (24h default)
|
|
|
|
## Failure posture
|
|
|
|
- Outbound DNS failure → fail closed, retry with jitter, surface to caller
|
|
- LLM 5xx → bounded retry (3 attempts), then return error to caller
|
|
- Brain MCP unavailable → continue without prior-art lookup; log degraded mode
|
|
- OTLP unavailable → drop spans silently; never block request path
|
|
|
|
## Review triggers
|
|
|
|
Bump this doc (and the deployment's egress enforcement) when:
|
|
|
|
- A new external endpoint is added
|
|
- A new tool with side effects is wired in
|
|
- The agent gains write access to anything (repo, DB table, filesystem path)
|
|
- A client engagement narrows or widens the data scope
|