quipu - Agent Instructions

Project Overview

AI-native knowledge graph with strict ontology enforcement — Bobbin's knowledge module

Conventions

Query Quipu before repository-wide discovery

Use configured Quipu MCP tools first for semantic context, SPARQL, stored queries, and guarded writes. Use the native quipu CLI second when operating on a local database. Raw HTTP is the fallback, with request shapes and authentication in docs/book/src/reference/rest-api.md; do not invent an endpoint from an MCP tool name.

For scoped knowledge, preserve Quipu's dataset semantics: ROOT is the default; named graphs and datasets are selected explicitly with FROM / FROM NAMED or the query graph field. Do not replace an explicit application or tenant dataset with an accidental all-graph query.

• Always use just instead of raw commands. The justfile is configured with quiet output by default to save context — you only see errors and warnings.
• Prefer subcommands over separate recipes. Group related operations under a single recipe with a subcommand argument (e.g., just docs build, just docs lint) rather than creating separate top-level recipes (e.g., just docs-build, just docs-lint).
• Keep source files small. scripts/check-file-size.sh warns at 400 lines and fails at 500 (tests exempt). It is a ratchet: files already over the limit are grandfathered in .file-size-baseline at their current size and may shrink freely, but growing past that size fails. A new file over 500 fails outright. When a baselined file shrinks, run scripts/check-file-size.sh --update-baseline and commit — it never loosens an entry.

Build Commands

just --list          # Show available commands
just setup           # Install pre-commit hooks
just check           # Run all quality checks

For verbose output when debugging:

just check verbose=true

Documentation Commands

just docs build      # Build the book
just docs serve      # Serve locally with hot reload
just docs lint       # Lint markdown files
just docs check      # Full docs quality gate

Quality Requirements

Before Every Push

You MUST run and pass the full quality gate before pushing:

just check

This runs all pre-commit hooks including:

• Trailing whitespace and EOF checks
• YAML/JSON validation
• Merge conflict detection
• Markdown linting Do NOT push if any check fails. Fix the issues and re-run.

Test Requirements

• All existing tests must pass before pushing
• New functionality must include corresponding tests
• Tests are part of the just check quality gate

Documentation Requirements

• User-facing changes MUST include documentation updates
• Run just docs build to verify the book builds cleanly
• Run just docs check to verify linting passes
• Update README.md if the change affects quick-start or usage

Git Workflow — trunk-based, straight to main

Work on main and push to main. Do not create feature branches, and do not open pull requests, unless you are explicitly asked for one. Stated by Stiwi, 2026-08-18.

git pull --rebase origin main     # before starting, and again before pushing
# ... work, with `just check` green ...
git add -A && git commit && git push origin main

What this costs, stated plainly, because the cost is the reason the rules below exist. There is no review step between a commit and the history everyone else pulls, so the quality gates are the only gate. A red main is immediately everyone's problem and there is no pull request standing between you and it.

• Run the gates before every push, not once at session end. just check. The pre-push gate this file specifies is not advisory here; it is the entire safety net.
• Never force-push main. If a push is rejected the remote has work you do not have; git pull --rebase and resolve it. A force-push discards someone else's commits silently, which is exactly the failure that has no undo.
• Prefer small complete commits to one large end-of-session commit. Each one lands live, so each one has to stand on its own.
• Work that cannot pass the gates does not get pushed. There is no branch to park it on — finish it, or leave it uncommitted and say so at handoff.

On the managed "Agent Context Profiles" block below. It sets a Conservative default that forbids commits and pushes without explicit instruction, and its Session Completion steps say to report proposed commands and wait for approval. Where that block and this section disagree, this section governs — the standing instruction above IS the explicit authority that block asks for, given once so it does not have to be re-granted every session. Everything else in that block still holds: an active "do not commit" or "do not push" from the current user still wins, and a blocked push is still reported with its exact command and error rather than worked around.

Landing the Plane (Session Completion)

When ending a work session, complete ALL steps below. Work is NOT complete until git push succeeds.

1. Run quality gates — just check must pass
2. Build docs — just docs build must succeed (if docs changed)

3. Commit and push:

   git add <files>
   git commit -m "<type>: <description>"
   git push

4. Verify — All changes committed AND pushed

CRITICAL RULES:

