@warpgogol/forge 0.9.0 → 0.10.0

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-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.