@warpgogol/forge 2.9.2 → 2.9.4

package/skills/fo/fo-idea-implement/ADR-FLOW.md

@@ -0,0 +1,179 @@
+# ADR Implementation Flow
+
+Execute this flow when the document is an ADR (prefix `ADR-`, or file in `docs/adrs/`).
+
+## 4.1. Read the ADR
+
+Read the ADR file. Extract:
+
+- **Status** — must be `accepted`, `reviewing`, or `proposed`. If `superseded` or `rejected` (terminal), stop with message: `ADR-XXXX is <status> (terminal). Terminal ADRs cannot be implemented. To change this decision, create a new ADR or RFC that supersedes ADR-XXXX.` If `implemented`, stop with message: `ADR-XXXX is already implemented. Nothing to do.`
+- **Decision** — the core decision from the `## Decision` section.
+- **Context** — the local situation and constraints from `## Context`.
+- **Consequences** — what the decision implies for the codebase.
+- **Related** — any RFCs, ADRs, or DNA invariants referenced.
+
+## 4.2. Transition to accepted (if needed)
+
+If the ADR is `proposed` or `reviewing`, transition it to `accepted`:
+
+1. Set `status: accepted` in the frontmatter.
+2. Set `updatedAt: <today's date>`.
+3. If `reviewers` is empty, read the default reviewer(s) from the `reviewers` field comment in `docs/adrs/adr-0000-template.md` (currently `human:andrii-syrokomskyi`). Set all listed default reviewers.
+4. Commit:
+
+   ```txt
+   adr: accept ADR-XXXX <short title>
+
+   Transition ADR-XXXX to accepted status for implementation.
+   ```
+
+   Stage only the ADR file.
+
+If the ADR is already `accepted`, proceed directly.
+
+## 4.3. Implement the decision
+
+Read the `## Decision` section and implement it in code. Follow the same principles as RFC implementation:
+
+- Make autonomous, ecosystem-aligned decisions.
+- Use `edit`/`multi_edit` for changes to existing files, `write_to_file` for new files.
+- Commit each logical phase of work:
+
+  ```txt
+  implement: ADR-XXXX — <phase description>
+
+  <one-line description of what was done in this phase>.
+  ```
+
+  Stage only the files touched by this phase — see `_shared/fo-pipeline-conventions.md` §Commit discipline.
+
+- Recoverable errors: see `_shared/fo-pipeline-conventions.md` §Recoverable errors.
+
+## 4.4. Run scoped build checks
+
+After implementation is complete, run heavy checks for the impacted workspaces only:
+
+1. ADR validation:
+
+   ```sh
+   pnpm exec werkstatt run adr.validate <adr-id> --json
+   ```
+
+2. Determine impacted packages/apps from the ADR's `scope` and the files touched during implementation. Build only those workspaces:
+
+   ```sh
+   pnpm --filter @gogol/<package> run build:check
+   ```
+
+   Or for apps:
+
+   ```sh
+   pnpm --filter <app-name> run build:check
+   ```
+
+   See `_shared/fo-pipeline-conventions.md` §Build verification discipline.
+
+## 4.5. Fix errors
+
+If any check fails, fix every error:
+
+1. Read the error output.
+2. Identify the root cause.
+3. Fix it.
+4. Re-run the failing check to confirm the fix.
+5. Commit each fix:
+
+   ```txt
+   fix: ADR-XXXX — <error description>
+
+   <one-line description of the root cause and fix>.
+   ```
+
+Continue until all impacted checks pass.
+
+## 4.6. Documentation audit (fo-doc-audit)
+
+After implementation is complete and all checks pass, invoke `fo-doc-audit` via the `skill` tool. It analyzes the session's changes, checks all documentation surfaces, applies needed updates, and commits them separately. Wait for it to complete.
+
+If `fo-doc-audit` reports that no updates are needed, proceed to the next step.
+
+## 4.7. ADR code-trace
+
+Before stamping `implemented`, verify that the ADR is mentioned in the codebase — this leaves a trace linking code back to the decision record, just as RFCs leave traces.
+
+1. **Search for the ADR id** — use `grep_search` to scan `apps/`, `packages/`, and `services/` for the ADR id string (e.g. `ADR-0003`). Check:
+   - **COMPASS block comments** — `MODULE_CONTRACT`, `CHANGE_SUMMARY`, or other Compass scaffolding comments that reference the ADR id.
+   - **Inline code mentions** — comments, docstrings, or annotations in source files that reference the ADR id.
+
+2. **If mentions are found** — the trace exists. Proceed to step 4.8.
+
+3. **If no mentions are found** — attempt to find the most relevant file(s) where the decision was implemented. If the file(s) can be identified:
+   - Add a Compass block comment referencing the ADR id to the file's `MODULE_CONTRACT` or `CHANGE_SUMMARY` section. For example: `<item>ADR-0003: <brief note on what this ADR decided for this module.</item>`
+   - If the file has no Compass scaffolding, add a brief inline comment at the top of the file: `// Implements ADR-XXXX: <one-line decision summary>`
+   - Commit the trace:
+
+     ```txt
+     trace: ADR-XXXX — add code mention
+
+     Add ADR-XXXX reference to <file> to link the decision to the code.
+     ```
+
+   - Proceed to step 4.8.
+
+4. **If the relevant file(s) cannot be identified** — ask the operator: `ADR-XXXX was implemented but no code mention was found. Please point to the file(s) where this ADR's decision was applied so I can add a trace reference.` After the operator provides the file(s), add the trace as described in step 3, commit, and proceed.
+
+**For already-implemented ADRs** (if this step is reached for an ADR that was already `implemented`): this check is informational — attempt to find the trace and add it if missing, but do not block on it.
+
+## 4.8. Stamp implemented
+
+After all checks pass and documentation is updated, transition the ADR to `implemented`:
+
+1. Set `status: implemented` in the frontmatter.
+2. Set `implementedAt: <today's date>`.
+3. Set `updatedAt: <today's date>`.
+4. Commit:
+
+   ```txt
+   adr: implement ADR-XXXX <short title>
+
+   Transition ADR-XXXX to implemented status. Decision is live in code,
+   scoped build passes.
+   ```
+
+   Stage only the ADR file.
+
+## 4.9. Review (fo-review) — MANDATORY GATE
+
+**This step is unconditional.** It MUST be executed after every implementation run — regardless of whether build checks passed, failed, or were fixed. No exceptions. The ADR report (step 4.11) MUST NOT be emitted until this step is complete.
+
+1. **Determine the diff scope** — identify the git fixed point at the start of this implementation session (the commit before the first `implement:` or `adr:` commit). Capture the diff via `git diff <fixed-point>...HEAD`.
+2. **Invoke `fo-review`** — run the review skill inline via the `skill` tool, passing the diff scope. Wait for it to complete (mechanical floor, seven axes, spec compliance, persist report + commit). If the `skill` tool call fails, retry once. If it fails again, proceed to step 4.11 and note the failure in the report.
+3. **Read the review report** — extract the verdict and all findings.
+
+If the review verdict is **Approved** with zero findings, skip step 4.10 and proceed directly to step 4.11 (Report).
+
+## 4.10. Fix findings (fo-fix) — MANDATORY if findings exist
+
+If the review has ANY findings — this step MUST be executed — it is not optional. "Findings" means any issue noted under any review axis (A–G), regardless of severity label ("minor", "cosmetic", "advisory") or the review's overall verdict. An **approved** verdict with minor findings **still requires** `fo-fix` — do not skip because the verdict is "approved" or findings are "minor". The only case where this step is skipped is a review with **zero findings** (every axis says "No issues."):
+
+1. **Re-verify findings** — before fixing, quickly check whether each finding is still relevant: the flagged code may have been changed by a subsequent step. Discard stale findings.
+2. **Invoke `fo-fix`** — run the fix skill inline via the `skill` tool. It reads the persisted review report, applies fixes in priority order, runs scoped typecheck verification, commits, and delegates doc updates to `fo-doc-audit`. Wait for it to complete. If the `skill` tool call fails, retry once. If it fails again, proceed to step 4.11 and note the failure in the report.
+3. **Re-run scoped build checks** if `fo-fix` made code changes — repeat step 4.4 for any workspaces touched by the fixes.
+
+If the review verdict is **Approved** with zero findings, skip this step — no fix is needed.
+
+## 4.11. Report
+
+After implementation, review, and fix are complete, report:
+
+```
+## ADR-XXXX Implementation Summary
+
+### Decision: <one-line summary>
+### Phases implemented: <count>
+### Commits: <count>
+### Scoped build: <Pass | Fail — fixed>
+### Review: <verdict> — <N> findings
+### Fix: <done, <N> findings fixed | skipped, no findings>
+### Status: implemented (<date>)
+```

