From b042b90d4da91cda11ab41da0f660271baeec3af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Jane=C5=BEi=C4=8D?= Date: Fri, 16 Oct 2026 14:20:28 +0000 Subject: [PATCH] feat(claude): track agents and the matej and notes skills --- .gitignore | 9 + claude/agents/explorer.md | 10 + claude/agents/junior.md | 10 + claude/agents/researcher.md | 8 + claude/agents/senior.md | 12 + claude/skills/matej/SKILL.md | 57 ++ claude/skills/notes/SKILL.md | 116 ++++ claude/skills/notes/notes.css | 961 ++++++++++++++++++++++++++++++++++ claude/skills/notes/notes.py | 788 ++++++++++++++++++++++++++++ 9 files changed, 1971 insertions(+) create mode 100644 claude/agents/explorer.md create mode 100644 claude/agents/junior.md create mode 100644 claude/agents/researcher.md create mode 100644 claude/agents/senior.md create mode 100644 claude/skills/matej/SKILL.md create mode 100644 claude/skills/notes/SKILL.md create mode 100644 claude/skills/notes/notes.css create mode 100755 claude/skills/notes/notes.py diff --git a/.gitignore b/.gitignore index 404e16a..94b8be9 100644 --- a/.gitignore +++ b/.gitignore @@ -124,3 +124,12 @@ claude/* !claude/settings.json !claude/statusline-command.sh !claude/rules +!claude/agents +!claude/skills +claude/skills/* +!claude/skills/matej +!claude/skills/notes +claude/skills/notes/* +!claude/skills/notes/SKILL.md +!claude/skills/notes/notes.css +!claude/skills/notes/notes.py diff --git a/claude/agents/explorer.md b/claude/agents/explorer.md new file mode 100644 index 0000000..02c96fb --- /dev/null +++ b/claude/agents/explorer.md @@ -0,0 +1,10 @@ +--- +name: explorer +description: Builds one option for an open design question in Matej's projects, as something he can inspect (runnable code on a prototype branch, a canvas frame), often alongside another explorer working the same brief independently. Use when the lead wants options to compare before deciding. +--- + +You answer an open question with an option Matej can look at and judge, not with a final implementation. Prototypes may cut corners where it doesn't change what he is judging; say which corners. If another explorer works the same brief, don't look at its work. + +Read `~/.config/claude/CLAUDE.md` and the project's AGENTS.md first. Work on the prototype branch your brief names; never merge, never push, never sign. Make the option inspectable the way the brief asks (a preview he can run on his host, screenshots, a frame), and leave what he needs to look at in place; stop your own servers and containers. + +Your reply is text: what the option is and why, how to look at it (exact commands and URLs), what you tried and dropped, its weak spots, what you created. diff --git a/claude/agents/junior.md b/claude/agents/junior.md new file mode 100644 index 0000000..627de72 --- /dev/null +++ b/claude/agents/junior.md @@ -0,0 +1,10 @@ +--- +name: junior +description: Implementer for one part of a larger unit of work, briefed by a senior agent - builds its part on its own branch and worktree, runs the checks for it, and reports back for review. Use when a senior splits work into parallel parts. +--- + +You build one part of a unit of work that a senior agent owns. Stay inside your brief: anything outside it goes in your report as a leftover, not into your branch. When the brief leaves a choice, take the simplest option and say so. + +Read `~/.config/claude/CLAUDE.md`, the project's AGENTS.md and the house-rule skills it points to before writing code. Work on the branch and worktree your brief names; commit a few logical commits, never sign, never merge, never push. + +Run the checks your brief lists before reporting, and stop your own servers and containers when you are done. Your reply is text: the branch and commits, what you built, the checks with their results, anything you could not do or verify, what you created. diff --git a/claude/agents/researcher.md b/claude/agents/researcher.md new file mode 100644 index 0000000..e1dcf2f --- /dev/null +++ b/claude/agents/researcher.md @@ -0,0 +1,8 @@ +--- +name: researcher +description: Answers a factual or technical question for Matej with sources and, where it can, a test in a throwaway sandbox - e.g. how a git or library feature behaves, which of several approaches holds up. Use when the lead needs a verified answer, not an implementation. +--- + +You find out, and you show how you know. Check claims against primary sources (official docs, man pages, source code) and cite them; mark anything you could not verify. Where a claim can be tested, test it in a throwaway setup under `$SANDBOX_VM_STATE//` and show the trimmed commands and output; never touch real keyrings, credentials or project repos. + +Read `~/.config/claude/CLAUDE.md` first for how Matej wants facts handled. Your reply is text: the answer first (a short recommendation), then the evidence per option, then what is unverified. Leave your sandbox folder for review and say where it is. diff --git a/claude/agents/senior.md b/claude/agents/senior.md new file mode 100644 index 0000000..d8d000c --- /dev/null +++ b/claude/agents/senior.md @@ -0,0 +1,12 @@ +--- +name: senior +description: Senior developer for one unit of work in Matej's projects - builds it on a branch (alone or with junior agents in parallel), reviews and condenses their work, runs every check, and hands back one branch that already works. Use when the lead session delegates implementation from a brief. +--- + +You are the senior developer for one unit of work. The lead session that briefed you talks to Matej; you don't, so when the brief leaves a choice, take the simplest option that works, keep going, and list it under "decided along the way". + +How Matej likes this run is in `~/.config/claude/skills/matej/SKILL.md` (roles, ownership, clean-up) and `~/.config/claude/CLAUDE.md` (git, comments, verification). Read both, then the project's AGENTS.md and any house-rule skills it points to, before writing code. + +You own the result: a branch that works, lint and format clean, every test suite green the way CI runs it, the change looked at in a browser when it has UI, reviewed for bugs. Split work across `junior` agents in parallel when the parts don't step on each other; review each part before you take it in. Never merge into the main branch, never push, never sign. Remove every branch, worktree, container and server you or your juniors created once it is merged into your branch or no longer needed, and nothing you didn't create. + +Your reply is text: the branch and its commits, what each delivers, the checks you ran with their results, what differs from the brief, what you decided along the way, what you created and removed, and what is left. Say plainly what you could not verify. diff --git a/claude/skills/matej/SKILL.md b/claude/skills/matej/SKILL.md new file mode 100644 index 0000000..3ac1883 --- /dev/null +++ b/claude/skills/matej/SKILL.md @@ -0,0 +1,57 @@ +--- +name: matej +description: How Matej likes larger work run - one lead session that talks to him and briefs agents, a senior agent that builds and hands back a checked branch, explorer agents for open questions, notes and a design canvas for review. Use when he asks for orchestrated work ("let the senior handle it", "spawn agents for this", parallel options to compare) or for work spanning several branches or sessions. +--- + +# Running work through agents + +Guidelines, not a procedure. Where a step is obvious, do it your way; what is written here is what isn't knowable from the repo. + +## Roles + +- **Lead**: the session Matej talks to. Discusses, locks decisions, keeps the notes, briefs agents, checks what they report and tells him plainly what is done, what is open and what it took on trust. It doesn't edit the project itself, so its context stays free for judgement. +- **Senior**: owns a unit of work from brief to a branch that works, and hands back that one branch, never merging it. + - When the work splits into parts that don't step on each other, it runs implementer agents in parallel, each on its own branch and worktree under the work id, briefed the way the lead briefs it. A few at a time; what everything else builds on (a shared shell, a schema) goes first, alone. Small or tightly coupled work it does itself. + - It reviews each part before taking it in (reads the diff, runs code-review and simplify, fixes what is real), condenses its history, and merges it into the work's integration branch, sorting out what parallel parts collide on (migrations, generated code). + - It runs every check the project has on the integration branch, not only on the parts, and looks at what changed in a browser when there is UI. + - It removes its implementers' branches, worktrees and containers once they are merged, and its own when it hands back; the lead checks. +- **Explorers**: answer an open question with something Matej can inspect, often two independently on the same brief so he can compare. Prototypes may cut corners; they never land as they are. + +## Protocol + +- Discuss, lock, relay. Only locked decisions go to builders, in the words that were agreed. When a relay replaces an earlier one, say what it replaces; when unsure what Matej meant, ask before relaying. +- Builders keep going while the next point is discussed; new locked items join the open branch. +- Builders decide what the brief doesn't settle the simple way and list it as "decided along the way". Only the lead asks Matej. + +## Spawning + +Use the agent types for the roles (`senior`, `junior`, `explorer`, `researcher` in `~/.config/claude/agents/`), not a general-purpose agent, so Matej sees who is doing what. An agent's label is set once, when it is spawned, so make it the top level: the unit of work it is for ("graph redesign", "how it works redraw", "signing agent commits"), never its first step. What it is doing right now is the activity Claude Code shows beside the label; that part takes care of itself. When a running agent is given a new item, the label stays as it was, so say the new item in the relay's first line. + +## A brief carries + +The goal and what done looks like; where the spec is (note ids, canvas frames, branches); the decisions that touch it; scope and what not to touch; pointers to the rules (AGENTS.md, CLAUDE.md, the house skills) rather than copies; the checks; the shape of the reply; what it may create and must clean up. Agents don't see the lead's memory: anything they need from it goes in the brief. + +## Before passing a report on + +Check the cheap facts yourself: branch heads, commit authors and subject lengths, nothing staged that shouldn't be, worktrees and containers gone. Re-run something long only when a claim looks off. Say what you checked. + +## Where things go + +- Plans, decisions, reports, leftovers: the project's `.notes/` (the notes skill). Agents can't write there; the lead files their reports. +- Visual design to discuss: the Design canvas (an Artifact), kept current; history frames get removed, not piled up. +- Prototypes and finished work: branches. The repo's `.git` is on Matej's host, so he can `git worktree add --detach` any branch there. +- Bulk files for Matej (screenshots, logs): the host handoff mount once it exists; never the project repo, never bulk in `.notes/`. + +## Ownership and clean-up + +- Everything a unit of work creates carries its work id: branches `/`, worktrees under `$SANDBOX_VM_STATE/wt//`, containers `-`. Agents remove what they created and nothing else. +- The lead keeps `made.md` in the work item: each branch, worktree, container and handoff folder, with its state (open, merged, prototype). +- Close-out removes the list: merged branches deleted, prototypes once their decision is recorded, worktrees, containers and handoff folders gone; then check nothing under the work id is left. + +## Interruptions + +Any agent can stop (usage limits, Matej stopping it), and a stopped agent can't be resumed. Keep state on disk: small commits on the branch, decisions and reports in the work item. Before re-briefing, look at the repo first and hand the new agent what is actually there. + +## Git + +Agents never sign; Matej re-signs on his host before pushing (CLAUDE.md, Git). diff --git a/claude/skills/notes/SKILL.md b/claude/skills/notes/SKILL.md new file mode 100644 index 0000000..b7b9a4b --- /dev/null +++ b/claude/skills/notes/SKILL.md @@ -0,0 +1,116 @@ +--- +name: notes +description: Manage the project's local .notes/ dir (design docs, work handoffs, parked questions). Use whenever writing a design doc, plan, proposal, research or review for local use; starting, handing off or closing out work that spans sessions (brief, plan, report); parking something for later, out of scope or a follow-up; picking up or settling a parked question; preparing a document for someone else; or when the user mentions .notes, handoffs, open questions or asks what is pending. +--- + +# Notes + +The policy is `~/.config/claude/rules/notes.md`: layout, numbering, status lines, close-out, what doesn't belong. This skill holds the procedures. Every step that changes `.notes/` ends with `commit`, which also regenerates `index.html`, `notes.css`, the markdown pages under `_pages/` and the portable copies under `_out/`. Change the look only in this skill's `notes.css`, never in a project. + +``` +N=~/.config/claude/skills/notes/notes.py +python3 $N init # create .notes/ if missing (idempotent) +python3 $N next d|w|q # next free id, counts deleted items too +python3 $N commit "" # regenerate the generated pages, commit all of .notes/ +python3 $N index # regenerate index.html, notes.css, _pages/ and _out/ only +python3 $N serve # every project's notes on http://127.0.0.1:8765/: hub filters projects, each project page searches its notes (the user runs this) +``` + +All commands take `--root `; the default is the git toplevel of the current dir. Never pick an id by hand or from `ls`; deleted ids live only in git history. + +## New doc + +1. `init`, then `next d` +2. write `docs/dNNN-slug.html` (or `docs/dNNN-slug/index.html` with its assets next to it, then every `../` below becomes `../../`) on this skeleton, using only the components documented at the top of `notes.css` (callout, tag, cards, grid-2, table, figure.diagram with its svg classes); no `" + for f in site.other.get("out", []): + target = out / f.relative_to(src) + target.parent.mkdir(parents=True, exist_ok=True) + if f.suffix != ".html": + target.write_bytes(f.read_bytes()) + continue + # the nav goes before the css comes in: its header comment shows a nav too + text = BACK_NAV.sub("", f.read_text(errors="replace"), count=1) + target.write_text(CSS_LINK.sub(lambda _: style, text, count=1)) + + +def write_index(notes: Path) -> None: + ensure_gitignore(notes) + (notes / "notes.css").write_text(CSS.read_text()) + site = Site(notes) + + clear(notes / PAGES) + write_portable(site) + for q in site.questions: + render_md(site, q, "question") + for w in site.work: + for f in sorted(w.rglob("*.md")): + render_md(site, f, "work") + for files in site.other.values(): + for f in files: + if f.suffix == ".md": + render_md(site, f, "other") + + e = html.escape + + def section(name: str, rows: list[str], empty: str, plain: bool = False) -> str: + head = f'

{name} {len(rows)}

' + if not rows: + return f'{head}

{empty}

' + cls = "rows plain" if plain else "rows" + return f'{head}
    {"".join(rows)}
' + + def row(item_id: str, href: str, title: str, meta: str = "", cls: str = "") -> str: + return ( + f'
  • {e(item_id)}' + f'{e(title)}' + f'{meta}
    • ' + ) + + docs = [ + row( + d["id"], + quote(d["page"]), + d["title"], + status_tag(d["status"]), + "superseded" if d["status"].startswith("superseded") else "", + ) + for d in site.docs + ] + work = [] + for w in site.work: + brief = w / "brief.md" + title = w.name[5:] + if brief.exists(): + title, _ = split_title(frontmatter(brief.read_text())[1], title) + work.append(row(w.name[:4], quote(site.urls[w.name[:4]]), title)) + questions = [] + for q in site.questions: + meta, body = frontmatter(q.read_text(errors="replace")) + title, _ = split_title(body, q.stem) + created = e(meta.get("created", "")) + questions.append(row(q.name[:4], quote(site.page_of(q)), title, created)) + + other = [] + for sub, files in site.other.items(): + for f in files: + target = site.page_of(f) if f.suffix == ".md" else f.relative_to(notes) + portable = "" + if sub == "out" and f.suffix == ".html": + rel = f.relative_to(notes / "other" / "out").as_posix() + portable = ( + f' to send' + ) + other.append( + f'
  • {e(f.name)}' + f' {sub}{portable}
    • ' + ) + + project = notes.parent.name + body = "\n".join( + [ + # under serve this is the hub, under a plain http.server it is this index + '', + '
    ', + f"

    {e(project)} notes

    ", + ( + f"

    {len(site.docs)} docs · {len(site.work)} in flight · " + f"{len(site.questions)} open questions · generated {date.today()}

    " + ), + "
    ", + '
    ', + section("Docs", docs, "no docs"), + section("Work in flight", work, "nothing in flight"), + section("Open questions", questions, "no open questions"), + section("Other", other, "nothing here", plain=True) if other else "", + "
    ", + ] + ) + (notes / "index.html").write_text( + page(site, "index.html", f"{project} notes", body) + ) + + +# serve: every project's notes on one port + + +SKIP_DIRS = {"node_modules", "target", "dist", "build", "vendor", "__pycache__"} + + +def find_notes(roots: list[Path], depth: int = 6) -> dict[str, Path]: + """url prefix (path relative to its root) -> .notes dir, for every project under roots""" + found: dict[str, Path] = {} + + def walk(d: Path, root: Path, left: int) -> None: + notes = d / ".notes" + if notes.is_dir() and (notes / "docs").is_dir(): + found[d.relative_to(root).as_posix() or d.name] = notes + # a repo's own subdirectories are its code, not more projects + if left == 0 or ((d / ".git").exists() and d != root): + return + try: + children = sorted(d.iterdir()) + except OSError: + return + for c in children: + skip = c.name.startswith(".") or c.name in SKIP_DIRS + if c.is_dir() and not c.is_symlink() and not skip: + walk(c, root, left - 1) + + for root in roots: + if root.is_dir(): + walk(root, root, depth) + return found + + +def hub_page(title: str, body: str) -> str: + return ( + '\n\n\n\n' + '\n' + f"{html.escape(title)}\n" + '\n\n' + f'\n
    \n{body}\n
    \n\n\n' + ) + + +def search_form(action: str, q: str = "") -> str: + return ( + f'" + ) + + +# filters the hub's project rows as you type, nothing leaves the page +FILTER_BOX = ( + '' +) +FILTER_SCRIPT = """""" + + +def hub(projects: dict[str, Path]) -> str: + e = html.escape + rows = [] + for prefix, notes in sorted(projects.items()): + questions = len(list((notes / "questions").glob("q[0-9]*.md"))) + work = len([p for p in (notes / "work").glob("w[0-9]*") if p.is_dir()]) + docs = len(list((notes / "docs").glob("d[0-9]*"))) + last = git(notes, "log", "-1", "--format=%cs", check=False).strip() + meta = f"{docs} docs · {work} in flight · {questions} open · {last or 'no commits'}" + rows.append( + f'
  • ' + f'{e(prefix)}' + f'{meta}
    • ' + ) + body = ( + '

    notes

    ' + f"

    {len(projects)} projects · generated {date.today()}

    " + + (FILTER_BOX if rows else "") + + '

    Projects

    ' + + ( + f'
      {"".join(rows)}
    ' + '' + if rows + else '

    no .notes/ found

    ' + ) + + "
    " + # after the rows, so the script finds them + + (FILTER_SCRIPT if rows else "") + ) + return hub_page("notes", body) + + +def page_text(page: str) -> str: + """the readable text of an html page, without its chrome, words kept apart""" + flags = re.DOTALL | re.IGNORECASE + page = re.sub(r"<(style|script|svg|nav|title)\b.*?", " ", page, flags=flags) + return html.unescape(re.sub(r"<[^>]+>", " ", page)) + + +def searchable(notes: Path) -> list[tuple[str, str, str, str]]: + """(id, title, url relative to .notes/, plain text) for every page worth searching""" + site = Site(notes) + out = [] + for d in site.docs: + text = (notes / d["page"]).read_text(errors="replace") + out.append((d["id"], d["title"], d["page"], page_text(text))) + mds = [*site.questions, *(f for w in site.work for f in sorted(w.rglob("*.md")))] + mds += [f for files in site.other.values() for f in files if f.suffix == ".md"] + for f in mds: + _, body = frontmatter(f.read_text(errors="replace")) + title, _ = split_title(body, f.stem) + item = next((p[:4] for p in f.parts if re.match(r"[dwq]\d{3}-", p)), "") + out.append((item, title, site.page_of(f), body)) + for files in site.other.values(): + for f in files: + if f.suffix == ".html": + text = page_text(f.read_text(errors="replace")) + out.append(("", f.name, f.relative_to(notes).as_posix(), text)) + return out + + +def search(prefix: str, notes: Path, q: str) -> str: + e = html.escape + terms = [t.lower() for t in q.split() if t] + hits = [] + for item, title, url, text in searchable(notes) if terms else []: + low_title, low = title.lower(), " ".join(text.split()).lower() + if not all(t in low_title or t in low for t in terms): + continue + flat = " ".join(text.split()) + # centre on the whole phrase if it occurs, else on the rarest word + at = low.find(" ".join(terms)) + if at < 0: + rarest = min((t for t in terms if t in low), key=low.count, default="") + at = max(low.find(rarest), 0) if rarest else 0 + start = max(0, at - 80) + snippet = e(("…" if start else "") + flat[start : at + 160] + "…") + for t in sorted(set(terms), key=len, reverse=True): + snippet = re.sub( + f"({re.escape(e(t))})", r"\1", snippet, flags=re.IGNORECASE + ) + score = sum(t in low_title for t in terms) * 100 + sum( + low.count(t) for t in terms + ) + hits.append((score, item, title, url, snippet)) + write_index(notes) + hits.sort(key=lambda h: -h[0]) + rows = "".join( + f'
  • {e(item)}' + f'{e(title)}' + f'{snippet}
    • ' + for _, item, title, url, snippet in hits + ) + found = ( + f'
      {rows}
    ' + if rows + else '

    nothing found

    ' + ) + body = ( + '' + f'

    {e(prefix)}: search

    ' + f"

    {len(hits)} results for “{e(q)}”

    " + + search_form("search", q) + + f'
    {found}
    ' + ) + return hub_page(f"{q} · {prefix} notes", body) + + +def serve(roots: list[Path], host: str, port: int) -> None: + import http.server + from urllib.parse import parse_qs, unquote, urlsplit + + class Handler(http.server.SimpleHTTPRequestHandler): + def guess_type(self, path: str) -> str: + if str(path).endswith(".md"): + return "text/plain; charset=utf-8" + return super().guess_type(path) + + def send_text(self, body: str, ctype: str) -> None: + data = body.encode() + self.send_response(200) + self.send_header("Content-Type", ctype) + self.send_header("Content-Length", str(len(data))) + self.send_header("Cache-Control", "no-cache") + self.end_headers() + self.wfile.write(data) + + def do_GET(self) -> None: + path = unquote(urlsplit(self.path).path) + if path in ("/", "/index.html"): + return self.send_text( + hub(find_notes(roots)), "text/html; charset=utf-8" + ) + if path == "/notes.css": + return self.send_text(CSS.read_text(), "text/css; charset=utf-8") + projects = find_notes(roots) + prefix = max( + (p for p in projects if path == f"/{p}" or path.startswith(f"/{p}/")), + key=len, + default=None, + ) + if prefix is None: + return self.send_error(404, "no such project") + if path == f"/{prefix}": + self.send_response(301) + self.send_header("Location", f"/{quote(prefix)}/") + self.end_headers() + return None + rest = path[len(prefix) + 2 :] + notes = projects[prefix] + if rest == "search": + q = parse_qs(urlsplit(self.path).query).get("q", [""])[0] + body = search(prefix, notes, q) + return self.send_text(body, "text/html; charset=utf-8") + if rest in ("", "index.html"): + # rebuilt on every visit, so a session that forgot to regenerate never shows stale; + # the search box only works under serve, so it is added here, not in the file + write_index(notes) + page = (notes / "index.html").read_text() + page = page.replace("", "" + search_form("search"), 1) + return self.send_text(page, "text/html; charset=utf-8") + self.serve_from = projects[prefix] + self.path = "/" + rest + return super().do_GET() + + def translate_path(self, path: str) -> str: + base = self.serve_from.resolve() + target = (base / unquote(urlsplit(path).path).lstrip("/")).resolve() + return str(target if target.is_relative_to(base) else base / "__outside__") + + def log_message(self, format: str, *args) -> None: + pass + + server = http.server.ThreadingHTTPServer((host, port), Handler) + print(f"serving notes from {', '.join(map(str, roots))} on http://{host}:{port}/") + try: + server.serve_forever() + except KeyboardInterrupt: + pass + + +def default_roots() -> list[Path]: + import os + + env = os.environ.get("NOTES_ROOTS") + if env: + return [Path(p).expanduser() for p in env.split(os.pathsep) if p] + return [Path.home() / "git"] + + +def main() -> None: + parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + parser.add_argument("--root") + sub = parser.add_subparsers(dest="cmd", required=True) + sub.add_parser("init") + p_next = sub.add_parser("next") + p_next.add_argument("letter", choices=sorted(BUCKETS)) + sub.add_parser("index") + p_commit = sub.add_parser("commit") + p_commit.add_argument("subject") + p_serve = sub.add_parser("serve") + p_serve.add_argument("--port", type=int, default=8765) + p_serve.add_argument("--host", default="127.0.0.1") + p_serve.add_argument("--roots", nargs="*", type=Path) + args = parser.parse_args() + + if args.cmd == "serve": + serve(args.roots or default_roots(), args.host, args.port) + return + + notes = project_root(args.root) / ".notes" + if args.cmd == "init": + init(notes) + return + if not notes.exists(): + sys.exit(f"{notes} does not exist, run init first") + if args.cmd == "next": + print(next_id(notes, args.letter)) + elif args.cmd == "index": + write_index(notes) + print(notes / "index.html") + elif args.cmd == "commit": + commit(notes, args.subject) + + +if __name__ == "__main__": + main()