khosra/CLAUDE.md

khosra — agent constitution

khosra is a flat-file personal publishing engine in Go, built solo, one feature at a time. You implement; the human owns scope and taste. This file overrides your defaults.

A personal publishing substrate: a directory of Markdown becomes an owned, networked home for fiction, webcomics, art, and essays, in English and Bengali. Values: data sovereignty, minimalism as aesthetic, comprehensibility by one person.

---

1. Read order (do not skip, do not exceed)

1. This file.
2. docs/state.md — what exists right now, plus the earn-it counters.
3. docs/README.md — always. The map: how you find which doc owns your topic. Not "exceeding".
4. Every doc owning a topic your change asserts a rule about (ownership table in docs/README.md).
5. Only the source files you will edit, plus their direct callers.

No reading the repo "for context", no speculative greps. Where docs/state.md and the code disagree, the code wins — say so, fix the doc in Document.

The ceiling has a floor. "Read less" governs breadth, never the doc that owns what you are writing. Before stating a rule, contract, threshold, or gate, read its owning doc; if it already says it, amend there instead of restating elsewhere.

ideas/ and reference/ are out of context by default, indexes included. Open one only when the human names it. Never sweep, never list, never cite unasked. Storage, not background.

2. The primitives — everything reduces to one

Bundle · Stage · Query · View · Interaction · Effect (+ bundle-as-program). Definitions and STATUS: docs/architecture.md.

Name the primitive before writing code. If it reduces to none it is a trunk (wants a permanent service or a core-model change): stop, say so in a paragraph, propose the leaf, wait.

Name the layer too. Content on disk · engine (data only the engine can produce) · theme (markup) · browser (CSS, and only then JS). Build it at the outermost layer that can do the job: a line-breaking or spacing problem CSS solves is not an engine feature, and code that edits an author's text to fix how it looks is at the wrong layer by definition (ADR-0045 — a whole feature was deleted for this). Layers and the test: docs/architecture.md.

3. Hard rules

1. No abstraction before its second concrete use — pipeline, resolver, interface, generic, config knob, registry. The counters table in docs/state.md holds every threshold and is the only place they are written down: read them, increment them, never anticipate them.
2. No new dependency without an ADR and human approval. Allowlist: scripts/allowed-deps.txt. Stdlib first, always.
3. Surgical diffs. Only the lines the feature needs. No renames, no reformatting beyond gofmt, no "while I was in there". Spotted something bad? Latent list in docs/state.md.
4. The untrusted boundary is absolute. Anything not from the site root (comments, webmentions, form input) never reaches shortcode or template evaluation. Crossing it needs a plan callout.
5. Permalinks are permanent. A published URL never changes meaning; renames add aliases and permanent redirects. The path shape is decided (ADR-0008) and written in docs/content-model.md — read it before emitting a URL, and never invent a second shape.
6. No speculative anything: no unused parameters, no interface{} for flexibility, no "we might want to" comments, no one-field options structs, no plugin registry before its counter is due, no cache until requests feel slow, no concurrency until profiled, no utils/helpers/common/manager/base packages, ever.
7. Delete before you add. If removing code buys the feature, do that.
8. Nothing ships without the doc that describes it, and nothing ships still describing what you replaced. Code carries its state.md update; harness changes (this file, scripts/, .claude/) carry their HARNESS.md update; both are gated. Changed a rule, value, name or path? Grep the repo for the old form and every doc that names the concept, and fix them in this change — verify.sh catches dangling paths and ADR numbers, never a superseded sentence. And never assert a mechanism that does not exist yet: if a doc says a gate rejects something, run it and watch it reject, or do not write the sentence. ./scripts/verify.sh --list names every gate there actually is. The harness evolves: when a rule here proves wrong, fix the rule and its description rather than working around it.
9. Surface conflicts; never resolve them silently. If a request contradicts a decision already recorded — an ADR, an architecture invariant, the permalink shape, the untrusted boundary, a budget, a frozen contract — say so before writing code: quote the line, name the file, and give the two paths (comply, or change the decision on purpose). A request that merely exceeds a convention is not a conflict; a request that reverses a deliberate choice always is. Kinds and procedure: the Clarify step in SKILL.md. Silently doing what was asked is the failure mode this rule exists to prevent — the human cannot audit a conflict they were never shown.

4. The loop (every request, no exceptions)

Clarify → Plan → Implement → Verify → Document → Report. Procedure: .claude/skills/khosra-feature-loop/SKILL.md. The two gates people skip:

Clarify. Only questions whose answer changes the code or the bytes on disk. Max three, batched, up front, each with a bold default so silence answers. Never about naming, formatting, or anything docs/conventions.md decides. None to ask? State assumptions in one line and move on.

Verify. ./scripts/verify.sh green, plus one piece of feature-specific evidence you actually ran (golden file, curl, test name, benchmark). Never report success from reading your own diff. "Should work" is not a result.

5. Definition of done

• Plan's success criteria demonstrated with real output.
• ./scripts/verify.sh green.
• Diff contains nothing outside the planned files.
• docs/state.md updated (inventory, counters, latent items, verified-at line).
• ADR in docs/decisions.md if a load-bearing choice was made.
• Report states LOC delta, what is now earned, what you deliberately did not do.

6. Stop conditions — halt and ask

• The change exceeds planned LOC by ~50%, or touches an unplanned file.
• You need a new dependency, a new package, or a change to a frozen contract.
• You are about to write a mock, a switch on a type, or a second copy of parsing logic.
• The feature only works if the untrusted boundary bends.
• Two reasonable designs exist and the choice is expensive to reverse — present both, briefly.

Stopping early costs one message. Guessing costs a refactor.

7. Style floor

Go stdlib idiom, net/http + html/template, no framework. %w wrapping at package boundaries only. log/slog. Table-driven tests, golden files in testdata/. Explicit wiring in one file, no init(). Size thresholds live in scripts/budgets.env only. Full rules: docs/conventions.md — read them, do not ask.