@warpgogol/forge 2.21.3 → 2.21.6

package/README.md

@@ -359,6 +359,187 @@ pnpm exec forge rfc.validate
 pnpm exec forge skill.list
 ```
 
+---
+
+## Working with your AI agent
+
+Forge works with any AI agent — Windsurf, Cursor, Claude Code, Codex CLI, or any IDE that supports agent skills. The setup is the same; only the conversation matters. Here are the patterns that make the biggest difference.
+
+### Start with questions, not commands
+
+The single most effective habit: before asking the agent to write code, ask it about the codebase. The agent can read files, search git history, and run Forge CLI commands — let it explore first.
+
+Good questions to start a session:
+
+- "How is this project structured?"
+- "What skills are available and what do they do?"
+- "Walk me through the RFC workflow in this project."
+- "What did we change this week?" (the agent reads git log)
+- "Why does this function have 15 parameters? Check git history."
+
+This works for onboarding too — new team members can get up to speed by asking the agent questions instead of reading code manually. The agent reads everything locally; nothing is uploaded or trained on.
+
+### AGENTS.md — your project's persistent memory
+
+Forge generates `AGENTS.md` files at the project root and in each workspace directory. The agent reads them automatically at the start of every session — think of them as instructions that survive between conversations.
+
+**What to put in AGENTS.md:**
+
+- Build and test commands (`pnpm test`, `pnpm run build:check`)
+- Code style conventions ("use 2 spaces, not tabs")
+- Architecture decisions ("the game package owns all scene logic")
+- "Do X, not Y" rules ("use `resolveImage()` for all image props, never raw `src`")
+- Common mistakes to avoid
+
+**When the agent makes a mistake**, tell it to update AGENTS.md so it doesn't repeat the error. Over time, AGENTS.md accumulates the team's hard-won knowledge.
+
+Forge generates AGENTS.md from `forge.yaml` via `forge.agents.generate`. Hand-written AGENTS.md files (without the generated marker) are preserved. Generated ones are regenerated when you run `forge upgrade` or `forge.agents.generate` — so put your custom rules in `forge.yaml` or in a hand-written AGENTS.md, not in a generated one.
+
+### Describe results, not steps
+
+The agent is an autonomous worker, not a typewriter. Tell it what you want, not how to do it.
+
+**Bad** (over-specified):
+
+> Open src/game/player.ts, add a function called calculateScore that takes a number array, sum it, return the result. Then open src/game/player.test.ts and add a test.
+
+**Good** (result-oriented):
+
+> Add a scoring system that calculates total points from collected items.
+
+For complex work, ask the agent to plan first:
+
+> I want to add a multiplayer mode. Make a plan first, show it to me, and wait for my approval before implementing.
+
+Forge's `/fo-idea` skill formalizes this: idea → audit → plan → implement → review. You can invoke it explicitly, or the agent will follow the pattern when the task is complex enough.
+
+### Let the agent explore
+
+Don't over-explain. The agent knows how to read files, search code, check git history, and run commands. Instead of pointing it to specific files, describe what you want to understand or change:
+
+**Instead of:** "Look in the src/game folder for player.ts and check if it has a move function."
+
+**Say:** "How does player movement work?"
+
+The agent will find the relevant files, trace the call chain, and explain it back to you. If it needs more context, it will ask.
+
+### Parallel work
+
+You can run multiple agent sessions simultaneously — in separate IDE windows, terminal tabs, or git worktrees. Each session works independently.
+
+This is useful for:
+
+- Writing an RFC in one session while implementing a different feature in another
+- Exploring two design approaches in parallel before committing to one
+- Running a long validation in one session while continuing work in another
+
+If you use the Werkstatt engine, its mission system keeps work isolated — each mission has its own workpiece directory, so parallel sessions don't conflict.
+
+### Let the agent verify its own work
+
+Give the agent criteria for "done" and let it check itself:
+
+- "Run the tests after you're done."
+- "Validate the RFC before committing."
+- "Check project health with `forge doctor`."
+
+Forge provides the tools — `forge doctor`, `forge rfc.validate`, `forge skill.list`, test runners. Tell the agent to use them. The agent can run commands, read the output, and fix issues without your intervention.
+
+---
+
+## Skill packs
+
+Skill packs let you create project-local skills under your own prefix, separate from Forge's portable `fo-` skills. This is useful when your project has domain-specific workflows that don't belong in Forge's portable skill set.
+
+### Declaring a pack
+
+Add a `skillPacks` entry to `forge.yaml`:
+
+```yaml
+skillPacks:
+  - prefix: wg
+    dir: packages/my-skills/skills
+```
+
+- `prefix` — short identifier used as a skill name prefix (e.g. `wg-deploy`, `wg-content-check`). Cannot be `fo` (reserved for Forge).
+- `dir` — directory containing your pack skills. Each skill is a subdirectory with a `SKILL.md` file.
+
+### Pack manifest (`forge.plugin.yaml`)
+
+Each pack directory must contain a `forge.plugin.yaml` manifest:
+
+```yaml
+id: my-pack
+version: 1.0.0
+```
+
+- `id` — kebab-case identifier for the pack.
+- `version` — semver version string.
+
+`forge init` auto-creates this manifest if it's missing. You can also create it manually.
+
+### Skill structure
+
+Skills follow the same structure as Forge skills:
+
+```
+packages/my-skills/skills/
+  forge.plugin.yaml          # pack manifest
+  wg-deploy/
+    SKILL.md                 # skill definition with frontmatter
+  wg-content-check/
+    SKILL.md
+```
+
+Each `SKILL.md` has standardized frontmatter (name, description, category, concerns, dependsOn) — the same format as Forge's `fo-` skills.
+
+### Validation commands
+
+```sh
+# Validate all pack manifests
+pnpm exec forge plugin.validate
+
+# List discovered packs
+pnpm exec forge plugin.discover
+
+# Validate individual skills (including pack skills)
+pnpm exec forge skill.validate
+
+# List all skills (pack skills annotated with pack:<prefix>)
+pnpm exec forge skill.list
+```
+
+### Extension points (Compass contract blocks)
+
+Packs can declare custom Compass contract blocks — source-file markers that `compass.validate` enforces. This lets your pack define its own `<MY_CONTRACT>` blocks with required tags:
+
+```yaml
+id: my-pack
+version: 1.0.0
+extensionPoints:
+  compass:
+    contract:
+      blocks:
+        - blockId: api-contract
+          requiredFor:
+            - "packages/my-pack/**/*.ts"
+          requiredTags:
+            - name: purpose
+              minWords: 3
+```
+
+`compass.validate` will emit `COMPASS-PLUGIN-01` (missing block), `COMPASS-PLUGIN-02` (missing required tag), and `COMPASS-PLUGIN-03` (tag below minWords) for files matching `requiredFor` that don't carry the block.
+
+### Rules
+
+- Pack skill names must start with the pack prefix (e.g. `wg-deploy` for prefix `wg`).
+- Pack skills cannot use the `fo-` prefix (reserved for Forge).
+- Pack skills cannot reference platform RFC/ADR ids or platform names.
+- Pack skills may depend on Forge skills, but Forge skills may not depend on pack skills (preserves portability).
+- If a pack skill name conflicts with a Forge skill name, the pack skill is skipped during sync.
+
+---
+
 ## Stack profiles
 
 A stack profile defines the project scaffold: directory structure, dependencies, CI config, and first workspace. Choose a profile with `--profile` when creating a new project.

package/README.uk.md

@@ -350,6 +350,187 @@ pnpm exec forge rfc.validate
 pnpm exec forge skill.list
 ```
 
