coulomb/railiance-forge
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Normalize agent instructions and workplan frontmatter (STATE-WP-0067)

Browse Source 
- Align agent files with on-disk workplan prefixes (infer from workplan ids)
- Set workplan domain to registered domain_slug; add topic_slug where applicable
- Repair frontmatter delimiter formatting; migrate legacy task status literals
- Regenerate AGENTS.md, CLAUDE.md, and .claude/rules from State Hub templates
This commit is contained in:
Bernd Worsch
2026-06-22 23:16:28 +02:00
parent 40a638ea37
commit 5a1c1ca629
15 changed files with 297 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files

138
AGENTS.md
View File

@@ -1,12 +1,10 @@
# railiance-forge - Agent Instructions
# 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.
**Purpose:** Railiance forge and artifact infrastructure: current Gitea operation, future Forgejo migration, container/package registries, runner substrate, artifact lifecycle, and forge operating evidence.
**Domain:** railiance
**Domain:** financials
**Repo slug:** railiance-forge
**Topic ID:** `ca369340-a64e-442e-98f1-a4fa7dc74a38`
**Workplan prefix:** `FORGE-WP-`
@@ -15,7 +13,7 @@ and future Forgejo migration.
## State Hub Integration
The Custodian State Hub tracks work across all domains. Interact via HTTP REST -
The Custodian State Hub tracks work across all domains. Interact via HTTP REST —
there is no MCP server for Codex agents.
| Context | URL |
@@ -26,23 +24,25 @@ there is no MCP server for Codex agents.
### Orient at session start
```bash
# 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=ca369340-a64e-442e-98f1-a4fa7dc74a38&status=active" \
| python3 -m json.tool
# Check inbox
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
### Log progress (required at session close)
```bash
curl -s -X POST http://127.0.0.1:8000/progress/ \
@@ -64,10 +64,9 @@ Omit `workstream_id` / `task_id` when not applicable.
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
```
Canonical task values: `wait | todo | progress | done | cancel`.
### Flag a task for human review
```bash
@@ -81,46 +80,24 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
## 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`.
1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe)
2. Check inbox: `GET /messages/?to_agent=railiance-forge&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/`.
- Keep forge responsibilities separate from S4 templates and S5 app releases.
## Verification Commands
This repo currently contains documentation, workplans, and read-only operator
entry points. There is no app build, package install, or unit-test command yet.
Use these checks for ordinary edits:
```bash
git diff --check
make registry-docs
make check-tools
make -C /home/worsch/state-hub fix-consistency REPO=railiance-forge
```
`make gitea-status` is read-only but requires a kubeconfig pointed at a
representative Railiance cluster.
- Update task statuses in workplan files as tasks progress
- Record significant decisions via `POST /decisions/`
**Close:**
1. Update workplan file task statuses.
2. Log progress with `POST /progress/`.
3. After workplan file changes, run from `~/state-hub`:
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`:
```bash
make fix-consistency REPO=railiance-forge
```
This syncs task status from files into the hub DB.
---
@@ -174,70 +151,69 @@ every repo's agent instructions because it is high-frequency, high-risk, and eas
get wrong.
**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml`
<!-- REPO-AGENTS-EXTENSIONS -->
<!-- Append repo-specific agent instructions below this marker.
The state-hub template sync preserves content after this line. -->
---
## Workplan Convention
## Workplan Convention (ADR-001)
Work items originate as files in this repo. State Hub indexes those files as
workstreams and task blocks.
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/FORGE-WP-NNNN-<slug>.md`
**File location:** `workplans/RAILIANCE-WP-NNNN-<slug>.md`
**Archived location:** `workplans/archived/YYMMDD-FORGE-WP-NNNN-<slug>.md`
**Archived location:** finished workplans may move to
`workplans/archived/YYMMDD-RAILIANCE-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:**
```yaml
---
id: FORGE-WP-NNNN
id: RAILIANCE-WP-NNNN
type: workplan
title: "..."
domain: railiance
domain: financials
repo: railiance-forge
status: proposed | ready | active | blocked | backlog | finished | archived
owner: codex
topic_slug: railiance
topic_slug: ...
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
state_hub_workstream_id: "<uuid>" # written by fix-consistency - do not edit
state_hub_workstream_id: "<uuid>" # written by fix-consistency — do not edit
---
```
**Task block format:**
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.
````text
**Task block format** (one per `##` section):
```
## Task Title
```task
id: FORGE-WP-NNNN-T01
status: todo | progress | done | wait | cancel
` ` `task
id: RAILIANCE-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
```
state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
` ` `
Task description text.
````
```
Status progression: `todo` -> `progress` -> `done`, or `wait` / `cancel`.
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. 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.
1. Write the file following the format above
2. Notify the custodian operator to run `make fix-consistency REPO=railiance-forge`
(or send a message to the hub agent via `POST /messages/`)