Topia

Topia — internal skill toolkit for AI coding assistants.
71 skills · 315 synapses · 49 pulses · 10 extension packs · optional persistent memory via agora-code MCP

Claude Code (native) · Cursor · Antigravity · Codex · OpenCode · OpenClaw

---

What Topia is

AI coding agents are smart but undisciplined. They skip steps, forget context across sessions, and ship code that "looks done." Topia gives them workflow rails the model can't skip:

• Plan before code — idea elicits requirements, plan writes phase files, adversary red-teams the plan, all before a line of code.
• Tests before commits — test writes failing tests first (red), fix implements until green. TDD enforced, not suggested.
• Hooks block bad work — guardian (secrets, OWASP), readiness (logic, regressions), completion-gate (validates agent claims have evidence). Auto-fire on tool use.
• Memory survives sessions — journal persists ADRs to .topia/, optional agora-code MCP adds SQLite-backed semantic recall across sessions.

One source of truth (skills/) compiles to six IDE rule formats — switch IDEs without rewriting your workflow rules.

---

Install (Claude Code)

Full guide: docs/INSTALL.md. Teams: see Team policy below.

Step 1 — Install the plugin (in chat, no terminal)

/plugin marketplace add linenoize/topia
/plugin install topia@linenoize

Restart Claude Code if /topia:build does not appear.

Marketplace path	Works?
linenoize/topia (recommended)	✓
Git URL to the repo	✓
Direct URL to marketplace.json	✓ (v3.1.2+)
Local clone path	✓

Plugin id is lowercase topia. If install fails, run /plugin marketplace update linenoize first.

After Step 1 you have: all /topia:* skills, plugin hooks (session-start, secrets-scan, quarantine, …), and file-based .topia/ memory — but not machine-wide dispatch hooks, team org.md policy, or agora-code MCP until Step 2.

Step 2 — Finalize (in chat, recommended)

/topia finalize

Run this once per machine (and again when you want to change hooks or org policy). It enables:

What finalize adds	Why it matters
Dispatch hooks (readiness, guardian, completion-gate, dependency-doctor)	Auto-fire on edits and shell commands in every repo, even when the plugin is not loaded
Team org policy (interview → .topia/org/org.md)	guardian and readiness enforce your review, security, and deploy rules — not the template
agora-code MCP (optional)	Cross-session semantic memory
Project .gitignore (optional)	Keeps .topia/ session state out of git (except org/)

If you skip Step 2: skills still work when you invoke them; discipline gates only run when you remember to call them or when plugin hooks fire in that session. Cross-repo consistency and team policy injection are the main gaps.

Details: docs/INSTALL-CLAUDE-CODE.md · commands/finalize.md

Per project (each repo you work in)

Run in that project's Claude Code session:

Step	Command	What you get
1	/topia onboard	CLAUDE.md + .topia/ context so every session starts with codebase knowledge
2	/topia org-config	Team policy in .topia/org/org.md (also offered during finalize)
3	/topia doctor	Verify install and nexus health

Teams: commit .topia/org/ to git so every teammate and agent shares the same gates. See docs/ORG-CONFIG.md.

Team policy (org.md)

.topia/org/org.md is where your team defines roles, reviewers, security SLAs, deploy windows, and governance level. Topia compiles it into guardian and readiness hooks — so "we require two reviewers on security files" becomes an actual gate, not a wiki page.

• Set up in chat: /topia org-config (structured interview) or during /topia finalize
• Edit later: change org.md, then refresh hooks (/topia finalize or topia setup --global)

Other IDEs (Cursor, Codex, Windsurf, …)

The Claude plugin does not compile Cursor/Codex rules. One-time terminal compile from your project root:

node "<path-to-topia>/compiler/bin/topia.js" init --platform cursor

→ docs/INSTALL-NON-CLAUDE.md (secondary path; Claude install above is primary)

Contributors / terminal install