@warpgogol/forge

Українська | English

ШІ може писати код. Forge тримає проєкт інженерним.

Репозиторіо-нативний шар управління для розробки за допомогою ШІ. Рішення, правила, навички та перевірки залишаються з проєктом — незалежно від агента, який з ним працює.

Розроблено в Warpgogol · Опубліковано як open source.

Почни зараз

Створіть нову папку, відкрийте її у вашому ШІ-IDE (Windsurf, Cursor, Claude Code, Codex CLI або будь-якому IDE з підтримкою ШІ-агентів) і вставте це:

Install https://npmjs.com/package/@warpgogol/forge in this folder and set up my project. I want to build: [describe your project]

Замініть [describe your project] своєю ідеєю — гра, бібліотека, база знань, будь-що. ШІ-агент встановить Forge, створить структуру проєкту і налаштує живий прев'ю. Далі ви просто говорите: описуєте, що хочете, і агент будує. Без програмування, без терміналу, без команд.

Після завершення промпту — Bootstrap skill

Коли ШІ-агент встановить Forge і створить структуру проєкту, він запустить навичку /forge-bootstrap. Це обов'язковий крок, який інтерактивно налаштовує ваш проєкт:

• Мову, якою ШІ спілкується з вами
• Мову документації проєкту (RFC, ADR, README) — за замовчуванням англійська
• Ваш стиль роботи — діловий або творчий
• Ваше ім'я та форму звернення
• Вашу конфігурацію стеку (або міграцію існуючого проєкту)

Навичка ставить кілька простих запитань у чаті, потім усе налаштовує. Після завершення ви готові творити — просто скажіть ШІ-агенту, що хочете побудувати.

Швидкий старт (термінал)

pnpm dlx @warpgogol/forge@latest create --in-place --profile typescript

Потім відкрийте проєкт у вашому ШІ-IDE (Windsurf, Cursor, Claude Code, Codex CLI або будь-якому IDE з підтримкою ШІ-агентів) і скажіть агентові, що ви хочете створити.

Одна команда. Далі — робота через агента.

Профілі стеку

Forge не залежить від типу проєкту. Профілі стеку — готові стартові точки.

| Профіль | Призначення | | ------------- | ------------------------------------------- | | forge-shell | Лише управління, бібліотеки, не-веб проєкти | | typescript | TypeScript монорепозиторій з валідаторами | | phaser-game | Браузерні ігри, інтерактивні досвіди | | godot-game | Десктопні/мобільні ігри на Godot 4.x + C# | | knowledge | Бази знань з підтримкою доказів |

# Перелічити доступні профілі
pnpm exec forge profile.validate

Архітектура

IDE / АГЕНТ / МОДЕЛЬ
       ↓
┌──────────────────────────────────┐
│             FORGE                 │
│                                   │
│ Контракт проєкту      forge.yaml  │
│ Рішення                RFC / ADR   │
│ Поведінка агента      Skills      │
│ Перевірка             Validators  │
│ Еволюція              Upgrade     │
└──────────────────────────────────┘
       ↓
ВАШ РЕПОЗИТОРІЙ

Агенти можуть змінюватися. Моделі можуть змінюватися. IDE можуть змінюватися. Інженерні правила залишаються з проєктом.

Що контролює Forge

| Площина | Що управляє | | -------------------- | --------------------------------------------------- | | Намір | RFC, архітектурна ДНК, критерії приймання | | Рішення | ADR, журнали рішень, відстежуваність | | Поведінка агента | Локальні навички та робочі процеси | | Перевірка | Doctor, валідатори, контракти, детерміновані гейти | | Еволюція | Профілі, вендоринг специфікацій, адитивні оновлення |

Без Forge / З Forge

| Розробка з ШІ без Forge | З Forge | | -------------------------------------- | ------------------------------------------------ | | Правила живуть у промптах | Правила живуть у репозиторії | | Архітектура неявна | Рішення стають RFC та ADR | | Поведінка агента залежить від сесії | Локальні навички визначають відтворювані процеси | | «Готово» означає, що агент так каже | Валідатори дають детерміновані перевірки | | Новий агент починає з нуля | Контракт проєкту подорожує з кодом | | Оновлення ризикує перезаписати рішення | Оновлення адитивне та ідемпотентне | | Конвенції специфічні для інструменту | Агент- та IDE-незалежний шар проєкту |

Forge Є / Forge Не Є

Forge Є

• Репозиторіо-нативний шар управління
• Агент-незалежна інфраструктура проєкту
• Детерміноване доповнення до ймовірнісних ШІ-агентів
• Портативний контракт проєкту

Forge Не Є

• Ще однією ШІ-моделлю
• Ще одним агентом-кодером
• IDE
• Хостованою платформою
• Заміною Git
• Магічною обгорткою «vibe coding»

Що ви отримуєте

• 37 навичок — пайплайн ідея→RFC, grilling, preferences, авторинг навичок
• RFC робочий процес — створення, валідація, перелік, граф, архівування, acceptance probes
• ADR робочий процес — легкі записи архітектурних рішень
• Вендоринг специфікацій — вендоринг зовнішніх специфікацій як незмінних снапшотів
• Конвенції найменування — kebab-case linting
• Linting робочих процесів — валідація frontmatter .agents/workflows/
• Скаффолдинг стеку — pnpm + Turborepo монорепозиторій з профілю
• Контракт прив'язок — деконкретизація команд проєкту через forge.yaml
• Doctor — перевірка здоров'я проєкту
• Upgrade — адитивна, ідемпотентна синхронізація навичок та конфігурації

