M0 «Основа проекта» — план реализации
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Превратить папку с исследованиями в репозиторий, в котором Claude и Codex могут вести разработку TERRITORY: git, единые правила агентов, монорепозиторий TypeScript, доска задач, карта статусов и одна команда проверки.
Architecture: pnpm-монорепозиторий с пакетами core, content, ai, sim и приложением client (пока заглушки со smoke-тестом). Задачи и дизайн-документы — markdown-файлы с YAML-шапкой; скрипты board и status читают их и падают с понятной ошибкой на неверной шапке. Исследовательские материалы вынесены в research/ и исключены из git.
Tech Stack: Node 22, pnpm 10, TypeScript 5 (strict), Vitest, ESLint 9 (flat config) + typescript-eslint, Prettier, tsx, пакет yaml.
Spec: docs/specs/2026-11-17-territory-design.md (разделы 3, 5, 6, 7 — M0, 8).
Global Constraints
- TypeScript
strict: trueво всех пакетах; pnpm workspaces. - Код, идентификаторы, комментарии, сообщения коммитов — английский; документация и задачи — русский.
research/целиком в.gitignore, кромеresearch/README.md.- Из
research/в код, данные и ассеты ничего не копируется (чистая разработка). - Статусы систем:
idea | designed | prototyped | playable | polished. - Статусы задач:
todo | doing | review | done | blocked; исполнители:claude | codex | user. - В
mainпопадает только то, что проходитpnpm check. - Пакеты
core,content,ai,simне зависят от DOM (в ихtsconfigнетlib: ["DOM"]).
Review Focus
- Шапка задачи с неверным
status/ownerили безid→pnpm boardиpnpm checkпадают и называют файл и поле, а не печатают неполную доску. - Два файла задач с одинаковым
id→ ошибка с обоими путями. - Пустая папка
tasks/(кроме шаблона) → доска печатает «Задач нет», без падения. git add -Aпосле работы вresearch/не добавляет ничего изresearch/кроме README.- Файл в
docs/game/без шапки или с неверным статусом →pnpm statusпадает с именем файла.
Task 1: Git, перенос исследований, правило чистой разработки
Files:
Move:
01_Modern_Concept/,02_Specification/,03_Game_Sources/,index.html,style.css,README.txt,OPEN_QUESTIONS.md,SOURCES.md,SHA256SUMS.txt→research/Create:
.gitignore,research/README.md,.gitattributesKeep:
docs/specs/2026-11-17-territory-design.md,docs/plans/2026-11-17-m0-foundation.mdStep 1:
git init -b mainв корне проекта.Step 2: Перенести перечисленное в
research/командойmv(без изменения содержимого). Проверить:ls researchпоказывает 9 элементов; в корне остались толькоdocs/и.claude/.Step 3: Создать
.gitignore:node_modules/,dist/,coverage/,.DS_Store,*.log,research/*,!research/README.md,.claude/settings.local.json.Step 4: Создать
.gitattributes:* text=auto eol=lf.Step 5: Написать
research/README.md(рус.): что лежит в каждой подпапке (1–2 строки), откуда взято (ссылка наSOURCES.md), и правило: «Материалы только для понимания логики и глубины жанра. В код, данные, тексты и ассеты TERRITORY ничего не переносится: ни код, ни таблицы, ни числа, ни тексты, ни изображения. Числа баланса выводятся заново».Step 6: Проверить исключение
Run: git check-ignore -v research/03_Game_Sources/civd/src/GAME.C research/01_Modern_Concept/screens/city.webp; git check-ignore research/README.md; echo "exit=$?"
Expected: первые два пути выведены с правилом research/*; для README ничего не выведено и exit=1.
- Step 7: Commit
git add .gitignore .gitattributes research/README.md docs/
git status --short # только эти файлы, ничего из research/ кроме README
git commit -m "chore: init repo, move research materials out of tracked tree"
Task 2: Монорепозиторий и pnpm check
Files:
- Create:
package.json,pnpm-workspace.yaml,tsconfig.base.json,tsconfig.json,eslint.config.js,.prettierrc.json,.prettierignore,vitest.config.ts,.nvmrc - Create для каждого из
packages/core,packages/content,packages/ai,packages/sim,apps/client:package.json,tsconfig.json,src/index.ts,src/index.test.ts
Interfaces:
Produces: имена пакетов
@territory/core,@territory/content,@territory/ai,@territory/sim,@territory/client; корневые скриптыtypecheck,lint,test,format,check.Step 1: Корневой
package.json:"private": true,"type": "module","packageManager": "pnpm@10.17.1","engines": {"node": ">=22"}; скрипты:typecheck=tsc -b,lint=eslint .,test=vitest run,format=prettier --write .,check=pnpm typecheck && pnpm lint && pnpm test && pnpm board --check && pnpm status --check(скриптыboard/statusпоявятся в задачах 3–4; до тех пор временно без двух последних частей)..nvmrc=22.Step 2:
pnpm-workspace.yaml:packages: ["packages/*", "apps/*"].Step 3:
tsconfig.base.json:strict,noUncheckedIndexedAccess,exactOptionalPropertyTypes,module/moduleResolution=NodeNext,target=ES2022,composite: true,declaration: true,lib: ["ES2022"]. Корневойtsconfig.json— толькоreferencesна пять пакетов. Вapps/client/tsconfig.jsonдобавить"lib": ["ES2022", "DOM"].Step 4: В каждом пакете
src/index.tsэкспортируетexport const PACKAGE_NAME = "@territory/<name>";. Зависимости между пакетами (workspace:*) — по таблице раздела 6 спецификации: content→core; ai→core; sim→core, content, ai; client→core, content, ai.Step 5: Smoke-тест в каждом пакете
import { describe, it, expect } from "vitest";
import { PACKAGE_NAME } from "./index.js";
describe("package", () => {
it("has its name", () => expect(PACKAGE_NAME).toBe("@territory/core")); // своё имя в каждом пакете
});
- Step 6: ESLint flat config с
typescript-eslintrecommended type-checked и правиломno-restricted-globals/no-restricted-properties, запрещающимMath.randomвpackages/**(ядро детерминировано — раздел 6). Prettier:printWidth: 100, игнорresearch/,docs/,tasks/. - Step 7:
pnpm install, затем:
Run: pnpm check
Expected: typecheck без ошибок, lint без ошибок, Vitest 5 passed.
- Step 8: Проверить запрет
Math.random: временно добавитьMath.random()вpackages/core/src/index.ts,pnpm lint→ ошибка с указанием правила; откатить. - Step 9: Commit —
chore: scaffold pnpm monorepo with typecheck, lint, test.
Task 3: Доска задач pnpm board
Files:
- Create:
scripts/lib/frontmatter.ts,scripts/lib/tasks.ts,scripts/board.ts,scripts/lib/tasks.test.ts,tasks/_template.md - Modify: корневой
package.json(скриптboard=tsx scripts/board.ts; добавить вcheck),vitest.config.ts(включитьscripts/**/*.test.ts)
Interfaces:
Produces:
parseFrontmatter(text: string): { data: Record<string, unknown>; body: string } | null—null, если шапки---нет.type TaskStatus = "todo" | "doing" | "review" | "done" | "blocked";type Owner = "claude" | "codex" | "user".interface Task { id: string; title: string; status: TaskStatus; owner: Owner | null; milestone: string; files: string[]; depends_on: string[]; path: string }parseTask(path: string, text: string): Task— бросаетTaskErrorс сообщением"<path>: <field>: <проблема>".loadTasks(dir: string): Task[]— читаетT-*.md, пропускает_template.md, бросает на дубликатidс обоими путями.renderBoard(tasks: Task[]): string.- CLI:
pnpm boardпечатает доску;pnpm board --checkтолько валидирует (код 1 при ошибке).
Step 1: Тесты в
scripts/lib/tasks.test.ts:- валидная шапка →
Taskсо всеми полями;files/depends_onпо умолчанию[],ownerпо умолчаниюnull; status: started→ ошибка, содержащая путь иstatus;owner: gpt→ ошибка, содержащаяowner;- нет
id→ ошибка, содержащаяid; - файл без шапки → ошибка «нет шапки»;
- два файла с
id: T-0001→ ошибка, содержащая оба пути; renderBoard([])содержитЗадач нет;renderBoardгруппирует поmilestone, внутри — по статусу в порядкеdoing, review, blocked, todo, done, строка задачи:T-0001 [codex] Заголовок.
- валидная шапка →
Step 2:
pnpm vitest run scripts→ FAIL (модули не существуют).Step 3: Реализовать
frontmatter.ts(разбор через пакетyaml),tasks.ts,board.ts.Step 4:
pnpm vitest run scripts→ PASS.Step 5:
tasks/_template.md— шапка со всеми полями и разделы тела: «Зачем», «Готово, когда», «Заметки», «Коммиты».Step 6:
pnpm board→Задач нет;pnpm checkзелёный.Step 7: Commit —
feat(tooling): task files and board script.
Task 4: Карта статусов систем pnpm status
Files:
- Create:
scripts/lib/systems.ts,scripts/lib/systems.test.ts,scripts/status.ts,docs/game/_template.md - Modify: корневой
package.json(скриптstatus=tsx scripts/status.ts; добавитьstatus --checkвcheck)
Interfaces:
Consumes:
parseFrontmatterиз задачи 3.Produces:
type SystemStatus = "idea" | "designed" | "prototyped" | "playable" | "polished"interface GameSystem { id: string; title: string; status: SystemStatus; milestone: string; path: string }loadSystems(dir: string): GameSystem[](рекурсивно, включаяdocs/game/guilds/, пропуская_template.md; ошибки в формате задачи 3)renderStatus(systems: GameSystem[]): string— markdown-таблицаСистема | Статус | Этап | Документ.- CLI:
pnpm statusперезаписывает блок между<!-- status:begin -->и<!-- status:end -->вdocs/STATUS.md;pnpm status --check— только валидация и сверка, чтоdocs/STATUS.mdактуален (код 1, если нет).
Step 1: Тесты: валидная шапка →
GameSystem;status: done→ ошибка с путём иstatus; файл без шапки → ошибка с путём;renderStatus([])содержитСистем пока нет; таблица отсортирована поmilestone, затемid.Step 2: Запустить тесты → FAIL.
Step 3: Реализовать.
Step 4: Тесты → PASS.
Step 5:
docs/game/_template.md: шапкаid, title, status, milestoneи разделы «Назначение», «Правила», «Открытые вопросы», «Решения пользователя».Step 6: Создать
docs/STATUS.mdс заголовком, абзацем «как читать статусы» и маркерами;pnpm status, затемpnpm checkзелёный.Step 7: Commit —
feat(tooling): system status map.
Task 5: Правила агентов, документация и задачи M1
Files:
Create:
AGENTS.md,CLAUDE.md,README.md,docs/README.md,docs/GLOSSARY.md,docs/decisions/0001-typescript-stack.md,docs/decisions/0002-clean-room.md,docs/decisions/0003-deterministic-command-core.md,docs/decisions/_template.mdCreate: задачи
tasks/T-0001-…md… (список ниже)Step 1:
AGENTS.md(рус., ≤ 150 строк) — единый источник правил для обоих агентов:- что за проект (2–3 строки) и ссылка на спецификацию;
- карта репозитория (таблица из раздела 8.1 спецификации);
- команды:
pnpm install,pnpm check,pnpm board,pnpm status,pnpm test; - правило чистой разработки дословно из
research/README.md; - протокол работы с задачами (раздел 8.3–8.4): перед началом —
ownerиdoing; не трогать файлы изfilesчужой задачи в статусеdoing/review; в конце — заметки, коммиты,review; каждый агент в своей веткеclaude/<T-id>илиcodex/<T-id>(git worktree); вmain— только послеpnpm check; - язык: код/коммиты английский, документация русский; формат коммитов
type(scope): summary; - архитектурные решения — запись в
docs/decisions/; изменения дизайна — вdocs/game/; - ограничения ядра: без DOM, без
Math.random, все изменения мира через команды.
Step 2:
CLAUDE.md— одна строка@AGENTS.mdи строка «Все правила проекта — в AGENTS.md; не дублировать их здесь».Step 3:
README.md(что это, как запустить, где что лежит — со ссылками),docs/README.md(карта документации),docs/GLOSSARY.md(таблицаТермин | В коде | Значениес первыми терминами: гильдия/guild, фракция/faction, эпоха/era, клетка/tile, город/city, юнит/unit, команда/command, ход/turn).Step 4: Три записи решений по шаблону «Контекст / Решение / Последствия / Отвергнутые варианты» — источники: спецификация разделы 5, 3 и 6 соответственно.
Step 5: Задачи M1 (статус
todo,milestone: M1; в теле — «Зачем» и «Готово, когда» по спецификации разделы 6, 7, 10, 11.1):T-0001План реализации M1 (ownerclaude).T-0002Черновики дизайна карты, местности и юнитов M1 вdocs/game/(ownerclaude).T-0003Черновики дизайна городов, производства и хода вdocs/game/(ownerclaude).T-0004Проба стиля графики: 3–4 клетки местности, юнит, город; предложение размера клетки и формата спрайтов (ownercodex).T-0005Проверка платформ M1.5: тестовая сборка Electron с оверлеем Steam (milestoneM1.5).T-0006Проверка платформ M1.5: большая карта на реальном iPhone (milestoneM1.5).
Step 6:
pnpm boardпоказывает 6 задач в M1/M1.5;pnpm checkзелёный.Step 7: Commit —
docs: agent rules, project docs, decisions, M1 tasks.
Task 6: Подключение Codex к правилам
Files:
Modify:
tasks/T-0004-…md(заметки)Step 1: Отправить Codex через
codex queue(вне песочницы) сообщение: прочитатьAGENTS.md,docs/specs/2026-11-17-territory-design.md, выполнитьpnpm checkиpnpm board, ничего не менять, ответить по-русски: (а) краткое понимание правил, (б) с чем не согласен или что неясно, (в) готов ли взятьT-0004.Step 2: Прочитать ответ во вкладке Codex. Возражения и неясности — показать пользователю; согласованные правки внести в
AGENTS.mdотдельным коммитомdocs(agents): clarify rules after Codex review.Step 3: Проверка: Codex назвал хотя бы правило чистой разработки, протокол задач и команду
pnpm check; егоpnpm checkзелёный.