sextant AGENTS.md

AGENTS.md — working on sextant

Operational notes for anyone (human or agent) editing this repository. What the tool is belongs in README.md; the iteration history and the reasoning behind decisions belong in docs/. This file is only what you need in order to change the code without breaking something invisible.

Build and verify

swift build && swift test          # 330 tests
make ci                            # build + test + self-lint — run this before committing
swift test --filter "<suite name>" # one suite

make lint runs sextant on its own sources with sextant-rules.json. The tool is dogfooded: if a change makes lint noisy on this repository, that is a finding about the change.

How a change lands

Every change goes through a branch and a pull request — maintainer changes included. main is protected: it takes no direct pushes, and a pull request merges only once CI is green on it.

git switch -c fix/what-it-fixes
# … work, `make ci` …
git push -u origin HEAD && gh pr create

The rule is written here because it was broken here. Five commits were pushed straight to main in one session, the last of them a change across twenty-one files, on the strength of a "commit straight to main" that had been said once about a one-line release chore. Nothing broke, and that is not the point: a green local make ci is a predictor, while CI on a pull request is a gate, and a twenty-one-file change with no reviewable unit is not reviewable in principle.

The protection is what makes this a rule rather than a resolution. It applies to administrators too — otherwise it would guard against everyone except the account that actually pushes here. An emergency turns it off in the repository settings, deliberately and visibly, which is the whole difference from bypassing it by habit.

Layout

• Sources/SextantCore — all logic, testable. Anything worth a test lives here.
• Sources/sextant — thin executable: argument dispatch, rendering, process exit. Keep it thin; the reason the codebase was refactored once already is that 1257 lines of main.swift were untestable.
• Tests/SextantCoreTests — behavioural tests, plus a fixture package under Tests/Fixtures/IndexFixture used to exercise a real IndexStoreDB.
• plugins/sextant — the Claude Code plugin: the MCP registration, a skill and a command. It ships no code of its own beyond two launcher scripts, registers no hooks (a hook that writes from the moment it is installed is the user's decision, not an install's), and it must not restate the MCP tool list — MCPTools.definitions() is that list, and the skill describes when to ask rather than what exists. .claude-plugin/marketplace.json at the root is what serves it.