@warpgogol/forge 0.8.0 → 0.10.0

package/skills/_shared/fo-pipeline-conventions.md

@@ -117,3 +117,68 @@ After completing implementation work, the operator may run a three-step session-
 3. **`fo-handoff`** — what does the next agent need? (continuity document)
 
 Most sessions need only `fo-doc-audit`. `fo-session-retro` is valuable after debugging sessions, exploratory work, or when non-obvious behaviors were discovered. `fo-handoff` is needed when work is incomplete and another agent will continue.
+
+## Context checkpoint between batch items
+
+When the orchestrator skill processes multiple documents (>=2), perform a context checkpoint after completing one document and before starting the next:
+
+1. **Emit checkpoint block** — output a YAML-formatted block in conversation output with the following fields:
+   - `completed`: RFC/ADR id of the completed document
+   - `status`: final status (implemented, accepted, draft, failed)
+   - `commits`: list of commit SHAs produced for this document
+   - `lessons`: 1-3 short freeform sentences capturing key errors, root causes, patterns discovered, or validator quirks encountered during this document's pipeline run
+   - `dependencies`: cross-RFC dependency notes (e.g., "RFC-YYYY depends on RFC-XXXX for schema field Z") — empty if none
+   - `next`: id of the next document to process, or `null` if this was the last
+2. **Release context** — explicitly treat all detailed context from the completed document as no longer actionable: file contents, search results, edit operations, intermediate reasoning. Retain only the checkpoint block. Release means treat as no longer actionable for reasoning, not delete or undo.
+3. **Fresh start** — begin the next document with a fresh read phase: re-read the RFC file and all related documents (amends, supersedes, related RFCs, DNA invariants, AGENTS.md sections).
+
+The checkpoint block doubles as a resume marker: when resuming an interrupted batch, scan conversation output for the last checkpoint block, extract completed ids and statuses, and continue with the next uncompleted item. If no checkpoint markers are found, fall back to the existing resume logic (git log, file inspection, frontmatter status).
+
+**Only applies to batch processing (>=2 documents).** Single-document invocations do not need a checkpoint — the context is already fresh at the start.
+
+## Step-level context checkpoint during implementation
+
+When the orchestrator skill implements a single RFC with >=5 plan steps, perform a step checkpoint after completing each plan step and committing:
+
+1. **Emit step-checkpoint block** — output a YAML-formatted block in conversation output with the following fields:
+   - `rfc`: RFC id being implemented
+   - `step`: plan step number (e.g., 3)
+   - `title`: plan step title
+   - `commit`: SHA of the commit produced by this step
+   - `decisions`: 1-3 short freeform sentences capturing key micro-decisions made during this step (e.g., "used flag instead of new command", "skipped validator X because it's in package Y, not in scope")
+   - `errors`: list of errors encountered and fixed during this step — empty if none
+   - `nextStep`: number of the next plan step, or `null` if this was the last
+2. **Release step context** — treat all detailed context from the completed step as no longer actionable: codebase search results, file reads, edit operations, validation output. Retain only the step-checkpoint block and the RFC's plan file.
+3. **Fresh start** — begin the next plan step with a fresh read of the plan file and the specific files the next step touches.
+
+The step checkpoint doubles as a resume marker: when resuming an interrupted implementation, scan conversation output for the last step-checkpoint block, extract the completed step number, and resume from the next step.
+
+**Only applies to plans with >=5 steps.** Small plans (4 or fewer steps) do not need step checkpoints — the context is manageable without them.
+
+## Progress beacon
+
+The orchestrator skill emits a one-line progress beacon after completing each pipeline step (audit, enhance, plan, implement, review, fix) for each RFC. The beacon is informational only — it does not pause the pipeline, does not request operator input, and does not release context.
+
+Format: `[beacon] RFC-XXXX | <step> ✓ | next: <next-step>`
+
+For failed steps being fixed: `[beacon] RFC-XXXX | <step> ✗ (fixing...) | next: <next-step>`
+
+The beacon text must use `aiLanguage` per the language policy.
+
+## Error checkpoint for pipeline step failures
+
+When a pipeline step fails and cannot be auto-fixed within 2 attempts (per §Command execution timeout discipline), emit a structured error checkpoint block in conversation output:
+
+1. **Emit error checkpoint** — output a YAML block with: rfc, step, planStep (if within implement phase), error (command, exitCode, summary, attempts), partialState (filesModified, commits, rfcStatus), resumePoint.
+2. **Stop the pipeline** — do not continue to the next pipeline step. The error is not auto-fixable; continuing would compound the problem. This is an **explicit exception** to the orchestrator's "no pauses between pipeline steps" constraint. The "no pauses" directive assumes the pipeline can proceed; when an error is unfixable after 2 attempts, continuing is impossible and the exception is justified. The pause is for error reporting, not for optional operator input.
+3. **Report to operator** — present the error checkpoint in `aiLanguage` and ask the operator how to proceed: fix manually, skip the step, or abort the RFC.
+
+The error checkpoint doubles as a resume marker: when resuming an interrupted session, scan for the last error checkpoint. If found, resume from the failed step using the partialState and resumePoint fields.
+
+## Batch plan preview
+
+When the orchestrator skill processes multiple documents (>=2), emit a batch plan preview before starting the first document. The preview is a table showing: processing order, document id, type, complexity estimate, dependencies, and notes.
+
+The preview is informational — it does not pause for operator approval unless the operator explicitly requests confirmation. The operator's invocation of the orchestrator is the instruction to proceed.
+
+The preview text must use `aiLanguage` per the language policy.

