The plugin is issues and nothing else now. `skills/page` (the page-tree
domain) and `skills/wiki` (its bridge to a Gitea wiki) are gone, and
with them the issue domain's `wiki:` field — page titles were the only
thing that tied the two domains together, and a field the tracker has
no column for never came back from a pull anyway.
What is left is the shape AGENTS.md already claimed for the rest of the
repo: one domain, one bridge, one transport. The docs, the plugin
manifest, and tea-runner's skill table now say so too, and
test_payload_root walks the one script directory that remains.
Also removes openspec/config.yaml; nothing in the repo referenced it.
378 tests pass.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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>
The skills carry meaning, the scripts carry work. Splitting the second
half onto a cheap model keeps the main session's context for the part
that needs judgement.
tea-runner is a Haiku subagent with Bash/Read/Grep/Glob/Skill and
nothing else. It loads /tea:sync or /tea:issue for the command table
rather than carrying its own copy, so the skills stay the single source
of truth for the script surface.
It executes and reports; it decides nothing. No Edit and no Write, so an
issue body is out of reach. No raw tea, no --force, no closing or
retitling, no pushing past the set it was handed, one retry maximum. A
failed validation, a missing type, an unpushed dependency come back as a
question in a `blocked:` line. The reply is a fixed receipt — commands
with ok/FAIL, touched paths, stderr verbatim — never a payload dump.
Knowledge still flows one way: nothing under skills/ knows the agent
exists, and deleting agents/ changes nothing.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
An issue was a Gitea row that happened to be cached locally: its identity
was the tracker's number (42.md), its dependencies were tracker numbers
(depends: [#12]), and a local issue existed only as a draft that push
deleted on success. Nothing could be planned or tracked without a tracker.
Split into layers, with knowledge flowing one way:
skills/issue DOMAIN what an issue is: format, validation, dep graph
^ offline; stdlib imports only, no subprocess
| imports
skills/sync BRIDGE map.py md <-> Gitea JSON, pure, no I/O
_gitea.py login pin, api, pagination, filters
skills/use REFERENCE tea CLI docs for non-issue entities
skills/issue never imports skills/sync. Delete the sync layer and the
domain keeps working.
Identity is now a slug derived from the title (wire-sqlc-appclick.md) and
is stable across retitles and pushes. Tracker numbers live in a `gitea:`
field, never in a file name and never in `depends:`; the pair is indexed
in .remote.json, which is a cache over the files, not a second source of
truth.
Behavior changes:
- Pushing is additive. The file is never deleted; it gains gitea:/url:/
synced: and origin: flips from local to gitea. `origin: local` is a
durable state, not a pending one.
- Pushes go in topological order so dependencies get numbers first.
- The dependency graph is computed offline from `depends:` metadata; body
prose is passed through unchanged in both directions rather than being
rewritten between slugs and #N.
- `origin` is domain-owned (whether work exists elsewhere is a fact about
the work); the handle and how to reach it stay with sync.
Script moves:
issue_get.py -> sync/pull.py
issue_push.py -> sync/push.py
issue_list.py -> sync/remote.py
issue_index.py -> issue/issue_index.py
_tea.py -> split into issue/issue.py, sync/map.py, sync/_gitea.py
New: issue/issue_new.py, issue/issue_check.py, issue/issue_tree.py, and
sync/comment.py — comment posting was the last issue operation still
hand-rolled through raw `tea api`.
references/issue-format.md moves to skills/issue/references/format.md;
label hex colors move out of it into map.py, since a color is how a
tracker paints a chip, not what an issue is.
Verified: offline path end to end (new, check, tree, index, push
--dry-run) and read-only against Gitea (remote listing, pull with
mapping, comment guard). Write paths of push.py and comment.py are not
exercised here.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Replace fetch_issue.py with four scripts around a flat, greppable cache in
tmp/issues/. Planning stays offline and issues reach Gitea in one push:
- issue_get.py: fetch by key or by filter (--milestone/--label/-q). The list
endpoint carries issue bodies, so a whole milestone costs one request per 50
issues. Gitea silently ignores an unresolvable milestones= filter and returns
the entire backlog, so the milestone is resolved up front and every returned
issue is re-checked locally. --deps walks the dependency graph downwards via
the structured sections plus native dependencies and writes tree-<slug>.md.
- issue_push.py: validate a local draft against the canonical format, create
missing labels with the right colors and exclusivity, POST, delete the draft.
- issue_list.py: discovery to stdout, writes nothing.
- issue_index.py: rebuild INDEX.md from what is on disk.
Files use one metadata field per line with inline lists so plain grep works
without a parser. This is a cache and a drafting area, not a mirror: no drift
tracking, no sync back.
Projects are not fetchable — the projects API is 404 on Gitea 1.26; documented
alongside the milestone caveat.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`/tea:login` could not be invoked as `/login` because Claude Code
reserves that name as a built-in command. Renaming the skill to `auth`
frees the short form: `/tea:auth` and `/auth` both resolve.
Updates all references in the guard hook, README, plugin manifests, and
the use skill.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Convert the standalone `tea` skill into a skills-dir plugin so commands are
namespaced and an enforcement hook can ship with it:
- /tea:login — pin the project Gitea login into .claude/settings.local.json
- /tea:use — tea CLI reference (was the old root SKILL.md), with the
login rule slimmed since the hook now enforces it
- hooks/tea-guard.sh — PreToolUse(Bash) guard: blocks any `tea` command that
touches Gitea unless it carries --login and $GITEA_LOGIN is set. Exempts
`tea logins list` and `tea --version/--help` so /tea:login can bootstrap.
References moved under skills/use/references/. `claude plugin validate` passes;
guard unit-tested across allow/block cases.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
naudachu
naudachu