Files

claude-bot dc1cb87818 feat(onboarding): turnkey project onboarding — kit + CLI + runbook (ORCH-009)

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>

2026-06-10 16:08:43 +03:00

5.2 KiB

Raw Blame History

CLAUDE.md — паспорт проекта {{PROJECT_NAME}}

TL;DR

Проект ведётся мульти-агентным оркестратором: задачи из Plane идут по конвейеру стадий через Quality Gates; на каждой стадии работает свой агент (analyst → architect → developer → reviewer → tester → deployer). Промпты агентов — в .openclaw/agents/ этого репо.

Стек

Команды

{{TEST_CMD}} — все тесты

Среды

prod — порт {{PROD_PORT}}
staging — порт {{STAGING_PORT}}

Детали топологии, env-карта и границы доступа — docs/operations/INFRA.md.

Привязка к оркестратору

Gitea-репо: {{GITEA_OWNER}}/{{REPO}}
Plane-проект: {{PLANE_PROJECT_ID}}
Префикс work-item: {{WORK_ITEM_PREFIX}}

Структура

docs/ARCHITECTURE.md — код-карта, потоки, БД.
docs/PIPELINE.md — конвейер стадий, Quality Gates, агенты.
docs/PRODUCT_VISION.md — зачем проект.
docs/operations/INFRA.md — RUNBOOK: топология, env, границы.
docs/architecture/adr/ — реестр сквозных ADR.
docs/work-items/<id>/ — артефакты задач (по docs/_standards/PIPELINE_DOCS.md).
docs/_templates/ — скелеты номерных документов (канон, не править локально).
docs/_standards/ — стандарты документов/handoff/трассировки (канон, не править локально).
docs/history/ — исторические записи.

Конвейер (кратко; детали — docs/PIPELINE.md)

created → analysis → architecture → development → review → testing → deploy-staging → deploy → done

Конвенции

Conventional Commits (feat:, fix:, docs:, refactor:, test:)
Ветки: feature/{{WORK_ITEM_PREFIX}}-NNN-slug, fix/{{WORK_ITEM_PREFIX}}-NNN-slug
ADR per work-item: docs/work-items/<id>/06-adr/ADR-NNN-slug.md
Сквозные ADR: docs/architecture/adr/adr-NNNN-slug.md
Машинные вердикты Quality Gate — строго YAML-frontmatter (verdict:, result:, staging_status:, deploy_status:, security_status:), никогда проза. Спека «стадия → обязательный выход» — docs/_standards/HANDOFF_PROTOCOL.md.

Артефакты задачи (`docs/work-items/<id>/`)

00-business-request.md, 01-brd.md, 02-trz.md, 03-acceptance-criteria.md, 04-test-plan.yaml, 06-adr/ADR-NNN-slug.md, 07-infra-requirements.md, 08-data-requirements.md, 10-tech-risks.md, 12-review.md, 13-test-report.md, 14-deploy-log.md, 15-staging-log.md, 16-post-deploy-log.md, 17-security-report.md, 18-coverage-report.md.

Перед написанием номерного дока бери скелет из docs/_templates/ и не меняй имя machine-key frontmatter (регистр чувствителен — иначе гейт упадёт ложно).

Правила для агентов

Перед любым действием прочесть этот файл и AGENTS.md.
Документация = golden source наравне с кодом. Изменил функционал → обнови доку В ТОМ ЖЕ PR. Архитектурное решение → заведи ADR. Обнови CHANGELOG.md.
Никогда не править артефакты других этапов.
Никогда не комментировать ТЗ задним числом — если ТЗ не годится, возвращай в Анализ.
Никогда не закрывать задачу самостоятельно — это делает CI / финальная стадия.
Reviewer проверяет: обновлена ли документация. Нет → REQUEST_CHANGES.
Не использовать --no-verify без явного одобрения Owner.
Секреты — только в .env на хосте, в гит НЕ коммитятся (канон — .env.example).
Трассировка маркеров: правишь строку/блок с маркером {{WORK_ITEM_PREFIX}}-NNN → ПЕРЕД изменением прочитай его docs/work-items/<id>/06-adr/ и не сломай зафиксированный инвариант. Стандарт — docs/_standards/TRACEABILITY.md.

⚠️ Общий хост

Проект живёт на общем хосте рядом с контейнерами других проектов. Не трогать чужие контейнеры, тома и env; рестарт прод-контура — только по процедуре docs/operations/INFRA.md.

Паспорт проекта {{PROJECT_NAME}}. Поддерживается агентами при каждой доработке. Изолирован: описывает только этот проект (канон per-repo).

5.2 KiB Raw Blame History Unescape Escape