tegwick
cca5bf83c3
Propagate shared credential-routing section (Codex, Claude, Grok, llm-connect) from state-hub template via scripts/propagate_credential_routing.py.
4.6 KiB
AGENTS.md
Guidance for agents working in shard-wiki.
Read First
INTENT.md— aspiration and boundaries (stable; architectural changes are rare).SCOPE.md— what we are achieving now and current maturity..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
pip install -e ".[dev]"
pytest
ruff check
ruff format
State Hub
Workplans register with State Hub. After workplan changes:
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)
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/toops-wardenasking forISSUE_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