package/skills/fo/fo-add-tests/SKILL.md

@@ -83,8 +83,10 @@ Mock at **system boundaries** only — external APIs, databases, time, randomnes
 
 For the target package:
 
+> Commands below assume RTK is installed. To check, run `rtk --version` (this is the detection command — it is not prefixed with `rtk` because it IS an `rtk` command). If `rtk --version` fails, RTK is not installed — run all commands without the `rtk` prefix.
+
 ```sh
-pnpm --filter <package-name> test
+rtk pnpm --filter <package-name> test
 ```
 
 If the tests fail (red):

package/skills/fo/fo-doc-audit/SKILL.md

@@ -124,6 +124,8 @@ If yes, update the **template** files in `packages/os/site-kernel-onboarding/src
 
 If yes, **do not edit the generated file directly**. Update the source registry or generator, then run the regeneration command:
 
+> Commands below assume RTK is installed. To check, run `rtk --version` (this is the detection command — it is not prefixed with `rtk` because it IS an `rtk` command). If `rtk --version` fails, RTK is not installed — run all commands without the `rtk` prefix.
+
 ```sh
 ref(forge.yaml bindings.commands.produce) --workspace=ecosystem.manifest.generate
 ref(forge.yaml bindings.commands.produce) --workspace=command.manifest.generate

package/skills/fo/fo-fix/SKILL.md

@@ -95,7 +95,9 @@ Otherwise, determine which workspaces were touched by the fixes in step 2 and ru
 
 - **For each touched `apps/*` workspace:**
 
-  ```sh
+  > Commands below assume RTK is installed. To check, run `rtk --version` (this is the detection command — it is not prefixed with `rtk` because it IS an `rtk` command). If `rtk --version` fails, RTK is not installed — run all commands without the `rtk` prefix.
+
+```sh
   pnpm --filter <app-name> exec astro check
   ```
 
@@ -121,8 +123,8 @@ All scoped checks must pass. If any fails:
 Stage and commit the changes with a descriptive message.
 
 ```text