+---
+
+## Робота з вашим ШІ-агентом
+
+Forge працює з будь-яким ШІ-агентом — Windsurf, Cursor, Claude Code, Codex CLI або будь-яким IDE, що підтримує навички агентів. Налаштування однакове; важлива лише розмова. Ось патерни, які дають найбільший ефект.
+
+### Починайте з питань, а не з команд
+
+Найефективніша звичка: перед тим, як просити агента писати код, запитайте його про кодову базу. Агент може читати файли, шукати в історії git та запускати CLI-команди Forge — дайте йому спочатку дослідити.
+
+Добрі питання для початку сесії:
+
+- "Як структурований цей проєкт?"
+- "Які навички доступні і що вони роблять?"
+- "Проведи мене через RFC робочий процес у цьому проєкті."
+- "Що ми змінили цього тижня?" (агент читає git log)
+- "Чому ця функція має 15 параметрів? Перевір історію git."
+
+Це працює і для онбордингу — нові члени команди можуть швидко ввійти в курс справи, запитуючи агента, замість того, щоб вручну читати код. Агент читає все локально; нічого не завантажується та не тренується на вашому коді.
+
+### AGENTS.md — постійна пам'ять вашого проєкту
+
+Forge генерує файли `AGENTS.md` в корені проєкту та в кожній директорії робочого простору. Агент читає їх автоматично на початку кожної сесії — сприймайте їх як інструкції, які зберігаються між розмовами.
+
+**Що писати в AGENTS.md:**
+
+- Команди збірки та тестування (`pnpm test`, `pnpm run build:check`)
+- Угоди стилю коду ("використовуйте 2 пробіли, а не таби")
+- Архітектурні рішення ("пакет гри володіє всією логікою сцен")
+- Правила "роби X, а не Y" ("використовуйте `resolveImage()` для всіх image-пропів, ніколи сирий `src`")
+- Типові помилки, яких слід уникати
+
+**Коли агент помиляється**, скажіть йому оновити AGENTS.md, щоб він не повторював помилку. З часом AGENTS.md накопичує здобуті командою знання.
+
+Forge генерує AGENTS.md з `forge.yaml` через `forge.agents.generate`. Написані вручну AGENTS.md (без згенерованого маркера) зберігаються. Згенеровані файли регенеруються при запуску `forge upgrade` або `forge.agents.generate` — тому кладіть свої правила в `forge.yaml` або в написаний вручну AGENTS.md, а не в згенерований.
+
+### Описуйте результат, а не кроки
+
+Агент — автономний працівник, а не друкарська машинка. Скажіть йому, що ви хочете, а не як це зробити.
+
+**Погано** (занадто детально):
+
+> Відкрий src/game/player.ts, додай функцію calculateScore, яка приймає масив чисел, сумує його, повертає результат. Потім відкрий src/game/player.test.ts і додай тест.
+
+**Добре** (орієнтовано на результат):
+
+> Додай систему підрахунку очок, яка обчислює загальні бали за зібрані предмети.
+
+Для складних задач просіть агента спочатку спланувати:
+
+> Я хочу додати багатокористувацький режим. Спочатку склади план, покажи мені, і чекай на моє схвалення перед реалізацією.
+
+Навичка Forge `/fo-idea` формалізує це: ідея → аудит → план → реалізація → рев'ю. Ви можете викликати її явно, або агент буде слідувати цьому патерну, коли задача достатньо складна.
+
+### Дайте агенту дослідити
+
+Не пояснюйте занадто детально. Агент вміє читати файли, шукати в коді, перевіряти історію git та запускати команди. Замість того, щоб вказувати на конкретні файли, опишіть, що ви хочете зрозуміти або змінити:
+
+**Замість:** "Подивись у папці src/game файл player.ts і перевір, чи є там функція move."
+
+**Скажіть:** "Як працює рух гравця?"
+
+Агент знайде відповідні файли, простежить ланцюг викликів і пояснить вам. Якщо йому потрібен буде додатковий контекст, він запитає.
+
+### Паралельна робота
+
+Ви можете запускати кілька сесій агента одночасно — в різних вікнах IDE, вкладках терміналу або git worktrees. Кожна сесія працює незалежно.
+
+Це корисно для:
+
+- Написання RFC в одній сесії, паралельно з реалізацією іншої функції в іншій
+- Дослідження двох дизайн-підходів паралельно перед вибором одного
+- Запуску тривалої валідації в одній сесії, продовжуючи роботу в іншій
+
+Якщо ви використовуєте рушій Werkstatt, його система місій ізолює роботу — кожна місія має власну директорію workpiece, тому паралельні сесії не конфліктують.
+
+### Дозвольте агенту перевіряти власну роботу
+
+Дайте агенту критерії "готово" і дозвольте йому перевірити себе:
+
+- "Запусти тести після завершення."
+- "Валідуй RFC перед комітом."
+- "Перевір стан проєкту через `forge doctor`."
+
+Forge надає інструменти — `forge doctor`, `forge rfc.validate`, `forge skill.list`, тест-ранери. Скажіть агенту використовувати їх. Агент може запускати команди, читати вивід та виправляти проблеми без вашої втручання.
+
+---
+
+## Пакети навичок
+
+Пакети навичок (skill packs) дозволяють створювати навички проєкту під власним префіксом, окремо від портативних `fo-` навичок Forge. Це корисно, коли ваш проєкт має домен-специфічні робочі процеси, які не належать до портативного набору Forge.
+
+### Оголошення пакету
+
+Додайте запис `skillPacks` у `forge.yaml`:
+
+```yaml
+skillPacks:
+  - prefix: wg
+    dir: packages/my-skills/skills
+```
+
+- `prefix` — короткий ідентифікатор, що використовується як префікс імені навички (наприклад `wg-deploy`, `wg-content-check`). Не може бути `fo` (зарезервовано для Forge).
+- `dir` — директорія, що містить навички вашого пакету. Кожна навичка — піддиректорія з файлом `SKILL.md`.
+
+### Маніфест пакету (`forge.plugin.yaml`)
+
+Кожна директорія пакету повинна містити маніфест `forge.plugin.yaml`:
+
+```yaml
+id: my-pack
+version: 1.0.0
+```
+
+- `id` — ідентифікатор пакету в kebab-case.
+- `version` — рядок версії у форматі semver.
+
+`forge init` автоматично створює цей маніфест, якщо він відсутній. Ви також можете створити його вручну.
+
+### Структура навичок
+
+Навички мають ту саму структуру, що й навички Forge:
+
+```
+packages/my-skills/skills/
+  forge.plugin.yaml          # маніфест пакету
+  wg-deploy/
+    SKILL.md                 # визначення навички з frontmatter
+  wg-content-check/
+    SKILL.md
+```
+
+Кожен `SKILL.md` має стандартизований frontmatter (name, description, category, concerns, dependsOn) — той самий формат, що й у `fo-` навичок Forge.
+
+### Команди валідації
+
+```sh
+# Валідувати всі маніфести пакетів
+pnpm exec forge plugin.validate
+
+# Перелічити виявлені пакети
+pnpm exec forge plugin.discover
+
+# Валідувати окремі навички (включно з навичками пакетів)
+pnpm exec forge skill.validate
+
+# Перелічити всі навички (навички пакетів позначені pack:<prefix>)
+pnpm exec forge skill.list
+```
+
+### Точки розширення (блоки Compass-контракту)
+
+Пакети можуть оголошувати власні блоки Compass-контракту — маркери у вихідних файлах, які `compass.validate` перевіряє. Це дозволяє вашому пакету визначати власні `<MY_CONTRACT>` блоки з обов'язковими тегами:
+
+```yaml
+id: my-pack
+version: 1.0.0
+extensionPoints:
+  compass:
+    contract:
+      blocks:
+        - blockId: api-contract
+          requiredFor:
+            - "packages/my-pack/**/*.ts"
+          requiredTags:
+            - name: purpose
+              minWords: 3
+```
+
+`compass.validate` видаватиме `COMPASS-PLUGIN-01` (відсутній блок), `COMPASS-PLUGIN-02` (відсутній обов'язковий тег) та `COMPASS-PLUGIN-03` (тег з меншою кількістю слів) для файлів, що відповідають `requiredFor`, але не містять блок.
+
+### Правила
+
+- Імена навичок пакету повинні починатися з префіксу пакету (наприклад `wg-deploy` для префіксу `wg`).
+- Навички пакету не можуть використовувати префікс `fo-` (зарезервовано для Forge).
+- Навички пакету не можуть посилатися на ідентифікатори платформених RFC/ADR або назви платформи.
+- Навички пакету можуть залежати від навичок Forge, але навички Forge не можуть залежати від навичок пакету (зберігає портативність).
+- Якщо ім'я навички пакету конфліктує з іменем навички Forge, навичка пакету пропускається під час синхронізації.
+
+---
+
 ## Профілі стеку
 
 Профіль стеку визначає каркас проєкту: структуру директорій, залежності, конфігурацію CI та перший робочий простір. Оберіть профіль прапорцем `--profile` під час створення проєкту.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpgogol/forge",
-  "version": "2.21.3",
+  "version": "2.21.6",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",