@warpgogol/forge 2.9.2 → 2.9.5

package/skills/fo/fo-idea-create-rfc/SKILL.md

@@ -52,7 +52,7 @@ Ask the user for, or infer from context:
 - **liveSpec** — for feature-level RFCs (not governance/policy), suggest `liveSpec: true` to auto-derive a living spec domain from `packagesImpacted[0]`, or `liveSpec: <domain>` for an explicit domain. This enables automatic delta-merge into `docs/specs/live/<domain>.md` when the RFC is implemented.
 - **satisfies** — for `architecture` or `contract` RFCs, at least one `DNA-NN` invariant from `ref(forge.yaml bindings.paths.invariantsFile)`.
 - **related** — relevant RFCs, DNA ids, anti-patterns, specs.
-- **reviewer** — if the caller specifies a reviewer identity, use it. If not, default to `human:andrii-syrokomskyi` (matching the default in `os/rfc/rfc-0000-template.md` inside `@warpgogol/forge`) **only when the skill is also responsible for moving the RFC out of draft**. For a pure draft scaffold, leave `reviewers: []`.
+- **reviewer** — if the caller specifies a reviewer identity, use it. If not, read the default reviewer(s) from the `reviewers` field comment in `docs/rfcs/rfc-0000-template.md` **only when the skill is also responsible for moving the RFC out of draft**. For a pure draft scaffold, leave `reviewers: []`.
 
 ### 3. Grill the concept
 
@@ -78,7 +78,7 @@ ref(forge.yaml bindings.commands.validateRfc) --create --title="<title>" --kind=
 
 ### 5. Fill every section
 
-Read the generated file and the full template (`os/rfc/rfc-0000-template.md` inside `@warpgogol/forge`) as a guide. Replace placeholder text in every required section:
+Read the generated file and the full template (`docs/rfcs/rfc-0000-template.md`) as a guide. Replace placeholder text in every required section:
 
 - **Context** — the concrete situation, not a generic preamble.
 - **Problem** — the exact risk or gap this RFC closes.
@@ -129,7 +129,7 @@ Stage only the RFC file — do not stage unrelated changes. Another agent may be
 - Use the **full** RFC template for every RFC. Lightweight local decisions now use ADRs instead.
 - Do not change `status` past `draft`.
 - Do not add self-authorizing language such as "implementation may start before acceptance."
-- Do not default `reviewers` on drafts unless the skill is explicitly performing a status transition and the caller has not supplied a reviewer — in that case use `human:andrii-syrokomskyi`.
+- Do not default `reviewers` on drafts unless the skill is explicitly performing a status transition and the caller has not supplied a reviewer — in that case read the default reviewer(s) from the `reviewers` field comment in `docs/rfcs/rfc-0000-template.md`.
 - Keep `rfc.validate` clean before presenting the draft.
 - **Commit the RFC draft.** The RFC file must be committed after creation and validation — never left in the working tree.
 - **Never manually determine the RFC number.** Always use `rfc.create` (step 4) to assign the number. The RFC number space includes archived RFCs under `docs/rfcs/archive/` — a top-level-only scan of `docs/rfcs/` misses them and produces duplicate IDs. `rfc.create` scans the full tree recursively and picks the correct next number.

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

@@ -204,9 +204,9 @@ Integrate audit findings into RFC-XXXX (<title>). <count> direct fixes,
 
 Stage only the RFC files and audit files touched by this enhancement — do not stage unrelated changes.
 
-### 11. Stop
+### 11. Stop and suggest next step
 
-Do not run `/fo-idea-plan` — that is a separate skill for accepted RFCs. If the user asks to plan implementation, suggest running `/fo-idea-plan` after the RFC is accepted. If the user asks to implement, suggest running `/fo-idea-implement` — it requires a plan file and will stop if one is missing. The full pipeline is: create → audit → enhance → plan → implement.
+Follow the pipeline continuation protocol per `_shared/fo-pipeline-conventions.md` §Pipeline continuation — proactively suggest the next step (`fo-idea-plan`) and offer to proceed via `ask_user_question`. Do not automatically run the next skill — ask the operator first. The full pipeline is: create → audit → enhance → plan → implement.
 
 ## Constraints
 

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`. 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
+   ref(forge.yaml bindings.commands.validateAdr)
+   ```
+
+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-implement/SKILL.md