-git add ...
-git commit -m "fix(scope): ..."
+rtk git add ...
+rtk git commit -m "fix(scope): ..."
 ```
 
 Do not commit secrets, API keys, or unrelated changes.

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

@@ -53,6 +53,8 @@ Read the full RFC file at `docs/rfcs/rfc-XXXX-*.md` for the first RFC to process
 
 Run the mechanical floor first — it catches format, referential, and structural violations that don't need semantic judgment:
 
+> Commands below assume RTK is installed. To check, run `rtk --version` (this is the detection command — it is not prefixed with `rtk` because it IS an `rtk` command). If `rtk --version` fails, RTK is not installed — run all commands without the `rtk` prefix.
+
 ```sh
 ref(forge.yaml bindings.commands.validateRfc) --json
 ```

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

@@ -76,6 +76,8 @@ Address every concern the grilling raises by adjusting the metadata, scope, or c
 
 Run:
 
+> Commands below assume RTK is installed. To check, run `rtk --version` (this is the detection command — it is not prefixed with `rtk` because it IS an `rtk` command). If `rtk --version` fails, RTK is not installed — run all commands without the `rtk` prefix.
+
 ```sh
 ref(forge.yaml bindings.commands.validateAdr) --create --title="<title>" --scope=<scope> --related=<related-ids>
 ```

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

@@ -31,6 +31,8 @@ Create a complete, `rfc.validate`-ready RFC draft in `docs/rfcs/` using the full
 
 Confirm that the proposed change is not already covered by an accepted/implemented RFC. Before drafting, run:
 
+> Commands below assume RTK is installed. To check, run `rtk --version` (this is the detection command — it is not prefixed with `rtk` because it IS an `rtk` command). If `rtk --version` fails, RTK is not installed — run all commands without the `rtk` prefix.
+
 ```sh
 ref(forge.yaml bindings.commands.validateRfc) --status accepted --json
 ```

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

@@ -67,7 +67,9 @@ Read the RFC's `status` frontmatter:
 - **`draft`** — proceed with enhancement.
 - **`reviewing`** — transition to `draft` before enhancement. Set `status: draft`, update `updatedAt` to today's date, commit:
 
-  ```txt
+  > Commands below assume RTK is installed. To check, run `rtk --version` (this is the detection command — it is not prefixed with `rtk` because it IS an `rtk` command). If `rtk --version` fails, RTK is not installed — run all commands without the `rtk` prefix.
+
+```txt
   rfc: revert RFC-XXXX to draft for enhancement
 
   Transition RFC-XXXX from reviewing to draft before enhance.

package/skills/fo/fo-idea-i-just-want-to-see-the-result/SKILL.md

@@ -54,6 +54,12 @@ Record the document id(s) and type(s) (RFC or ADR). If multiple documents were c
 
 For each document, run the full pipeline inline. The pipeline differs for RFCs and ADRs.
 
+**Between batch items:** After completing one document's pipeline and before starting the next, perform a context checkpoint per `_shared/fo-pipeline-conventions.md` §Context checkpoint between batch items. Emit the checkpoint block, release completed-item context, and start the next item with a fresh read phase. This does not pause for operator input — the checkpoint is an agent-internal context management step, not a user interaction.
+
+**Batch plan preview:** When processing >=2 documents, emit a batch plan preview per `_shared/fo-pipeline-conventions.md` §Batch plan preview before starting the first document.
+
+**Progress beacon:** After completing each pipeline step, emit a one-line progress beacon per `_shared/fo-pipeline-conventions.md` §Progress beacon. The beacon is informational — it does not pause the pipeline.
+
 #### RFC pipeline
 
 Execute these steps **in order**, invoking each skill inline via the `skill` tool. Do not stop between steps. Do not ask the operator "shall I proceed?" between steps — the operator's invocation of this skill IS the instruction to proceed through the entire pipeline.
@@ -80,6 +86,10 @@ Invoke `fo-idea-implement` on the RFC. Pass the RFC id. Wait for it to complete.
 
 Do not invoke `fo-review` or `fo-fix` separately — they are built into `fo-idea-implement`.
 
+**Step-level checkpoints:** When implementing an RFC with >=5 plan steps, perform a step checkpoint after each plan step per `_shared/fo-pipeline-conventions.md` §Step-level context checkpoint during implementation. Emit the step-checkpoint block, release completed-step context, and start the next step with a fresh plan read.
+
+**Error checkpoint:** If a pipeline step fails after 2 auto-fix attempts, emit a structured error checkpoint per `_shared/fo-pipeline-conventions.md` §Error checkpoint for pipeline step failures. Stop the pipeline and report to the operator.
+
 **Fallback verification (MANDATORY).** After `fo-idea-implement` returns, verify that review and fix were actually executed:
 
 1. Check for a review report in `docs/reviews/code/` dated today or with a `diffRange` covering this session's commits.

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

@@ -73,7 +73,9 @@ Execute the plan's step sequence in order. For each step:
 2. **Validate** — run the step's validation command (lightweight only: `rfc.validate`, type checks, unit tests on touched files). Do **not** run heavy checks (`root build`, `build:check`, `astro:check`) during implementation — they run only after all steps are complete.
 3. **Commit** after each step or phase that produces a coherent, complete unit of work:
 
-   ```txt
+   > Commands below assume RTK is installed. To check, run `rtk --version` (this is the detection command — it is not prefixed with `rtk` because it IS an `rtk` command). If `rtk --version` fails, RTK is not installed — run all commands without the `rtk` prefix.
+
+```txt
    implement: RFC-XXXX step N — <step title>
 
    <one-line description of what was done in this step>.

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

@@ -64,7 +64,9 @@ If the RFC is `draft` or `reviewing` and has `enhancedAt` — the user's instruc
 3. Set `updatedAt` to today's date.
 4. Commit:
 
-   ```txt
+   > Commands below assume RTK is installed. To check, run `rtk --version` (this is the detection command — it is not prefixed with `rtk` because it IS an `rtk` command). If `rtk --version` fails, RTK is not installed — run all commands without the `rtk` prefix.
+
+```txt
    rfc: accept RFC-XXXX <short title>
 
    Transition RFC-XXXX to accepted status for planning.

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

@@ -36,6 +36,8 @@ Check the operator's input for:
 
 **Always** make a single call to `rfc.list --json` (no `--status` flag) and a single call to `adr.list --json`. Filter by status in memory from the returned `entries` array. Never make per-status calls.
 
+> Commands below assume RTK is installed. To check, run `rtk --version` (this is the detection command — it is not prefixed with `rtk` because it IS an `rtk` command). If `rtk --version` fails, RTK is not installed — run all commands without the `rtk` prefix.
+
 ```sh
 ref(forge.yaml bindings.commands.validateRfc) --list --json
 ref(forge.yaml bindings.commands.validateAdr) --list --json

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

