@warpgogol/forge 0.3.1

package/skills/shared/grilling/qa-log.md

@@ -0,0 +1,10 @@
+# Q&A Log (L0)
+
+Append-only log of questions asked and answers given during grilling sessions. Used for meta-analysis to distill recurring decision patterns.
+
+<!-- Entries are appended by the skill during each run. -->
+<!-- Format:
+## <date> — <context>
+- **Question:** <short question summary>
+- **Answer:** <operator's decision>
+-->

package/skills/shared/my-preferences/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: my-preferences
+description: Read, create, or edit the operator's preferences file at the repository root. Run when the operator wants to change language settings for AI conversations, grilling, or project documentation.
+invocation: user
+category: shared
+concerns: document-only
+dependsOn: []
+languagePolicy: ref(PREFERENCES.md)
+---
+
+# my-preferences
+
+Before starting, read `PREFERENCES.md` at the repository root. If the file is missing, create it using the semantics below.
+
+Manage the operator's personal settings for AI interaction in this repository. The settings live in `PREFERENCES.md` at the repo root (Markdown with YAML frontmatter).
+
+## Supported preferences
+
+- `aiLanguage` — language the AI uses for **all** communication with the operator in this session: questions, responses, summaries, reports, status updates, and any other chat output.
+- `documentationLanguage` — default language for newly generated RFCs, ADRs, READMEs, and other project documentation.
+
+Language values are free-form strings such as `en`, `ru`, `uk`, `de`, `es`. Prefer IETF BCP 47 language tags when the operator provides them.
+
+## Process
+
+### 1. Read the current preferences
+
+Look for `PREFERENCES.md` at the repository root.
+
+- If it exists, read the frontmatter and display the current values.
+- If it does not exist, proceed to step 2 (create).
+
+### 2. Ask what to change
+
+If the file exists:
+
+> "Current preferences: aiLanguage = <value>, documentationLanguage = <value>. What would you like to change?"
+
+Let the operator pick one or more keys, or choose "create new preference file from template".
+
+If the file does not exist, ask for the two values one at a time. Use sensible defaults based on the language the operator is already using in the conversation.
+
+For each value, ask:
+
+> "In which language should the AI <respond to you / write project documentation>?"
+
+Accept free-form answers like "Russian", "русский", "uk" or "English".
+
+### 3. Write the file
+
+Use `PREFERENCES.md.template` at the repo root as the baseline if creating the file for the first time. Replace the placeholder values with the operator's answers. Update `updatedAt` to today's date. Preserve any existing body text when only updating values.
+
+### 4. Confirm
+
+Show the operator the final frontmatter and ask if anything else should change. If not, report success and remind them that other interactive skills will read this file at the start of the next session.
+
+### 5. Commit
+
+Commit the preferences file. This is **mandatory** — `PREFERENCES.md` must be committed, not left in the working tree.
+
+Commit message format:
+
+```txt
+prefs: update operator preferences
+
+<one-line description of what changed in PREFERENCES.md>.
+```
+
+Stage only `PREFERENCES.md` — do not stage unrelated changes. Another agent may be working in a different session; `git add -A` or `git add .` is forbidden.
+
+## Constraints
+
+- Do not store secrets, API keys, or environment-specific values in `PREFERENCES.md`.
+- Do not delete `PREFERENCES.md` unless the operator explicitly asks.
+- Do not change a preference without confirmation.
+- Do not add new preference keys beyond the two defined here unless the operator asks and a matching RFC/ADR exists.
+- **Commit only your own files.** Stage only `PREFERENCES.md`. Do not stage unrelated changes. Another agent may be working in a different session; `git add -A` or `git add .` is forbidden.

