Architecture¶

Techne is a collection of independent, composable skills that share conventions but don't hard-depend on each other. This page maps the skill ecosystem, names the typical workflows, and states the design philosophy.

Skill categories¶

Build and toolchain. techne:audit validates that your local build is clean (lint, test, end-to-end) by walking your Makefile dependency graph and diffing terminal output against per-invocation log archives. techne:ci-audit does the same for GitHub Actions runs; flags warnings, deprecations, and noise; fixes what's fixable in-repo (workflow YAML, action pins, dependency versions).

Documentation and prose. techne:docs-site maintains the Zensical-built Pages workflow, link integrity, and asset hygiene. techne:docsync verifies prose claims (CLI commands, paths, signatures, config keys) against the actual codebase. techne:deslop flags AI-generated slop in comments and docstrings; techne:reslop rewrites docstrings grounded in the implementation rather than deleting them outright.

Planning and provenance. techne:research-grounded audits design decisions in IMPL.md / ROADMAP.md for missing # research(YYYY-MM): provenance, then web-searches to ground each choice against current best practice before it hardens into code.

Versioning and observability. techne:auto-commit groups working-tree changes into a structured commit plan at COMMITS.md for staged review before anything lands. techne:theoros starts an observed live dev session in a tmux pane; Claude drives the REPL, the human spectates read-only via tmux attach -r.

Review and collaboration. techne:board keeps one GitHub Projects board of every repo's work by stage (Idea, Issue, In PR, Merged, Live), and a hook files each issue or PR a gh command opens. techne:catchup reads every comment, review and state change on a repo since you last participated and reports who is blocked on whom; read-only. techne:elenchus is adversarial pre-merge review: an independent reviewer sized to the change's risk (plus /code-review for risky changes) reproduces the load-bearing claim, traces every consumer across the repo, and walks a bug-class rubric.

Setup. techne:setup, graphe:setup, heuresis:setup and phylax:setup each run a read-only doctor for their plugin and print the install command for anything missing; epistole:setup guides the Google sign-in and schole:setup the course-site sign-in.

Mail. epistole runs a local Gmail MCP server that searches, reads and drafts in each configured account and sends a draft only after you approve it; epistole:setup guides the one-time Google sign-in. See epistole.

Bibliographies. dokimasia:check lints any .bib or hand-written thebibliography, resolves its identifiers against arXiv and Crossref, and checks that every cited key rendered in the built document; a failed lookup is reported apart from a wrong entry.

Ideas. heuresis is a Python package with a command-line interface that the skills call. heuresis:idea dispatches four scout agents (papers, patents, products, your own work) and a judge agent, and the package pools their records, verifies every quote and enforces the verdict rules in code. Its search code is the shared _shared/scholarly.py, and every request goes through _shared/polite_http.py (per-host pacing across processes, Retry-After, an identifying User-Agent, robots.txt for page fetches); both are copied from techne and kept identical by make guards; heuresis:setup checks the tools and creates the ideas repository. See heuresis:idea.

Documents and research. graphe:latex builds a LaTeX document and gates it on its log, its PDF and the assignment it answers. graphe:pdf renders markdown to print-quality PDFs through Typst and verifies the words survived. graphe:slides starts a talk from an animated reveal.js web deck, gates it on titles, contrast, alt text, missing files and phone fit in a real browser, renders it, and publishes it on GitHub Pages; existing .pptx and PDF decks get the same text gates. graphe:paper scaffolds a paper directory in a papers-style monorepo, and graphe:paper-review runs a novelty and reviewer pass grounded in retrieved prior work.

Cross-repo consistency. techne:sisters audits drift across the repos listed in ~/.claude/techne.toml: CI action pins, toolchain pins, skill-context structural parity, GitHub merge settings, open PRs, branch hygiene. Its report is read-only and leaves fixes to follow-up work; its clean mode removes finished branches and worktrees after you approve the list.

Typical workflows¶

Pre-push validation. Group local changes with techne:auto-commit, validate the build with techne:audit, scan for prose slop with techne:deslop, push. When CI finishes, run techne:ci-audit against the run for warnings and deprecations.

Documentation accuracy. After a refactor, run techne:docsync to find stale claims. Review the drift report; rewrite affected docstrings with techne:reslop if rewrite is preferable to deletion. Run techne:docs-site to confirm link integrity hasn't regressed.

Multi-repo release. Run techne:sisters to surface CI/toolchain/branch drift across the linked repos. Fix the drift in each repo (action pins, Python versions, merge settings). Validate each with techne:audit. Coordinate merges in consistent order.