@@ -51,14 +51,16 @@ Run the mechanical floor first — it catches type errors, lint violations, and
 
 For a single affected package:
 
+> Commands below assume RTK is installed. To check, run `rtk --version` (this is the detection command — it is not prefixed with `rtk` because it IS an `rtk` command). If `rtk --version` fails, RTK is not installed — run all commands without the `rtk` prefix.
+
 ```sh
-pnpm --filter <package-name> build:check
+rtk pnpm --filter <package-name> build:check
 ```
 
 For an affected app:
 
 ```sh
-pnpm --filter <app-name> exec astro check
+rtk pnpm --filter <app-name> exec astro check
 ```
 
 For cross-workspace changes, run the affected workspaces' checks individually rather than a full root build.

package/skills/fo/fo-session-retro/SKILL.md

@@ -9,7 +9,7 @@ languagePolicy: ref(PREFERENCES.md)
 bindings:
   requires: []
   optional: [paths.invariantsFile]
-triggers: ["session retrospective", "capture insights from this session", "triage session discoveries"]
+triggers: ["session retrospective", "capture insights from this session", "triage session discoveries", "Завершаем эту сессию", "Завершаем сессию", "Заканчиваем сессию", "Завершить сессию", "End session", "Wrap up", "Session end", "/session-end"]
 ---
 
 # Session Retro
