2026-06-08 13:55:27 +02:00
|
|
|
|
# AGENTS.md
|
|
|
|
|
|
|
|
|
|
|
|
Guidance for agents working in `shard-wiki`.
|
|
|
|
|
|
|
|
|
|
|
|
## Read First
|
|
|
|
|
|
|
|
|
|
|
|
1. `INTENT.md` — aspiration and boundaries (stable; architectural changes are rare).
|
|
|
|
|
|
2. `SCOPE.md` — what we are achieving now and current maturity.
|
|
|
|
|
|
3. `.custodian-brief.md` — State Hub snapshot (generated; do not edit manually).
|
|
|
|
|
|
|
|
|
|
|
|
## Documentation Layout
|
|
|
|
|
|
|
|
|
|
|
|
This repo follows the CoulombSocial / HelixForge / MarkiTect documentation
|
|
|
|
|
|
layout (recommendation, not strict law). Efficient retrieval by purpose:
|
|
|
|
|
|
|
|
|
|
|
|
| Path | Purpose |
|
|
|
|
|
|
|------|---------|
|
|
|
|
|
|
| `INTENT.md` | Aspiration and boundaries |
|
|
|
|
|
|
| `SCOPE.md` | Top-level view of current achievement; closes gap to INTENT |
|
|
|
|
|
|
| `research/` | Exploration results (`yymmdd-` prefix on files or subdirs) |
|
|
|
|
|
|
| `demand/` | Inbound requests not yet reviewed into spec or workplans |
|
|
|
|
|
|
| `spec/` | Implementation guardrails (PRD, TSD, use cases, architecture) |
|
|
|
|
|
|
| `workplans/` | State Hub–registered implementation tasks |
|
|
|
|
|
|
| `docs/` | Stakeholder documentation (users, developers, humans, agents) |
|
|
|
|
|
|
| `wiki/` | Perspective-free interconnected knowledge (wiki UI when connected) |
|
|
|
|
|
|
| `issues/` | Mirror of relevant open tickets when ticket systems are in use |
|
|
|
|
|
|
| `history/` | Archived material (`yymmdd-` prefix); out of scope for daily work |
|
|
|
|
|
|
|
|
|
|
|
|
**Mode of operation:** close SCOPE → INTENT while learning; refine both as needed.
|
|
|
|
|
|
|
|
|
|
|
|
## Domain Vocabulary
|
|
|
|
|
|
|
|
|
|
|
|
Honor terms from `INTENT.md`: shard, root entity, adapter contract, projection,
|
|
|
|
|
|
overlay, coordination journal, shard modes. Do not invent parallel vocabulary.
|
|
|
|
|
|
|
|
|
|
|
|
## Build And Test
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
pip install -e ".[dev]"
|
|
|
|
|
|
pytest
|
|
|
|
|
|
ruff check
|
|
|
|
|
|
ruff format
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## State Hub
|
|
|
|
|
|
|
|
|
|
|
|
Workplans register with State Hub. After workplan changes:
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
cd ~/state-hub && make fix-consistency REPO=shard-wiki
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
Finished or canceled workplans move to `history/` with a `yymmdd-` archive prefix.
|
|
|
|
|
|
|
|
|
|
|
|
## Where To Put New Material
|
|
|
|
|
|
|
|
|
|
|
|
- Exploratory analysis → `research/yymmdd-<topic>/`
|
|
|
|
|
|
- Raw feature ask or external requirement → `demand/`
|
|
|
|
|
|
- Reviewed design ready to guide code → `spec/`
|
|
|
|
|
|
- Implementation tasks → `workplans/`
|
|
|
|
|
|
- User/dev/agent how-to → `docs/`
|
2026-06-18 22:48:39 +02:00
|
|
|
|
- Collaborative unstructured notes → `wiki/`
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## Credential and access routing
|
|
|
|
|
|
|
|
|
|
|
|
**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect**
|
|
|
|
|
|
for inference. Run this check **before** requesting secrets, API keys, SSH access,
|
|
|
|
|
|
login tokens, or database passwords — in any repo, not only `ops-warden`.
|
|
|
|
|
|
|
|
|
|
|
|
ops-warden **issues SSH certificates only** (`warden sign`, `cert_command`). Every
|
|
|
|
|
|
other credential need belongs to another subsystem. **Do not** message
|
|
|
|
|
|
`ops-warden` on State Hub expecting a secret value; the reply is a pointer, not a key.
|
|
|
|
|
|
|
|
|
|
|
|
### Lookup (do this first)
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
warden route find "<describe your need>" --json
|
|
|
|
|
|
warden route show <catalog-id> --json
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run warden`).
|
|
|
|
|
|
|
|
|
|
|
|
| Agent runtime | How to orient |
|
|
|
|
|
|
| --- | --- |
|
|
|
|
|
|
| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=shard-wiki` is for coordination, not secret vending |
|
|
|
|
|
|
| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workstreams; **still** use `warden route` for credential ownership |
|
|
|
|
|
|
| **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` |
|
|
|
|
|
|
|
|
|
|
|
|
### Quick routing table
|
|
|
|
|
|
|
|
|
|
|
|
| I need… | Owner | ops-warden executes? |
|
|
|
|
|
|
| --- | --- | --- |
|
|
|
|
|
|
| SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` |
|
|
|
|
|
|
| API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only |
|
|
|
|
|
|
| Login / OIDC / MFA | key-cape / Keycloak | No — route only |
|
|
|
|
|
|
| Authorization decision | flex-auth | No — route only |
|
|
|
|
|
|
| activity-core → issue-core emission | activity-core + issue-core | No — `warden route show activity-core-issue-sink` |
|
|
|
|
|
|
| SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only |
|
|
|
|
|
|
|
|
|
|
|
|
### Anti-patterns (do not do these)
|
|
|
|
|
|
|
|
|
|
|
|
- `POST /messages/` to `ops-warden` asking for `ISSUE_CORE_API_KEY`, `OPENROUTER_API_KEY`, etc.
|
|
|
|
|
|
- Inventing `warden secret`, `warden login`, `warden bao`, `warden tunnel` — they do not exist
|
|
|
|
|
|
- Pasting secrets into Git, State Hub, workplans, logs, or chat
|
|
|
|
|
|
|
|
|
|
|
|
### Other capabilities (reuse-surface)
|
|
|
|
|
|
|
|
|
|
|
|
Non-credential capabilities are usually discovered through **reuse-surface** federation
|
|
|
|
|
|
(`reuse-surface` registry / `capability.*` indexes). Credential routing is inlined in
|
|
|
|
|
|
every repo's agent instructions because it is high-frequency, high-risk, and easy to
|
|
|
|
|
|
get wrong.
|
|
|
|
|
|
|
|
|
|
|
|
**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml`
|
