repo-scoping/AGENTS.md

repo-scoping — Agent Instructions

Repo Identity

Purpose: Repository Scoping — turns Git repositories into reviewable, source-linked maps of Ability → Capability → Feature → Evidence. Deterministic scanners establish observed facts; LLM-assisted extractors propose interpreted claims; humans or trusted agents approve registry truth.

Domain: capabilities
Repo slug: repo-scoping
Topic ID: 64418556-3206-457a-ba29-6884b5b12cf3
Workplan prefix: RREG-WP-

---

State Hub Integration

The Custodian State Hub tracks work across all domains. It runs at http://127.0.0.1:8000 (local) or http://127.0.0.1:18000 when accessed from a remote machine via tunnel.

Interact via HTTP — there is no MCP integration for Codex agents.

Orient at session start

# Domain workstreams
curl -s "http://127.0.0.1:8000/workstreams/?topic_id=64418556-3206-457a-ba29-6884b5b12cf3&status=active" \
  | python3 -m json.tool

# Open tasks for this repo (once workstreams are registered)
curl -s "http://127.0.0.1:8000/tasks/?status=todo" | python3 -m json.tool

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

Also read workplans/ directly — the files are the source of truth:

ls workplans/
grep -h "^status:" workplans/RREG-WP-*.md

Log progress (required at session close)

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

Include "workstream_id": "<uuid>" and "task_id": "<uuid>" when known.

Mark a message read

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

Update task status (after workstreams are synced)

curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
  -H "Content-Type: application/json" \
  -d '{"status": "in_progress"}'

---

Session Protocol

Start:

1. ls workplans/ — note active workplans and their open tasks
2. Check inbox via GET /messages/?to_agent=repo-scoping&unread_only=true
3. Check for human-flagged tasks: GET /tasks/?needs_human=true

During work:

• Update task status in the workplan file as tasks progress
• For significant decisions, record them: POST /decisions/

Close:

1. Update task statuses in workplan files to match progress
2. Call POST /progress/ with a summary of what was done
3. If workplan files changed, sync them to the hub DB:

curl -s -X POST "http://127.0.0.1:8000/repos/repo-scoping/sync" | python3 -m json.tool

This runs the ADR-001 consistency check with --fix and returns a JSON report. A "result": "warn" with only C-17 is normal (unpushed commits); no action needed. A "result": "fail" means file/DB drift that could not be auto-fixed — read the issues list.

---

Workplan Convention (ADR-001)

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

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

Frontmatter:

---
id: RREG-WP-NNNN
type: workplan
title: "..."
domain: capabilities
repo: repo-scoping
status: active | done
owner: codex
topic_slug: foerster-capabilities
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
state_hub_workstream_id: "<uuid>"   # populated by fix-consistency
---

Task blocks (one per ## section):

## Task Title

\`\`\`task
id: RREG-WP-NNNN-T01
status: todo | in_progress | done | blocked
priority: high | medium | low
\`\`\`

Task description.

Status values: todo → in_progress → done (or blocked)

---

Stack and Commands

Runtime: Python 3.x, FastAPI, SQLite (dev) / PostgreSQL (prod)
Package manager: pip / uv

# Install
pip install -e ".[dev]"

# Run dev server
uvicorn repo_scoping.web_api.app:app --reload

# Run tests
pytest tests/
pytest tests/ -k "e2e"

# Check API health
curl http://127.0.0.1:8001/health

---

Repo Boundary

This repo owns: repository ingestion, deterministic scanning, LLM-assisted candidate extraction, review/approval workflow, registry query and search.

It does NOT own: the Custodian State Hub, other domain repos, deployment infrastructure.

Coordination with other domains goes through the State Hub message inbox.