--- name: specialize description: Author a new built-in Lagune specialization inside the Lagune source, not a project's own catalog. Use when adding or refining a security knowledge module that ships with Lagune, against the native layout (`catalog/*.md` plus the built-in index). user-invocable: true disable-model-invocation: true metadata: internal: true --- # Authoring a built-in Lagune specialization (development workspace) The published skill `skills/lagune-specialize/SKILL.md` writes into a **project's own catalog**: `.lagune/catalog/.md` plus its entry in `.lagune/configs.json`. This repo is the **Lagune source**, where built-in specializations live in `catalog/.md` and their index is a TypeScript array, not a runtime JSON file. A built-in is registered in code, published with the engine, and tested. So you reuse the skill's **authoring discipline** (terrain, defense-only gate, template, tags, reconcile-never-append) but **override every output path** to the native layout, and you update the registration points the published skill never has to. ## Step 1: Run the skill's authoring steps, with redirected paths Read and follow `skills/lagune-specialize/SKILL.md` in full. Its authoring steps hold unchanged. The one thing that does not is where files are read and written, since the skill targets a project and you are in the source. Remap every path it names: | Skill path (a project's own catalog) | Native path (use this instead) | | ---------------------------------------------------------- | ------------------------------------------------------------------------------- | | `read catalog ` for `regex`, `javascript`, `browser` | every `*.md` already in `catalog/` (list the directory, mirror the closest one) | | `template.md`, next to the skill | `skills/lagune-specialize/template.md` | | `read catalog` (list what exists) | read `catalog/` and `BUILTIN_SPECIALIZATIONS` in `src/catalog/builtin.ts` | | `.lagune/catalog/.md` (the specialization file) | `catalog/.md` | | `.lagune/configs.json` (index entry) | a `BuiltinSpecialization` in `src/catalog/builtin.ts` | A hook reference inside the `.md` body is a call to the `lagune_read` tool, with `command` set to the hook and long flags only in `arguments`, because that body ships verbatim to the end user and the skill that loads it carries the npx fallback. ## Step 2: Decide the category Every built-in belongs to at least one **category**, which is how a project brings it into its catalog with `npx lagune write add --categories `. Categories live in `CATEGORIES` in `src/categories/categories.ts`. - A language specialization goes under its language key (`python` under `python`, and so on). - A specialization about an application-security risk OWASP tracks goes under `owasp`. - Match the specialization to the category that actually describes it. If none fits, that is a signal a new category may be needed, adding a `Category` to `CATEGORIES` (key, label, description) and its icon. Ask the user before inventing one, do not force an unrelated module into `owasp` to avoid the question. A project's own index entry carries no categories, but the **built-in** index entry does. Set it. ## Step 3: Write and register, then verify A new built-in is not done when the `.md` exists. Touch each of these: ### Required (a specialization is broken without these) 1. Write the authored module to **`catalog/.md`** (Step 1). The engine reads `catalog/.md` by name, so the file resolves once it is on disk and indexed. 2. Add the `BuiltinSpecialization` `{ name, tags, categories }` to **`src/catalog/builtin.ts`**. Without this row, `read catalog` never lists it and `read catalog ` cannot resolve it. 3. Add a `Category` to **`src/categories/categories.ts`**, but only when you introduced a new category. 4. Add its label, description, icon, and prompt task to **`src/dashboard/shared/specialization-meta.ts`**, which the dashboard and the website share. ### Tests (the suite asserts the index, the files, and the docs stay in sync) 5. The catalog tests iterate `BUILTIN_SPECIALIZATIONS` (for example, no built-in repeats its name inside its own tags, every index row has a file and every file a row, every engine call carries the package version and long flags), so a new entry is exercised automatically. Update a hardcoded list only when your change alters it, such as the built-ins a category holds. 6. Run the full suite: `npm test`. It runs `scripts/build.sh` first, so the engine the e2e tests exercise is rebuilt automatically. All green before you call it done. ### Documentation (the built-in catalog is enumerated by hand in the website) 7. Add a row to the table of built-ins in **`website/docs/catalog.mdx`**, giving the built-in its categories and focus. The sync test fails until the row matches the index. 8. Update **`README.md`** only when it enumerates built-ins. ### Not touched - `.lagune/configs.json` and `.lagune/catalog/`: these hold a **project's own** catalog. A built-in never writes there. ## Quick checklist ``` [ ] catalog/.md authored from skills/lagune-specialize/template.md (reconciled on a refine), verify closing only on what the repository shows and detect recording the rest as a side quest [ ] src/catalog/builtin.ts BuiltinSpecialization added { name, tags, categories } [ ] src/categories/categories.ts only if a new category was introduced [ ] src/dashboard/shared/specialization-meta.ts label, description, icon, prompt task [ ] tests updated + npm test green [ ] website/docs/catalog.mdx table row added ``` ## Summary to the user As Step 8 of the skill: state the name, tags, categories, what it covers, and that the phases load it on demand once shipped (a prompt loads it directly with the engine's `read catalog `). Note that a project's own specialization of the same name shadows it. Suggest a commit such as ``feat: add specialization in `` defense``, matching the wording the existing built-ins use, as a suggestion, not a mandate.