coulomb/vergabe-teilnahme
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:29 +02:00
parent b31409649c
commit a3cec3f221
23 changed files with 90 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
.claude/rules/first-session.md
View File

@@ -1,11 +1,11 @@
## First Session Protocol
Triggered when `get_domain_summary("vergabe_teilnahme")` shows **no workstreams**.
Triggered when `get_domain_summary("communication")` shows **no workstreams**.
The project is registered but work has not yet been structured.
**Step 1 — Read, don't write**
- `~/the-custodian/canon/projects/vergabe_teilnahme/project_charter_v0.1.md` — purpose, scope
- `~/the-custodian/canon/projects/vergabe_teilnahme/roadmap_v0.1.md` — planned phases
- `~/the-custodian/canon/projects/communication/project_charter_v0.1.md` — purpose, scope
- `~/the-custodian/canon/projects/communication/roadmap_v0.1.md` — planned phases
- Scan repo root: README, directory structure, existing code or docs
**Step 2 — Survey in-progress work**
@@ -17,20 +17,20 @@ roadmap phase. **Wait for approval before creating.**
**Step 4 — Create workplan file first, then DB record (ADR-001)**
```
workplans/vergabe_teilnahme-WP-NNNN-<slug>.md ← write this first
workplans/WP-NNNN-<slug>.md ← write this first
```
Then register in the hub:
```
create_workstream(topic_id="7d4d3e35-312f-4723-bde9-ddb43799109e", title="...", owner="...", description="...")
create_workstream(topic_id="36c7421b-c537-4723-bf75-42a3ebc6a1dc", title="...", owner="...", description="...")
create_task(workstream_id="<id>", title="...", priority="high|medium|low")
```
**Step 5 — Record the setup**
```
add_progress_event(
summary="First session: structured vergabe_teilnahme into N workstreams, M tasks",
summary="First session: structured communication into N workstreams, M tasks",
event_type="milestone",
topic_id="7d4d3e35-312f-4723-bde9-ddb43799109e",
topic_id="36c7421b-c537-4723-bf75-42a3ebc6a1dc",
detail={"workstreams": [...], "tasks_created": M}
)
```

8
.claude/rules/repo-identity.md
View File

@@ -1,5 +1,5 @@
**Purpose:** Django 6 + Tailwind + HTMX bid management app
**Purpose:** Coulomb project repository (bootstrapped from repo-seed template)
**Domain:** vergabe_teilnahme
**Repo slug:** vergabe_teilnahme
**Topic ID:** 7d4d3e35-312f-4723-bde9-ddb43799109e
**Domain:** communication
**Repo slug:** vergabe-teilnahme
**Topic ID:** 36c7421b-c537-4723-bf75-42a3ebc6a1dc

23
.claude/rules/session-protocol.md
View File