Returning to a shared repo. Run techne:catchup before touching a team repo. When it lists a PR that needs review, run techne:elenchus on it.

Observed session. For long-running tasks (multi-hour test suites, large refactors), spin up a tmux session with techne:theoros. Share the session name; collaborators attach read-only with tmux attach -r -t <session>. The transcript persists in tmux scrollback.

Design philosophy¶

Skills are independent; each invocable without the others; but share conventions: .claude/skill-context.md for per-repo config, ~/.claude/techne.toml for user-level config, the dev-runner log archive at logs/dev-*.log. Audits are read-only, and skills that edit show their plan, report or diff before changing anything, so every change to the repo has a human approval in front of it. See Conventions for the standard file locations and adoption path.

Stale-assumption audit¶

Each skill encodes assumptions about the ecosystem it audits: techne:audit assumes the dev-runner archive convention, techne:ci-audit assumes a particular GitHub Actions failure shape, techne:docs-site assumes the Zensical strict-build target, techne:auto-commit assumes Conventional Commits. Those assumptions decay as upstream tools, action SHAs, model families, and platform features ship.

The maintenance invariant: whenever a Claude Code release, MCP spec revision, GitHub Actions schema change, or frontier-model capability shift lands, audit which skill in this repo exists to compensate for a gap that may now be closed, and which skill's structural assumption has just gone stale. Skills are not write-once; they are kept in sync with the moving substrate they audit. Treat any skill last touched more than a quarter ago as suspect until re-verified against current platform docs.

This invariant runs philosophically; there is no automated check, it's a stance the maintainer holds when reading release notes. The sibling sister repos apply the same audit to their own code (see phalanx-fl, velocity-fl, kourai-khryseai ROADMAPs); techne's variant is meta, it audits the audit tools themselves.

How the skills are tested¶

Two layers, for two kinds of failure.

Scripts (make test-unit). Every script a skill ships has pytest coverage: the LaTeX log gates, the markdown-to-Typst renderer, the bibliography checker, the catch-up sweep, the slide-deck checker, auto-commit's staleness fingerprint, and the theoros session lifecycle, which drives real tmux sessions. These run in CI. A test that needs a tool fails when the tool is missing, so a skipped case is never silent: set TECHNE_NO_TMUX, TECHNE_NO_TEX, TECHNE_NO_TYPST or TECHNE_NO_BROWSER to 1 to opt out on purpose on a machine without tmux, TeX Live, Typst or Chromium. make test-sandboxed runs the same suite inside Anthropic's sandbox-runtime, pinned in scripts/srt, on Linux. It has no network, writes only to the repo and a private temp folder, cannot read credential folders, /tmp, the session D-Bus, WSL interop or /mnt, and gets a cleaned environment and its own uv cache and venv, so a test that reaches outside the repo fails instead of touching real repositories, credentials or tmux sessions. It still reads the rest of the home folder, and Unix sockets stay open because tmux and Chromium need them. make install-probe is the other check: it installs the marketplace from GitHub into Claude Code, Codex and Copilot CLI in a clean container.

Routing (make evals). A skill that never fires does nothing, and a skill that fires on someone else's request does harm. claude plugin eval sends natural-language prompts to fresh sessions and records which skill Claude chose. Each skill has a case that must fire it, and collision cases must not: merging a PDF is not graphe:pdf, an email catch-up is not techne:catchup, editing a slide's title is not graphe:slides. Every case also loads every sibling plugin's skills and stand-ins for the general PDF, PPTX and BibTeX-formatting skills; an email catch-up must reach epistole's catch-me-up, which every case loads as a sibling, so a description that overlaps any of them fails a case instead of shipping. Evals run on your own credential and are not part of CI.

Staying current¶

Claude Code, its plugin system and the Agent Skills spec change weekly, and a skill written against last month's docs can quietly fall behind. Every Monday the freshness workflow has Claude read the Claude Code changelog and releases, the plugin and skill docs, the Agent Skills spec and claude-code-action releases, compare each change with techne's files, and, when something affects techne, open one issue labelled freshness listing what to change, with a link and a file for each item. The job that reads the web has read-only permissions, fetches only from the source domains, and returns the issue as structured output; a second job with no model in it files the issue. The changes go through ordinary pull requests. The instructions are .github/freshness.md, and make freshness runs the same check on your own login and prints the issue instead of opening it. The workflow needs an ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN repository secret and skips with a notice without one.