diff --git a/.gitignore b/.gitignore index 36b13f1..88a5c1b 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ +# Claude Code local state +.claude/ + # ---> Python # Byte-compiled / optimized / DLL files __pycache__/ diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..e122f74 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,209 @@ +# CLAUDE.md + +This file provides guidance to Claude Code when working in this repository. + +## What This Repo Is + +**marki-docx** (markidocx) is a Markdown ↔ DOCX round-trip editing system. + +- Markdown is the **canonical structured source** +- Word documents are **editorial projections** — generated for review, not authoritative +- Conversion must be deterministic, inspectable, and semantically stable across cycles +- Interfaces: CLI, REST service, MCP tools + +Key artefacts already in this repo: +- `specs/MarkiDocxProductRequirementsDocument_v0.1.md` — PRD (implementation-independent) +- `specs/MarkiDocxFunctionalRequirementsSpecification_v0.2.md` — FRS (binding functional contract) +- `specs/MarkiDocxUseCaseCatalog_v0.1.md` — use case catalogue + +--- + +## Custodian State Hub Integration + +This project is tracked as the **markitect** domain in the Custodian State Hub. + +| Key | Value | +|-----|-------| +| Domain | `markitect` | +| Topic ID | `5571d954-0d30-4950-980d-7bcaaad8e3e2` | +| Repo ID | `75d31180-acf5-4d47-aea8-2a5b1e71e6a9` | +| Repo slug | `marki-docx` | + +Hub API: `http://127.0.0.1:8000` — if offline: `cd ~/the-custodian/state-hub && make api` + +--- + +## Session Protocol (MANDATORY) + +### On session start — before writing any response text: + +**Step 1 — Orient via State Hub** +``` +get_domain_summary("markitect") +``` +Note: active workstreams, blocking decisions, recent progress, SBOM status. + +**Step 2 — Scan local workplans** + +```bash +ls workplans/ # or Glob(pattern="workplans/**/*.md") +``` +For each file with `status: active`, extract pending `todo` / `in_progress` tasks. + +**Step 3 — Present orientation** + +Output a concise brief: +1. **Active workstreams** for `markitect` domain — title, task counts, blocking decisions +2. **Pending tasks** — from local `workplans/` + state hub tasks with `[repo:marki-docx]` +3. **Goal guidance** — if `goal_guidance` is present in the summary: + - `needs_workplan`: surface as top suggested action — create workplan file + workstream + - `alignment_warnings`: name the misaligned workstream and flag it +4. **Suggested next action** — highest-priority open item +5. **SBOM status** — `last_sbom_at` set? If not, note it as a gap + +If no workstreams exist → follow **First Session Protocol** below. + +### During work: +- `record_decision()` — any decision affecting direction or dependencies +- `add_progress_event()` — milestones, blockers, insights +- `resolve_decision()` — once a decision is made + +### On session end: +```python +add_progress_event( + summary="", + event_type="note|milestone|blocker", + topic_id="5571d954-0d30-4950-980d-7bcaaad8e3e2", + workstream_id="" +) +``` + +> **Design boundary:** The State Hub is a *read model*. Two write operations are +> permanently sanctioned: **Resolving Decisions** and **Suggesting Next Steps**. +> Bootstrap tools (`create_workstream`, `create_task`) are First Session Protocol only. +> Work items originate as files in this repo (ADR-001), not in the hub alone. + +--- + +## Repo Boundary Rule + +This agent is responsible for files **in this repo only**. + +- Do **not** write files or commit in any other repository +- Work identified for another repo → create a state hub task with `[repo:]` in the title +- Work identified for an upstream package → create a contribution artefact in `contrib/` + +--- + +## First Session Protocol + +Triggered when `get_domain_summary("markitect")` shows **no workstreams** linked to `marki-docx`. + +**Step 1 — Read the specs** +- `specs/MarkiDocxProductRequirementsDocument_v0.1.md` +- `specs/MarkiDocxFunctionalRequirementsSpecification_v0.2.md` +- `specs/MarkiDocxUseCaseCatalog_v0.1.md` +- Scan the repo root for any existing code or further docs + +**Step 2 — Survey the canon** +- `~/the-custodian/canon/projects/markitect/project_charter_v0.1.md` +- `~/the-custodian/canon/projects/markitect/roadmap_v0.1.md` + +**Step 3 — Propose workstreams to Bernd** +Propose 1–3 workstreams — coherent strands of work lasting weeks to months, anchored +to a roadmap phase. **Wait for approval before creating anything.** + +**Step 4 — Create workplan file first, then DB record (ADR-001)** +``` +workplans/MRKD-WP-0001-.md ← write this first +``` +Then register: +```python +create_workstream( + topic_id="5571d954-0d30-4950-980d-7bcaaad8e3e2", + title="...", owner="marki-docx", description="..." +) +create_task(workstream_id="", title="...", priority="high|medium|low") +``` + +**Step 5 — Record the setup** +```python +add_progress_event( + summary="First session: structured marki-docx work into N workstreams, M tasks", + event_type="milestone", + topic_id="5571d954-0d30-4950-980d-7bcaaad8e3e2", + detail={"workstreams": [...], "tasks_created": M} +) +``` + +--- + +## Workplan Convention (ADR-001) + +Work items MUST originate as files in this repo before being registered in the hub. + +**File location:** `workplans/MRKD-WP-NNNN-.md` + +**Required frontmatter:** +```yaml +--- +id: MRKD-WP-NNNN +type: workplan +domain: markitect +repo: marki-docx +status: active|done|paused +state_hub_workstream_id: +created: YYYY-MM-DD +updated: YYYY-MM-DD +--- +``` + +**Task blocks (embedded in the workplan file):** +```markdown +## Task Title +​```task +id: MRKD-WP-NNNN-T01 +status: todo +priority: high +state_hub_task_id: +​``` +``` + +After writing or modifying workplan files, run: +```bash +cd ~/the-custodian/state-hub && make fix-consistency REPO=marki-docx +``` +This syncs task blocks → DB. Without it, the dashboard shows 0 progress. + +--- + +## Contribution Tracking + +Track upstream contributions in `contrib/`: +``` +contrib/ + bug-reports/ # br-YYYY-MM-DD--org--repo--slug.md + feature-requests/ # fr-YYYY-MM-DD--org--repo--slug.md + extension-points/ # EP-MRKD-NNN--org--repo--slug.md + upstream-prs/ # upr-YYYY-MM-DD--org--repo--slug.md +``` + +Templates: `~/the-custodian/canon/standards/contrib-templates/` + +--- + +## SBOM + +After updating dependencies: +```bash +cd ~/the-custodian/state-hub +make ingest-sbom REPO=marki-docx SCAN=1 REPO_PATH=/home/worsch/marki-docx +``` + +--- + +## Quick Reference + +- MCP tool reference: `~/the-custodian/state-hub/mcp_server/TOOLS.md` +- ADR-001 (workplan convention): `~/the-custodian/canon/architecture/adr-001-workplans-as-repo-artefacts.md` +- Contribution convention: `~/the-custodian/canon/standards/contribution-convention_v0.1.md`