@@ -308,7 +308,7 @@ 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.
+3. If `reviewers` is empty, read the default reviewer(s) from the `reviewers` field comment in `docs/adrs/adr-0000-template.md`. Set all listed default reviewers.
 4. Commit:
 
    ```txt

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

@@ -60,7 +60,7 @@ If all checks pass, proceed to step 0.3.
 If the RFC is `draft` or `reviewing` and has `enhancedAt` — the user's instruction to plan IS the architecture acceptance. Transition the RFC to `accepted`:
 
 1. Set `status: accepted`.
-2. Set `reviewers` — if the operator specified a reviewer at invocation, use that. Otherwise, read the default reviewer(s) from the `reviewers` field comment in `os/rfc/rfc-0000-template.md` inside `@warpgogol/forge` (currently `human:andrii-syrokomskyi`). Set all listed default reviewers.
+2. Set `reviewers` — if the operator specified a reviewer at invocation, use that. Otherwise, read the default reviewer(s) from the `reviewers` field comment in `docs/rfcs/rfc-0000-template.md`. Set all listed default reviewers.
 3. Set `updatedAt` to today's date.
 4. Commit:
 
@@ -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.
@@ -243,5 +245,5 @@ When an RFC was planned in this session, prefer implementing it in this session
 - The plan MUST NOT propose changing DNA invariants without a new superseding RFC.
 - The plan MUST respect RFC-XXXX: only `accepted → implemented` is agent-permitted; all other status transitions are human-only. The `draft → accepted` transition in step 0.3 is an exception authorized by the user's explicit instruction to plan the RFC.
 - The plan MUST reference the RFC's acceptance criteria as the source of truth for completion.
-- **Default reviewer source.** When transitioning `draft → accepted` and the operator has not specified a reviewer, read the default reviewer(s) from the `reviewers` field comment in `os/rfc/rfc-0000-template.md` inside `@warpgogol/forge` (currently `human:andrii-syrokomskyi`). Set all listed default reviewers.
+- **Default reviewer source.** When transitioning `draft → accepted` and the operator has not specified a reviewer, read the default reviewer(s) from the `reviewers` field comment in `docs/rfcs/rfc-0000-template.md`. Set all listed default reviewers.
 - **No pauses for recoverable tool errors.** If a tool call fails with a recoverable error — e.g. `write_to_file` content too long, JSON truncation, line count/character limit exceeded, or similar — do not stop and ask the user. Recover autonomously: split the content into smaller writes, use `edit`/`multi_edit`, decompose oversized files, and retry immediately. The operator's default answer to "Shall I proceed?" is always "yes".

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/fo/fo-step-commit/SKILL.md

@@ -34,8 +34,8 @@ After every standalone operator request that produces file changes, perform the
 2. **Verify diff before staging.** Run `git diff` (not just `git diff --cached`) on every file the agent touched in this request, in each dirty tree. Confirm the changes are the agent's own work and not foreign changes from another session. If foreign changes are found, exclude them from staging.
 3. **Stage only agent-changed files.** Stage only the files the agent modified in this request. Never use `git add -A` or `git add .` — another agent or session may have unrelated changes in the working tree. Stage files by explicit path: `git add <path1> <path2> ...`.
 4. **Form commit message.** Write a conventional commit message (`fix:`, `feat:`, `refactor:`, `docs:`, `chore:`) based on the work performed in this request. The agent determines the type and description from the context of the request.
-5. **Commit in monorepo.** Use `pnpm exec werkstatt run ecosystem.commit --message="<message>"` (NOT raw `git commit`) as required by the canonical commit-discipline contract. Stage files with `git add <paths>` first, then run ecosystem.commit.
-6. **Commit in mission workpiece (if applicable).** If the agent changed files in the active mission workpiece, commit there via `pnpm exec werkstatt run mission.git.commit --mission=<missionId> --message="<message>"` as required by the canonical commit-discipline contract.
+5. **Commit in monorepo.** Use `pnpm exec werkstatt run ecosystem.commit --message "<message>"` to commit in the werkstatt monorepo. This handles platform-scope version bumps and X-Platform-Bump trailers automatically. Stage files with `git add <paths>` first (the pre-commit hook blocks raw `git commit` for platform-scope files). For non-platform-only changes (docs/**), `ecosystem.commit` delegates to a plain `git commit` without version bump.
+6. **Commit in mission workpiece (if applicable).** If the agent changed files in the active mission workpiece, commit there via `git commit` in the workpiece directory.
 7. **Verify clean trees.** After all commits, run `bash scripts/check-clean-trees.sh` again. If any tree is still dirty, report to the operator.
 
 ## What this skill does NOT do

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"
+```