stormlight AGENTS.md

Working on Stormlight

Guidance for coding agents and contributors. Design rationale lives in README.md (the Design section) and docs/; this file covers how work gets done.

Philosophy

Stormlight is pre-release. There are no users to break yet, so build things the right way the first time:

• No half measures, no backwards-compatibility shims, no quick hacks layered on wrong designs. When a fix reveals a design flaw, fix the design, not the symptom.
• Breaking refactors are welcome.
• Verify real behavior empirically (run the thing, capture the bytes) rather than building on assumptions about how a provider or terminal behaves.

Tracking work

• Outstanding work is tracked as GitHub issues. File follow-ups with gh issue create, reference issues in commits, and close them (Fixes #N or gh issue close) when the work lands.
• Commit and push completed work as it lands; don't let it pile up.
• Commits carry no AI attribution — no Co-Authored-By trailers.

Work in a worktree

Every task starts in its own git worktree, cut from the freshly fetched origin/main — never in the primary checkout, and never from local main:

git fetch origin
git worktree add -b <branch> --no-track .claude/worktrees/<branch> origin/main

Fetch every time. Branching off local main inherits whatever that checkout last saw, which is stale the moment anyone else's PR merges; origin/main after a fetch is the real tip. --no-track is not optional — a branch created from a remote-tracking ref otherwise adopts origin/main as its upstream, and a later git push either refuses or aims at the wrong branch. With it, the branch starts upstreamless and git push -u origin <branch> does the right thing.

While the work is in flight, keep the branch stacked on current main. Fetch and rebase before you push:

git fetch origin && git rebase origin/main

That keeps the PR a linear diff against the tip rather than a merge knot, and surfaces conflicts while the change is still yours to reshape.