package/skills/shared/windows-ai-tooling/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: windows-ai-tooling
+description: Bootstrap a Windows project for AI agents. Installs verified tools, generates .gitattributes, and emits a command allow-list for agent prompts. Run when starting a new project or when agents fail.
+invocation: user
+category: shared
+concerns: document-only
+dependsOn: []
+languagePolicy: ref(PREFERENCES.md)
+---
+
+# Windows AI Tooling
+
+Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
+
+Prepare any Windows project so AI agents can work in it reliably. This skill does not assume a Turborepo, TypeScript, or even an existing `AGENTS.md`; it works for any repo that will be edited by AI agents on Windows 10/11.
+
+It produces three artifacts:
+
+1. **Installed tooling baseline** — verified via `winget` and WSL2 where needed.
+2. **A project `.gitattributes`** — prevents line-ending drift and marks binary files.
+3. **A machine-specific agent prompt snippet** — lists exactly which commands the agent may use.
+
+This is a prompt-driven, interactive skill. Explore the current environment, walk the operator through the decisions one at a time, confirm, then write the files.
+
+## Process
+
+### 1. Read or create operator preferences
+
+Before asking anything, check `PREFERENCES.md` at the repository root.
+
+- If it exists, read the frontmatter and use `aiLanguage` for all subsequent questions and responses in this skill session.
+- If it does not exist, ask the operator once:
+
+> "In which language should I ask questions and report results during this session? (e.g., en, ru, uk, de)"
+
+Create `PREFERENCES.md` from `PREFERENCES.md.template` with the operator's answer, plus a reasonable default for `documentationLanguage` (e.g., `en` unless the operator says otherwise). Use the `my-preferences` skill semantics if the operator wants to adjust more than one value.
+
+All further communication with the operator in this skill session must be in the chosen `aiLanguage`.
+
+### 2. Explore the current environment
+
+Before asking about installations, gather the facts. Run the commands below (or their equivalents) and report the results to the operator as a short summary.
+
+- `Get-Command git, node, npm, python, jq, curl, docker, wsl, bash -ErrorAction SilentlyContinue | Select-Object Name, Source, Version`
+- `wsl --status` (or `wsl -l -v`)
+- `winget --version`
+- `git config --global core.autocrlf` and `git config --global core.eol`
+- Check whether the project already has `.gitattributes` and `AGENTS.md` / `CLAUDE.md` at the repo root.
+
+Summarize what is present and what is missing. Do not install anything yet.
+
+### 3. Ask the operator for each step (auto-first)
+
+For every section below, follow the same pattern:
+
+1. Briefly explain what the step does and why it matters.
+2. Propose the automatic action with the exact command(s).
+3. Ask: **"Выполнить этот шаг автоматически? (Y — да / m — дать команды для ручного запуска / s — пропустить)"**. Default: **Y**.
+4. If the operator answers `m`, print the exact commands and wait for them to run them manually before continuing. If `s`, skip the step and adjust the generated snippets accordingly.
+
+Do not dump all questions at once. Walk through A → B → C → D one at a time, waiting for an answer before the next section.
+
+#### Section A — Native Windows tools
+
+Explainer: PowerShell-native tools (`git`, `node`, `python`, `jq`, `curl`, `docker`) cover the most common agent needs. They install via verified `winget` IDs.
+
+Automatic command block:
+
+```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
+```
+
+Notes:
+
+- `Git.Git` also installs Git Bash (`bash`, `grep`, `sed`, `awk`, `find`, `tar`, `ls`, `xargs`).
+- Docker enables WSL2 integration; skip it if the operator does not want containers.
+
+Ask: **"Выполнить установку недостающих native-инструментов автоматически? (Y/m/s)"**. Default **Y**.
+
+#### Section B — WSL2 Ubuntu bridge
+
+Explainer: Linux-only tools run in WSL2 Ubuntu. This is optional — if skipped, the agent prompt must forbid `wsl`.
+
+Automatic command:
+
+```powershell
+wsl --install -d Ubuntu
+```
+
+After the reboot, inside Ubuntu:
+
+```bash
+sudo apt update && sudo apt install -y build-essential git curl wget jq python3 python3-pip nodejs npm
+```
+
+Note: requires a reboot.
+
+Ask: **"Установить WSL2 Ubuntu автоматически? (Y/m/s)"**. Default **Y**.
+
+#### Section C — `.gitattributes`
+
+Explainer: Forces LF line endings and marks binary files, preventing CRLF drift in cross-platform repos.
+
+Automatic action: generate or overwrite `.gitattributes` from `.gitattributes.template`.
+
+Ask: **"Сгенерировать .gitattributes автоматически? (Y/m/s)"**. Default **Y** if missing; ask before overwrite if it already exists.
+
+Use the template in this skill folder as the baseline. Adjust it to the project's actual file extensions (e.g., `.go`, `.rs`, `.java`, `.cs`, `.php`). Do not remove the `* text=auto eol=lf` line or the binary file rules.
+
+#### Section D — AGENTS/CLAUDE integration
+
+Explainer: Adds the Windows tooling section to the existing agent doc or creates a minimal `AGENTS.md`.
+
+Automatic action: edit existing `AGENTS.md`/`CLAUDE.md` or create minimal `AGENTS.md` from `AGENTS_WINDOWS.md.template`.
+
+Ask:
+
+1. Which agent-doc file should be edited? (`AGENTS.md` or `CLAUDE.md`)? If neither exists, create `AGENTS.md`.
+2. **"Обновить agent-документ автоматически? (Y/m/s)"**. Default **Y**.
+
+### 4. Generate the agent prompt snippet
+
+After the operator has chosen auto/manual/skip for every section, produce a machine-specific snippet that the operator can paste into their agent's system prompt. The snippet must list exactly which commands are available and which are forbidden, based on the exploration in step 2 and the operator's choices.
+
+Example snippet (adjust to actual machine state):
+
+```markdown
+## Windows environment
+
+This project is developed on Windows 10/11. Use the following command rules:
+
+- **Native Windows tools (PowerShell):** `git`, `node`, `npm`, `pnpm`, `python`, `pip`, `jq`, `curl`, `docker`, `wsl`.
+- **Git Bash POSIX coreutils:** `bash`, `grep`, `sed`, `awk`, `find`, `tar`, `ls`, `xargs`. Use through `bash -c "..."`. Paths remain Windows-style.
+- **WSL2 Ubuntu bridge:** for any GNU tool not listed above, use `wsl <command>` or `wsl bash -c "..."`. Convert Windows paths with `wslpath` first.
+- **Not available:** do not call `grep`, `find`, `sed`, `awk`, `jq`, `curl` directly in PowerShell unless they were installed natively and verified.
+- **Path rule:** when passing `C:\...` paths to WSL commands, wrap them with `wslpath`:
+  `wsl bash -c "cat $(wslpath 'C:\Users\user\file.txt')"`.
+
+Installation fallback (verified winget IDs):
+- `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`
+```
+
+If the operator chose not to install WSL, remove the WSL lines and add: `wsl` is not available on this machine — stop and ask the operator before installing it.
+
+### 5. Execute the approved steps
+
+Run only the steps the operator marked as `Y` (automatic). For steps marked `m`, print the exact commands and wait for the operator to run them manually before continuing. For steps marked `s`, skip them and adjust the generated artifacts accordingly.
+
+Order of execution:
+
+1. **Native tools** — run approved `winget install` commands. Show progress; use `--silent` only if the operator explicitly asked for it.
+2. **WSL2** — run `wsl --install -d Ubuntu` if approved. Remind the operator that a reboot is required and do not run Ubuntu commands until after the reboot.
+3. **`.gitattributes`** — write from `.gitattributes.template` if approved.
+4. **Agent doc** — write or edit `AGENTS.md` / `CLAUDE.md` from `AGENTS_WINDOWS.md.template` if approved.
+5. **Re-explore** — re-run the exploration commands from step 1 and update the agent prompt snippet with the actual installed paths and versions.
+6. **CRLF recovery** — run `git add --renormalize .` only if explicitly requested; otherwise mention it as a manual recovery step.
+
+### 6. Commit
+
+Commit the artifacts produced by this skill. This is **mandatory** — all files created or modified by this skill must be committed, not left in the working tree.
+
+Commit message format:
+
+```txt
+tooling: bootstrap Windows AI tooling artifacts
+
+<one-line description of which artifacts were created or updated>.
+```
+
+Stage only the files this skill produced or modified (`.gitattributes`, `AGENTS.md` / `CLAUDE.md`, `PREFERENCES.md`) — do not stage unrelated changes. Another agent may be working in a different session; `git add -A` or `git add .` is forbidden.
+
+### 7. Done
+
+Report:
+
+- Which tools are now installed and which are still pending (e.g., WSL waiting for reboot).
+- The exact path of `.gitattributes` and the agent-doc file.
+- A copyable block with the agent prompt snippet.
+- A reminder that re-running this skill is useful when adding a new tool or onboarding a new machine.
+
+## Constraints
+
+- Default to automatic execution (`Y`) for every step. Offer `m` (manual) and `s` (skip) only as explicit opt-outs.
+- Do not run any step automatically if the operator chose `m` or `s` for that step.
+- Do not overwrite an existing `.gitattributes` without explicit confirmation, even in automatic mode.
+- Do not create `AGENTS.md` when `CLAUDE.md` already exists unless the operator explicitly chose to.
+- Do not assume the project is TypeScript, Turborepo, or Astro. This skill is generic; add project-specific rules only when the operator asks.
+- Keep the verified winget IDs as the single source of truth. Do not invent package IDs; if an ID changes, update this skill and notify the operator.
+- **Commit only your own files.** Stage only the files this skill produces or modifies — `.gitattributes`, `AGENTS.md` / `CLAUDE.md`, `PREFERENCES.md`. Do not stage unrelated changes. Another agent may be working in a different session; `git add -A` or `git add .` is forbidden.

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