Робота з вашим ШІ-агентом

Forge працює з будь-яким ШІ-агентом — Windsurf, Cursor, Claude Code, Codex CLI або будь-яким IDE, що підтримує навички агентів. Налаштування однакове; важлива лише розмова.

Починайте з питань, а не з команд. Перед тим, як просити агента писати код, запитайте його про кодову базу. Агент може читати файли, шукати в історії git та запускати CLI-команди Forge — дайте йому спочатку дослідити.

Описуйте результат, а не кроки. Скажіть агенту, що ви хочете, а не як це зробити. Для складних задач просіть агента спочатку спланувати.

Дозвольте агенту перевіряти власну роботу. Дайте критерії «готовно» і дозвольте агенту перевірити себе: «Запусти тести після завершення.» «Валідуй RFC перед комітом.» «Перевір здоров'я проєкту через forge doctor.»

AGENTS.md — постійна пам'ять вашого проєкту. Forge генерує файли AGENTS.md, які агент читає на початку кожної сесії. Кладіть туди команди збірки, стиль коду, архітектурні рішення та правила «роби X, а не Y».

CLI

# Перевірити здоров'я проєкту
pnpm exec forge doctor

# Валідувати RFC
pnpm exec forge rfc.validate

# Перелічити доступні навички
pnpm exec forge skill.list

# Синхронізувати навички та конфігурацію
pnpm exec forge upgrade

# Перевірити консистентність публічної поверхні
pnpm exec forge public-surface.validate

Повний довідник CLI: docs/reference/cli.md

forge.yaml

Єдине джерело істини для конфігурації проєкту:

schema: forge/config@1
project:
  name: my-project
  stack: [typescript]
  packageManager: pnpm
paths:
  rfcsDir: docs/rfcs
  adrsDir: docs/adrs
  skillsDir: .agents/skills
bindings:
  schema: forge/bindings@1
  commands:
    validateRfc: "forge rfc.validate {id} --json"
    typecheck: "pnpm run build:check"
    test: "pnpm test"
  paths:
    invariantsFile: docs/architecture-dna.md
  terminology:
    invariants: DNA

Повний довідник: docs/reference/forge-yaml.md

Програмний API

import {
  forgeCoreModule,
  forgeRfcModule,
  loadForgeConfig,
  resolveBinding,
  FORGE_SKILLS,
} from "@warpgogol/forge";

const config = loadForgeConfig(process.cwd());
const cmd = resolveBinding(config, "commands.validateRfc", { id: "RFC-0001" });

const registry = /* ваш ForgeModuleRegistry */;
await forgeCoreModule.register(registry);
await forgeRfcModule.register(registry);

Повний API: docs/reference/programmatic-api.md

Структура

| Директорія | Призначення | | --- | --- | | src/ | Портативне ядро — типи, конфіг, реєстр навичок, валідатори, онбординг. Нуль @warpgogol/* імпортів. | | os/ | Реєстрації ForgeModule. compass та werkstatt — повністю автономні. | | bin/ | Точка входу CLI (команда forge). | | skills/ | 37 визначень навичок (29 fo + 5 спільних + 3 мета) з SKILL.md frontmatter. | | profiles/ | Профілі стеку для scaffold. |

Оновлення

pnpm update @warpgogol/forge
pnpm exec forge upgrade
pnpm exec forge doctor

forge upgrade — адитивний: ніколи не перезаписує прив'язки, встановлені оператором, ідемпотентний, і при кожному запуску (включно з noop тієї ж версії) узгоджує згенеровану поверхню: синхронізовані каталоги скілів отримують маніфест .forge-managed, застарілі позначені каталоги видаляються лише коли їхній вміст відповідає маніфесту, а споживачі prettier отримують делімітований forge-managed блок у .prettierignore (RFC-1154). Використовуйте --dry-run для попереднього перегляду. Редаговані згенеровані гайди (AGENTS.md) об'єднуються, а не перезаписуються: вміст нижче межі <!-- forge:custom --> зберігається без змін при регенерації (RFC-1153), а --dry-run звітує nestedAgentsPlanned / nestedAgentsPreserved / nestedAgentsSkipped.

Документація

• Початок роботи
• Чому Forge?
• Контракт проєкту
• Модель управління
• Перенесення наявного проєкту
• Оновлення
• Навички
• RFC та ADR робочі процеси
• Довідник CLI
• Довідник forge.yaml
• Профілі
• Програмний API
• Публікація

Ліцензія

Apache-2.0

Відкрита інженерія

Цей пакет походить з виробничої інженерної роботи Warpgogol, інженерної студії в Німеччині.

Ми публікуємо багаторазово використовувані частини нашої інфраструктури, коли вони можуть бути корисні поза нашими власними проєктами. Пакет публікується незалежно від будь-якого комерційного сервісу Warpgogol. Використання цього пакету не створює залежності від Warpgogol.

Створено для реальних систем. Поділяємо відкрито.