• Work is NOT complete until git push succeeds
• NEVER stop before pushing — that leaves work stranded locally
• NEVER say "ready to push when you are" — YOU must push
• If push fails, resolve and retry until it succeeds

Beads: this repo is JSONL-only, no Dolt

Do not run bd init here, and do not create a Dolt database.

.beads/metadata.json declares a Dolt backend, but there is no Dolt database: not in a fresh clone, and — checked with git ls-remote origin — no refs/dolt/* on the remote either. There is no store to hydrate from and nothing to reconcile against. bd 1.2.2 refuses to operate without one ("no beads database found"), including with no-db: true set in .beads/config.yaml, so bd commands cannot read or write this tracker.

So .beads/issues.jsonl is this repo's tracker, not an export of one — which is what the history has been doing all along, in commits titled chore(beads): … (jsonl export). bd init would mint a second identity alongside the project_id already in .beads/metadata.json rather than adopting it.

Use the script:

scripts/beads-jsonl.py list [--status open]
scripts/beads-jsonl.py create "Title" [--description ...] [--priority 3]
scripts/beads-jsonl.py close <id> --reason "..."
scripts/beads-jsonl.py note  <id> --text   "..."

It refuses any write that loses information — a record disappearing, a closed issue reopening, notes or comments shrinking — because the file has no schema enforcement and one bad write is a silent data loss committed as a normal diff. note appends and never replaces. It writes in this file's own measured convention (json.dumps defaults), so a one-record edit is a one-line diff rather than a whole-file reformat; hand-editing with different settings reformats all 78 records and buries the real change.

On the managed block below. It describes a Dolt-backed architecture and calls hand-editing the JSONL an anti-pattern. That warning is correct when a Dolt store exists, because then the JSONL is derived and the next export reverts the edit. Here there is no store to derive from and nothing to revert it. Where that block and this section disagree, this section governs. The sibling repos scbrown/bobbin and scbrown/camayoc reached the same place and carry the same script.

Beads Issue Tracker

This project uses bd (beads) for issue tracking. Run bd prime to see full workflow context and commands.

Quick Reference

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work
bd close <id>         # Complete work

Rules

• Use bd for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
• Run bd prime for detailed command reference and session close protocol
• Use bd remember for persistent knowledge — do NOT use MEMORY.md files

Architecture in one line: issues live in a local Dolt DB; sync uses refs/dolt/data on your git remote; .beads/issues.jsonl is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md for details and anti-patterns.

Agent Context Profiles

The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.

• Conservative (default): Use bd for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands.
• Minimal: Keep tool instruction files as pointers to bd prime; use the same conservative git policy unless active instructions say otherwise.
• Team-maintainer: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins.

Session Completion

This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.

1. File issues for remaining work - Create beads for anything that needs follow-up
2. Run quality gates (if code changed) - Tests, linters, builds
3. Update issue status - Close finished work, update in-progress items

4. Handle git/sync by active profile:

   # Conservative/minimal/default: report status and proposed commands; wait for approval.
   git status
   
   # Team-maintainer opt-in only, unless current instructions forbid it:
   git pull --rebase
   bd dolt push
   git push
   git status

5. Hand off - Summarize changes, validation, issue status, and any blocked sync/commit/push step

Critical rules:

• Explicit user or orchestrator instructions override this Beads block.
• Do not commit or push without clear authority from the active profile or the current user request.
• If a required sync or push is blocked, stop and report the exact command and error.

Beads Issue Tracker (codex)

Use Beads (bd) for durable task tracking in repositories that include it. Use the beads skill at .agents/skills/beads/SKILL.md (project install) or ~/.agents/skills/beads/SKILL.md (global install) for Beads workflow guidance, then use the bd CLI for issue operations.

Quick Reference

bd ready                # Find available work
bd show <id>            # View issue details
bd update <id> --claim  # Claim work
bd close <id>           # Complete work
bd prime                # Refresh Beads context

Rules

• Use bd for all task tracking; do not create markdown TODO lists.
• Run bd prime when Beads context is missing or stale. Codex 0.129.0+ can load Beads context automatically through native hooks; use /hooks to inspect or toggle them.
• Keep persistent project memory in Beads via bd remember; do not create ad hoc memory files.

Architecture in one line: issues live in a local Dolt DB; sync uses refs/dolt/data on your git remote; .beads/issues.jsonl is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md for details and anti-patterns.