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>
52 lines
3.7 KiB
Markdown
52 lines
3.7 KiB
Markdown
# CONTRIBUTING — канон процесса проекта {{PROJECT_NAME}}
|
||
|
||
Как ведётся этот репозиторий: где что лежит, как оформлять изменения, как вести документацию.
|
||
Канон обязателен и для агентов конвейера, и для людей.
|
||
|
||
## Где что лежит
|
||
|
||
| Путь | Содержимое |
|
||
|------|-----------|
|
||
| код проекта | по код-карте `docs/ARCHITECTURE.md` |
|
||
| тесты | прогон: `{{TEST_CMD}}` |
|
||
| `.openclaw/agents/` | промпты 6 агентов конвейера (канон структуры — см. ниже) |
|
||
| `docs/` | документация (карта — `AGENTS.md`) |
|
||
| `docs/work-items/<id>/` | артефакты задач конвейера |
|
||
| `.env.example` | карта env-переменных (без секретов) |
|
||
|
||
## Процесс изменения
|
||
|
||
1. Задача рождается в Plane (проект `{{PROJECT_NAME}}`, префикс `{{WORK_ITEM_PREFIX}}`).
|
||
2. Конвейер ведёт её по стадиям (`docs/PIPELINE.md`); артефакты каждой стадии — в
|
||
`docs/work-items/<id>/` по `docs/_standards/PIPELINE_DOCS.md`.
|
||
3. Код едет веткой `feature/{{WORK_ITEM_PREFIX}}-NNN-slug` → PR в `main` → merge только через
|
||
PR-merge (никогда push в `main`).
|
||
4. Conventional Commits: `feat(scope):`, `fix(scope):`, `docs(scope):`, `refactor:`, `test:`;
|
||
футер `Refs: {{WORK_ITEM_PREFIX}}-NNN`.
|
||
5. Документация обновляется **в том же PR**, что и код (reviewer-gate вернёт PR без неё).
|
||
6. `CHANGELOG.md` — запись под `## [Unreleased]` на каждый смысловой PR.
|
||
|
||
## Промпты агентов (`.openclaw/agents/`)
|
||
|
||
- Структурный канон: 5 XML-секций в порядке `<context>` → `<task>` → `<deliverables>` →
|
||
`<constraints>` → `<output_format>`; запреты в формате «❌ X → ✅ Y»; `<escalation>` у
|
||
developer/reviewer/tester; машинные verdict-ключи байт-в-байт.
|
||
- **Языковая политика:** 5 промптов на русском + `deployer.md` на английском (самый
|
||
safety-critical промпт; en-раскладка минимизирует регресс-поверхность verdict-ключей).
|
||
Отступление от политики — только отдельным ADR этого проекта в `docs/architecture/adr/`.
|
||
- Правка промптов = обычный PR с ревью; машинные ключи (`verdict:`, `result:`,
|
||
`staging_status:`, `deploy_status:`, `security_status:`) не переименовывать.
|
||
|
||
## Документация
|
||
|
||
- Стандарты (`docs/_standards/`) и скелеты (`docs/_templates/`) — копия живого канона
|
||
оркестратора на момент онбординга; **локально не править** (обновления приходят отдельными PR).
|
||
- Сквозные решения — `docs/architecture/adr/adr-NNNN-slug.md`; per-task —
|
||
`docs/work-items/<id>/06-adr/ADR-NNN-slug.md`.
|
||
- Маркеры трассировки `{{WORK_ITEM_PREFIX}}-NNN` в коде — по `docs/_standards/TRACEABILITY.md`.
|
||
|
||
## Секреты
|
||
|
||
Секреты живут ТОЛЬКО в `.env` на хосте; в гит не коммитятся. Карта переменных — `.env.example`
|
||
(дескрипторы без значений). Утечка секрета в коммит = инцидент: ротация ключа обязательна.
|