wellwelwel/lagune / .claude/skills/architecture
architecture
VerifiedAuthoritative record of Lagune's architecture decisions, covering the three owners, what ships, the engine, the skills and plugins, project state, the catalog, the tracking map, and the website's languages. Use when a change depends on one or alters it.
Lagune architecture
This skill records Lagune's architecture decisions: each states a structural choice and why it holds. Consult it before changing source and whenever a decision depends on the shape of the codebase.
The three owners
| Owner | What it holds | Where it lives |
|---|---|---|
| The project | the charter, the phase artifacts, the tracking map, its categories and its own catalog | .lagune/, committed with the project |
| Lagune's instructions | the nine commands, each beside the template it fills | the skill folders the skills CLI, the GitHub CLI, or an agent's plugin installer copies from skills/ |
| Lagune's engine | the hooks, validation, the built-in specializations and their categories | the lagune package on npm and the plugin branches that carry its build |
Installing and updating the commands belongs to the skills CLI, the GitHub CLI, and each agent's own plugin installer. The engine never inspects how its skills were installed: it applies wherever its artifacts exist.
What ships
- The package carries no runtime dependency. Everything it runs is bundled at build time, so running the engine installs nothing on the user's machine, and
src/is never published. - A parser written in another language ships compiled to WebAssembly beside the bundle, never as a native binary. A format that is a whole programming language is read faithfully only by that language's own parser, and WebAssembly runs wherever Node.js runs with no install step and reaches only what the engine hands it, so a crafted file can only stop it, which fails closed.
- Whatever lands on the default branch reaches users. The skills CLI and the plugins that install from the default branch take the skills from it as it stands, while the GitHub CLI, the plugin branches, and the npm package take them at each release.
- One version across the package, every plugin manifest, and the npx fallback. The release moves them together, and no release goes out while a pinned call on the default branch disagrees with the package version.
The engine
- Skills and built-in specializations write every engine call as a call to the engine's own MCP tools, spelling every flag in full. An agent follows the form a call is written in, so a call written as a shell command draws the shell even when the tools are there. Where an agent can load the tools up front instead of deferring them, its plugin does that too.
- Each skill ends with the npx fallback, after the work. An agent without the tools runs each call through npx, pinned at the package version so each skill runs the engine it was written for and none fetches whatever is newest. What a person reads, from the docs to the engine's own messages, shows the same command unpinned.
- The tool names are a contract. The skills name
lagune_readandlagune_write, so every agent must reach the tools under names that end in them. A prefix the agent adds is fine, and any other renaming is not. - The MCP server splits reading from writing. One tool runs the commands that only read and the other the commands that write
.lagune/, so a user can allow reading alone. Each call runs the engine in its own process with no shell. - A tool command has only its tool's shape. On the command line, a command an engine tool runs answers only behind that tool's prefix,
readorwrite, and a tool call runs as that same command line. A model without the tools translates a tool call into the shell literally, so the tool's shape is the form that answers it. The tool definitions alone decide each command's prefix, so the CLI and the MCP server never disagree. An unprefixed command fails, naming its prefixed form, so the refusal teaches the one form instead of keeping a second. - The MCP server serves only a project. It never serves its own folder or the root of the file system, and where it cannot tell which project it was started for it serves nothing, so the skills fall back to npx instead of writing elsewhere.
- The checkers scan only inside the project. A target above the project root, or a link that leaves it, fails, since the MCP server runs outside the agent's sandbox.
- The engine never runs Git. It reads a repository's state itself, since a project's Git config can carry commands.
- The checkers leave out what Git ignores, and say how much. Build output and local artifacts would otherwise reach the agent in every session and draw it into fixing code that is not the project's. A repository that ships a crafted
.gitcan narrow that default, which is why the project's configs can switch it off. - The project's configs shape what each checker leaves out, and a malformed one stops the checker, since a fallback would hide code or bring the noise back unannounced. No skill adds a path the user did not choose, since a hostile repository can make its code look like fixtures.
- A checker's sections answer to the evidence. A finding fails the run only on proof that the risk is exposed, a risk the evidence cannot settle is a lead, a real risk not yet exposed is an advisory, and what only resembles a risk earns nothing. The exit code is what a pipeline or an agent acts on without reading further, so it moves only on what the evidence decides.
- A checker's proof binds the agent, and its silence does not. No reading clears what a checker proves, since the checker is deterministic and the agent's judgment is not. A checker reads only what its rules reach, so its specialization names what lies beyond them, and the agent's reading there can keep a risk open.
- The engine fails closed. An unknown subcommand or a malformed payload fails instead of reading as clean.
- Every hook answers before a fixed deadline, or reports that it did not. It runs in a worker the engine ends at that deadline, set under the minute that agents commonly allow a tool call, since a project can craft input that stalls a hook and an agent that cancels one does the check by hand.
- A manifest-based project answers to its manifest. That manifest alone decides:
migrateruns this design, everything else the manifest-based Lagune knows is handed to the frozenlagune@0.15.0, and what only this design has fails, pointing to the migration. The hand-off never runs a program the project could plant. - Migrate removes only what the manifest-based Lagune wrote, and keeps the skills-based
/lagunethat shares its name. src/types/is the single home of every type declaration.
The published skills
- A skill instructs and a template structures. Each command is a folder under
skills/holding its skill and, when it fills one, the template beside it. The skill carries the reasoning of the phase, and the template carries the shape of its result. - A folder holds only what an agent loads, since every installer copies the whole folder as it stands.
- Names join lowercase words with hyphens, such as
lagune-detect, the Agent Skills form every agent accepts, since an agent may reject any other form and unload the whole plugin with it. - One skill serves every agent. Its input section names every place an agent may deliver the input, since only some agents fill the placeholder.
- Prove and specialize run only when the user invokes them. Every agent that can keep a skill from the model keeps these two from it, even when that takes a file of the agent's own inside their folders.
- Nothing Lagune ships grants a permission. No skill carries
allowed-toolsand no plugin pre-approves the engine, so the first engine call stays the user's to allow.
The plugins
- A plugin is the thinnest adapter its agent accepts. Whatever form it takes, it reaches the skills in
skills/, never a copy of one, and carries no instruction of its own. - A manifest is distribution metadata only. Each names the plugin
lagune, and a marketplace listing beside one leaves the version to the manifest. - Each plugin installs from a branch of its own where its agent can, then from npm, then from the default branch. npm comes first where it is the agent's native plugin format. A plugin installed from the default branch keeps only the npx fallback, since that branch carries no build.
- A plugin branch carries the engine. Its bundle holds only what its agent loads, the build, and the built-in specializations, plus the server declaration its agent reads, which no other tree holds, since the default branch has no build to start. A listing that weighs every file it receives gets exactly that tree. Each release builds once, and the npm package and every branch take that same build.
- The default branch still ships as a plugin. Every tracked file at its root reaches the plugin folder of an agent that installs from it, so the root holds no symlink and nothing an agent would load beside the skills, and no folder holds an instruction file an agent could surface into the user's session.
CLAUDE.mdalone stays, for contributors. - Release archives leave out
CLAUDE.mdand the contributor folders. An agent that installs a release can readCLAUDE.mdas context when the user's settings name it, and since the website is among the folders left out, the art that plugin listings show lives inassets/. - An agent that loads code gets the smallest entry that hands it the skills. Where the agent's plugin API registers tools, the entry registers the two engine tools from the engine's own definitions instead of starting the server, and it runs the engine only on a Node.js the project could not plant. Where an agent accepts only another language, the entry uses that language's standard library alone, the one exception to TypeScript in, JavaScript out. No entry holds a copy of the tools.
- No session-start bootstrap. The user invokes the commands and
/laguneis matched by its description, so no plugin injects context into a session, and the server sends no instructions, which an agent would load into every session.
The project's state
.lagune/ holds the project's state and one engine folder that ignores itself, so Git never sees it. This design writes no manifest there and adds no block to the project's .gitignore. An engine write that reads the state before changing it holds a lock and lands atomically, since parallel phases can write at once. Of the project's state, the proofs alone stay out of version control, so an open issue never reaches a commit.
The catalog
- The engine composes the catalog on demand from the built-ins it ships, each indexed with its tags and categories, and the specializations the project keeps in its
.lagune/. - Reading one by name ignores the categories. It resolves the project's own first, then the built-in.
- A specialization is written for whoever audits it and read for whoever applies it. Its file credits its sources and carries the guidance for every phase, while a read leaves the credit out and carries guidance only for the phase reading it, since an agent weighs every line it reads and can act on neither. Only whoever rewrites the file reads it as written.
- A required built-in always applies, on every detect run, whatever the project's context.
The tracking map
- The finding's name is the item's identity. Each detect finding is one item, carried forward under the same section title in every artifact rather than as one entry per phase, and the map keys on that name alone.
- Paths live only in the map. The prose never holds one, so a rename is corrected in one place and every memory stays valid.
- The map holds tracking only. An entry is a name and its paths, with no prose, note, separate id, phase, or link to another entry, since which artifacts carry an item's section is what records its progress. It is never hand-edited and never shown to the user.
- Track registers and never removes. Detect registers the findings it wrote, and plan and harden re-report each by name, following a renamed path. That order is a convention the hook never enforces.
- Untrack belongs to verify alone. It stands a proven-closed finding down, removing its section from every artifact and its entry from the map in one pass, which is why verify is the one phase that writes across the other phases' artifacts. It is the only act that edits the memory prose, and it injects no id or anchor and authors no security content.
- Repair is maintenance, never a phase. Only
/lagune-repairruns it, to realign the whole map against the artifacts and the code. It is the only act that surfaces what is gone, and it never removes an entry itself. A phase that finds the tracking inconsistent runs/lagune-repairand continues instead of repairing the map. - The tracking hooks are mechanical. They act only on what they are handed, and the one call none makes alone, whether a vanished path means fixed or renamed, goes back to the agent or the user instead of being guessed.
Memory validation
- Validation judges shape, never security content. A written artifact must keep its template's shape, and a value the template derives from another, such as a score from its vector, is part of that shape, so one that drifted fails.
- Ownership stays with the writer. Each phase checks the artifact it wrote, verify the record it wrote its verdicts into, and the sweep over the whole memory belongs to
/lagune-repair, which reports drift for the owning phase to fix. Validation writes nothing, and like track and untrack it is internal plumbing with no user-facing command.
The website's languages
- English is the source and stays at the root. Every other language derives from it under its own prefix, so no existing URL, backlink, or redirect moves, and a change always starts in English before it reaches a translation.
- One locale registry decides every language and whether it is published. The build, the language switcher, hreflang, the sitemaps,
robots.txt, and the AI corpus all derive from it, so no layer can disagree about which languages exist. A draft builds in development and CI and never deploys, so a half-translated language never reaches readers or crawlers. - A right-to-left language mirrors the layout, never the code. The registry declares its direction and the build mirrors the styles from it, so no component keeps a second layout. Code, terminals, and commands keep reading left to right, since a command or a path shown in mirrored order is one a reader could copy wrong.
- A translation pairs with its English page by doc id and records the English version it came from. That pairing gives each page one state, translated, stale, or untranslated, and every layer follows the state instead of deciding on its own, so a page cannot be translated for search and untranslated for its reader.
- Every route exists in every published language. An untranslated page shows its English content inside the language's interface, with its canonical on the English page, so navigation never leaves the language and search engines never index the copy.
- hreflang pairs only real translations. The Docusaurus default declares every locale on every page, which would point crawlers at English content dressed as a translation.
- One structured-data identity in every language. The organization, the author, the website, and the software are the same entity across languages, and a translated page points to its English original, so search engines and AI assistants never split the project into one entity per language.
- The website overlays engine and Dashboard text by key and never edits it. That text keeps its English source in the engine, where the engine and the Dashboard also read it, so a translation can never change what they show, and a missing translation falls back to it key by key.
- The translation check is a barrier, not a style linter. A mistranslated command in a security product is a real risk, so commands, code, tokens, paths, and links stay as in English, and the check rejects any translation that changes or adds one.
- A translated language's build keeps only what it serves. Root-only files, such as
robots.txtand the host's settings, and every static file its pages take from the root stay at the root alone, since the host reads them only at the root and the language's pages load them from there, so a copy under its prefix would only be dead weight.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |