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

Refresh agent instruction files

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-18 16:55:54 +02:00
parent a32ebb9e12
commit 341c718511
11 changed files with 519 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
.claude/rules/agents.md Normal file
View File

@@ -0,0 +1,20 @@
## Kaizen Agents
Specialized agent personas available on demand via the state-hub MCP.
**Discover:** `list_kaizen_agents()` — returns all agents with name, description, category
**Load:** `get_kaizen_agent("tdd-workflow")` — returns full instructions; read and follow them
Common agents:
| Agent | Category | When to use |
|-------|----------|-------------|
| `tdd-workflow` | testing | Step-by-step TDD8 workflow for any feature |
| `code-refactoring` | quality | Code quality analysis and safe refactoring |
| `test-maintenance` | testing | Diagnose and fix failing tests |
| `requirements-engineering` | process | Prevent interface/mock mismatches upfront |
| `keepaTodofile` | process | Maintain TODO.md during work |
| `project-management` | process | Track status, determine next steps |
| `datamodel-optimization` | quality | Optimize dataclasses and data structures |
All 17 agents: call `list_kaizen_agents()` for the full list.

8
.claude/rules/architecture.md Normal file
View File

@@ -0,0 +1,8 @@
## Architecture
<!-- TODO: Describe the key design decisions and component structure.
Key modules, data flows, external integrations, state machines, etc. -->
## Quick Reference
`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference

38
.claude/rules/first-session.md Normal file
View File

@@ -0,0 +1,38 @@
## First Session Protocol
Triggered when `get_domain_summary("vergabe_teilnahme")` 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
- Scan repo root: README, directory structure, existing code or docs
**Step 2 — Survey in-progress work**
Look for TODOs, open branches, half-finished files. Note done vs. started but incomplete.
**Step 3 — Propose workstreams to Bernd**
Propose 1–3 workstreams — each a coherent strand, weeks to months, anchored to a
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
```
Then register in the hub:
```
create_workstream(topic_id="7d4d3e35-312f-4723-bde9-ddb43799109e", 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",
event_type="milestone",
topic_id="7d4d3e35-312f-4723-bde9-ddb43799109e",
detail={"workstreams": [...], "tasks_created": M}
)
```
<!-- Delete or archive this file once past first session -->

8
.claude/rules/repo-boundary.md Normal file
View File

@@ -0,0 +1,8 @@
## Repo boundary
This repo owns **vergabe-teilnahme** only. It does not own:
<!-- TODO: List what belongs in adjacent repos, e.g.:
- SSH key management → railiance-infra/
- State hub code → state-hub/
-->

5
.claude/rules/repo-identity.md Normal file
View File

@@ -0,0 +1,5 @@
**Purpose:** Django 6 + Tailwind + HTMX bid management app
**Domain:** vergabe_teilnahme
**Repo slug:** vergabe_teilnahme
**Topic ID:** 7d4d3e35-312f-4723-bde9-ddb43799109e

84
.claude/rules/session-protocol.md Normal file
View File

