naudachu
1815d91cdf
A discussion leaves behind a directory of markdown somewhere outside this repo, and the only durable home for it is the Gitea wiki. Getting it there by hand means re-deriving the same three things every time: what each file should be called, where it goes, and whether the page already exists. Two skills wrap that, along the split the repo already uses. `skills/page` is domain, offline, stdlib-only, and knows nothing about Gitea. It imports a directory into a space under `tmp/wiki/`, titles every file, records the result in `.pages.json`, and writes the index. `skills/wiki` is the bridge — `wikimap.py` translates, and the transport is `_gitea.py`, the same one the issue side uses. There is no second transport, and `tea` has no wiki subcommand to offer one. The Gitea wiki is flat, and that fact shapes everything There are no directories. A title of `a/b` is stored as one file named `a%2Fb.md`, and Gitea escapes it by rules of its own: space becomes `-`, `/` becomes `%2F`, and a literal `-` forces a trailing `.-` marker so the two stay distinct. `Chain decisions — DC` under two levels of prefix comes back as `Simple-Chains%2FParked%2FChain-decisions-%E2%80%94-DC`. So `sub_url` is the identity, it is read back from whatever the API returned, and it is never constructed. One built by hand that is almost right does not fail — it creates a second page and abandons the first. And a real subdirectory committed into a wiki's git repository is a ghost: the file exists, the API and the web UI do not see it. `folder/page.md` in this repo's own wiki is one. Nothing here clones a wiki repo. A title is a decision, not a derivation Titles come from the first heading, because there is no mechanical route from `03-q-01-do-we-know-the-chain-participant-by-name.md` to `Q-01. Do We Know the Chain Participant by Name`. But they are derived exactly once. A re-import replaces bodies and keeps titles, so editing a heading cannot rename a published page — which would not rename it, it would publish a second one. `--retitle` opts in. It finds the prior entry by `source` rather than by path, because the path is derived from the title and a retitle moves it; looked up by path the page would read as new and the next push would duplicate it. The old file goes, `sub_url` comes along, and `pushed` is cleared — a rename can leave the body byte-identical, and push decides by body hash alone, so a stale hash would skip the rename forever. Ordering is a `NN-` file-name prefix and never reaches the title. `00-` means "this is the directory's own page", and that page is named for the directory, not for its own heading: a child's title has to extend its parent's exactly, and `ideas/00-intro.md` opens with "Ideas for chain business requirements". Path collisions are reported and never resolved. Picking a winner is how a discussion loses a document. The index is navigation, not decoration Nothing draws a tree from flat titles. `page_index.py` writes one as an ordinary page, nested by title depth rather than by manifest path order — those disagree, since on disk `Top/System.md` sorts before `Top/Ideas/Scale.md` while in the hierarchy System is a child and Scale a grandchild. A parent with no page of its own still gets a node, so its children are not hidden. Links use `sub_url` when there is one and Gitea's `[[Title|label]]` syntax when there is not, so the order is push, rebuild, push. The same stances as the issue store, for the same reasons Pull overwrites, push is additive and never deletes, change detection is one hash and there is no drift model. A page with no `sub_url` has never been published, and that is a durable state. Issues gain a `wiki:` field holding page titles — titles, not URLs, so the reference stays in the domain. It already round-trips as a foreign key; this documents it. Verified against a live Gitea 1.26.1: create, update with a message, unchanged-skip, prefix-filtered pull, byte-identical round trip, and the per-page revision history carrying the operator's own words. The probe pages were deleted afterwards. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
162 lines
8.2 KiB
Markdown
162 lines
8.2 KiB
Markdown
# AGENTS.md
|
|
|
|
## Project goals
|
|
|
|
1. **Unify and systematize issue workflow** for the development team with
|
|
minimal context usage. Issue operations are wrapped in scripts so agents
|
|
spend tokens on the task, not on re-deriving commands and formats.
|
|
2. **Keep the tracker out of the work.** An issue is a unit of work first and a
|
|
Gitea row second. The two are separate layers, and the first one does not
|
|
know the second exists.
|
|
3. **Route all Gitea interaction through the `tea` CLI via scripts** instead of
|
|
direct ad-hoc calls wherever possible. Scripts give deterministic,
|
|
reviewable behavior; the `tea-guard` hook enforces that every `tea`
|
|
invocation runs under the operator-pinned login.
|
|
|
|
## Layers
|
|
|
|
The hard rule of this repo. Two domains, two bridges, one transport, and
|
|
knowledge flows one way only:
|
|
|
|
```
|
|
skills/issue DOMAIN what an issue is: format, validation, dependency graph
|
|
skills/page DOMAIN what a page tree is: title <-> path, order, the index
|
|
▲ offline — no tracker, no network, stdlib imports only
|
|
│ imports
|
|
skills/sync BRIDGE map.py md <-> Gitea issue JSON, pure, no I/O
|
|
_gitea.py login pin, tea api, pagination, filters
|
|
skills/wiki BRIDGE wikimap.py md <-> Gitea wiki JSON, pure, no I/O
|
|
transport is _gitea.py — there is no second one
|
|
skills/use REFERENCE tea CLI docs for everything that is not an issue
|
|
skills/auth IDENTITY pin the login the whole tracker side runs under
|
|
▲
|
|
│ calls
|
|
agents/ EXECUTION tea-runner: runs the scripts, reports a receipt
|
|
```
|
|
|
|
A domain never imports its bridge, and the two domains do not import each
|
|
other: delete `skills/sync` and issues still work, delete `skills/wiki` and page
|
|
trees still work, delete either domain and the other is untouched. The check is
|
|
mechanical — every import under a domain's `scripts/` is stdlib, and
|
|
`subprocess` is not among them:
|
|
|
|
```bash
|
|
grep -rh '^import \|^from ' skills/issue/scripts/ | sort -u
|
|
grep -rh '^import \|^from ' skills/page/scripts/ | sort -u
|
|
```
|
|
|
|
If a tracker concept (issue number, login, HTTP call, label color, `sub_url`,
|
|
`content_base64`) shows up in a domain layer, it is in the wrong place.
|
|
|
|
## Repo layout
|
|
|
|
- `skills/auth` — pin the Gitea login used by `tea` (`/tea:auth`)
|
|
- `skills/issue` — issues as units of work (`/tea:issue`), entirely offline
|
|
- `references/format.md` — canonical issue format; single source of truth
|
|
- `scripts/issue.py` — domain module: slug identity, parse/render, validation,
|
|
taxonomy, dependency graph, body checkboxes
|
|
- `scripts/issue_new.py` — create a local issue from its type template
|
|
- `scripts/issue_check.py` — validate against the format
|
|
- `scripts/issue_ac.py` — list the body's checkboxes; tick one by number or
|
|
substring, changing exactly one character of the file
|
|
- `scripts/issue_tree.py` — draw the dependency graph
|
|
- `scripts/issue_index.py` — rebuild `tmp/issues/INDEX.md`
|
|
- `skills/sync` — move issues between the local store and Gitea (`/tea:sync`)
|
|
- `scripts/map.py` — md ↔ Gitea JSON, pure, no I/O; label colors live here
|
|
- `scripts/_gitea.py` — transport: login pin, `tea api`, pagination, filters,
|
|
label ids, the remote-id map
|
|
- `scripts/pull.py`, `push.py`, `remote.py`, `comment.py`
|
|
- `skills/page` — a discussion's artifacts as a page tree (`/tea:page`),
|
|
entirely offline
|
|
- `references/pages.md` — canonical page-tree format; single source of truth
|
|
- `scripts/page.py` — domain module: title ↔ path, ordering, the manifest,
|
|
importing a directory of markdown, the index
|
|
- `scripts/page_import.py` — copy a directory of markdown into a space,
|
|
titling every file
|
|
- `scripts/page_index.py` — write the table-of-contents page
|
|
- `scripts/page_ls.py` — the tree, the titles, one sync-state tag per page
|
|
- `skills/wiki` — move page trees between a local space and a Gitea wiki
|
|
(`/tea:wiki`)
|
|
- `scripts/wikimap.py` — md ↔ Gitea wiki JSON, pure, no I/O
|
|
- `scripts/wiki_ls.py`, `wiki_pull.py`, `wiki_push.py` — transport is
|
|
`skills/sync/scripts/_gitea.py`
|
|
- `skills/use` — `tea` CLI reference for everything that is not an issue
|
|
(`/tea:use`); `references/tea/` holds the command docs
|
|
- `agents/tea-runner.md` — subagent on Haiku that executes the scripts and
|
|
returns a compact receipt. Delegate batches (bulk pull, push a named set,
|
|
bootstrap labels, rebuild the index), never the thinking: it has no `Edit`
|
|
and no `Write`, may not `--force`, and may not decide what an issue says.
|
|
Delegating a single call costs more than running it inline — the win is the
|
|
loop, the retry, and the error triage.
|
|
- `hooks/` — PreToolUse hooks: `tea-guard` blocks or rewrites `tea` invocations
|
|
that don't use the pinned login; `agents-sync` keeps every directory canonical
|
|
(`AGENTS.md` real file, `CLAUDE.md` symlink to it)
|
|
- `tests/` — stdlib `unittest`, no third-party anything
|
|
|
|
## Tests
|
|
|
|
```bash
|
|
python3 -m unittest discover -s tests -v
|
|
```
|
|
|
|
Plain `unittest`; no pytest, no dependencies — the scripts under test are
|
|
stdlib-only and the tests hold the same line. `skills/*/scripts/` are not
|
|
packages, so a test that needs the domain module imports it with
|
|
`sys.path.insert`.
|
|
|
|
**A test never touches `tmp/issues/` or `tmp/wiki/`.** Anything that needs a
|
|
store builds a throwaway repository in a `tempfile.TemporaryDirectory()` — a
|
|
`.git` marker, a copy of the script layers, fixture issues or artifacts — and
|
|
runs the real scripts inside it as subprocesses. That is the only way to test
|
|
behavior that depends on where a script is run from, and it keeps the
|
|
developer's own store out of the blast radius.
|
|
|
|
## Local issue store
|
|
|
|
`tmp/issues/` (gitignored) is **the store, not a cache of Gitea**. One flat
|
|
markdown file per issue, named by its slug, with one metadata field per line so
|
|
plain grep works without a parser.
|
|
|
|
- **The path is `<repo root>/tmp/issues`, resolved from `issue.py`'s own
|
|
location, not from cwd.** `issue.store_root()` walks up from `__file__` to the
|
|
nearest `.git` or `AGENTS.md` — so every script in both layers sees one store
|
|
whatever directory it is run from. An explicit `--out` overrides it and is
|
|
used exactly as typed; a relative `--out` stays relative to cwd.
|
|
- Nothing creates the store as a side effect of a write. Readers distinguish
|
|
"does not exist" from "is empty"; only `issue_new.py` and `pull.py` create it,
|
|
and they say so on stderr.
|
|
- Identity is the slug (`wire-sqlc-appclick.md`), never a tracker number.
|
|
Numbers live in the `gitea:` field.
|
|
- `origin: local` is a durable state. An issue that never leaves this machine is
|
|
complete and valid, not a draft.
|
|
- Pushing is additive: the file is never deleted, it gains `gitea:` / `url:` /
|
|
`synced:`.
|
|
- Pulling overwrites the body — a fetch, not a merge.
|
|
- No drift tracking. `synced:` tells you how old your copy is; re-pull when it
|
|
matters.
|
|
|
|
## Local wiki cache
|
|
|
|
`tmp/wiki/<space>/` (gitignored) holds page trees — a discussion's artifacts,
|
|
organized. Same stance as the issue store, resolved the same way from
|
|
`page.py`'s own location, with the same `--out` rule.
|
|
|
|
- Identity is the **title**, and `/` inside it is the only hierarchy there is.
|
|
The Gitea wiki is flat: it escapes a title into one filename by rules of its
|
|
own (`space -> -`, `/ -> %2F`, a literal `-` forces a trailing `.-`).
|
|
- **`sub_url` is Gitea's address for a page and is never constructed.** It is
|
|
read back from the API and stored in `.pages.json`. One built by hand that is
|
|
almost right creates a second page instead of editing the first.
|
|
- **Never commit a subdirectory into a wiki's git repository.** Gitea does not
|
|
see it — the page exists on disk and nowhere in the API or the UI. Do not
|
|
clone the wiki repo to work in; use the scripts.
|
|
- A title is a decision, not a derivation. A re-import replaces bodies and
|
|
keeps titles, so editing a heading cannot silently rename a published page.
|
|
`--retitle` opts in, and the rename reaches the wiki on the next push.
|
|
- A page with no `sub_url` has never been published — a durable state, exactly
|
|
as `origin: local` is for an issue.
|
|
- Change detection is one hash (`pushed`). Pulling overwrites; pushing is
|
|
additive and never deletes.
|
|
- The `tea` CLI has no wiki subcommand. `tea api` is the only route, through
|
|
`_gitea.py`.
|