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.

Read the compressed form first. docs/surface.md (generated, gated) says where every declaration lives; go doc ./internal/<pkg> gives a package's surface; a test states a contract in a fifth of the lines that implement it. Locate with grep -n, then read that range — a whole file is for the doc that owns a rule you are asserting, or code you are about to rewrite. Every discipline, and the floor none of them may cross: docs/context-economy.md. A saving that buys a guess is not a saving.

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 → Commit → Report. Procedure: .claude/skills/feature-loop/SKILL.md. The three 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 --quiet 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.

Commit. Work lands in git without being asked, every time, before you report. What one commit contains is docs/conventions.md "Git": the changes that would be reverted together, bundled together. Never git push, and never --no-verify without saying why in the body. Asymmetry is the whole reason — a commit is one git revert away from undone, while work that only ever existed in the working tree is not recoverable at all.

Announce it once per session, prominently, when it was not asked for. If the human has not already asked for automatic commits in this session, the first commit is preceded by a visible line of its own — not a clause inside the report — saying that this change is being committed, that later changes will be too, and that saying so turns it off. Silence is consent only after the notice exists; before it, an unannounced commit is a surprise in someone else's repository.

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.
• Committed — one revertible unit per commit, announced if this session did not ask for it.
• 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.