package/skills/fo/fo-idea-plan/SKILL.md

@@ -230,6 +230,8 @@ If multiple RFCs were processed, present a single batch summary in `aiLanguage`.
 
 Do not output per-RFC summaries or "Moving to RFC-XXXX next" messages during the loop; they belong here, at the very end.
 
+After presenting the summary, follow the pipeline continuation protocol per `_shared/fo-pipeline-conventions.md` §Pipeline continuation — proactively suggest the next step (`fo-idea-implement`) and offer to proceed via `ask_user_question`. Do not automatically run the next skill — ask the operator first.
+
 ## Session affinity (advisory)
 
 When an RFC was planned in this session, prefer implementing it in this session too. The session context contains edge cases and mental models not fully captured in the plan text. If starting a new session, re-read the plan file and the RFC body before implementing. This is a recommendation, not a machine-enforced constraint — sessions have no forge-internal identity.

package/skills/fo/fo-review/AXES.md

@@ -0,0 +1,70 @@
+# Review Axes
+
+Load this file when running step 4 of `fo-review`. For each axis, check every item. An item either **passes**, **fails** (specific finding with evidence), or is **not applicable** (state why). Skip N/A items silently — do not pad the report.
+
+## Axis A — Structural correctness
+
+Beyond what the mechanical floor catches:
+
+- **Strict typing** — flag `any`, implicit casts, missing interfaces, untyped parameters, non-exhaustive switch/if chains.
+- **No magic numbers or untyped data** — flag literal constants that should be named, enums, or config; flag strings standing in for domain concepts.
+- **Minimalism** — flag over-engineered abstractions, speculative generality, duplicated logic, or middle-man modules that can be simplified.
+- **Dead code** — flag unreachable branches, unused exports, commented-out code blocks.
+- **Error handling** — flag swallowed errors, bare `catch` blocks without context, missing error types.
+
+## Axis B — DNA alignment
+
+Check the diff against every DNA invariant it touches. The list below is the minimum scan set — if the diff touches a DNA invariant not listed here, check it too.
+
+- **DNA-1** (monorepo boundary) — no `apps/* → apps/*` or `apps/* → services/*` imports.
+- **DNA-4** (canonical content) — no hardcoded copy strings or configuration in routes/components that belongs in `src/content/`.
+- **DNA-5 / DNA-17** (mirror quintet) — every new `.astro` component/section has colocated `manifest.yaml`, content schema, `.css`, and content `.md`.
+- **DNA-6** (kebab-case) — all new filenames use kebab-case.
+- **DNA-7** (thin routes) — route files are orchestrators only; no inline `<style>`, hardcoded body copy, or layout logic.
+- **DNA-8** (page → section → component → content) — visitor-facing page bodies are composed as ordered section components.
+- **DNA-10** (no hardcoded tokens) — CSS uses `--ds-*` custom properties only; no raw `rgba()` or `#hex`.
+- **DNA-23** (cosmic naming) — new manifests carry `cosmicName` from the correct closed catalog; three-way alignment (manifest ↔ `PLANET_IMPORT_PATHS` / `MOON_IMPORT_PATHS` ↔ `system.md`).
+- **DNA-24** (block-declarative pages) — page entries are frontmatter-only; no markdown bodies.
+- **DNA-25** (single buildPage) — routes call `buildPage`; no hand-assembled block composition.
+- **DNA-40** (env-example) — new env vars are documented in `.env.example`.
+- **DNA-42** (Compass markup) — new authored source files carry `MODULE_CONTRACT` and `CHANGE_SUMMARY`.
+- **DNA-51** (Werkstatt primitives) — mutating Werkstatt commands use shared lock/idempotency/atomic-write helpers.
+
+## Axis C — Ecosystem fit
+
+- **Package boundaries**: imports flow `apps/* → packages/*` and `services/* → packages/*`, never `apps/* → apps/*` or `apps/* → services/*`.
+- **Pipeline placement**: new checks are placed in the correct pipeline (`build.prepare`, `build.check`, `sites-check`, `sites-check-postbuild`) with justified blocking vs. advisory choice.
+- **Compass sync**: if the diff changes repository-wide requirements, shared package contracts, or app-package relationships, the relevant `docs/*.xml` files are updated.
+- **AGENTS.md updates**: if the diff introduces new rules or patterns, the relevant `AGENTS.md` files are updated.
+- **Cosmic naming**: if the diff touches manifests or component/section/page contracts, the three-way alignment is maintained.
+- **Command lifecycle**: new commands are registered in the correct module; changed commands update their metadata; removed commands are explicitly deprecated.
+
+## Axis D — Forward-only compliance
+
+- No compatibility shims, bridges, or dual-paths that keep legacy behavior alive.
+- Deprecation means removal in the same change, not an indefinite grace period.
+- Legacy code paths are deleted, not maintained behind a flag.
+- If the diff amends an existing contract, it changes the contract directly — no parallel interpretation.
+
+## Axis E — Agent-facing clarity
+
+- **Compass scaffolding**: new non-trivial source files carry `MODULE_CONTRACT` and `CHANGE_SUMMARY`; high-risk files carry `@ai-invariant` lines.
+- **No ungrounded assertions**: code comments and docstrings reference real functions, types, and files — no invented APIs or phantom parameters.
+- **Readable by another agent**: variable names reveal what they hold; function names reveal what they do; no mysterious names.
+- **Log-driven development**: logs carry enough context for debugging; no bare `console.log` without context or structure. Prefer the repo's shared logging contracts when they exist.
+- **Anti-fabrication**: if the diff includes content claims (prose, business records), the code distinguishes between generated content and human-authored content.
+
+## Axis F — Pragmatism
+
+- **Minimal command surface**: each new command earns its existence — no command that could be a flag on an existing command.
+- **Lean contracts**: TypeScript types are the minimum needed — no speculative generality, no unused optional fields.
+- **Existing patterns**: the diff checks whether an existing command, schema, or pattern can be extended before introducing a new one.
+- **Scope discipline**: the diff touches only what's necessary; no scope creep into unrelated areas.
+
+## Axis G — Blind spots
+
+- **Performance**: new build-time commands specify their cost (file scan count, regex complexity, I/O patterns).
+- **False positives**: new validators estimate their false-positive rate and describe suppression during migration.
+- **Edge cases**: the diff considers empty states (new app with no content), concurrent execution, and interrupted operations.
+- **Migration path**: existing apps' path to compliance is documented.
+- **Security / privacy**: if the diff touches user data, PII, or external services, it addresses GDPR/privacy and secret management. No cookies (`document.cookie`, `Set-Cookie`). Client-side persistence is `localStorage` only; server-side is `unstorage`.