@@ -0,0 +1,84 @@
## Session Protocol
State Hub: http://127.0.0.1:8000
**Step 1 — Orient**
Read the offline-safe brief first — it works without a live hub connection:
```bash
cat .custodian-brief.md
```
Then call the MCP tool for richer cross-domain context when MCP tools are exposed:
```
get_domain_summary("vergabe_teilnahme")
```
If MCP tools are unavailable in the current agent session, use the REST API:
```bash
curl -s "http://127.0.0.1:8000/state/summary" | python3 -m json.tool
```
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)
```
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" \
| python3 -m json.tool
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
-H "Content-Type: application/json" -d '{}'
```
**Step 3 — Scan workplans**
```bash
ls workplans/
```
For each file with `status: ready`, `active`, or `blocked`, note pending
`todo`/`in_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
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
4. **Suggested next action** — highest-priority open item
5. **SBOM status** — flag if `last_sbom_at` is unset for this repo
If no workstreams: follow First Session Protocol (`first-session.md`).
**During work:** `record_decision()` · `add_progress_event()` · `resolve_decision()`
> State Hub is a *read model*. Bootstrap tools (`create_workstream`, `create_task`)
> are First Session Protocol only. Work structure belongs in repo files (ADR-001).
**Session close:**
With MCP tools:
```
add_progress_event(summary="...", topic_id="7d4d3e35-312f-4723-bde9-ddb43799109e", 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"}'
```
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
```
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
```
**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
until you pull — intentional to prevent clobbering remote progress.

19
.claude/rules/stack-and-commands.md Normal file
View File

@@ -0,0 +1,19 @@
## Stack
<!-- 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
# Run tests
# Lint / type check
# Build / package (if applicable)
```

28
.claude/rules/workplan-convention.md Normal file
View File

@@ -0,0 +1,28 @@
## Workplan Convention (ADR-001)
File location: `workplans/vergabe_teilnahme-WP-NNNN-<slug>.md`
ID prefix: `VERGABE_TEILNAHME-WP`
Work items originate as files in this repo **before** being registered in the hub.
Canonical workplan/workstream frontmatter statuses are:
`proposed`, `ready`, `active`, `blocked`, `backlog`, `finished`, `archived`.
Use `proposed` for a newly drafted plan, `ready` after review against current
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
unchanged; the prefix is only for quick visual reference.
Small opportunistic tasks discovered during another session use **Ad Hoc Tasks**:
`workplans/ADHOC-YYYY-MM-DD.md`, workstream slug `adhoc-YYYY-MM-DD`, and task ids
`ADHOC-YYYY-MM-DD-T01`, `T02`, etc. Use adhocs only for low-risk work completed
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 —
visible at session start. Pick one up by creating the workplan file, then registering
the workstream.
<!-- Ralph Loop rules and HEUREKA sequence: ~/.claude/CLAUDE.md — do not duplicate here -->

162
AGENTS.md Normal file
View File

@@ -0,0 +1,162 @@
# vergabe-teilnahme — Agent Instructions
## Repo Identity
**Purpose:** Django 6 + Tailwind + HTMX bid management app
**Domain:** vergabe_teilnahme
**Repo slug:** vergabe_teilnahme
**Topic ID:** `7d4d3e35-312f-4723-bde9-ddb43799109e`
**Workplan prefix:** `VERGABE_TEILNAHME-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
# 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=7d4d3e35-312f-4723-bde9-ddb43799109e&status=active" \
| python3 -m json.tool
# Check inbox
curl -s "http://127.0.0.1:8000/messages/?to_agent=vergabe_teilnahme&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 (required 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": "in_progress"}'
# values: todo | in_progress | done | blocked
```
### 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 (offline-safe)
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`
**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`:
```bash
make fix-consistency REPO=vergabe_teilnahme
```
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/VERGABE_TEILNAHME-WP-NNNN-<slug>.md`
**Archived location:** finished workplans may move to
`workplans/archived/YYMMDD-VERGABE_TEILNAHME-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: VERGABE_TEILNAHME-WP-NNNN
type: workplan
title: "..."
domain: vergabe_teilnahme
repo: vergabe_teilnahme
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: VERGABE_TEILNAHME-WP-NNNN-T01
status: todo | in_progress | done | blocked
priority: high | medium | low
state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
` ` `
Task description text.
```
Status progression: `todo` → `in_progress` → `done` (or `blocked`)
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`
(or send a message to the hub agent via `POST /messages/`)

85
CLAUDE.md
View File

@@ -1,76 +1,11 @@
# CLAUDE.md # vergabe-teilnahme — Claude Code Instructions
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. @SCOPE.md
@.claude/rules/repo-identity.md
## Project Overview @.claude/rules/session-protocol.md
@.claude/rules/first-session.md
**Vergabe Teilnahme** is a web-based tender/bid management system (internal collaboration tool) that supports a company through the full lifecycle of public and private procurement bids — from initial research through post-award retrospective. The language of the application and all domain documentation is **German**. @.claude/rules/workplan-convention.md
@.claude/rules/stack-and-commands.md
The authoritative requirements are in `wiki/ProductRequirementsDocument.md`. Technical architecture in `wiki/ArchitectureBlueprint.md`. Use cases in `wiki/UseCaseCatalog.md`. @.claude/rules/architecture.md
@.claude/rules/repo-boundary.md
## Tech Stack @.claude/rules/agents.md
**Django 6.x** · **uv** (package manager) · **Tailwind CSS v4** (via Vite) · **HTMX 2.x** · **Alpine.js 3.x** · **PostgreSQL 16+** (psycopg3)
## Entwicklungs-Commands
Run `make` without arguments for a full list with descriptions.
```bash
make db # PostgreSQL starten (Noop wenn :5432 bereits erreichbar)
make css # Tailwind CSS Watch-Modus — Terminal A, laufen lassen
make dev # Django-Dev-Server auf :9000 — Terminal B
make seed # Seed-Daten laden (idempotent)
make superuser # Superuser anlegen (einmalig für /admin/)
make migrate # Migrations generieren und ausführen
make test # pytest ausführen
make lint # ruff + mypy
uv run pytest vergabe_teilnahme/apps/<app>/tests/ # Einzelne Testdatei
```
## Projektstruktur
```
vergabe_teilnahme/
├── apps/ # Alle Django-Apps
│ ├── core/ # FlexibleModel, CustomAttribute, EntityFieldConfig, Freigabe
│ ├── accounts/ # Mitarbeiter (AbstractUser)
│ └── ... # je eine App pro Fachdomäne
├── settings/ # base.py, dev.py, prod.py
└── urls.py
static/
├── src/main.css # Tailwind-Quelldatei (mit @layer components und @theme brand tokens)
├── vendor/ # HTMX, Alpine.js (lokal, kein CDN)
└── dist/ # Build-Output (gitignored)
workplans/ # Ralph-Loop-Workplans (WP-0001 bis WP-0012)
wiki/ # PRD, Blueprint, Use-Case-Katalog
```
## Shared Infrastructure Note
Port 5432 is used by `infra-postgres-1` (the Custodian shared PostgreSQL container). The `vergabe_db` database and `vergabe` user are created there. `docker-compose.dev.yml` documents the intended standalone setup but is not started when infra container is active.
## Domain Model — Key Concepts
The system manages **Ausschreibungen** (tenders) through 8 phases:
| Phase | Name |
|-------|------|
| 1 | Recherche & Unterlagen bereitstellen |
| 2 | Teilnahmeentscheidung treffen |
| 3 | Detaillierte Durchsicht & offene Punkte |
| 4 | Bieterfragen, Subunternehmer, offene Punkte klären |
| 5 | Preismodell dokumentieren |
| 6 | Unterlagen finalisieren |
| 7 | Abgabe |
| 8 | Zuschlag / Nachbetrachtung |
Core entities: `Ausschreibung`, `Los` (lot), `Anforderung` (requirement), `Aufgabe` (task), `Bieterfrage` (bidder question), `Dokument`, `Subunternehmer`, `Preispunkt` (price point), `Marktbegleiter` (competitor), `Nachweis` (compliance certificate), `Referenz`, `Freigabe` (approval), `Nachbetrachtung` (retrospective).
**Vergleichsgewicht** (comparison weight): price points carry a weight in [0.0, 2.0] (default 1.0). Weighted averages use `Σ(value × weight) / Σ(weight)`; points with weight 0.0 are excluded from averages entirely.
## Custodian State Hub
This repo is tracked by the Custodian State Hub. At session start inside this repo, call `get_domain_summary("<domain_slug>")` via the `state-hub` MCP tool. End every non-trivial session with `add_progress_event()`.

137
SCOPE.md Normal file
View File

@@ -0,0 +1,137 @@
# SCOPE
> This file helps you quickly understand what this repository is about,
> when it is relevant, and when it is not.
> It is intentionally lightweight and may be incomplete.
---
## One-liner
<!-- Describe the purpose of this repository in one precise sentence. -->
<!-- Example: "Provides a lightweight event router for Kubernetes-native systems." -->
---
## Core Idea
<!-- What is the main capability or idea behind this repository? -->
<!-- What problem does it try to solve? -->
---
## In Scope
<!-- What this repository is responsible for. -->
<!-- Be explicit and concrete. -->
-
-
-
---
## Out of Scope
<!-- What this repository deliberately does NOT do. -->
<!-- This is often more important than "In Scope". -->
-
-
-
---
## Relevant When
<!-- When should someone consider using or exploring this repository? -->
-
-
-
---
## Not Relevant When
<!-- When should someone ignore this repository? -->
-
-
-
---
## Current State
<!-- Rough indication of maturity. No strict format required. -->
- Status: <!-- e.g. concept / experimental / active / stable / deprecated -->
- Implementation: <!-- e.g. idea / partial / substantial / complete -->
- Stability: <!-- e.g. unstable / evolving / stable -->
- Usage: <!-- e.g. none / personal / internal / production -->
<!-- Add any notes that help set expectations. -->
---
## How It Fits
<!-- Where does this repository sit in the bigger picture? -->
- Upstream dependencies:
- Downstream consumers:
- Often used with:
---
## Terminology
<!-- Terms that are important to understand this repo. -->
<!-- Especially useful if naming differs from other repos. -->
- Preferred terms:
- Also known as:
- Potentially confusing terms:
---
## Related / Overlapping Repositories
<!-- List repositories that have similar or adjacent responsibilities. -->
<!-- Helps detect duplication and navigate the ecosystem. -->
- <repo-name> — <!-- how it relates -->
---
## Getting Oriented
<!-- If someone decides to look deeper, where should they start? -->
- Start with:
- Key files / directories:
- Entry points:
---
## Provided Capabilities
<!-- What can this repo's domain provide to other domains on request? -->
<!-- Each capability block is parsed by the state-hub capability catalog ingest. -->
<!-- Remove the examples and add your own, or leave empty if none. -->
<!--
```capability
type: infrastructure
title: Example capability title
description: What this capability provides, in one or two sentences.
keywords: [keyword1, keyword2, keyword3]
```
-->
---
## Notes
<!-- Anything else worth knowing. Keep it short. -->