generated from coulomb/repo-seed
seeded repo
This commit is contained in:
174
AGENTS.md
Normal file
174
AGENTS.md
Normal file
@@ -0,0 +1,174 @@
|
||||
# railiance-forge - Agent Instructions
|
||||
|
||||
## Repo Identity
|
||||
|
||||
**Purpose:** Railiance forge and artifact infrastructure - source forge runtime,
|
||||
container/package registries, forge-backed runner substrate, artifact lifecycle,
|
||||
and future Forgejo migration.
|
||||
|
||||
**Domain:** railiance
|
||||
**Repo slug:** railiance-forge
|
||||
**Topic ID:** `ca369340-a64e-442e-98f1-a4fa7dc74a38`
|
||||
**Workplan prefix:** `FORGE-WP-`
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
```bash
|
||||
cat .custodian-brief.md
|
||||
|
||||
curl -s "http://127.0.0.1:8000/workstreams/?topic_id=ca369340-a64e-442e-98f1-a4fa7dc74a38&status=active" \
|
||||
| python3 -m json.tool
|
||||
|
||||
curl -s "http://127.0.0.1:8000/messages/?to_agent=railiance-forge&unread_only=true" \
|
||||
| python3 -m json.tool
|
||||
```
|
||||
|
||||
Mark a message read:
|
||||
|
||||
```bash
|
||||
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
|
||||
-H "Content-Type: application/json" -d '{}'
|
||||
```
|
||||
|
||||
### Log progress at session close
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"status": "progress"}'
|
||||
```
|
||||
|
||||
Canonical task values: `wait | todo | progress | done | cancel`.
|
||||
|
||||
### Flag a task for human review
|
||||
|
||||
```bash
|
||||
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.
|
||||
2. Check inbox:
|
||||
`GET /messages/?to_agent=railiance-forge&unread_only=true`; mark read.
|
||||
3. Scan workplans: `ls workplans/` and note `ready`, `active`, or `blocked`
|
||||
workplans and open tasks.
|
||||
4. Check blocked tasks: `GET /tasks/?needs_human=true`.
|
||||
|
||||
**During work:**
|
||||
|
||||
- Update task statuses in workplan files as tasks progress.
|
||||
- Record significant decisions via `POST /decisions/`.
|
||||
- Keep forge responsibilities separate from S4 templates and S5 app releases.
|
||||
|
||||
**Close:**
|
||||
|
||||
1. Update workplan file task statuses.
|
||||
2. Log progress with `POST /progress/`.
|
||||
3. After workplan file changes, run from `~/state-hub`:
|
||||
|
||||
```bash
|
||||
make fix-consistency REPO=railiance-forge
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workplan Convention
|
||||
|
||||
Work items originate as files in this repo. State Hub indexes those files as
|
||||
workstreams and task blocks.
|
||||
|
||||
**File location:** `workplans/FORGE-WP-NNNN-<slug>.md`
|
||||
|
||||
**Archived location:** `workplans/archived/YYMMDD-FORGE-WP-NNNN-<slug>.md`
|
||||
|
||||
**Frontmatter:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: FORGE-WP-NNNN
|
||||
type: workplan
|
||||
title: "..."
|
||||
domain: railiance
|
||||
repo: railiance-forge
|
||||
status: proposed | ready | active | blocked | backlog | finished | archived
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
created: "YYYY-MM-DD"
|
||||
updated: "YYYY-MM-DD"
|
||||
state_hub_workstream_id: "<uuid>" # written by fix-consistency - do not edit
|
||||
---
|
||||
```
|
||||
|
||||
**Task block format:**
|
||||
|
||||
````text
|
||||
## Task Title
|
||||
|
||||
```task
|
||||
id: FORGE-WP-NNNN-T01
|
||||
status: todo | progress | done | wait | 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`, or `wait` / `cancel`.
|
||||
|
||||
To create a new workplan:
|
||||
|
||||
1. Write the file following the format above.
|
||||
2. Run from `~/state-hub`:
|
||||
|
||||
```bash
|
||||
make fix-consistency REPO=railiance-forge
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Repository Boundaries
|
||||
|
||||
This repo owns forge runtime and artifact infrastructure. It does not own:
|
||||
|
||||
- OS/host provisioning (`railiance-infra`);
|
||||
- Kubernetes runtime primitives (`railiance-cluster`);
|
||||
- shared database/storage/secret platforms (`railiance-platform`);
|
||||
- generic CI/CD templates and developer portal paths (`railiance-enablement`);
|
||||
- user-facing application releases (`railiance-apps`);
|
||||
- source application code.
|
||||
Reference in New Issue
Block a user