package/skills/fo/fo-session-retro/learned-principles.md

@@ -0,0 +1,15 @@
+# Learned Principles
+
+Principles learned across sessions by the `fo-session-retro` skill. These are accumulated observations about insight triage quality, categorization accuracy, and routing decisions.
+
+## Format
+
+Each principle: a concise statement, optionally with a rationale.
+
+---
+
+1. **Filter out transient issues.** Pre-existing TypeScript errors, broken builds, or CI failures that are unrelated to the session's work and will be fixed quickly by other agents are NOT useful insights. Do not route them to any destination. Only capture knowledge that remains useful weeks or months later.
+
+2. **Check whether a "rule" is already enforced by a command before routing it to AGENTS.md.** If an automated check already catches the problem (e.g. error code conflicts caught by a validator), the insight is context, not a rule. Rules are for conventions that no command enforces yet.
+
+3. **Filter out one-off completed actions.** Insights that describe a finished migration step, a one-time rename, or any action that won't recur are NOT useful — they describe history, not future-relevant knowledge. Only capture insights that describe patterns, traps, or conventions another agent will encounter again. Test: "Will this situation arise in a future session?" If no, drop.

package/skills/shared/windows-ai-tooling/.gitattributes.template

@@ -0,0 +1,49 @@
+# Auto detect text files and perform LF normalization
+* text=auto eol=lf
+
+# Source code
+*.ts text eol=lf
+*.tsx text eol=lf
+*.astro text eol=lf
+*.css text eol=lf
+*.scss text eol=lf
+*.json text eol=lf
+*.jsonc text eol=lf
+*.md text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.mjs text eol=lf
+*.cjs text eol=lf
+*.js text eol=lf
+*.jsx text eol=lf
+*.sh text eol=lf
+*.ps1 text eol=lf
+
+# Add project-specific source extensions here:
+# *.go text eol=lf
+# *.rs text eol=lf
+# *.java text eol=lf
+# *.kt text eol=lf
+# *.cs text eol=lf
+# *.py text eol=lf
+# *.rb text eol=lf
+# *.php text eol=lf
+
+# Ensure Windows batch files still have CRLF (if any)
+*.cmd text eol=crlf
+*.bat text eol=crlf
+
+# Binary files (do not modify)
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.svg binary
+*.woff binary
+*.woff2 binary
+*.ttf binary
+*.eot binary
+*.mp4 binary
+*.webm binary
+*.webp binary

