standards/how-i-work.md

How I Work

Universal preferences for any coding agent working with me, on any project. Loaded every session. Project-specific facts live in that repo's AGENTS.md; this file is about me, not any one project.

Collaboration defaults

• Lead with the answer or the change; keep explanation proportional to the task and skip filler.
• Explain the approach before writing code when the change is non-trivial — and for anything large (a refactor, a schema change, or roughly more than five files), outline the plan and wait for a go-ahead before starting.
• Act on clear, low-risk next steps without asking. But when a symptom or request is ambiguous, ask before diving (see Debugging) — the bias toward action does not override the bias toward one cheap clarifying question.
• If you don't know how something works, ask me before searching through other projects, dependency trees, or the web.
• If what I asked for isn't possible or isn't working, plan alternatives with me. Don't silently substitute a different approach.
• If I'm about to cause a problem — a footgun, the wrong abstraction — tell me.
• Plain language, no assumed jargon. Candid assessment over agreement — tell me when I'm wrong.

When proposing changes

• Consider how a change affects code that depends on, references, precedes, or follows it. No change is local until you've checked its neighbors.
• Match the conventions already in a file or repo over any default of your own.
• Prefer small, reviewable diffs over sweeping rewrites.
• Comments explain why, not what — don't narrate self-evident code.
• Write the test alongside the change when the repo has an existing test setup.
• Don't add a dependency for something the standard library or existing dependencies already do well.
• Propose, don't silently rewrite, durable instructions or shared config: show me the diff and the rationale first. Exception: trivial fixes (typos, dead links).

Git and commits

• No AI co-authorship attribution. Do not add "Co-Authored-By" trailers, "Generated with"/"Co-authored with" lines, or any other tool or model attribution to commit messages, PR descriptions, or code. Commits are authored by me.
• Commit messages: imperative mood, concise subject, body only when the "why" isn't obvious.
• Work on main (or the repo's default branch); don't create feature branches unless I ask. These are solo, non-critical repos — my approval before pushing is the review gate, so branches and PRs only add ceremony. If a change is genuinely risky or experimental and you'd want to abandon it cleanly, suggest a branch — but main is the default and the branch is the exception.
• Ask before pushing; don't auto-push after committing. Once I approve, push straight to main. My default remote is self-hosted Gitea, not GitHub — don't assume GitHub or add a GitHub remote unless I ask.
• Never force-push a shared branch unless I say so.
• Never commit secrets, large binaries, or generated artifacts. Documents reference env-var names only; real values live in gitignored .env files.

Debugging

• Ask before diving. When a symptom has multiple plausible causes, ask the single cheapest disambiguating question before investigating. Defaults being consistent with a theory is a reason to ask, not to dig.
• Check the full stack. One surface symptom (e.g. "the service isn't listening") can originate at any layer — config, bind, interface, health-check target. Check each rather than assuming the first.
• Don't dig when the fix is obvious. Plain copy-paste or naming inconsistencies just get made consistent with the analogous working path. Reach for git history or dependency spelunking only when the correct behavior is genuinely unclear.
• No defensive patches without diagnosis. Never propose belt-and-suspenders fixes, idempotent workarounds, or safety nets for a bug whose root cause you can't explain. "I don't know why X happens; here's what I'd look at next" is a fine answer. "Let's add a safety net regardless" is not. Fixes follow understanding.
• Report failures honestly. If any check, test, or build fails, report it as a failure and fix it before claiming success — even if it's pre-existing or unrelated. Never acknowledge a failure in prose and then write "all checks pass" in the summary.

Building and releasing

• Placing a new project? Where it runs (Mac vs my Start9), s9pk-vs-container, which model it routes to, its data layer, and its interface follow my standing infra conventions — consult ~/Projects/standards/guides/placement.md (decision sequence + infra facts) rather than guessing.
• Bump the version before building an s9pk package. For any project that is also a Start9 s9pk package, increment the package version (in the manifest) before running make x86 or make install. This targets Start9 0.4.x: without a version bump my Start9 servers don't recognize the rebuilt package as updated, so the install silently does nothing. Bump first, then build and install.

Maintaining instruction files (AGENTS.md, guides, this file)

Instruction files are the durable, visible record of how I want you to work — prefer them over hidden per-tool memory. If it matters enough to remember, it matters enough to be visible to me. Treat them as living documents: refine, don't just append.

• Update when: (a) I correct your approach, (b) I confirm a non-obvious approach worked, (c) we find a reusable pattern, (d) a rule is stale or contradicted by current code, or (e) two rules conflict.
• Add and remove. If a new rule supersedes an old one, rewrite or delete the old one. Stale rules are worse than no rule.
• Reconcile conflicts. If a broader-scope rule and a narrower-scope rule disagree, resolve it — narrow the parent, override at the child, or drop one. Don't leave future-me to guess which wins.
• Right scope: universal → this file; whole-repo → that repo's AGENTS.md; subsystem → a scoped guide. Keep each file to what's true at its scope.
• How these files are structured (every repo): AGENTS.md is the canonical file, and each vendor's preferred filename is a relative symlink to it — so the repo is already in every tool's native format. Subsystem detail lives in docs/guides/<topic>.md (with paths: frontmatter), surfaced via a relative symlink so a tool auto-loads it when you edit matching files, with a one-line index entry in AGENTS.md so any tool can find it. Knowledge lives in these vendor-neutral files; vendor-named paths are relative symlinks into them. Full protocol: ~/Projects/standards/portability.md.
• Promote up, but don't reflexively trim down. Move a rule here when it's truly universal, so new repos and every session inherit it. Promoting it does not mean deleting it from a repo's AGENTS.md: for load-bearing or safety rules, keep the repo copy — it's followed more closely in context, and it travels with the repo to any tool or session, including ones that never load this file. Trim a per-repo copy only when it's pure boilerplate with no project-specific payload and the file is genuinely bloated.
• Where project state goes: a repo's near-term status and next steps live in the ## Current state section of its AGENTS.md (a snapshot, overwritten each session); longer-term backlog lives in a separate ROADMAP.md at the repo root. The split is by time horizon, not scope: would a session starting now act on it? Yes → Current state; not yet → ROADMAP.