@@ -1,6 +1,7 @@
## Session Protocol
State Hub: http://127.0.0.1:8000
Dev Hub (State Hub API): http://127.0.0.1:8000
MCP server name in `~/.claude.json`: `dev-hub`
**Step 1 — Orient**
@@ -10,7 +11,7 @@ cat .custodian-brief.md
```
Then call the MCP tool for richer cross-domain context when MCP tools are exposed:
```
get_domain_summary("vergabe_teilnahme")
get_domain_summary("communication")
```
If MCP tools are unavailable in the current agent session, use the REST API:
```bash
@@ -21,14 +22,14 @@ If the hub is offline: `cd ~/state-hub && make api`
**Step 2 — Check inbox**
With MCP tools:
```
get_messages(to_agent="vergabe_teilnahme", unread_only=True)
get_messages(to_agent="vergabe-teilnahme", unread_only=True)
```
Mark read with `mark_message_read(message_id)`. Reply or act on coordination
requests before proceeding.
Without MCP tools:
```bash
curl -s "http://127.0.0.1:8000/messages/?to_agent=vergabe_teilnahme&unread_only=true" \
curl -s "http://127.0.0.1:8000/messages/?to_agent=vergabe-teilnahme&unread_only=true" \
| python3 -m json.tool
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
-H "Content-Type: application/json" -d '{}'
@@ -39,12 +40,12 @@ curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
ls workplans/
```
For each file with `status: ready`, `active`, or `blocked`, note pending
`todo`/`in_progress` tasks.
`wait`/`todo`/`progress` tasks.
**Step 4 — Present brief**
1. **Active workstreams** for `vergabe_teilnahme` — title, task counts, blocking decisions
2. **Pending tasks** from `workplans/` + any `[repo:vergabe_teilnahme]` hub tasks
1. **Active workstreams** for `communication` — title, task counts, blocking decisions
2. **Pending tasks** from `workplans/` + any `[repo:vergabe-teilnahme]` hub tasks
3. **Goal guidance** — if `goal_guidance` in summary:
- `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"*
- `alignment_warnings`: flag if active work is not aligned with current goal
@@ -61,23 +62,23 @@ If no workstreams: follow First Session Protocol (`first-session.md`).
**Session close:**
With MCP tools:
```
add_progress_event(summary="...", topic_id="7d4d3e35-312f-4723-bde9-ddb43799109e", workstream_id="<uuid>")
add_progress_event(summary="...", topic_id="36c7421b-c537-4723-bf75-42a3ebc6a1dc", workstream_id="<uuid>")
```
Without MCP tools:
```bash
curl -s -X POST http://127.0.0.1:8000/progress/ \
-H "Content-Type: application/json" \
-d '{"topic_id":"7d4d3e35-312f-4723-bde9-ddb43799109e","workstream_id":"<uuid>","event_type":"note","summary":"what changed","author":"codex"}'
-d '{"topic_id":"36c7421b-c537-4723-bf75-42a3ebc6a1dc","workstream_id":"<uuid>","event_type":"note","summary":"what changed","author":"codex"}'
```
If workplan files were modified, ensure the local copy is up to date first:
```bash
git -C <repo_path> pull --ff-only
cd ~/state-hub && make fix-consistency REPO=vergabe_teilnahme
cd ~/state-hub && make fix-consistency REPO=vergabe-teilnahme
```
For repos where implementation runs on a remote machine (e.g. CoulombCore),
use the combined target which pulls before fixing:
```bash
cd ~/state-hub && make fix-consistency-remote REPO=vergabe_teilnahme
cd ~/state-hub && make fix-consistency-remote REPO=vergabe-teilnahme
```
**C-15** (DB task ahead of file) is normal in multi-machine workflows — writeback
will sync the file to match DB. **C-16** (repo behind remote) blocks all writes

29
.claude/rules/stack-and-commands.md
View File

@@ -1,32 +1,19 @@
## Stack
- **Language:** Python 3.12 (Django 6), Node 22 (Vite + Tailwind v4)
- **Key deps:** Django, htmx, Alpine.js, Tailwind v4, whynot-design (vendored
under `static/src/vendor/whynot-design/`)
<!-- TODO: Fill in language, frameworks, and key dependencies -->
- **Language:**
- **Key deps:**
## Dev Commands
```bash
# TODO: Fill in the standard commands for this repo
# Install dependencies
uv sync # Python
npm ci # Node (Vite/Tailwind)
# Run dev stack
make db # Start postgres if not running
make dev # Django runserver on :9000
make css # Tailwind/Vite watcher (rebuilds main.css)
# Run tests
# Build CSS bundle for prod / for verification
npm run build # → static/dist/main.css
# Lint / type check
# Re-vendor the whynot-design system from a pinned upstream commit
make sync-whynot-design # reads .whynot-design-ref by default
# or: ./scripts/sync-whynot-design.sh <ref>
# Tests / lint
make test # uv run pytest
make lint # ruff + mypy
# Build / package (if applicable)
```
See `wiki/DesignSystem.md` for the whynot-design adoption status (Phase 1
tokens+CSS done; Phase 2 components deferred) and local style conventions.

20
.claude/rules/workplan-convention.md
View File

@@ -1,7 +1,7 @@
## Workplan Convention (ADR-001)
File location: `workplans/vergabe_teilnahme-WP-NNNN-<slug>.md`
ID prefix: `VERGABE_TEILNAHME-WP`
File location: `workplans/WP-NNNN-<slug>.md`
ID prefix: `WP-`
Work items originate as files in this repo **before** being registered in the hub.
@@ -12,7 +12,7 @@ repo state, and `finished` when implementation is complete. `stalled` and
`needs_review` are derived health labels, not stored statuses.
Closed workplans may be moved to `workplans/archived/` with a completion-date
prefix: `YYMMDD-vergabe_teilnahme-WP-NNNN-<slug>.md`. The frontmatter id remains
prefix: `YYMMDD-WP-NNNN-<slug>.md`. The frontmatter id remains
unchanged; the prefix is only for quick visual reference.
Small opportunistic tasks discovered during another session use **Ad Hoc Tasks**:
@@ -21,8 +21,20 @@ Small opportunistic tasks discovered during another session use **Ad Hoc Tasks**
directly. Promote anything requiring analysis, design, approval, dependencies, or
multiple planned phases into a normal workplan.
Ecosystem todos from other agents arrive as `[repo:vergabe_teilnahme]` hub tasks —
Ecosystem todos from other agents arrive as `[repo:vergabe-teilnahme]` hub tasks —
visible at session start. Pick one up by creating the workplan file, then registering
the workstream.
Task blocks use this shape:
```task
id: 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
```
Status progression is `todo` → `progress` → `done`; use `wait` for waiting or
blocked work and `cancel` for stopped work.
<!-- Ralph Loop rules and HEUREKA sequence: ~/.claude/CLAUDE.md — do not duplicate here -->

47
AGENTS.md
View File

@@ -2,12 +2,12 @@
## Repo Identity
**Purpose:** Django 6 + Tailwind + HTMX bid management app
**Purpose:** Coulomb project repository (bootstrapped from repo-seed template)
**Domain:** vergabe_teilnahme
**Repo slug:** vergabe_teilnahme
**Topic ID:** `7d4d3e35-312f-4723-bde9-ddb43799109e`
**Workplan prefix:** `VERGABE_TEILNAHME-WP-`
**Domain:** communication
**Repo slug:** vergabe-teilnahme
**Topic ID:** `36c7421b-c537-4723-bf75-42a3ebc6a1dc`
**Workplan prefix:** `WP-`
---
@@ -28,11 +28,11 @@ there is no MCP server for Codex agents.
cat .custodian-brief.md
# Active workstreams for this domain
curl -s "http://127.0.0.1:8000/workstreams/?topic_id=7d4d3e35-312f-4723-bde9-ddb43799109e&status=active" \
curl -s "http://127.0.0.1:8000/workstreams/?topic_id=36c7421b-c537-4723-bf75-42a3ebc6a1dc&status=active" \
| python3 -m json.tool
# Check inbox
curl -s "http://127.0.0.1:8000/messages/?to_agent=vergabe_teilnahme&unread_only=true" \
curl -s "http://127.0.0.1:8000/messages/?to_agent=vergabe-teilnahme&unread_only=true" \
| python3 -m json.tool
```
@@ -63,8 +63,8 @@ Omit `workstream_id` / `task_id` when not applicable.
```bash
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
-H "Content-Type: application/json" \
-d '{"status": "in_progress"}'
# values: todo | in_progress | done | blocked
-d '{"status": "progress"}'
# values: wait | todo | progress | done | cancel
```
### Flag a task for human review
@@ -81,9 +81,9 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
**Start:**
1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe)
2. Check inbox: `GET /messages/?to_agent=vergabe_teilnahme&unread_only=true`; mark read
2. Check inbox: `GET /messages/?to_agent=vergabe-teilnahme&unread_only=true`; mark read
3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks
4. Check blocked tasks: `GET /tasks/?needs_human=true`
4. Check human-needed tasks: `GET /tasks/?needs_human=true`
**During work:**
- Update task statuses in workplan files as tasks progress
@@ -95,7 +95,7 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
3. Note for the custodian operator: after workplan file changes, run from
`~/state-hub`:
```bash
make fix-consistency REPO=vergabe_teilnahme
make fix-consistency REPO=vergabe-teilnahme
```
This syncs task status from files into the hub DB.
@@ -151,6 +151,11 @@ 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 (ADR-001)
@@ -158,10 +163,10 @@ get wrong.
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/VERGABE_TEILNAHME-WP-NNNN-<slug>.md`
**File location:** `workplans/VERGABE-WP-NNNN-<slug>.md`
**Archived location:** finished workplans may move to
`workplans/archived/YYMMDD-VERGABE_TEILNAHME-WP-NNNN-<slug>.md`. The `YYMMDD` prefix is
`workplans/archived/YYMMDD-VERGABE-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
@@ -173,11 +178,11 @@ anything needing analysis, design, approval, dependencies, or multiple phases.
```yaml
---
id: VERGABE_TEILNAHME-WP-NNNN
id: VERGABE-WP-NNNN
type: workplan
title: "..."
domain: vergabe_teilnahme
repo: vergabe_teilnahme
domain: communication
repo: vergabe-teilnahme
status: proposed | ready | active | blocked | backlog | finished | archived
owner: codex
topic_slug: ...
@@ -197,8 +202,8 @@ derived health labels, not frontmatter statuses.
## Task Title
` ` `task
id: VERGABE_TEILNAHME-WP-NNNN-T01
status: todo | in_progress | done | blocked
id: VERGABE-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
` ` `
@@ -206,9 +211,9 @@ state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
Task description text.
```
Status progression: `todo` → `in_progress` → `done` (or `blocked`)
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=vergabe_teilnahme`
2. Notify the custodian operator to run `make fix-consistency REPO=vergabe-teilnahme`
(or send a message to the hub agent via `POST /messages/`)

1
workplans/WP-0001-projektgeruest.md
View File

@@ -4,6 +4,7 @@ title: Projektgerüst — Django-Setup, Tailwind, Dev-Stack
status: done
phase: 1-of-12
created: "2026-05-08"
domain: communication
---
# WP-0001 — Projektgerüst

1
workplans/WP-0002-fachmodelle.md
View File

@@ -5,6 +5,7 @@ status: done
phase: 2-of-12
created: "2026-05-08"
depends_on: WP-0001
domain: communication
---
# WP-0002 — Fachmodelle

1
workplans/WP-0003-basis-ui.md
View File

@@ -5,6 +5,7 @@ status: done
phase: 3-of-12
created: "2026-05-08"
depends_on: WP-0002
domain: communication
---
# WP-0003 — Basis-UI

1
workplans/WP-0004-dashboard-ausschreibungen.md
View File

@@ -5,6 +5,7 @@ status: done
phase: 4-of-12
created: "2026-05-08"
depends_on: WP-0003
domain: communication
---
# WP-0004 — Dashboard und Ausschreibungen-CRUD

1
workplans/WP-0005-lose-anforderungen.md
View File

@@ -5,6 +5,7 @@ status: done
phase: 5-of-12
created: "2026-05-08"
depends_on: WP-0004
domain: communication
---
# WP-0005 — Lose und Anforderungen

1
workplans/WP-0006-aufgaben-bieterfragen.md
View File

@@ -5,6 +5,7 @@ status: done
phase: 6-of-12
created: "2026-05-08"
depends_on: WP-0005
domain: communication
---
# WP-0006 — Aufgaben und Bieterfragen

1
workplans/WP-0007-dokumente.md
View File

@@ -5,6 +5,7 @@ status: done
phase: 7-of-12
created: "2026-05-08"
depends_on: WP-0006
domain: communication
---
# WP-0007 — Dokumentenmanagement

1
workplans/WP-0008-preise.md
View File

@@ -5,6 +5,7 @@ status: done
phase: 8-of-12
created: "2026-05-08"
depends_on: WP-0007
domain: communication
---
# WP-0008 — Preise und Marktpreisauswertung

1
workplans/WP-0009-abgabe-nachbetrachtung.md
View File

@@ -5,6 +5,7 @@ status: done
phase: 9-of-12
created: "2026-05-08"
depends_on: WP-0008
domain: communication
---
# WP-0009 — Abgabe (Phase 6/7) und Nachbetrachtung (Phase 8)

1
workplans/WP-0010-partner-bibliothek.md
View File

@@ -5,6 +5,7 @@ status: done
phase: 10-of-12
created: "2026-05-08"
depends_on: WP-0009
domain: communication
---
# WP-0010 — Subunternehmer, Partner und Bibliothek

1
workplans/WP-0011-marktbegleiter.md
View File

@@ -5,6 +5,7 @@ status: done
phase: 11-of-12
created: "2026-05-08"
depends_on: WP-0010
domain: communication
---
# WP-0011 — Marktbegleiter-Analyse

1
workplans/WP-0012-querschnitt.md
View File

@@ -5,6 +5,7 @@ status: done
phase: 12-of-12
created: "2026-05-08"
depends_on: WP-0011
domain: communication
---
# WP-0012 — Querschnitt

1
workplans/WP-0013-feedback-bugs.md
View File

@@ -5,6 +5,7 @@ status: done
phase: 13-of-13
created: "2026-05-14"
depends_on: WP-0012
domain: communication
---
# WP-0013 — Feedback-Bugs

1
workplans/WP-0014-aufgaben-lose-scores.md
View File

@@ -5,6 +5,7 @@ status: done
phase: 14-of-n
created: "2026-05-14"
depends_on: WP-0013
domain: communication
---
# WP-0014 — Aufgaben-Phasenzuordnung und Scores

1
workplans/WP-0015-aufgaben-verknuepfungen-frist-issuefacade.md
View File

@@ -5,6 +5,7 @@ status: done
phase: 15-of-n
created: "2026-05-14"
depends_on: WP-0014
domain: communication
---
# WP-0015 — Aufgaben: Verknüpfungen, implizite Fälligkeit, Issue-Facade

1
workplans/WP-0016-issue-facade-integration.md
View File

@@ -5,6 +5,7 @@ status: done
phase: 16-of-n
created: "2026-05-14"
depends_on: WP-0015
domain: communication
---
# WP-0016 — Issue-Facade Integration

1
workplans/WP-0017-whynot-design-tokens.md
View File

@@ -5,6 +5,7 @@ status: finished
phase: 17-of-n
created: "2026-05-23"
depends_on: WP-0016
domain: communication
---
# WP-0017 — whynot-design Adoption · Phase 1 (Tokens + CSS)