claude-bot
dc1cb87818
Operator capability to bring a NEW project online in one pass, fully
outside the runtime and the pipeline (src/** byte-exact, no kill-switch
needed — activation is an explicit human CLI run). Reference = the
orchestrator repo itself (ORCH-52b/c/d/e canons).
* onboarding/repo-skeleton/ — parametrized kit of a new repo: 6 agent
prompt templates per canon 52d/92 (5 ru + deployer en with the
shared-host guardrail frame), reviewer doc-gate (REQUEST_CHANGES),
CLAUDE.md passport, AGENTS.md, CONTRIBUTING.md, docs/ skeleton with
mandatory operations/INFRA.md, .env.example; {{NAME}} placeholders +
stdlib render, dictionary onboarding/placeholders.json (bijection
held by tests). Canon is NOT forked: docs/_templates + docs/_standards
are live-copied from the checkout at materialization time (BR-2/D3).
* scripts/onboard_project.py — plan (default, GET-only, zero mutations)
/ apply (idempotent ensure, no delete ops at all) / verify (registry
round-trip via the actual projects._parse_projects_json, all 22 state
names incl. fail-closed Confirm Deploy/STOP, labels, webhook, kit
completeness, unresolved-placeholder scan). Closed read-only src
import list (ADR D4); state groups fixed per ADR D5 (STOP→cancelled,
terminal groups only Done/Cancelled/STOP); Gitea webhook reuses the
single global ORCH_GITEA_WEBHOOK_SECRET (TR-6); initial push ONLY
into a freshly created empty repo (INV-4 untouched); never restarts
prod / never edits .env / deletes nothing (NFR-2); secrets masked
(NFR-3); Plane CE API gaps degrade to manual-step (fail-safe).
* docs/operations/ONBOARDING.md runbook + SETUP_WEBHOOKS.md generalized
per-repo; CLAUDE.md / docs/architecture/README.md / CHANGELOG.md
updated in the same PR (golden source).
* Anti-drift tests: test_onboarding_kit.py / test_onboarding_script.py
(mocked, no network) / test_onboarding_invariants.py (snapshots of
STAGE_TRANSITIONS/QG_CHECKS, closed CLI import list, reference
.openclaw/agents/ prompts untouched). Full regression: 1713 passed.
Refs: ORCH-009
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
38 lines
3.9 KiB
Markdown
38 lines
3.9 KiB
Markdown
# AGENTS.md — точка входа агентов проекта {{PROJECT_NAME}}
|
||
|
||
Карта документации и правила её ведения. Любой агент читает этот файл **сразу после**
|
||
`CLAUDE.md` (паспорта) и **до** начала работы.
|
||
|
||
## Карта документации
|
||
|
||
| Документ | Что в нём | Когда читать | Когда обновлять |
|
||
|----------|-----------|--------------|-----------------|
|
||
| `CLAUDE.md` | паспорт: стек, команды, среды, правила | ВСЕГДА, первым | при изменении стека/команд/правил |
|
||
| `AGENTS.md` | этот файл: карта доков | ВСЕГДА, вторым | при изменении состава доков |
|
||
| `README.md` | витрина: что это, quickstart | при онбординге в задачу | при изменении quickstart/обзора |
|
||
| `docs/ARCHITECTURE.md` | код-карта, потоки, БД | перед изменением кода | при изменении компонентов/API/БД |
|
||
| `docs/PIPELINE.md` | стадии, Quality Gates, агенты | при вопросах процесса | при изменении процесса |
|
||
| `docs/PRODUCT_VISION.md` | зачем проект, ценность | при продуктовых решениях | при смене видения |
|
||
| `docs/operations/INFRA.md` | топология, env, границы, риски общего хоста | перед deploy/инфра-работой | при изменении топологии/env |
|
||
| `docs/architecture/adr/` | сквозные ADR | перед архитектурным решением | новый сквозной ADR |
|
||
| `docs/work-items/<id>/` | артефакты конкретной задачи | свою задачу — всегда | по своей стадии |
|
||
| `docs/_templates/` | скелеты номерных доков (канон) | перед записью номерного дока | НЕ править локально |
|
||
| `docs/_standards/` | PIPELINE_DOCS / HANDOFF_PROTOCOL / TRACEABILITY (канон) | по ссылкам из промптов | НЕ править локально |
|
||
| `CHANGELOG.md` | история изменений | — | каждый PR с изменением функционала |
|
||
|
||
## Правила ведения
|
||
|
||
1. **Артефакты задач** пиши ТОЛЬКО в `docs/work-items/<id>/` по стандарту
|
||
`docs/_standards/PIPELINE_DOCS.md`; скелеты бери из `docs/_templates/` (не угадывай структуру).
|
||
2. **Машинные вердикты** — строго YAML-frontmatter; имена/регистр ключей не менять
|
||
(`docs/_standards/HANDOFF_PROTOCOL.md`).
|
||
3. **Документация = golden source.** Изменил код → обнови `docs/ARCHITECTURE.md` /
|
||
`README.md` / `CHANGELOG.md` в том же PR. Reviewer обязан вернуть PR без обновлённой доки.
|
||
4. **ADR.** Архитектурные решения фиксируются в `docs/work-items/<id>/06-adr/`; сквозные — в
|
||
`docs/architecture/adr/adr-NNNN-slug.md` (реестр — `docs/architecture/adr/README.md`).
|
||
5. **Трассировка.** Нетривиальный инвариант в коде помечается маркером
|
||
`{{WORK_ITEM_PREFIX}}-NNN`; правка чужого маркера — только после чтения его ADR
|
||
(`docs/_standards/TRACEABILITY.md`).
|
||
6. **Канон не форкается.** `docs/_templates/` и `docs/_standards/` — копия живого канона
|
||
оркестратора на момент онбординга; их обновление приходит отдельными PR, локально не править.
|