@@ -25,6 +25,166 @@ Review the current session for discoveries that other agents would benefit from
 - **After exploring a new area** — when conventions or patterns were learned that are not yet documented.
 - **Inline by other skills** — `fo-doc-audit` or session-end workflows may delegate here for the "what did you learn?" step.
 
+### Session-end trigger phrases
+
+When the operator says any of the following, invoke this skill via the `skill` tool BEFORE producing a closing summary:
+
+- "Завершаем эту сессию"
+- "Завершаем сессию"
+- "Заканчиваем сессию"
+- "Завершить сессию"
+- "End session"
+- "Wrap up"
+- "Session end"
+- "/session-end"
+
+Do NOT produce a closing summary first — this skill IS the closing protocol. The skill's report is the session-end output. Do not add a separate "session complete" message.
+
+## Step 0: Save session transcript (NON-NEGOTIABLE when saveSessions is true)
+
+This step ensures the session transcript is persisted to `docs/sessions/` before any retro work begins. Without it, the transcript is lost when the conversation closes.
+
+### 0a. Check preference
+
+Read `PREFERENCES.md` at the repository root. If `saveSessions: false`, skip this step entirely and proceed to Step 1.
+
+### 0b. Construct raw ATIF file
+
+The agent reconstructs the current session's conversation from its context window and writes it as a JSON-lines ATIF file to `docs/sessions/.raw/`. Each line is a JSON object with `role`, `timestamp`, and `content` fields.
+
+**Format:**
+
+```
+{"role":"user","timestamp":"2026-08-04T12:12:00+02:00","content":"<user message>"}
+{"role":"assistant","timestamp":"2026-08-04T12:12:05+02:00","content":"<assistant response>"}
+{"role":"user","timestamp":"2026-08-04T12:15:00+02:00","content":"<next user message>"}
+...
+```
+
+**Instructions:**
+
+1. Create the directory `docs/sessions/.raw/` if it does not exist.
+2. Generate a timestamp-based filename: `<YYYY-MM-DD-HH-MM-SS>-session.atif` (use current time in the operator's timezone).
+3. Reconstruct the conversation from context — include every user message and assistant response you can recall from the current session, in chronological order. This is a best-effort reconstruction: the agent's context window is the source, not an external export tool.
+4. **Redact sensitive information** — remove API keys, passwords, PII, and secret values before writing. Replace with `<redacted>`.
+5. **Truncate very long tool outputs** — if a tool call produced thousands of lines of output, summarize it as `<tool output truncated, N lines>` in the content field. Keep the tool call name and key results.
+6. Write the file using `write_to_file` to `docs/sessions/.raw/<timestamp>-session.atif`.
+
+### 0c. Run session.save
+
+Convert the raw file to structured markdown:
+
+```
+ref(forge.yaml bindings.commands.sessionSave)
+```
+
+This produces a file at `docs/sessions/<id>.md` with auto-extracted metadata (RFC-ids, commit hashes, file paths, commands, session types) and a `## Transcript` section.
+
+### 0d. Verify
+
+Check that the output file was created in `docs/sessions/`. If `session.save` reported "No raw files to process", the raw file was not written correctly — retry 0b.
+
+If the save succeeded, proceed to Step 1. The saved session file will be annotated later by `fo-session-save` if the operator requests it.
+
+## Pre-retro steps
+
+Before gathering insights, perform these housekeeping steps:
+
+### Step 1: Clean up test temp directories
+
+Remove leftover `tmp-*` and `tmp/` directories created by unit tests anywhere in the repo:
+
+> Commands below assume RTK is installed. To check, run `rtk --version` (this is the detection command — it is not prefixed with `rtk` because it IS an `rtk` command). If `rtk --version` fails, RTK is not installed — run all commands without the `rtk` prefix.
+
+```bash
+rtk find . -type d -name 'tmp-*' -not -path './.git/*' -exec rm -rf {} + 2>/dev/null
+rtk find . -type d -name 'tmp' -not -path './.git/*' -not -path './node_modules/*' -exec rm -rf {} + 2>/dev/null
+```
+
+This is safe to auto-run.
+
+### Step 2: Archive terminal documents
+
+Run the `docs.archive` umbrella command to move terminal RFCs, ADRs, plans, audits, sessions, and missions into their respective `archive/` subdirectories:
+
+```bash
+rtk pnpm exec forge docs.archive
+```
+
+The command is idempotent — re-running is safe. If files were moved, commit them in step 3 as part of the clean tree check (they are "our" changes).
+
+### Step 3: Clean tree check (NON-NEGOTIABLE)
+
+Verify that this session has no uncommitted changes left in the working tree. Other agents may be working in parallel, so you MUST distinguish your changes from theirs.
+
+**3a. Collect dirty files from all git repos in the workspace:**
+
+```bash
+# Workspace root
+rtk git status --porcelain
+# All active mission workpieces (glob — safe even if no matches)
+for d in missions/*/workpiece; do [ -d "$d/.git" ] && echo "=== $d ===" && rtk git -C "$d" status --porcelain; done
+```
+
+**3b. Classify each dirty file as "ours" or "theirs":**
+
+- A file is "ours" if EITHER:
+  - You directly modified it via `edit`, `write_to_file`, `multi_edit`, or `edit_notebook` tools.
+  - You indirectly modified it by running a command (`run_command`) that generates or updates it (e.g. codegen pipelines, build commands, etc.).
+- A file is "theirs" if it appears dirty but you have no record of touching it in this session. This means another parallel agent modified it. Do NOT commit, stash, or revert these files.
+
+**3c. Commit our changes:**
+
+- If there are "our" dirty files in the workspace root: `git add <files>` and `git commit -m "<descriptive message>"`.
+- If there are "our" dirty files in a workpiece: `git -C missions/<missionId>/workpiece add <files>` and `git -C missions/<missionId>/workpiece commit -m "<descriptive message>"`.
+- Use descriptive commit messages that explain what the changes are, not just "session cleanup".
+
+**3d. Report remaining dirty files:**
+
+- If any dirty files remain after committing ours, report them to the operator: "The following files were modified by another agent and left untouched: <list>". Then proceed.
+- If the tree is now clean (or was clean from the start), proceed silently.
+
+### Step 4: RFC implementation verification (NON-NEGOTIABLE)
+
+If any RFC was worked on during this session (implementation, audit, enhance, plan, or fix work), verify that each such RFC is either stamped as `implemented` or has an explicit operator-acknowledged reason for remaining in a non-terminal status. This step prevents sessions from ending with silently unfinished RFCs — the agent must either complete the stamp or obtain explicit operator consent to leave the RFC as-is.
+
+**4a. Identify RFCs touched in this session:**
+
+Scan the session conversation and git log for RFC IDs that were the subject of implementation work:
+
+```bash
+# Session commits that reference RFCs (adjust --since to session start)
+rtk git log --oneline --since="today 00:00:00" --grep="RFC-" -i
+```
+
+Also scan the conversation for any `RFC-XXXX` mentions where the agent performed implementation work (code changes, test creation, validator runs, stamp commands, plan/audit/enhance steps). Exclude RFCs that were only mentioned in passing (e.g. referenced as related context but not worked on).
+
+**4b. Check each RFC's status:**
+
+For each identified RFC, read the frontmatter `status` field from `docs/rfcs/rfc-XXXX-*.md` (or `docs/rfcs/archive/implemented/rfc-XXXX-*.md` if already archived by Step 2).
+
+**4c. Classify and act:**
+
+- **Status `implemented`** — the RFC is complete. No action needed.
+- **Status `rejected` or `superseded`** — terminal status, no action needed.
+- **Status `accepted` (or any other non-terminal status)** — the RFC was worked on but not stamped as `implemented`. This is the state this step targets. For each such RFC, present the status to the operator and ask via `ask_user_question` (in `aiLanguage`):
+
+  | Option | Description |
+  | --- | --- |
+  | Complete now | The agent proceeds to finish the remaining `fo-idea-implement` steps (3.6–3.8: check acceptance criteria with evidence, stamp implemented). This may require running validators, fixing errors, and committing the stamp. |
+  | Leave as-is | The operator explicitly acknowledges the RFC remains in its current non-terminal status with unchecked acceptance criteria. No further action is taken on the RFC. |
+
+  If the operator chooses "Complete now", execute `fo-idea-implement` steps 3.6–3.8 for that RFC before proceeding. If multiple RFCs are in this state, ask about each one (or present them as a batch with `allowMultiple: true`).
+
+**4d. Report:**
+
+Include the RFC status verification result in the session retro report (Step 7). List:
+
+- RFCs verified as `implemented` (count).
+- RFCs left in non-terminal status by explicit operator choice (list with RFC IDs and operator's acknowledgment).
+
+If no RFCs were worked on in this session, skip this step silently.
+
 ## What this skill is NOT
 
 - It is not `fo-doc-audit` — that skill checks whether existing docs are in sync with code changes. This skill captures **new knowledge** that does not yet exist in any doc.
@@ -86,6 +246,28 @@ Each discovered insight is categorized into exactly one of six types. The catego
 - Not a rule for all agents — it is specific to this operator.
 - Examples: "prefers concise responses", "works best in morning sessions", "dislikes long explanations", "responds well to visual summaries".
 
+## Insight filtering guidance
+
+When gathering session insights, not every observation deserves to be saved. Apply this filter before presenting the triage table:
+
+**Save as insight** — the observation is:
+
+- A convention or rule that other agents would benefit from following (Rule).
+- An architectural choice with rationale worth preserving (Decision).
+- A cross-workspace invariant that could warrant DNA status (Invariant).
+- A reusable code pattern worth porting (Pattern).
+- A preference or behavioral insight about the operator (Operator).
+- Session-local context useful for the next agent picking up this work area (Context).
+
+**Do NOT save** — the observation is:
+
+- A one-off fact with no future impact (e.g. "RFC-0676 was skipped due to a duplicate"). These are historical events, not knowledge. They do not help future agents work better.
+- A tool quirk already documented elsewhere (check `AGENTS.md` and existing memories first).
+- A transient state that will be irrelevant by the next session (e.g. "file X was dirty at session end").
+- A bug that was found and fixed in the same session with no broader lesson.
+
+When in doubt, ask: "Would another agent working in this area make a different decision if they knew this?" If the answer is no, drop it.
+
 ## Process
 
 ### 1. Read preferences and shared conventions
@@ -104,6 +286,8 @@ Review the current session to identify discoveries. Use in priority order:
 
 For each candidate, ask: "Would another agent working in this area benefit from knowing this?" If no, drop it. If yes, proceed to categorization.
 
+**No-insights shortcut:** If zero candidates survive filtering, skip Step 3 (Categorize and present) and Step 4 (Route) entirely. Do NOT ask the operator to confirm the absence of insights — proceed directly to Step 7 (Report) with a report that states "No insights found" in the insights section. This avoids a pointless confirmation round when the session produced no durable knowledge worth capturing.
+
 ### 3. Categorize and present
 
 **Language requirement (NON-NEGOTIABLE):** The triage table, the `ask_user_question` confirmation prompt, and all inline commentary MUST be written in `PREFERENCES.md` `aiLanguage`. The English template below is structural only — translate ALL headings, column names, labels, and prose to `aiLanguage` before presenting. Only identifiers (file paths, skill names, RFC/ADR ids) stay untranslated. Example: if `aiLanguage` is `ru`, the heading is «Сортировка инсайтов сессии», column headers are «№ | Инсайт | Категория | Назначение | Действие».

package/skills/meta/forge-bootstrap/SKILL.md

@@ -198,9 +198,11 @@ The transplant mode performs real code migration via a migration-adapter registr
 
 After git init (greenfield step 6.4) or after post-setup (transplant step 6.6), commit the synced Forge and pack skills to git:
 
+> Commands below assume RTK is installed. To check, run `rtk --version` (this is the detection command — it is not prefixed with `rtk` because it IS an `rtk` command). If `rtk --version` fails, RTK is not installed — run all commands without the `rtk` prefix.
+
 ```
-git add .agents/skills/
-git commit -m "chore: sync Forge skills"
+rtk git add .agents/skills/
+rtk git commit -m "chore: sync Forge skills"
 ```
 
 This ensures skills are tracked in version control from the start. The commit includes only `.agents/skills/` — no other files.
@@ -217,7 +219,11 @@ Run `rtk --version` silently. If the command succeeds and reports a version, RTK
 
 If `rtk --version` fails with "command not found" or returns a different tool, proceed to installation.
 
-#### 6.10.2. Install RTK (Linux/macOS)
+#### 6.10.2. Install RTK (cross-platform)
+
+Detect the platform: run `process.platform` (Node.js) or check `$env:OS` (PowerShell). On Linux/macOS, use the install script. On Windows, use Cargo or a prebuilt binary.
+
+**Linux/macOS:**
 
 Install RTK from the official repository `github.com/rtk-ai/rtk` using the install script:
 
@@ -231,7 +237,24 @@ If the install script fails (e.g. no `curl`, network restriction), try the Cargo
 cargo install --git https://github.com/rtk-ai/rtk
 ```
 
-If both methods fail, log the error silently (in agent logs, not shown to the operator), note RTK as "not installed" in the welcoming report, and continue to the next step. The operator can install RTK manually later.
+**Windows (PowerShell):**
+
+Primary — install via Cargo (works if Rust is installed):
+
+```
+cargo install --git https://github.com/rtk-ai/rtk
+```
+
+Secondary — download the prebuilt binary via PowerShell:
+
+```powershell
+New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.cargo\bin" | Out-Null
+Invoke-WebRequest -Uri "https://github.com/rtk-ai/rtk/releases/latest/download/rtk-x86_64-pc-windows-msvc.exe" -OutFile "$env:USERPROFILE\.cargo\bin\rtk.exe"
+```
+
+If the prebuilt binary URL is unavailable or the download fails, note RTK as "not installed" and continue.
+
+If all methods fail on any platform, log the error silently (in agent logs, not shown to the operator), note RTK as "not installed" in the welcoming report, and continue to the next step. The operator can install RTK manually later.
 
 After installation, verify with `rtk --version` and `rtk gain` — confirm the command exists and `rtk gain` shows statistics (not "command not found").
 

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

@@ -94,8 +94,10 @@ wsl --install -d Ubuntu
 
 After the reboot, inside Ubuntu:
 
+> Commands below assume RTK is installed. To check, run `rtk --version` (this is the detection command — it is not prefixed with `rtk` because it IS an `rtk` command). If `rtk --version` fails, RTK is not installed — run all commands without the `rtk` prefix.
+
 ```bash
-sudo apt update && sudo apt install -y build-essential git curl wget jq python3 python3-pip nodejs npm
+rtk sudo apt update && rtk sudo apt install -y build-essential git curl wget jq python3 python3-pip nodejs npm
 ```
 
 Note: requires a reboot.