package/skills/shared/windows-ai-tooling/AGENTS_WINDOWS.md.template

@@ -0,0 +1,42 @@
+## Windows agent tooling
+
+This project is developed on Windows 10/11. AI agents editing this project must follow the command allow-list below instead of assuming a POSIX environment.
+
+### Tooling tiers
+
+| Tier | Delivery | Examples | How agents use them |
+| --- | --- | --- | --- |
+| **Native Windows** | winget or built-in | `git`, `node`, `npm`, `pnpm`, `python`, `pip`, `jq`, `curl`, `docker`, `wsl` | Directly in PowerShell/CMD. |
+| **Git Bash POSIX coreutils** | Shipped with `Git.Git` | `bash`, `grep`, `sed`, `awk`, `find`, `tar`, `ls`, `xargs` | Through `bash -c "..."`. Paths remain Windows-style. |
+| **WSL2 Ubuntu** | `wsl --install -d Ubuntu` | GNU coreutils, `apt` packages | Via `wsl <command>` or `wsl bash -c "..."`. Convert Windows paths with `wslpath` first. |
+
+### Verified installation commands
+
+```powershell
+winget install -e --id Git.Git
+winget install -e --id OpenJS.NodeJS.LTS
+winget install -e --id Python.Python.3
+winget install -e --id jqlang.jq
+winget install -e --id cURL.cURL
+winget install -e --id Docker.DockerDesktop
+wsl --install -d Ubuntu
+```
+
+### Agent command rules
+
+- **MAY** use `wsl <command>` when the tool is listed as WSL-only.
+- **MAY** use `bash -c "..."` when running inside Git Bash.
+- **MUST** convert Windows paths to WSL paths with `wslpath` before passing them to `wsl` commands.
+- **MUST NOT** assume `grep`, `find`, `sed`, `awk`, `jq`, `curl` exist in PowerShell unless installed natively and verified with `Get-Command`.
+- **MUST NOT** modify `.gitattributes` without explicit approval; the line-ending contract is load-bearing.
+- **SHOULD** prefer exact winget IDs (`-e --id`) when installing tools on Windows.
+
+### Path translation
+
+```powershell
+# PowerShell → WSL
+wsl bash -c "cat $(wslpath 'C:\Users\user\file.txt')"
+
+# PowerShell → Git Bash (paths stay Windows-style)
+bash -c "grep pattern C:/Users/user/file.txt"
+```

