Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,14 @@ To learn how a project works through code walkthroughs and practical checks:

Study sessions track explored areas and demonstrated understanding separately. Significant decisions are maintained as a regular project practice, with a map linking to their rationale and implementation evidence.

For a large task with independent parts, generate a prompt for Codex:

```powershell
.\ai-rules.ps1 prompt parallel -ProjectRoot C:\path\to\project
```

Paste the prompt and your task into Codex. It will assess whether parallel work helps, give each writer a bounded task and separate workspace, and assign one owner to integrate and verify the result. Ordinary tasks continue as before.

## Update rules

Preview the available changes:
Expand Down
8 changes: 5 additions & 3 deletions ai-rules.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,8 @@ Agent Engineering Kit
Подготовить запрос для глубокого аудита.
prompt study -ProjectRoot ПУТЬ
Подготовить запрос для изучения проекта.
prompt parallel -ProjectRoot ПУТЬ
Подготовить запрос для параллельной задачи.
connect -ProjectRoot ПУТЬ
Подготовить проект и показать изменения.
connect -ProjectRoot ПУТЬ -Apply
Expand Down Expand Up @@ -729,12 +731,12 @@ try {
}
}
'prompt' {
if ([string]::IsNullOrWhiteSpace($ListTarget) -or $ListTarget.ToLowerInvariant() -notin @('audit', 'connect', 'deep-audit', 'study')) {
throw "Для команды 'prompt' укажите 'connect', 'audit', 'deep-audit' или 'study'."
if ([string]::IsNullOrWhiteSpace($ListTarget) -or $ListTarget.ToLowerInvariant() -notin @('audit', 'connect', 'deep-audit', 'study', 'parallel')) {
throw "Для команды 'prompt' укажите 'connect', 'audit', 'deep-audit', 'study' или 'parallel'."
}
$promptName = $ListTarget.ToLowerInvariant()
$promptArguments = @('-Name', $promptName)
if ($promptName -in @('connect', 'deep-audit', 'study')) {
if ($promptName -in @('connect', 'deep-audit', 'study', 'parallel')) {
$resolvedProjectRoot = Resolve-ProjectRoot -Path $ProjectRoot
$promptArguments += @('-ProjectRoot', $resolvedProjectRoot)
}
Expand Down
4 changes: 3 additions & 1 deletion hub/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ AGENTS.md целевого проекта

Подробные нормы для продукта, архитектуры и данных, реализации, качества, эксплуатации, безопасности, документации, Git, совместной работы с AI и исследований. Каталог включает их в итоговый набор, но агент читает только темы текущей задачи.

Рабочие процессы конкретных задач находятся в `workflows/` и не считаются постоянными нормативными правилами. Идентификатор `project-study` пока сохраняется для совместимости `.ai-rules/manifest.json`, но создаёт `workflows/PROJECT_STUDY.md`. Идентификатор `project-audit` подключает `workflows/PROJECT_DEEP_AUDIT.md` для отдельной задачи глубокого аудита. Ни один из этих процессов не входит в профиль и не подключается автоматически.
Рабочие процессы конкретных задач находятся в `workflows/` и не считаются постоянными нормативными правилами. Идентификатор `project-study` пока сохраняется для совместимости `.ai-rules/manifest.json`, но создаёт `workflows/PROJECT_STUDY.md`. Идентификатор `project-audit` подключает `workflows/PROJECT_DEEP_AUDIT.md` для отдельной задачи глубокого аудита. Идентификатор `parallel-delivery` подключает `workflows/PARALLEL_DELIVERY.md` для явно выбранной параллельной задачи; `prompt parallel` только печатает стартовый запрос и не меняет проект. Ни один из этих процессов не входит в профиль и не подключается автоматически.

### `profiles/`

Expand Down Expand Up @@ -86,6 +86,8 @@ hub checkout + project manifest

`AGENTS.md` остаётся канонической точкой входа проекта. В самом хабе проверяется один пилот для Claude Code: корневой `CLAUDE.md` содержит только импорт `@AGENTS.md`. Этот файл не входит в каталог, шаблоны подключения или управляемую копию и не означает массовое добавление таких файлов.

Для параллельной работы Codex первая версия использует ту же точку входа, явно выбранный `parallel-delivery` и сгенерированный `prompt parallel`. Шаблон `templates/TASK_CONTRACT.md` читается из локального хаба по пути в запросе и не копируется синхронизацией; подключённый процесс перечисляет обязательные поля и остаётся понятным без доступного хаба. Отдельный Codex Skill нужен только после наблюдения повторяющейся ручной механики, которую этот маршрут не устраняет. Штатный Agent Command Center координирует агентов, когда доступен; хаб не запускает их процессы и не ведёт собственное состояние задач.

### `hub/`

Продуктовые и архитектурные правила самого Agent Engineering Kit и решения о структуре.
Expand Down
10 changes: 9 additions & 1 deletion rules/AI_COLLABORATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,15 @@

## Параллельная работа

До параллельной работы зафиксируй владельца подзадачи, границы файлов или контракта и способ интеграции. Несколько исполнителей не меняют один контракт без координации. Один владелец отвечает за итоговую интеграцию, разрешение пересечений и общий прогон проверок.
Сначала определи общий результат и зависимости подзадач. Запускай одновременно только задачи с независимым проверяемым результатом, чьи зависимости уже выполнены и области записи не конфликтуют. Наличие свободных агентов само по себе не причина для параллельности.

До запуска зафиксируй для каждой подзадачи владельца, область записи, зависимости и затрагиваемые общие контракты, а для всей работы — одного владельца интеграции. Общий контракт — интерфейс между подзадачами, например публичный API, тип или схема, миграция, маршрут, сетевое событие, корневая конфигурация или файл блокировки зависимостей. У каждого изменяемого общего контракта один владелец; несколько исполнителей не меняют его независимо.

Каждый агент, изменяющий отслеживаемые файлы, получает одну конкретную задачу и один назначенный изолированный рабочий каталог. Он не использует каталог другого пишущего агента. Если используется Git, задача также получает одну назначенную ветку от известной базы; рекомендуемый способ изоляции нескольких пишущих агентов — отдельные Git worktree. Эквивалентная изоляция допустима в среде без worktree.

Исполнители передают результаты и запросы на изменение общего контракта координатору или владельцу интеграции, а не согласовывают пересекающиеся правки друг с другом. Если нужное изменение выходит за область записи или затрагивает чужой контракт, исполнитель останавливает эту часть работы, описывает причину и затронутый контракт и ждёт нового решения. Остальную независимую работу можно продолжить.

Один владелец интеграции объединяет результаты, разрешает пересечения, проверяет взаимодействие частей и выполняет общий набор проверок. Локальная проверка исполнителя не доказывает готовность интегрированного результата. Для ограниченного процесса используй явно выбранный рабочий процесс, если он подключён к проекту; эти инварианты действуют и без него.

## Улучшение системы после ошибок

Expand Down
7 changes: 7 additions & 0 deletions rules/GIT_AND_DELIVERY.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,13 @@
- Не веди обычную разработку прямо в ветке, которая объединяет работу или переключает постоянный staging/production. Исключение допустимо для явно принятого проектом процесса `direct-to-trunk`, локального репозитория без такой границы либо согласованного аварийного изменения; причина и эквивалентная проверка до переключения фиксируются явно.
- Если задача началась не в той ветке, не продолжай по инерции: остановись до следующей записи или внешнего действия, сохрани чужую работу и перенеси только относящийся к задаче diff безопасным способом.

## Параллельные пишущие задачи в Git

- Для каждой пишущей задачи зафиксируй базовую ветку и точный базовый commit до создания ветки задачи. Назначь ей одну ветку и один рабочий каталог; отдельный `git worktree` — рекомендуемый способ изоляции параллельных исполнителей. Другой пишущий исполнитель не использует этот каталог.
- Исполнитель не переключает ветку внутри назначенного worktree произвольно. Изменение базы или ветки координируется с владельцем интеграции и не переносит чужие незавершённые изменения.
- Владелец интеграции отвечает за `merge`, `rebase` или `cherry-pick` результатов в интеграционную ветку и за проверку итогового состояния. Исполнитель не интегрирует свою работу без выданных полномочий. Добавление в индекс, коммит, отправка, запрос на слияние и внешняя поставка сохраняют границы разрешения из раздела «Локальная история».
- Удаляй рабочий каталог или worktree только с разрешения владельца после проверки, что нужный результат сохранён, доступен владельцу интеграции и больше не требуется для проверок. Нельзя терять незакоммиченные или ещё не интегрированные изменения при очистке.

## Сообщения коммитов и автоматическая проверка

- Проект явно фиксирует формат сообщений коммитов и способ его проверки. Соблюдай локальный контракт; если его нет, предложи Conventional Commits как совместимый вариант, но не объявляй его универсальным требованием без решения владельца.
Expand Down
2 changes: 1 addition & 1 deletion rules/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
| [`GIT_AND_DELIVERY.md`](GIT_AND_DELIVERY.md) | ветки, коммиты, CI/CD, релиз или внешняя операция |
| [`AI_COLLABORATION.md`](AI_COLLABORATION.md) | распределение работы между человеком и AI, менторский режим |
| [`RESEARCH_AND_EVIDENCE.md`](RESEARCH_AND_EVIDENCE.md) | неизвестный API, исследование, эксперимент, аудит или доказательная рекомендация |
Тематическое правило задаёт нормы для класса задач. Рабочие процессы конкретных задач находятся в [`../workflows/`](../workflows/) и не становятся постоянными нормативными правилами. Для совместимости manifest идентификатор `project-study` пока выбирает `workflows/PROJECT_STUDY.md`; отдельный идентификатор `project-audit` выбирает `workflows/PROJECT_DEEP_AUDIT.md`. Профили не подключают эти процессы автоматически.
Тематическое правило задаёт нормы для класса задач. Рабочие процессы конкретных задач находятся в [`../workflows/`](../workflows/) и не становятся постоянными нормативными правилами. Для совместимости manifest идентификатор `project-study` пока выбирает `workflows/PROJECT_STUDY.md`; `project-audit` выбирает `workflows/PROJECT_DEEP_AUDIT.md`, а `parallel-delivery` — `workflows/PARALLEL_DELIVERY.md`. Профили не подключают эти процессы автоматически.

## Приоритет правил

Expand Down
3 changes: 3 additions & 0 deletions scripts/check-hub.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,10 @@ $requiredPaths = @(
'workflows/PROJECT_DEEP_AUDIT_PROMPT.md',
'workflows/PROJECT_STUDY.md',
'workflows/PROJECT_STUDY_PROMPT.md',
'workflows/PARALLEL_DELIVERY.md',
'workflows/PARALLEL_DELIVERY_PROMPT.md',
'templates/DECISIONS.md',
'templates/TASK_CONTRACT.md',
'workflows/PROJECT_DEEP_AUDIT.md',
'evals/README.md',
'evals/controls.json',
Expand Down
14 changes: 12 additions & 2 deletions scripts/show-prompt.ps1
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[CmdletBinding()]
param(
[Parameter(Mandatory = $true)]
[ValidateSet('audit', 'connect', 'deep-audit', 'study')]
[ValidateSet('audit', 'connect', 'deep-audit', 'study', 'parallel')]
[string]$Name,

[string]$ProjectRoot
Expand Down Expand Up @@ -32,6 +32,12 @@ switch ($Name) {
}
$promptPath = Join-Path $hubRoot 'workflows/PROJECT_STUDY_PROMPT.md'
}
'parallel' {
if ([string]::IsNullOrWhiteSpace($ProjectRoot)) {
throw 'ProjectRoot is required for prompt parallel.'
}
$promptPath = Join-Path $hubRoot 'workflows/PARALLEL_DELIVERY_PROMPT.md'
}
}

$promptDocument = Get-Content -LiteralPath $promptPath -Raw -Encoding UTF8
Expand All @@ -41,10 +47,14 @@ if (-not $promptMatch.Success) {
}

$prompt = $promptMatch.Groups['prompt'].Value.Trim()
if ($Name -in @('connect', 'deep-audit', 'study')) {
if ($Name -in @('connect', 'deep-audit', 'study', 'parallel')) {
$resolvedProjectRoot = (Resolve-Path -LiteralPath $ProjectRoot).Path
$cliPath = Join-Path $hubRoot 'ai-rules.ps1'
$prompt = $prompt.Replace('{{PROJECT_ROOT}}', $resolvedProjectRoot).Replace('{{HUB_CLI_PATH}}', $cliPath)
if ($Name -eq 'parallel') {
$taskContractPath = Join-Path $hubRoot 'templates/TASK_CONTRACT.md'
$prompt = $prompt.Replace('{{TASK_CONTRACT_PATH}}', $taskContractPath)
}
}

Write-Output $prompt
6 changes: 6 additions & 0 deletions sync/catalog.json
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,12 @@
"kind": "workflow",
"description": "Рабочий процесс глубокого аудита проекта с явным пространством проверки и покрытием.",
"readWhen": "Только при явном выборе project-audit и задаче на глубокий системный аудит проекта."
},
"parallel-delivery": {
"file": "workflows/PARALLEL_DELIVERY.md",
"kind": "workflow",
"description": "Рабочий процесс параллельной доставки независимых подзадач с одним владельцем интеграции.",
"readWhen": "Только при явном выборе parallel-delivery и большой задаче с независимыми частями."
}
},
"profiles": {
Expand Down
3 changes: 2 additions & 1 deletion sync/project-manifest.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,8 @@
"ai-collaboration",
"research-and-evidence",
"project-study",
"project-audit"
"project-audit",
"parallel-delivery"
]
}
},
Expand Down
Loading
Loading