## Ground rules

- When asked to make a code change, suggest a commit message. You may actually perform the commit. Use the Conventional Commits prefixes (e.g., `feat:` `fix:` `chore:` `build:` etc.)
- In general, when asked to make a change, scope your work within your turn to fit cleanly within one commit that can be classified with a Conventional Commit. Tell the human clearly how you scoped your work. If you feel you cannot scope your work cleanly, end your turn and ask the human if you should move forward with the larger scope change.
- Use the file `./TODO.md` as an editable file-based todo list.
- If you encounter a noteworthy and/or unintuitive behavior, record your findings in `doc/wiki/footguns/`.
- If you will read/write memories, use Markdown files in `./doc/memory/` instead of your harness's native memory framework/location.
- The `./doc/canonical/` folder contains knowledge documents written by or otherwise vetted by a human. Treat these as "word of God" with respect to the project.
- Roadmap items go in `doc/roadmap/`.
  - Use `./doc/roadmap/plan_queue/` for keeping plans which were conceived as a batch, or in parallel, that must now be taken one at a time. The intended way to consume the plan queue is to dequeue plans one at a time and reconstitute them to fit the current state of the repository before being marked ready for execution.
  - Use `./doc/roadmap/deferred/` for keeping plans/tasks that are explicitly deferred for later execution. This dir should not grow too large.
- `./reference/` contains read-only symlinks to other projects. Never write to anything under ./reference/; treat it as reference material only.
- When writing any document, use ASD-STE100 as your base style.
    - You may occasionally break ASD-STE100 if you feel that critical nuance will be lost otherwise.
- Expect a general workflow to look like this: `study` -> `plan` -> `execute plan` -> `rendezvous` -> `sync docs`. In particular `sync docs` is important; remind the human that they may want to do this after they `rendezvous`.
- Do not take the initiative to send effectful commands over SSH. Wait for or request explicit instructions to do so.

## Common Tasks

### General

- "study": study the requested topic and write a reviewable Markdown document to @./doc/study/{current-unix-timestamp}_{topic}.md. Do not write to any file other than the study doc. Fetch the timestamp before writing. Get the unix timestamp reliably first by running `date +%s` with your shell tool. Commit it under a `docs:` conventional commit.
    - If a study says `NOTE: `, this came from a human annotation.
    - Studies may be marked as "noncurrent" by moving them under `@./doc/study/noncurrent/`. This is purely for file organization purposes and should not be taken as a demotion or a marker of unimportance.
    - Multi-file studies may be constituted under `@./doc/study/{current-unix-timestamp}_{topic}/`.
- "plan": you will be given a goal/objective -- write a plan in @./doc/plan/{current-unix-timestamp}_{topic}.md for implementation. structure it to be the actual editable task board for another agent session. Commit it under a `docs:` conventional commit.
- "execute plan": you will be given an existing plan doc; your job is to execute the plan. keep track of your progress by editing the plan doc as necessary.
    - in general, when executing a plan doc, make a new branch.
    - "rendezvous", in the context of executing a plan, means to finish the plan execution. The codebase should be in a workable state. Merge the plan changes back to main. Update the docs to reflect the new state of the codebase after plan execution.
    - Multi-file plans may be constituted under `@./doc/plan/{current-unix-timestamp}_{topic}/`.
- "sync docs": ensure that the living docs accurately reflect the state of the codebase. this is usually run after one or more feature branches has been implemented. Run `bin/check-doc-links` as part of this to catch dead internal doc references (moved-plan link rot).
- "collect-commit": understand uncommitted work and commit it all. you may use one or more commits as appropriate.
- "defer": record that a task/instruction must be completed at some point in the future. Optionally record a timestamp.