@@ -0,0 +1,132 @@
+---
+name: writing-great-skills
+description: Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable.
+invocation: user
+category: shared
+concerns: read-only
+dependsOn: []
+languagePolicy: ref(PREFERENCES.md)
+---
+
+Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
+
+A skill exists to wrangle determinism out of a stochastic system. **Predictability** — the agent taking the same _process_ every run, not producing the same output — is the root virtue; every lever below serves it.
+
+**Bold terms** are defined in [`GLOSSARY.md`](GLOSSARY.md); look them up there for the full meaning.
+
+## Invocation
+
+Two choices, trading different costs:
+
+- A **model-invoked** skill keeps a **description**, so the agent can fire it autonomously _and_ other skills can reach it (you can still type its name too). It contributes to **context load** — the description sits in the window every turn. Mechanics: omit `disable-model-invocation`, and write a model-facing description with rich trigger phrasing ("Use when the user wants…, mentions…").
+- A **user-invoked** skill strips the description from the agent's reach: only you, typing its name, can invoke it — and no other skill can. Zero context load, but it spends **cognitive load**: _you_ are the index that must remember it exists. Mechanics: set `disable-model-invocation: true`; the `description` becomes human-facing — a one-line summary, trigger lists stripped.
+
+Pick model-invocation only when the agent must reach the skill on its own, or another skill must. If it only ever fires by hand, make it user-invoked and pay no context load.
+
+When user-invoked skills multiply past what you can remember, that piled-up cognitive load is cured by a **router skill**: one user-invoked skill that names the others and when to reach for each.
+
+## Writing the description
+
+A model-invoked **description** does two jobs — state what the skill is, and list the **branches** that should trigger it. Every word increases **context load**, so a description earns even harder pruning than the body:
+
+- **Front-load the skill's leading word** — the description is where it does its invocation work.
+- **One trigger per branch.** Synonyms that rename a single branch are **duplication** — "build features using TDD … asks for test-first development" is one branch written twice. Collapse them; keep only genuinely distinct branches.
+- **Cut identity that's already in the body.** Keep the description to triggers, plus any "when another skill needs…" reach clause.
+
+## Information hierarchy
+
+A skill is built from two content types — **steps** and **reference** — that mix freely: a skill can be all steps, all reference, or both. The core decision is which to use and where each sits on the **information hierarchy**, a ladder ranked by how immediately the agent needs the material:
+
+1. **In-skill step** — an ordered action in `SKILL.md`, the primary tier: what the agent does, in order. Each step ends on a **completion criterion**, the condition that tells the agent the work is done. Make it _checkable_ (can the agent tell done from not-done?) and, where it matters, _exhaustive_ ("every modified model accounted for", not "produce a change list") — a vague criterion invites **premature completion**.
+2. **In-skill reference** — a definition, rule, or fact in `SKILL.md`, consulted on demand. Often a legitimately flat peer-set (every rule of a review on one rung) — a fine arrangement, not a smell. _This skill is all reference._
+3. **External reference** — reference pushed out of `SKILL.md` into a separate file, reached by a **context pointer**, loaded only when the pointer fires. (Spans _disclosed_ reference — a sibling file like `GLOSSARY.md`, still part of the skill — through fully **external reference** that lives outside the skill system and any skill can point at.)
+
+A demanding completion criterion drives thorough **legwork** — the digging the agent does within the work — whether the skill has steps or not, since "every rule applied" binds flat reference just as "every step done" binds a sequence.
+
+Push too little down and the top bloats; push too much and you hide material the agent actually needs. That tension is the whole decision.
+
+**Progressive disclosure** is the move down the ladder — out of `SKILL.md` into a linked file — so the top stays legible. Mechanics: a linked `.md` file in the skill folder, named for what it holds (this skill discloses its full definitions to `GLOSSARY.md`). Some skills are used in more than one way, and each distinct way is a **branch** — different runs taking different paths through the skill. Branching is the cleanest disclosure test: inline what every branch needs, and push behind a pointer what only some branches reach. A **context pointer**'s _wording_, not its target, decides when and how reliably the agent reaches the material.
+
+Where the ladder decides _how far down_ a piece sits, **co-location** decides _what sits beside it_ once there: keep a concept's definition, rules, and caveats under one heading rather than scattered, so reading one part brings its neighbours with it.
+
+## When to split
+
+**Granularity** is how finely you divide skills, and each cut spends one of the two loads, so split only when the cut earns it. Two cuts:
+
+- **By invocation** — split off a **model-invoked** skill when you have a distinct **leading word** that should trigger it on its own, or another skill must reach it. You pay **context load** for the new always-loaded **description**, so that independent reach has to be worth it.
+- **By sequence** — split a run of **steps** when the steps still ahead (a step's **post-completion steps**) tempt the agent to rush the one in front of it (**premature completion**). Keeping them out of view encourages the agent to do more **legwork** on the current task.
+
+## Pruning
+
+Keep each meaning in a **single source of truth**: one authoritative place, so changing the behaviour is a one-place edit.
+
+Check every line for **relevance**: does it still bear on what the skill does?
+
+Then hunt **no-ops** sentence by sentence, not just line by line: run the no-op test on each sentence in isolation, and when one fails, delete the whole sentence rather than trim words from it. Be aggressive — most prose that fails should go, not be rewritten.
+
+## Leading words
+
+A **leading word** is a compact concept already living in the model's pretraining that the agent thinks with while running the skill (e.g. _lesson_, _fog of war_, _tracer bullets_). Repeated throughout the text (though not necessarily - a strong leading word might only be needed once), it accumulates a distributed definition and anchors a whole region of behaviour in the fewest tokens, by recruiting priors the model already holds.
+
+It serves predictability twice. In the body it anchors _execution_: the agent reaches for the same behaviour every time the word appears. In the description it anchors _invocation_: when the same word lives in your prompts, docs, and code, the agent links that shared language to the skill and fires it more reliably.
+
+Hunt for opportunities to refactor skills to use leading words. A triad spelled out at three sites (**duplication**), a description spending a sentence to gesture at one idea — each is a passage begging to **collapse** into a single token. Examples include:
+
+- "fast, deterministic, low-overhead" -> _tight_ — one quality restated across a phase — into a single pretrained word (a _tight_ loop).
+- "a loop you believe in" -> _red_ — converts a fuzzy gate into a binary observable state (the loop goes _red_ on the bug, or it doesn't).
+
+You win twice over: fewer tokens, _and_ a sharper hook for the agent to hang its thinking on. Assume every skill is carrying restatements that leading words retire — go find them.
+
+## Failure modes
+
+Use these to diagnose issues the user may be having with the skill.
+
+- **Premature completion** — ending a step before it's genuinely done, attention slipping to _being done_. Defence, in order: sharpen the completion criterion first (cheap, local); only if it is irreducibly fuzzy _and_ you observe the rush, hide the post-completion steps by splitting (the sequence cut).
+- **Duplication** — the same meaning in more than one place. Costs maintenance and tokens, and inflates a meaning's prominence on the ladder past its real rank.
+- **Sediment** — stale layers that settle because adding feels safe and removing feels risky. The default fate of any skill without a pruning discipline.
+- **Sprawl** — a skill simply too long, even when every line is live and unique. Hurts readability and maintainability and wastes tokens. The cure is the ladder: disclose **reference** behind pointers, and split by **branch** or sequence so each path carries only what it needs.
+- **No-op** — a line the model already obeys by default, so you pay load to say nothing. The test: does it change behaviour versus the default? A weak leading word (_be thorough_ when the agent is already thorough-ish) is a no-op; the fix is a stronger word (_relentless_), not a different technique.
+- **Negation** — steering by prohibition backfires: _don't think of an elephant_ names the elephant and makes it more available, not less. Prompt the **positive** — state the target behaviour so the banned one is never spoken; keep a prohibition only as a hard guardrail you can't phrase positively, and even then pair it with what to do instead.
+
+## Cumulative knowledge pattern
+
+Skills that run repeatedly accumulate knowledge across sessions. The cumulative knowledge convention provides an opt-in three-layer reference pattern for this.
+
+### Knowledge frontmatter
+
+A skill declares its knowledge files by adding a `knowledge:` array to SKILL.md frontmatter, listing file names relative to the SKILL.md directory:
+
+```yaml
+knowledge:
+  - qa-log.md
+  - learned-principles.md
+```
+
+`forge.skill.validate` enforces SKILL-13: declared knowledge files must exist. `forge.create` syncs them to `.agents/skills/`. `forge.doctor` detects stale copies.
+
+### Three-layer reference pattern
+
+Skills adopt 0, 1, 2, or 3 layers as needed — the pattern is adaptive, not mandatory.
+
+| Layer | File name | Role |
+| --- | --- | --- |
+| L0 | `qa-log.md` | Append-only log of questions asked and answers given during runs |
+| L1 | `fix-patterns.md` | Baseline fix patterns for recurring violations |
+| L2 | `learned-principles.md` | Concrete principles distilled from past runs, with `confirmations: N` counter |
+
+Not every skill needs all three. `grilling` uses L0 and L2 only (no fix patterns). A site-scanning skill may use all three.
+
+### Confidence progression
+
+L2 entries carry a `confirmations: N` counter. When confirmations reach threshold 3, the skill may apply the principle autonomously without asking the operator. Rejecting a recommended answer resets confirmations to 0. Autonomous application is context-dependent — the skill should re-evaluate if context changes.
+
+### Mutation contract
+
+- **Source-of-truth**: `packages/forge/skills/<category>/<name>/`. Skills mutate knowledge files here during runs and commit to main repo. Skills always read from source.
+- **Runtime copy**: `.agents/skills/<name>/`. Synced by `forge.create`. Read-only — skills never write here. The `.agents/` copy exists for consumers who install `@warpgogol/forge` as an npm package.
+- **Sync**: one-way (source → `.agents/`), never the reverse.
+- **Stale detection**: `forge.doctor` compares source and `.agents/` copies, reports drift as warnings.
+
+### npm portability
+
+`@warpgogol/forge` is published to npm with `skills/` in the `files` array. Knowledge files ship as empty templates (header comments only). Forge's accumulated Q&A and learned principles are project-specific and should not leak to npm consumers. Each project accumulates its own knowledge locally after running `forge.create`.