hubkasten — AI-friendly zettelkasten on GitHub Issues

[srid]

hubkasten — design doc for /hk

AI-friendly zettelkasten built on GitHub Issues. One repo = one kasten. Each issue = one node. #N references are links, and GitHub's CrossReferencedEvent gives backlinks for free.

Shipped as the /hk skill (#585). Lives at agents/.apm/skills/hk/SKILL.md; will eventually move to a standalone APM package.

Core model

• Every issue is a node. Content is markdown. The markdown is the schema — roadmaps, TILs, ADRs, bugs, questions all look different and that's fine.
• #N is the only link primitive. Mention it in any body and GitHub logs a CrossReferencedEvent on the target's timeline. No labels, no types, no taxonomy.
• Free bidirectional linking. Forward: grep the body for #\d+. Backward: query timeline via GraphQL or search/issues.

How /hk works

/hk #N <free-form prompt> — the LLM reads the node's current structure and infers the edit. No subcommands, no flags. See agents/.apm/skills/hk/SKILL.md for the full skill and heuristics.

Two rules that are non-negotiable:

1. Always fetch fresh before mutating. Concurrent edits are real (see Canvas mode: freeform 2D terminal workspace #559's history).
2. Just mutate — no confirmation. The fresh read + push-immediately flow removes stale-state risk.

Roadmap

• Initial skill implementation — feat(ai): add /hk skill — zettelkasten on GitHub Issues #585
• Extract to a standalone APM package so non-kolu repos can depend on it
• Session-level repo memoization (currently re-infers repo each invocation)
• /hk dogfood loop: use only /hk to maintain Canvas mode: freeform 2D terminal workspace #559 for a week, note friction
• Backlink-cluster summarization: /hk #N summarize everything that links here
• Sub-issues / blocking surfaces (GitHub's native sub-issue relation)
• Dry-run preview for large edits (opt-in, off by default)

Why GitHub Issues (vs wiki, Notion, etc.)

Feature	Issues	Wiki
Backlinks	Automatic via CrossReferencedEvent	None
Search	search/issues API	No API
Relationships	Sub-issues, blocking/blockedBy	None
Programmatic access	gh issue + gh api	Must clone .wiki.git repo
Version history	userContentEdits GraphQL	Git history per file

Name

hubkasten (hub + German kasten, "box") is the project name. /hk is the invocation — every keystroke is a tax on frictionless capture. Other candidates (zetthub, issueloom, hubknot, hubrain, …) kept in commit history.

Dogfood

This issue is itself a hubkasten node. Every /hk #568 … invocation mutates it in place; the timeline above shows the full history, and this PR (#585) appears as a backlink automatically.

[srid]

Temporary issue ^ until I put this on an external repo.