generated from coulomb/repo-seed
tegwick
cca5bf83c3
Propagate shared credential-routing section (Codex, Claude, Grok, llm-connect) from state-hub template via scripts/propagate_credential_routing.py.
115 lines
4.6 KiB
Markdown
115 lines
4.6 KiB
Markdown
# 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/`
|
||
- 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`
|