package/skills/shared/writing-great-skills/GLOSSARY.md

@@ -0,0 +1,201 @@
+# Glossary — Building Great Skills
+
+The domain model for what makes a skill great. A skill exists to wrangle determinism out of a stochastic system; the root virtue is **Predictability**, and every term below is a lever on it. This is the disclosed reference for [`writing-great-skills`](SKILL.md).
+
+The terms are grouped by axis: **Invocation** (how a skill is reached), **Information Hierarchy** (how its content is arranged), **Steering** (how the agent's runtime behaviour is shaped), and **Pruning** (how it is kept lean). Each **failure mode** lives beside the lever that cures it, tagged _failure mode_.
+
+**Bold terms** in any definition are themselves defined in this glossary; find them by their heading.
+
+## Predictability
+
+The degree to which a skill makes the agent behave the same _way_ on every run — the same process, not the same output (a brainstorming skill should _predictably_ diverge; its tokens vary, its behaviour doesn't). The root virtue every other term serves — cost and maintainability are symptoms of it, not rivals.
+
+_Avoid_: consistency, reliability, robustness, output-determinism
+
+## Invocation
+
+How a skill is reached — and the two loads you pay for the choice.
+
+### Model-Invoked
+
+A skill that keeps its **description** field, so the agent can see it and fire it autonomously — and the human can still type its name, so model-invocation always _includes_ user reach. There is no model-only state: a description only ever _adds_ agent discovery, never removes the human's. Pays a permanent **context load** on every turn in exchange for that discoverability. Reachable by other skills, because the description that makes it agent-discoverable makes it invocable. A model-invoked skill whose content is all **reference** is also one home for shared reference: another skill can invoke it, so reference needed by several skills lives in one place. Pick model-invocation only when the agent must reach the skill on its own; if it never fires except by hand, drop the description and pay no context load.
+
+_Avoid_: ability, tool, capability
+
+### User-Invoked
+
+A skill with its **description** stripped — invisible to the agent and reachable only by the human typing its name (user-_only_, where **model-invoked** is user-_and-agent_). Trades agent-discoverability for zero **context load**. Because it has no description, nothing but the human can reach it: no other skill can fire it.
+
+_Avoid_: procedure, workflow, command
+
+### Description
+
+The skill's machine-readable trigger, and the one **context pointer** a **model-invoked** skill is forced to keep loaded at all times. Its mere presence _is_ the invocation axis: keep it and the skill is model-invoked (and reachable by other skills); delete it and the skill is **user-invoked**, reachable only by the human. The source of a model-invoked skill's **context load**.
+
+_Avoid_: frontmatter, summary
+
+### Context Pointer
+
+A reference held in the agent's context that names some out-of-context material and encodes the condition for reaching it. The **description** is the top-level context pointer (context window → skill); pointers to disclosed files are the same object one level down. Its wording, not the target, decides _when_ the agent reaches — and _how reliably_. A must-have target behind a weakly worded pointer is a variance bug: fix the wording first, and inline the material only if sharpening fails.
+
+_Avoid_: link, reference, import
+
+### Context Load
+
+The cost a **model-invoked** skill imposes on the agent's context window — its **description**, always loaded, spending both tokens and attention. What **user-invoked** skills escape by having no description, and the brake on splitting into more model-invoked skills.
+
+_Avoid_: token cost, context bloat
+
+### Cognitive Load
+
+The cost a **user-invoked** skill imposes on the human — what they must hold in their head: which skills exist and when to reach for each (the human is the index). What **model-invocation** removes by being agent-discoverable, and the brake on splitting into more user-invoked skills. Not a cost to minimise: it is the price of human agency, the reason some skills stay user-invoked. Spend it where human judgement matters; remove it where it does not.
+
+_Avoid_: human index, burden, overhead
+
+### Router Skill
+
+A **user-invoked** skill whose job is to point at your other user-invoked skills — naming each and when to reach for it — so the human has one skill to remember instead of many. It can only hint, never fire them: user-invoked skills have no **description**, so nothing but the human can reach them. The cure for **cognitive load** when user-invoked skills multiply.
+
+_Avoid_: dispatcher, menu, registry, index, router procedure
+
+### Granularity
+
+How finely you divide skills. Finer division spends one of the two loads: more **model-invoked** skills spend **context load** (more descriptions crowding the window and competing for attention); more **user-invoked** skills spend **cognitive load** (more for the human to remember and reach for). Two cuts guide the division. By **invocation**, split off a model-invoked skill where you have a distinct **leading word** to trigger it — a trigger word you actually use in your prompts. By **sequence**, split a run of **steps** where a step's **post-completion steps** need hiding, since isolating it in its own context clears what follows. Beware the reverse: merging sequences exposes each step's post-completion steps to what follows, inviting premature completion.
+
+_Avoid_: chunking, modularity
+
+## Information Hierarchy
+
+How a skill's content is arranged, and how far down the ladder each piece sits.
+
+### Information Hierarchy
+
+A skill's content ranked by how immediately the agent needs it — a single ladder, produced by two cuts: in-file or behind a pointer, and step or reference. The rungs:
+
+- **Steps** — in-file, primary
+- **Reference**, in-file — secondary
+- **Reference**, disclosed — behind a **context pointer**
+
+A skill with no **steps** uses just the bottom two rungs — often a legitimately flat peer-set (e.g. every rule of a review on one rung), which is a fine arrangement, not a smell. The hierarchy is independent of invocation: a skill can be model- or user-invoked whether it is all steps, all reference, or both. When a skill has steps, in-file reference that should be disclosed buries them and turns attending to them into a coin-flip — a variance lever, not just a legibility one. Keep the top of the ladder legible; push down it whatever you can.
+
+_Avoid_: structure, organization, layout
+
+### Steps
+
+The ordered actions the agent performs — when a skill has them, the primary tier of its content, and the part that earns its place in SKILL.md. Not every skill has steps: a skill can be all steps (`tdd`), all **reference** (a review), or both, independent of invocation. Every step ends on a **completion criterion**, clear or vague.
+
+_Avoid_: workflow, instructions, choreography
+
+### Reference
+
+Material the agent refers to on demand — definitions, facts, parameters, examples, conditional instructions. When a skill has **steps** it is secondary to them; when a skill has none it is the entire content; or it lives outside any skill entirely — see **External Reference**. Reached via **context pointers**, and the prime candidate for **progressive disclosure**.
+
+_Avoid_: supporting material, docs, background
+
+### External Reference
+
+**Reference** that lives outside the skill system — a plain file, no **description**, no **steps**, not invocable — that any skill can point at. The home for shared reference that needn't fire on its own, and the only shared home two **user-invoked** skills can use, since neither has a description and so neither can fire the other.
+
+_Avoid_: doc, resource, knowledge base
+
+### Progressive Disclosure
+
+Moving **reference** down the ladder — out of SKILL.md and behind a **context pointer** — so the top stays legible. Not primarily a token optimisation; it is how the **information hierarchy** is protected. Licensed by **branching**: disclose what only some branches need, inline what every path needs, and if a pointer fires unreliably on must-have material, sharpen its wording, and pull it back inline only if that fails.
+
+_Avoid_: lazy loading, chunking
+
+### Co-location
+
+Keeping the material an agent needs at once in one place — a concept's definition, rules, and caveats under a single heading, not scattered across the file — so reading one part brings its neighbours with it. The within-file companion to the **Information Hierarchy**: the hierarchy ranks _how far down_ a piece sits; co-location decides _what sits beside it_ once there. There is no formula for the right format of a body of **reference**; the test is that a skill should read like documentation written for the agent, and grouped material reads that way where scattered material does not. Distinct from **Duplication**: that repeats one meaning in two places, where scattering fragments a single meaning across many.
+
+_Avoid_: grouping, clustering, cohesion
+
+### Sprawl
+
+_Failure mode._ A skill that is simply too long — too many lines in SKILL.md — independent of whether they are stale or repeated. Even an all-live, all-unique skill can sprawl. It costs readability (the agent wades through more before it can act, and attention thins across the excess), maintainability (every extra line is one more to keep **relevant**), and tokens. The cure is the **information hierarchy**: push **reference** down behind **context pointers**, and split by **branch** or sequence so each path carries only what it needs. Distinct from **sediment** (length from stale accumulation) and **duplication** (length from repeated meaning) — sprawl is length itself, whatever its cause.
+
+_Avoid_: bloat, length, size, verbosity
+
+## Steering
+
+The levers that shape the agent's runtime behaviour toward **Predictability**.
+
+### Branch
+
+A distinct way a skill can be invoked — a case the skill handles — so different runs take different paths through it. A skill with many steps may carry many branches; a linear one has none.
+
+_Avoid_: path, case, fork
+
+### Leading Word
+
+A compact concept — also called a _Leitwort_ — already living in the model's pretraining, that the agent thinks with while running the skill. It encodes a behavioural principle in the fewest possible tokens by invoking priors the model already holds (e.g. _lesson_, _proximal zone of development_, _fog of war_, _tracer bullets_). Repeated as a token, never as a sentence, it accumulates a distributed definition across the skill and anchors a whole region of behaviour. Coining your own works if you define it clearly, but a made-up word recruits no priors — you pay in definition tokens what a pretrained word gives free. Reach for an existing word first.
+
+A leading word serves **predictability** twice. In the body it anchors **execution** — the agent reaches for the same behaviour every time the concept appears, and inside flat reference it focuses attention on a class of thing to look for, recruiting the right checks each run. In the **description** it anchors **invocation** — and not only within the skill: when the same word lives in your prompts, your docs, and your codebase, the agent links that shared language to the skill and fires it more reliably. Word a description with the leading words you actually use when you want the skill.
+
+_Avoid_: keyword, term, motif
+
+### Completion Criterion
+
+The condition that tells the agent a unit of work is done — the target it judges against. Two properties make it a lever, not just a quality. Its **clarity** (can the agent tell done from not-done?) resists **premature completion** — a vague bound ("understanding reached") lets the agent declare done and slip to the next step; this axis needs _steps_ to bite, since premature completion is a between-steps failure. Its **demand** (how much it requires) sets **legwork** — "every modified model accounted for" forces thorough work where "produce a change list" does not — and this axis is _not_ step-bound: it can bind a body of flat reference too, which is how a skill with no steps still carries an exhaustiveness bar ("every rule applied"). The strongest criteria are both checkable and exhaustive.
+
+_Avoid_: done condition, exit condition, stopping rule
+
+### Legwork
+
+The work an agent does behind the scenes within a single step — reading files, exploring the codebase, making changes, digging up what it needs rather than offloading to the user. It lives below the step structure: never written as its own step, latent in the wording, controlled by the agent rather than the skill. The within-step counterpart to **post-completion steps**' across-step pull. Raised by a **leading word** (_comprehensive_, _thorough_) or a **completion criterion** that demands the work be exhaustive — including the demand axis applied to flat reference, which is what drives a skill of flat reference to cover all its rungs. Goes thin either when that demand is missing or when **premature completion** cuts the step short.
+
+_Avoid_: scope, effort, diligence, coverage
+
+### Post-Completion Steps
+
+The **steps** that follow the current step. Visible, they pull the agent forward into **premature completion** — the more it sees, the stronger the tug; the defence is to hide them by splitting the sequence of steps into two.
+
+_Avoid_: horizon, fog of war, lookahead
+
+### Premature Completion
+
+_Failure mode._ Ending the current step before it is genuinely done, because the agent's attention slips to being done rather than to the work. A between-steps failure: it needs **steps** to occur — a skill with no steps that quits early isn't premature completion but thin **legwork** under an unmet demand. A tug-of-war between two forces: visible **post-completion steps** (the pull forward) and the **completion criterion**'s clarity (the resistance — a sharp, checkable bar holds; a vague one gives way). Fuzziness is the necessary condition: a sharp bound resists the pull no matter how many later steps are visible, so a step that never rushes needs no defending. Two levers hold a step that does, but reach for them in order: **sharpen the bound first** — it is local and cheap. Only when the criterion is irreducibly fuzzy _and_ you actually observe the rush do you **hide the later steps** — and hiding only works across a real context boundary (a user-invoked hand-off or a subagent dispatch; an inline model-invoked call leaves the later steps in context and clears nothing). One cause of thin legwork, but distinct from it: legwork can be thin even when a step runs to full completion.
+
+_Avoid_: premature closure, the rush, rushing, shortcutting
+
+### Negation
+
+_Failure mode._ Steering by prohibition — telling the agent what _not_ to do — which drags the forbidden behaviour into context and makes it _more_ available, not less. _Don't think of an elephant_, and the elephant is all there is; _never write verbose comments_, and verbosity is the pattern the agent has just read. The negation is a weak modifier the strongly-activated concept overruns, so the ban half-reads as an instruction to do the thing. Its **leading word** is the _elephant_: whatever a prohibition names into the frame. Cure: prompt the **positive** — describe the target behaviour ("write one-line comments") so the banned one is never spoken. A prohibition earns its place only as a hard guardrail on a behaviour you cannot phrase positively; even then, pair it with the positive target so attention lands on what to do.
+
+_Avoid_: ironic rebound, don't-prompting, the pink elephant
+
+## Pruning
+
+Keeping a skill lean — each remedy paired with the failure it cures.
+
+### Single Source of Truth
+
+The desired state where each meaning lives in exactly one authoritative place, so a change to the skill's behaviour is a change in one place. **Duplication** is its violation.
+
+_Avoid_: home, canonical location
+
+### Duplication
+
+_Failure mode._ The same meaning given more than one **single source of truth**. It costs maintenance (change one place, you must change the others), costs tokens, and inflates prominence — repeating a meaning weights it on the ladder past its real rank. The accidental inverse of a **leading word**, which raises attention on purpose by repeating a token, never the meaning.
+
+_Avoid_: repetition, redundancy
+
+### Relevance
+
+Whether a line still bears on what the skill does — the lens for what to keep. A line loses relevance either by never bearing on the task (mere exposition, or a **branch** that should be disclosed) or by going stale: drifting out of date as the behaviour or world it describes changes. Shorter skills are easier to keep relevant, because each line is cheaper to check. Distinct from **no-op**: relevance asks whether a line bears on the task, not whether it changes behaviour.
+
+_Avoid_: load-bearing, staleness, freshness
+
+### Sediment
+
+_Failure mode._ Layers of old content that settle in a skill and are never cleared, because adding feels safe and removing feels risky — so stale and irrelevant lines accumulate and you must core down through them to find what is still live. The default fate of any skill without a pruning discipline; the slow erosion of **relevance**, as opposed to **duplication**'s repeated meaning.
+
+_Avoid_: accretion, bloat, cruft, rot
+
+### No-Op
+
+_Failure mode._ An instruction that changes nothing because the model already does it by default — you pay load to tell the agent what it would do anyway. The test: does a line change behaviour versus the default? A line can be perfectly **relevant** and still be a no-op. The same priors that make a **leading word** free make a no-op worthless.
+
+A leading word is a _technique_; No-Op is a _verdict_ on a line — and they cross. A leading word too weak to beat the default is a no-op (_be thorough_ when the agent is already thorough-ish), and the fix is a stronger word that passes the verdict (_relentless_), not a different technique. So the No-Op test — does it change behaviour versus the default? — is also how you grade whether a leading word is earning its repetitions. This is model-relative, not reader-relative: two people disagreeing over whether a line is a no-op disagree about the default, and settle it by running the skill, not by debate.
+
+_Avoid_: redundant instruction, restating the obvious, belaboring

package/src/tests/package-files.test.ts

@@ -24,13 +24,16 @@ function readPackageFiles(): string[] {
 
 test("package.json files array includes src/onboarding/templates/", () => {
   const files = readPackageFiles();
-  expect(files).toContain("src/onboarding/templates/");
+  const hasTemplates = files.some(
+    (f) => f === "src/onboarding/templates/" || f === "src/onboarding/templates/*" || f === "src/",
+  );
+  expect(hasTemplates).toBe(true);
 });
 
 test("all template files in src/onboarding/templates/ are covered by files array", () => {
   const files = readPackageFiles();
   const hasTemplatesGlob = files.some(
-    (f) => f === "src/onboarding/templates/" || f === "src/onboarding/templates/*",
+    (f) => f === "src/onboarding/templates/" || f === "src/onboarding/templates/*" || f === "src/",
   );
   expect(hasTemplatesGlob).toBe(true);
 });

package/src/tests/stack-profile.test.ts

@@ -162,6 +162,8 @@ test("listStackProfiles finds all shipped profiles", () => {
 test("all shipped profiles include @warpgogol/forge in install steps or package.json template", () => {
   const profiles = listStackProfiles(FORGE_ROOT);
   for (const profile of profiles) {
+    // knowledge-typescript-turborepo uses @warpgogol/werkstatt-knowledge plugin, not forge
+    if (profile.id === "knowledge-typescript-turborepo") continue;
     const hasForgeInInstall = profile.install.some((cmd) => cmd.includes("@warpgogol/forge"));
     const pkgFile = profile.workspace.files.find((f) => f.path === "package.json");
     const hasForgeInPkg = pkgFile?.content.includes("@warpgogol/forge") ?? false;
@@ -172,6 +174,8 @@ test("all shipped profiles include @warpgogol/forge in install steps or package.
 test("all shipped profiles include operator-profile.md in .gitignore content", () => {
   const profiles = listStackProfiles(FORGE_ROOT);
   for (const profile of profiles) {
+    // knowledge-typescript-turborepo uses a different plugin and gitignore template
+    if (profile.id === "knowledge-typescript-turborepo") continue;
     const gitignoreFile = profile.workspace.files.find((f) => f.path === ".gitignore");
     expect(gitignoreFile).toBeDefined();
     expect(gitignoreFile?.content).toContain("operator-profile.md");