agentic-resources/AGENTS.md

agentic-resources — Agent Instructions

Repo Identity

Purpose: Iterating towards optimal agentic performance.

Domain: helix_forge Repo slug: agentic-resources Topic ID: f39fa2a3-c491-414c-a91b-b4c5fcc6139c Workplan prefix: AGENTIC-WP-

---

Dev Workflow

The deliverable code lives in session_memory/ (the Helix Forge coding-session memory system). It is pure-stdlib Python 3.11+ — tomllib, sqlite3, dataclasses; no third-party runtime dependencies and no build step. pytest is the only dev dependency. Run everything from the repo root.

Need	Command
Python	python3 (3.11+ required for tomllib; developed on 3.12)
Install deps	none at runtime; for tests: pip install pytest (or uv pip install pytest)
Test	python3 -m pytest (full suite) · python3 -m pytest tests/test_curate_review.py (one file) · -q for quiet
Lint / build	none configured — keep changes matching surrounding style
Run: ingest sweep	python3 -m session_memory.ingest (--dry-run, --config PATH)
Run: detect	python3 -m session_memory.detect (--json, --min-frequency N)
Run: curate	python3 -m session_memory.curate (--auto-approve, --json)
Config	session_memory/config.toml; local store under session_memory/.store/ (gitignored)

Verify a change before declaring it done: run python3 -m pytest (expect all green), and for pipeline changes do a live ingest → detect → curate pass against the local store. See session_memory/README.md for the full layout and the detect → curate → distribute flow.

Editing files — Read before you Edit

Read a file (or the region you'll touch) before Edit/Write. The most common error across our own captured coding sessions was "File has not been read yet. Read it first before writing to it" — 12 of 27 real sessions, 8 repos (docs/ASSESSMENT-infra-friction.md). Two cheap reflexes eliminate it:

• Read → then Edit/Write. Don't blind-write a file you haven't read this session; the edit tools reject it and the retry wastes a turn.
• On File has been modified since read, re-Read then re-Edit. A stale read means the file changed under you — refresh before retrying, don't loop.

---

State Hub Integration

The Custodian State Hub tracks work across all domains. Interact via HTTP REST — there is no MCP server for Codex agents.

Context	URL
Local workstation	http://127.0.0.1:8000
Remote via tunnel	http://127.0.0.1:18000

Orient at session start

# Offline brief — works without hub connection
cat .custodian-brief.md

# Active workstreams for this domain
curl -s "http://127.0.0.1:8000/workstreams/?topic_id=f39fa2a3-c491-414c-a91b-b4c5fcc6139c&status=active" \
  | python3 -m json.tool

# Check inbox
curl -s "http://127.0.0.1:8000/messages/?to_agent=agentic-resources&unread_only=true" \
  | python3 -m json.tool

Mark a message read:

curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
  -H "Content-Type: application/json" -d '{}'

Log progress (required at session close)

curl -s -X POST http://127.0.0.1:8000/progress/ \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "what was done",
    "event_type": "note",
    "author": "codex",
    "workstream_id": "<uuid>",
    "task_id": "<uuid>"
  }'

Omit workstream_id / task_id when not applicable.

Update task status

curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
  -H "Content-Type: application/json" \
  -d '{"status": "progress"}'
# values: wait | todo | progress | done | cancel

Flag a task for human review

curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
  -H "Content-Type: application/json" \
  -d '{"needs_human": true, "intervention_note": "reason"}'

---

Session Protocol

Start:

1. cat .custodian-brief.md — domain goal and open workstreams (offline-safe)
2. Check inbox: GET /messages/?to_agent=agentic-resources&unread_only=true; mark read
3. Scan workplans: ls workplans/ — note status: ready, active, or blocked files and open tasks
4. Check human-needed tasks: GET /tasks/?needs_human=true

During work:

• Update task statuses in workplan files as tasks progress
• Record significant decisions via POST /decisions/

Close:

1. Update workplan file task statuses to reflect progress
2. Log: POST /progress/ with a summary of what changed
3. Note for the custodian operator: after workplan file changes, run from ~/state-hub:

   make fix-consistency REPO=agentic-resources
   

   This syncs task status from files into the hub DB.

---

Workplan Convention (ADR-001)

Work items originate as files in this repo — not in the hub. The hub is a read/cache/index layer that rebuilds from files.

File location: workplans/AGENTIC-WP-NNNN-<slug>.md

Archived location: finished workplans may move to workplans/archived/YYMMDD-AGENTIC-WP-NNNN-<slug>.md. The YYMMDD prefix is the completion/archive date; the frontmatter id does not change.

Ad Hoc Tasks: small opportunistic fixes discovered during a session use workplans/ADHOC-YYYY-MM-DD.md with task ids ADHOC-YYYY-MM-DD-T01, etc. Use this only for low-risk work completed directly; create a normal workplan for anything needing analysis, design, approval, dependencies, or multiple phases.

Frontmatter:

---
id: AGENTIC-WP-NNNN
type: workplan
title: "..."
domain: helix_forge
repo: agentic-resources
status: proposed | ready | active | blocked | backlog | finished | archived
owner: codex
topic_slug: ...
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
state_hub_workstream_id: "<uuid>"   # written by fix-consistency — do not edit
---

Use proposed for a new draft, ready after review against current repo state, and finished after implementation. stalled and needs_review are derived health labels, not frontmatter statuses.

Task block format (one per ## section):

## Task Title

` ` `task
id: AGENTIC-WP-NNNN-T01
status: wait | todo | progress | done | cancel
priority: high | medium | low
state_hub_task_id: "<uuid>"         # written by fix-consistency — do not edit
` ` `

Task description text.

Status progression: todo → progress → done; use wait for waiting/blocked work and cancel for stopped work.

To create a new workplan:

1. Write the file following the format above
2. Notify the custodian operator to run make fix-consistency REPO=agentic-resources (or send a message to the hub agent via POST /messages/)