architecture
Authoritative architecture reference for Lagune, covering repository layout, the command/template split, the core/adapter boundary, what it scaffolds, and the tracking-map model. Use before adding an agent or when a decision depends on repo shape.
wellwelwel · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add wellwelwel/lagune --skill architecture技能说明
name: architecture description: Authoritative architecture reference for Lagune, covering repository layout, the command/template split, the core/adapter boundary, what it scaffolds, and the tracking-map model. Use before adding an agent or when a decision depends on repo shape. user-invocable: true metadata: internal: true
Lagune architecture
This skill is the specialized, authoritative description of how Lagune is structured: repository layout, how commands and templates are organized, the core/adapter boundary, what Lagune scaffolds into a target project, and the tracking-map model. Consult it before changing source, before adding an agent, and whenever a decision depends on the shape of the codebase.
The product mission and workflow philosophy live in CLAUDE.md. The toolchain, code conventions, build path, and how the tracking hooks are implemented live in the engineering skill. The language conventions and the boundaries on what prose carries and who may author it live in the writer skill. This skill covers the shape, not the build.
Repository layout
Top-level directories. Their internal structure is defined in the sections below.
| Directory | Purpose |
|---|---|
src/ | TypeScript source. Everything authored by hand lives here. |
src/types/ | The single home for every type declaration. No type is declared elsewhere. |
lib/ | Compiled JavaScript build output. Generated, not edited. This is what ships. |
spec/ | The Lagune core: the commands, templates, and sub-skills that ship. |
spec/commands/ | The /lagune.* command definitions an agent reads to run each phase. |
spec/templates/ | The files a command fills in (the security artifacts produced per phase). |
spec/skills/ | Non-invocable sub-skills: on-demand knowledge the phases load. |
test/ | Poku test suites, run against Node, Bun, and Deno. |
Command & template anatomy
A phase of the workflow is a pair: a command and one or more templates.
- A command instructs. It is the agent's reading: how to think about the phase, what to look for, what questions to resolve. Commands live in
spec/commands/, as markdown (.md) files with frontmatter, the format Claude Code consumes natively. - A template structures. It is the mould for the phase's output: the security artifact the command produces, with its sections and the fields to fill in. Templates live in
spec/templates/.
A phase command points to its template. The command carries the reasoning, the template carries the shape of the result. Splitting them keeps the "how to think" reusable and the "what to produce" consistent.
A command that fills no template has none, and the type layer encodes that: TemplateKey is CommandKey minus repair and verify. Verify records its verdicts on the harden record, so it fills no template of its own. specialize is the exception that is not a phase yet still pairs with a template (specialize-template.md): its artifact is a sub-skill file under .lagune/skills/, not a memory/ phase artifact.
Sub-skills
spec/skills/ holds the built-in sub-skills: agent-agnostic knowledge modules that load only on demand. They are not commands. Detect consumes them inline: it reads the catalog from .lagune/specializations.md (which lists each sub-skill as name: tags, suffixing [required] on any the catalog flags), then reads and follows the matching .lagune/skills/<name>.md directly. A user can import one into any prompt with @.lagune/skills/<name>.md. Adding a built-in is one .md plus one row in the baked catalog (src/hooks/skills/catalog.ts), no new command. A user grows the same set at runtime with /lagune.specialize, which writes a sub-skill into .lagune/skills/ and its row into .lagune/skills.json. .lagune/specializations.md is an internal, gitignored listing rebuilt from the catalog (by renderSpecializations, exposed as the specializations hook and rerun on every scaffold, pull, update, and skill change), merging the user's .lagune/skills.json over the baked catalog, the user's entry winning a name collision.
Agent-agnostic core vs. agent adapters
The codebase splits into two layers, and the split is what lets new agents be added later without rewriting the workflow.
- The core is agent-agnostic. Templates, the per-phase content, and the context-detection logic know nothing about which agent runs them. This is where the security value lives, and it is written once.
- An adapter is thin. Its only job is to translate the core's commands into the format and location a given agent expects. It carries no security logic of its own.
Adapters are data, not code. Each supported agent is a single entry in the agent registry under src/providers/, declaring its key, display name, command format, and target directory. A factory turns each entry into a provider, and a format dispatcher under src/transform/ renders the same core command into that agent's packaging. Adding an agent is adding a row, not writing a module. The registry is the single source of truth for which agents are supported.
The command formats are:
- Skill (
<dir>/lagune.<phase>/SKILL.md): a directory per command withname/description/argument-hint/user-invocablefrontmatter. Skill directories use each agent's current, project-scoped location (for example.claude/skills,.codex/skills,.agent/skills,.cursor/skills). - Copilot prompt file (
.github/prompts/lagune.<phase>.prompt.md): GitHub Copilot's prompt-file format, invoked as/lagune.<phase>. -