From 0fd9fd2d0629fad345200bd907d5a1ff3e9243a3 Mon Sep 17 00:00:00 2001
From: Danil Pismenny <dapi@users.noreply.github.com>
Date: Mon, 24 Aug 2026 20:39:55 +0500
Subject: [PATCH] docs: streamline README onboarding

---
 AGENTS.md    |  11 ++
 README.md    | 240 +++++++++++++++++++++++++++--------------
 README.ru.md | 299 +++++++++++++++++++++++++++------------------------
 3 files changed, 327 insertions(+), 223 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index fa4b1cd..c4e1f29 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -38,6 +38,17 @@ Do not inspect or use files under template/memory-bank/prompts/** as workflow de
 
 Для обычных документов используйте lowercase kebab-case, например `testing-policy.md`. Для структурированных артефактов сохраняйте шаблонные naming rules, например `features/FT-XXX/` и `ADR-XXX-short-decision-name.md`.
 
+## Языковые версии README
+
+- `README.md` — канонический источник структуры, позиционирования,
+  пользовательского маршрута и технических утверждений корневой README.
+- `README.ru.md` — производная русская адаптация. Она может адаптировать
+  формулировки для русскоязычного читателя, но не добавляет и не изменяет
+  самостоятельные тезисы.
+- При изменении обеих версий сначала обновите и проверьте `README.md`, затем
+  синхронизируйте с ним `README.ru.md` по смыслу, порядку разделов, ссылкам и
+  командам.
+
 ## Правила проверки
 
 Документационный шаблон проверяется вручную через lint с явным template scope и `memory-bank-cli doctor --profile template`. При изменениях:
diff --git a/README.md b/README.md
index 4b36aa0..09166d6 100644
--- a/README.md
+++ b/README.md
@@ -1,102 +1,168 @@
 # Memory Bank
 
-**A version-controlled development system that gives coding agents durable knowledge, explicit governance, and repeatable delivery flows.**
+**Memory Bank is a version-controlled `memory-bank/` directory that coding
+agents read before work and update after delivery. It stores project knowledge,
+ownership rules, and repeatable development processes.**
 
-[Русская версия](README.ru.md) · [Quick start (Russian)](docs/quick-start.md) · [Adoption guide](docs/adoption.md) · [Daily usage](docs/usage.md)
+[Русская версия](README.ru.md) · [Quick start (Russian)](docs/quick-start.md) ·
+[Adoption guide (Russian)](docs/adoption.md) ·
+[Daily usage (Russian)](docs/usage.md)
 
-**`AGENTS.md` can tell an agent how to start. Memory Bank preserves what the project means, why decisions were made, how work moves from a problem to verified code, and what the next agent needs to know.**
-
-## What it is
-
-Memory Bank combines three parts that reinforce one another:
-
-1. **A project knowledge base** for product, domain, engineering, operations, requirements, and decisions.
-2. **A governance layer** that defines who owns each fact, how documents depend on one another, and which source wins when documents disagree.
-3. **A delivery system** whose flows turn tasks into governed artifacts, implementation, verification, and new durable knowledge.
+## What you get
 
-Memory Bank is built on the **First Principles Framework (FPF)**. Work starts from explicit facts, constraints, assumptions, and desired outcomes; decisions preserve their rationale and evidence instead of disappearing into a chat session.
+- **Durable project context** — product intent, domain language, engineering
+  rules, and operational constraints survive across agent sessions.
+- **A Single Source of Truth** — every canonical fact has one owner; derived
+  documents point back to that source instead of becoming competing copies.
+- **Governed delivery** — task routing selects the smallest suitable process for
+  incidents, bugs, research, small changes, epics, refactoring, or features.
+- **Reusable reasoning tools** — templates make the agent state the problem,
+  constraints, selected solution, implementation steps, and verification
+  evidence explicitly.
+- **A self-growing knowledge base** — delivery leaves behind decisions,
+  requirements, scenarios, and evidence that future work can reuse.
+- **A portable starting point** — an agent installs the template in a repository
+  and adapts it from that project's own evidence.
+
+## Example: complete GitHub issue #123
 
-It is not a wiki, task tracker, or agent runner. It is the development control plane around those tools: durable context, ownership rules, lifecycle gates, reusable processes, and verification contracts.
+![Running a task through Memory Bank routing](docs/assets/quick-start-routing-en.gif)
 
-Use it when a project has one or more of these symptoms:
+1. You give the agent an issue and point it to
+   `memory-bank/flows/routing.md`.
+2. The agent reads the task and project context, then Task Routing selects the
+   smallest process that still controls the risk.
+3. The selected process governs the required documents, code changes, and
+   verification. Lasting decisions and evidence return to their canonical
+   owners in Memory Bank.
 
-- a fresh agent has to reconstruct product intent from chat history;
-- the same rule appears in several documents and drifts;
-- implementation starts before requirements, risks, or acceptance are clear;
-- a task cannot be resumed without the person who ran the previous session;
-- a successful test is reported without a durable link to what was verified.
+The result is a feedback loop: project knowledge guides delivery, and delivery
+improves project knowledge.
 
-## What you get
+## Install in a project
 
-- **Durable project context** — product intent, domain language, engineering rules, and operational constraints survive across sessions.
-- **A Single Source of Truth** — every canonical fact has one owner; derived documents point back to that source instead of becoming competing copies.
-- **Governed delivery** — task routing selects the smallest suitable flow for incidents, bugs, research, small changes, epics, refactoring, or features.
-- **Reusable reasoning tools** — artifact templates make the agent state the problem, constraints, selected solution, implementation steps, and verification evidence explicitly.
-- **A self-growing knowledge base** — delivery leaves behind decisions, requirements, scenarios, and evidence that future work can reuse.
-- **A portable starting point** — an agent brings the template into a repository and adapts it from the project's own evidence.
+You need Git, an installed and authenticated
+[Codex CLI](https://developers.openai.com/codex/cli/), and a project repository.
+Run the matching command from the project root.
 
-![Running a task through Memory Bank routing](docs/assets/quick-start-routing-en.gif)
+### Existing project
 
-The result is a feedback loop: project knowledge guides delivery, and delivery improves project knowledge.
+```bash
+codex --search \
+  'This is an existing project. Follow https://github.com/dapi/memory-bank/blob/main/docs/brownfield-adaptation-protocol.md.'
+```
 
-## Start with an agent
+### New project
 
-Copy the prompt that matches the repository. It tells the agent to bring in and
-adapt Memory Bank; the linked protocols define the full lifecycle.
+```bash
+codex --search \
+  'This is a new project. Follow https://github.com/dapi/memory-bank/blob/main/docs/greenfield-integration-protocol.md.'
+```
 
-### Greenfield
+The agent studies the repository, installs the tracked template payload, and
+adapts it to confirmed project facts. The expected starting point is:
 
 ```text
-This is a new project. Follow
-https://github.com/dapi/memory-bank/blob/main/docs/greenfield-integration-protocol.md.
+memory-bank/
+init.sh
 ```
 
-### Brownfield
+Review the installation before continuing:
 
-```text
-This is an existing project. Follow
-https://github.com/dapi/memory-bank/blob/main/docs/brownfield-adaptation-protocol.md.
+```bash
+git status --short
+git diff --check
 ```
 
-For reproducible use, replace `main` in a protocol URL with an immutable commit
-SHA.
+For reproducible use, replace `main` in the protocol URL with an immutable
+commit SHA. The [adoption guide (Russian)](docs/adoption.md) explains the full
+lifecycle, expected artifacts, and completion criteria.
 
-## Deliver a task
+## Run the first task
 
-After Memory Bank is adapted, give the agent the task and this prompt:
+After Memory Bank is adapted, give Codex a real task and the routing entrypoint:
 
-```text
-Read the task, ./memory-bank/README.md, and ./memory-bank/flows/routing.md.
-Choose the applicable flow and follow its canonical lifecycle. Report the route,
-changed artifacts, verification, and open risks.
+```bash
+codex -C . \
+  'Read GitHub issue #123, ./memory-bank/README.md, and ./memory-bank/flows/routing.md.
+Choose the applicable process and follow its canonical lifecycle. Report the
+route, changed artifacts, verification, and open risks.'
 ```
 
-The [daily usage guide](docs/usage.md) explains the task-to-flow-to-verification
-cycle and its smaller routes.
+Replace `#123` with the real issue number, or describe the task directly if the
+project does not use GitHub Issues. A successful run leaves a sufficient,
+verifiable trail rather than the largest possible set of documents.
+
+## Where to go next
+
+Most supporting guides are currently available in Russian.
+
+| Goal | Read or use |
+| --- | --- |
+| Complete a guided first task | [Quick start](docs/quick-start.md) |
+| Adapt Memory Bank to a new or existing repository | [Adoption guide](docs/adoption.md) |
+| Use Memory Bank for daily delivery | [Daily usage](docs/usage.md) |
+| Prepare only the context relevant to one task | [Context priming](docs/context-priming.md) |
+| Automate issue startup | [`start-issue`](https://github.com/dapi/start-issue) or [Symphony](docs/symphony-github-issues.md) |
+| Look up project-memory terminology | [Glossary](docs/glossary.md) |
 
 ## How it works
 
+### Knowledge, governance, and delivery
+
+Memory Bank combines three parts that reinforce one another:
+
+1. **A project knowledge base** for product, domain, engineering, operations,
+   requirements, and decisions.
+2. **A governance layer** that defines who owns each fact, how documents depend
+   on one another, and which source wins when documents disagree.
+3. **A delivery system** whose processes turn tasks into governed artifacts,
+   implementation, verification, and new durable knowledge.
+
+Memory Bank is built on the **First Principles Framework (FPF)**. Work starts
+from explicit facts, constraints, assumptions, and desired outcomes; decisions
+preserve their rationale and evidence instead of disappearing into a chat
+session.
+
+It is not a wiki, task tracker, or agent runner. It is the development control
+plane around those tools: durable context, ownership rules, lifecycle gates,
+reusable processes, and verification contracts.
+
+It is useful when project intent has to be reconstructed from chat history,
+rules drift across documents, implementation starts before acceptance is clear,
+or another agent cannot resume the work from repository state.
+
 ### DNA and Single Source of Truth
 
-The `dna/` layer is the constitution of the knowledge base. It defines Single Source of Truth, document ownership, dependency direction, lifecycle, frontmatter, and navigation rules. These principles keep Memory Bank internally consistent as it grows.
+The `dna/` layer is the constitution of the knowledge base. It defines Single
+Source of Truth, document ownership, dependency direction, lifecycle,
+frontmatter, and navigation rules.
 
-A canonical document owns a fact. Another document may derive a requirement, plan, or view from it, but must preserve the dependency. When two documents disagree, ownership and dependency direction show which source is authoritative.
+A canonical document owns a fact. Another document may derive a requirement,
+plan, or view from it, but must preserve the dependency. When documents
+disagree, ownership and dependency direction identify the authoritative source.
 
 ### Project knowledge
 
-Stable project context lives in `product/`, `domain/`, `engineering/`, and `ops/`. Research, product initiatives, scenarios, delivery packages, and decisions live in `research/`, `prd/`, `epics/`, `use-cases/`, `features/`, and `adr/`.
-
-Documents own intent, requirements, rationale, and contracts. Code owns implementation. A fresh agent session can therefore resume from the same task and canonical sources without reconstructing the project from chat history.
+Stable project context lives in `product/`, `domain/`, `engineering/`, and
+`ops/`. Research, product initiatives, scenarios, delivery packages, and
+decisions live in `research/`, `prd/`, `epics/`, `use-cases/`, `features/`, and
+`adr/`.
 
-### Flows and Feature Packs
+Documents own intent, requirements, rationale, and contracts. Code owns
+implementation. A fresh agent session can therefore resume from the same task
+and canonical sources without reconstructing the project from chat history.
 
-The `flows/` layer describes repeatable processes that an agent can follow. Every task begins with [Task Routing](template/memory-bank/flows/routing.md), which selects the applicable lifecycle and its evidence requirements.
+### Processes and Feature Packs
 
-For a substantial feature, Feature Flow produces a Feature Pack in three stages:
+The `flows/` layer describes repeatable processes that an agent can follow.
+Every task begins with
+[Task Routing](template/memory-bank/flows/routing.md), which selects the
+applicable lifecycle and its evidence requirements.
 
-The flow treats the feature as a testable vertical slice and follows
-specification-driven development: the documents required by the selected route
-are created and reviewed before implementation begins.
+For a substantial feature, Feature Flow treats the change as a testable
+vertical slice and follows specification-driven development. It produces a
+Feature Pack in three stages:
 
 ```text
 brief.md                 design.md                  implementation-plan.md
@@ -105,23 +171,38 @@ problem space            solution space             execution space
 ```
 
 - `brief.md` owns the problem, scope, requirements, and verification contract;
-- the Design Pack owns the selected solution, its rationale, and solution-level contracts;
+- the Design Pack owns the selected solution, its rationale, and
+  solution-level contracts;
 - `implementation-plan.md` owns execution sequencing and checkpoints.
 
-The implementation changes the code, while lasting decisions and evidence return to their canonical owners in Memory Bank. The Feature Pack remains as a durable account of what changed, why it changed, and how the result was verified.
+The documents required by the selected route are created and reviewed before
+implementation begins. Implementation changes the code, while lasting
+decisions and evidence return to their canonical owners. The Feature Pack
+remains as a durable account of what changed, why it changed, and how the result
+was verified.
 
 ### Templates as reasoning tools
 
-The templates in `flows/templates/` are not merely blank forms. They require an agent to separate the problem, solution, execution, and verification; name assumptions and constraints; compare meaningful alternatives; and preserve traceability. Filling the template therefore improves the decision process as well as its documentation.
+Templates in `flows/templates/` are not merely blank forms. They require an
+agent to separate the problem, solution, execution, and verification; name
+assumptions and constraints; compare meaningful alternatives; and preserve
+traceability. Filling the template improves the decision process as well as its
+documentation.
 
 ## Automation
 
-Memory Bank does not require a runner or CLI, but this repository includes two automation paths:
+Memory Bank does not require a runner or CLI. Automation is optional:
 
-- the optional [`memory-bank-cli`](docs/memory-bank.md) adds ownership-aware updates, link checks, diagnostics, and downstream CI;
-- the experimental [Symphony integration](docs/symphony-github-issues.md) dispatches selected GitHub Issues to Codex in isolated workspaces and hands completed pull requests to human review.
+- [`start-issue`](https://github.com/dapi/start-issue) prepares a branch and
+  worktree, then launches the configured agent for one issue;
+- [`memory-bank-cli`](docs/memory-bank.md) adds ownership-aware updates, link
+  checks, diagnostics, and downstream CI;
+- the experimental [Symphony integration](docs/symphony-github-issues.md)
+  dispatches selected GitHub Issues to Codex in isolated workspaces and hands
+  completed pull requests to human review.
 
-Symphony runs agents and repository work. Memory Bank supplies the knowledge, governance, delivery flows, and verification contracts those agents follow.
+Runners launch agents and repository work. Memory Bank supplies the knowledge,
+governance, delivery processes, and verification contracts those agents follow.
 
 ## Template layout
 
@@ -140,23 +221,22 @@ This repository is the upstream source. An agent copies the tracked payload in
 | [`use-cases/`](template/memory-bank/use-cases/README.md), [`features/`](template/memory-bank/features/README.md), [`adr/`](template/memory-bank/adr/README.md) | Scenarios, delivery packages, and architecture decisions |
 | [`flows/`](template/memory-bank/flows/README.md) | Task lifecycles and reusable document templates |
 
-After installation, `memory-bank/README.md` is the primary index inside the downstream project.
+After installation, `memory-bank/README.md` is the primary index inside the
+downstream project.
 
-## Documentation
+## Reference
 
-- [Quick start (Russian)](docs/quick-start.md)
-- [Adopting Memory Bank](docs/adoption.md)
-- [Using Memory Bank day to day](docs/usage.md)
-- [Context priming for an agent task](docs/context-priming.md)
-- [Glossary](docs/glossary.md)
-- [Optional CLI automation](docs/memory-bank.md)
-- [Symphony with GitHub Issues](docs/symphony-github-issues.md)
+- [BDD, user stories, and use cases](docs/bdd-user-stories-and-use-cases.md)
 - [Ownership and safe updates](docs/ownership.md)
+- [Managed agent instructions](docs/agent-instructions.md)
 - [Repository development](docs/development.md)
-- [Detailed overview in Russian](README.ru.md)
+- [Detailed Russian adaptation](README.ru.md)
 
-The governance model applies the [MECE principle](https://en.wikipedia.org/wiki/MECE_principle): categories should be mutually exclusive and collectively exhaustive within their declared scope.
+The governance model applies the
+[MECE principle](https://en.wikipedia.org/wiki/MECE_principle): categories
+should be mutually exclusive and collectively exhaustive within their declared
+scope.
 
-The optional CLI for safe updates and automated checks is developed separately
-in [`dapi/memory-bank-cli`](https://github.com/dapi/memory-bank-cli). This
-template is available under the [Apache License 2.0](LICENSE).
+The optional CLI is developed separately in
+[`dapi/memory-bank-cli`](https://github.com/dapi/memory-bank-cli). This template
+is available under the [Apache License 2.0](LICENSE).
diff --git a/README.ru.md b/README.ru.md
index f38038f..2a60b5e 100644
--- a/README.ru.md
+++ b/README.ru.md
@@ -1,110 +1,171 @@
-# Memory Bank — система разработки программного обеспечения с ИИ-агентами
+# Memory Bank — система разработки с ИИ-агентами
 
-**Версионируемая система, которая даёт агентам долговременные знания о проекте, явные правила и повторяемые процессы разработки.**
+**Memory Bank — это версионируемая директория `memory-bank/`, которую
+агенты читают до начала работы и обновляют после завершения задачи. В ней
+хранятся знания о проекте, правила владения и повторяемые процессы разработки.**
 
-[English version](README.md) · [Быстрый старт](docs/quick-start.md) · [Внедрение](docs/adoption.md) · [Повседневная работа](docs/usage.md)
+[English version](README.md) · [Быстрый старт](docs/quick-start.md) ·
+[Внедрение](docs/adoption.md) · [Повседневная работа](docs/usage.md)
 
-**`AGENTS.md` объясняет агенту, как начать. Memory Bank сохраняет смысл проекта, причины принятых решений, путь от задачи до проверенного кода и знания, необходимые следующему агенту.**
-
-## Что это
-
-Memory Bank объединяет три взаимосвязанные части:
-
-1. **Базу знаний проекта** — сведения о продукте, предметной области, инженерии, эксплуатации, требованиях и решениях.
-2. **Правила управления знаниями** — кто владеет каждым фактом, как документы зависят друг от друга и какому источнику доверять при противоречии.
-3. **Систему процессов разработки** — как превратить задачу в согласованные документы, реализацию, проверку и новые долговременные знания.
+## Что вы получаете
 
-В основе Memory Bank лежит **First Principles Framework (FPF), метод мышления от первых принципов**. Работа начинается с явно сформулированных фактов, ограничений, допущений и желаемого результата, а решения сохраняют обоснование и подтверждения вместо того, чтобы исчезнуть вместе с историей чата.
+- **Долговременный контекст проекта** — замысел продукта, язык предметной
+  области, инженерные правила и эксплуатационные ограничения сохраняются
+  между сессиями агента.
+- **Единственный источник истины** — у каждого канонического факта есть один
+  владелец, а производные документы ссылаются на него вместо создания
+  конкурирующих копий.
+- **Управляемая разработка** — маршрутизация выбирает наименьший подходящий
+  процесс для инцидента, дефекта, исследования, небольшого изменения, крупной
+  инициативы, рефакторинга или функционального изменения.
+- **Повторяемые инструменты мышления** — шаблоны заставляют агента явно
+  сформулировать проблему, ограничения, выбранное решение, шаги реализации и
+  подтверждения результата.
+- **Самонаполняющаяся база знаний** — после разработки остаются решения,
+  требования, сценарии и подтверждения, которые используют следующие задачи.
+- **Переносимая точка старта** — агент устанавливает шаблон в репозиторий и
+  адаптирует его по фактам этого проекта.
+
+## Пример: выполнить GitHub issue #123
 
-Memory Bank — не вики, не трекер задач и не инструмент запуска агентов. Это управляющий слой разработки вокруг этих инструментов: долговременный контекст, правила владения знаниями, этапы готовности, повторяемые процессы и критерии проверки.
+![Запуск задачи через маршрутизацию Memory Bank](docs/assets/quick-start-routing.gif)
 
-Memory Bank полезен, если в проекте встречается хотя бы одна из этих проблем:
+1. Вы передаёте агенту задачу и указываете
+   `memory-bank/flows/routing.md`.
+2. Агент читает задачу и контекст проекта, а маршрутизация выбирает
+   наименьший процесс, который сохраняет контроль над риском.
+3. Выбранный процесс определяет нужные документы, изменения кода и
+   проверки. Долговременные решения и подтверждения возвращаются к своим
+   каноническим владельцам в Memory Bank.
 
-- новый агент вынужден восстанавливать замысел продукта из истории переписки;
-- одно правило записано в нескольких документах, и версии начинают расходиться;
-- реализация начинается до прояснения требований, рисков и критериев приёмки;
-- задачу нельзя продолжить без человека, который вёл предыдущую сессию;
-- успешная проверка заявлена, но не связана с тем, что именно проверялось.
+Так возникает замкнутый цикл: знания проекта направляют разработку, а её
+результаты улучшают знания.
 
-## Что вы получаете
+## Установить в проект
 
-- **Долговременный контекст проекта** — замысел продукта, язык предметной области, инженерные правила и эксплуатационные ограничения сохраняются между сессиями.
-- **Единственный источник истины** — у каждого канонического факта есть один владелец, а производные документы ссылаются на него, а не создают конкурирующие копии.
-- **Управляемую разработку** — маршрутизация выбирает наименьший подходящий процесс для инцидента, дефекта, исследования, небольшой задачи, крупной инициативы, рефакторинга или функционального изменения.
-- **Повторяемые инструменты мышления** — шаблоны заставляют явно сформулировать проблему, ограничения, выбранное решение, шаги реализации и подтверждения результата.
-- **Самонаполняющуюся базу знаний** — после разработки остаются решения, требования, сценарии и подтверждения, которыми воспользуются следующие задачи.
-- **Переносимую точку старта** — агент устанавливает шаблон в репозиторий и адаптирует его по фактам самого проекта.
+Вам нужны Git, установленный и авторизованный
+[Codex CLI](https://developers.openai.com/codex/cli/) и репозиторий проекта.
+Запустите подходящую команду из корня проекта.
 
-![Запуск задачи через маршрутизацию Memory Bank](docs/assets/quick-start-routing.gif)
+### Существующий проект
 
-Так возникает замкнутый цикл: знания проекта направляют разработку, а результаты разработки улучшают знания проекта.
+```bash
+codex --search \
+  'Это существующий проект. Выполни https://github.com/dapi/memory-bank/blob/main/docs/brownfield-adaptation-protocol.md.'
+```
 
-## Начать с агентом
+### Новый проект
 
-Скопируйте запрос для своего типа проекта. Он поручает агенту установить и
-адаптировать Memory Bank; полный жизненный цикл определяют связанные протоколы.
+```bash
+codex --search \
+  'Это новый проект. Выполни https://github.com/dapi/memory-bank/blob/main/docs/greenfield-integration-protocol.md.'
+```
 
-### Новый проект
+Агент изучит репозиторий, установит отслеживаемое содержимое шаблона и
+адаптирует его по подтверждённым фактам проекта. Начальный результат:
 
 ```text
-Это новый проект. Выполни
-https://github.com/dapi/memory-bank/blob/main/docs/greenfield-integration-protocol.md.
+memory-bank/
+init.sh
 ```
 
-### Существующий проект
+Перед продолжением просмотрите установленные изменения:
 
-```text
-Это существующий проект. Выполни
-https://github.com/dapi/memory-bank/blob/main/docs/brownfield-adaptation-protocol.md.
+```bash
+git status --short
+git diff --check
 ```
 
 Для воспроизводимого запуска замените `main` в адресе протокола на неизменяемый
-идентификатор коммита.
+идентификатор коммита. [Инструкция по внедрению](docs/adoption.md) описывает полный
+жизненный цикл, ожидаемые артефакты и критерии готовности.
 
-## Выполнить задачу
+## Выполнить первую задачу
 
-После адаптации Memory Bank передайте агенту задачу и этот запрос:
+После адаптации Memory Bank передайте Codex реальную задачу и точку входа в
+маршрутизацию:
 
-```text
-Прочитай задачу, ./memory-bank/README.md и ./memory-bank/flows/routing.md.
+```bash
+codex -C . \
+  'Прочитай GitHub issue #123, ./memory-bank/README.md и ./memory-bank/flows/routing.md.
 Выбери подходящий процесс и следуй его каноническому жизненному циклу. В финале
-сообщи выбранный маршрут, изменённые документы, результаты проверок и открытые
-риски.
+сообщи маршрут, изменённые документы, результаты проверок и открытые риски.'
 ```
 
-![Запуск задачи через маршрутизацию Memory Bank](docs/assets/quick-start-routing.gif)
+Замените `#123` на номер реальной задачи или опишите задачу прямо, если проект не
+использует GitHub Issues. Успешный запуск оставляет достаточный проверяемый след, а не
+максимальное количество документов.
 
-[Инструкция по повседневной работе](docs/usage.md) объясняет цикл «задача →
-процесс → проверка» и короткие маршруты.
+## Куда идти дальше
+
+| Цель | Что читать или использовать |
+| --- | --- |
+| Пройти первую задачу по готовому сценарию | [Быстрый старт](docs/quick-start.md) |
+| Адаптировать Memory Bank к новому или существующему репозиторию | [Внедрение](docs/adoption.md) |
+| Использовать Memory Bank в повседневной разработке | [Повседневная работа](docs/usage.md) |
+| Подготовить только уместный для задачи контекст | [Подготовка контекста](docs/context-priming.md) |
+| Автоматизировать запуск задач | [`start-issue`](https://github.com/dapi/start-issue) или [Symphony](docs/symphony-github-issues.md) |
+| Уточнить термины проектной памяти | [Словарь](docs/glossary.md) |
 
 ## Как это работает
 
+### Знания, правила и разработка
+
+Memory Bank объединяет три взаимосвязанные части:
+
+1. **Базу знаний проекта** — сведения о продукте, предметной области, инженерии,
+   эксплуатации, требованиях и решениях.
+2. **Правила управления знаниями** — кто владеет каждым фактом, как документы
+   зависят друг от друга и какому источнику доверять при противоречии.
+3. **Систему процессов разработки** — как превратить задачу в управляемые документы,
+   реализацию, проверку и новые долговременные знания.
+
+В основе Memory Bank лежит **First Principles Framework (FPF), метод мышления от
+первых принципов**. Работа начинается с явно сформулированных фактов,
+ограничений, допущений и желаемого результата, а решения сохраняют обоснование и
+подтверждения вместо того, чтобы исчезнуть вместе с историей чата.
+
+Memory Bank — не вики, не трекер задач и не инструмент запуска агентов. Это управляющий
+слой разработки вокруг этих инструментов: долговременный контекст, правила владения знаниями,
+этапы готовности, повторяемые процессы и критерии проверки.
+
+Memory Bank полезен, когда замысел проекта приходится восстанавливать из истории чатов,
+правила расходятся между документами, реализация начинается до прояснения критериев или
+другой агент не может продолжить работу по состоянию репозитория.
+
 ### ДНК и единственный источник истины
 
-`dna/` — конституция базы знаний. Здесь определены принцип единственного источника истины, владение документами, направление зависимостей, жизненный цикл, метаданные и правила навигации. Эти принципы сохраняют внутреннюю согласованность Memory Bank по мере его роста.
+`dna/` — конституция базы знаний. Здесь определены принцип единственного источника истины,
+владение документами, направление зависимостей, жизненный цикл, метаданные и правила
+навигации.
 
-Канонический документ владеет фактом. Другой документ может вывести из него требование, план или представление, но обязан сохранить зависимость от источника. Если документы противоречат друг другу, правила владения и направление зависимостей показывают, какой источник является авторитетным.
+Канонический документ владеет фактом. Другой документ может вывести из него требование, план или
+представление, но обязан сохранить зависимость от источника. Если документы противоречат друг
+другу, правила владения и направление зависимостей указывают авторитетный источник.
 
 ### Знания о проекте
 
-Постоянный контекст проекта находится в `product/`, `domain/`, `engineering/` и `ops/`. Исследования, продуктовые инициативы, сценарии, комплекты документов разработки и решения находятся в `research/`, `prd/`, `epics/`, `use-cases/`, `features/` и `adr/`.
+Постоянный контекст проекта находится в `product/`, `domain/`, `engineering/` и `ops/`.
+Исследования, продуктовые инициативы, сценарии, комплекты документов разработки и решения
+находятся в `research/`, `prd/`, `epics/`, `use-cases/`, `features/` и `adr/`.
 
-Документы владеют замыслом, требованиями, обоснованием решений и контрактами. Код владеет реализацией. Поэтому новую сессию агента можно начать с той же задачи и канонических источников, не восстанавливая проект из истории переписки.
+Документы владеют замыслом, требованиями, обоснованием решений и контрактами. Код владеет
+реализацией. Поэтому новая сессия агента может продолжить работу с той же задачи и канонических
+источников, не восстанавливая проект из истории чата.
 
 ### Процессы и Feature Pack
 
-В `flows/` описаны повторяемые процессы, которым может следовать агент. Каждая задача начинается с [маршрутизации](template/memory-bank/flows/routing.md): она выбирает подходящий жизненный цикл и необходимые подтверждения.
-
-Для значимого функционального изменения процесс Feature Flow создаёт Feature Pack — комплект документов фичи, который проходит три стадии:
+В `flows/` описаны повторяемые процессы, которым может следовать агент. Каждая задача
+начинается с [маршрутизации](template/memory-bank/flows/routing.md), которая выбирает подходящий
+жизненный цикл и необходимые подтверждения.
 
-Процесс рассматривает функциональное изменение как проверяемый вертикальный
-срез и следует разработке на основе спецификации: предусмотренные
-выбранным маршрутом документы создаются и проходят проверку до начала
-реализации.
+Для значимого функционального изменения Feature Flow рассматривает задачу как проверяемый
+вертикальный срез и следует разработке на основе спецификации. Процесс создаёт Feature Pack в три
+стадии:
 
 ```text
 brief.md                 design.md                  implementation-plan.md
-что и зачем       →      выбранное решение   →     реализация и проверки
+что и зачем       →      выбранное решение     →     реализация и проверки
 пространство задачи      пространство решения      пространство исполнения
 ```
 
@@ -112,26 +173,38 @@ brief.md                 design.md                  implementation-plan.md
 - дизайн-пакет владеет выбранным решением, его обоснованием и контрактами решения;
 - `implementation-plan.md` владеет порядком реализации и контрольными точками.
 
-Реализация изменяет код, а долговременные решения и подтверждения возвращаются к своим каноническим владельцам в Memory Bank. Feature Pack остаётся описанием того, что изменилось, почему это изменилось и как был проверен результат.
+Предусмотренные выбранным маршрутом документы создаются и проходят проверку до начала
+реализации. Реализация изменяет код, а долговременные решения и подтверждения возвращаются к
+своим каноническим владельцам. Feature Pack остаётся долговременным описанием того, что изменилось,
+почему и как был проверен результат.
 
 ### Шаблоны как инструменты мышления
 
-Шаблоны в `flows/templates/` — не пустые бланки. Они требуют от агента разделить задачу, решение, исполнение и проверку; назвать допущения и ограничения; сравнить значимые варианты; сохранить прослеживаемость. Поэтому заполнение шаблона улучшает не только документацию, но и сам процесс принятия решения.
+Шаблоны в `flows/templates/` — не пустые бланки. Они требуют от агента разделить задачу,
+решение, исполнение и проверку; назвать допущения и ограничения; сравнить значимые варианты и
+сохранить прослеживаемость. Заполнение шаблона улучшает не только документацию, но и сам процесс
+принятия решения.
 
 ## Автоматизация
 
-Для базовой работы Memory Bank не требует отдельного инструмента запуска или командной утилиты, но этот репозиторий содержит два направления автоматизации:
+Для базовой работы Memory Bank не требует отдельного инструмента запуска или командной утилиты.
+Автоматизация необязательна:
 
-- необязательная утилита [`memory-bank-cli`](docs/memory-bank.md) добавляет безопасные обновления с учётом владельцев, проверку ссылок, диагностику и проверки в непрерывной интеграции;
-- экспериментальная [интеграция с Symphony](docs/symphony-github-issues.md) передаёт выбранные задачи GitHub агенту Codex в изолированных рабочих директориях, а готовые запросы на слияние направляет человеку на проверку.
+- [`start-issue`](https://github.com/dapi/start-issue) готовит ветку и директорию worktree, а затем
+  запускает настроенного агента для одной задачи;
+- [`memory-bank-cli`](docs/memory-bank.md) добавляет обновления с учётом владельцев, проверку
+  ссылок, диагностику и проверки в непрерывной интеграции;
+- экспериментальная [интеграция с Symphony](docs/symphony-github-issues.md) передаёт выбранные задачи GitHub
+  агенту Codex в изолированных рабочих директориях и передаёт готовые запросы на слияние человеку
+  на проверку.
 
-Symphony запускает агентов и работу с репозиторием. Memory Bank предоставляет знания, правила, процессы разработки и критерии проверки, которым следуют эти агенты.
+Инструменты запускают агентов и работу с репозиторием. Memory Bank предоставляет знания,
+правила, процессы разработки и критерии проверки, которым следуют эти агенты.
 
 ## Что находится в шаблоне
 
-В этом исходном репозитории содержимое шаблона хранится в `template/`. Агент
-переносит файлы, отслеживаемые Git, из этой директории в корень проекта-получателя:
-например, `template/memory-bank/` становится `memory-bank/`, а
+Этот репозиторий — исходник шаблона. Агент переносит отслеживаемое содержимое из
+`template/` в корень проекта-получателя: `template/memory-bank/` становится `memory-bank/`, а
 `template/init.sh` — `./init.sh`.
 
 | Директория | Назначение |
@@ -145,80 +218,20 @@ Symphony запускает агентов и работу с репозитор
 | [`use-cases/`](template/memory-bank/use-cases/README.md), [`features/`](template/memory-bank/features/README.md), [`adr/`](template/memory-bank/adr/README.md) | Сценарии, комплекты документов разработки и архитектурные решения |
 | [`flows/`](template/memory-bank/flows/README.md) | Жизненные циклы задач и повторно используемые шаблоны документов |
 
-После установки [`memory-bank/README.md`](template/memory-bank/README.md) становится основным указателем внутри проекта-получателя.
+После установки `memory-bank/README.md` становится основным указателем внутри проекта-получателя.
 
-Корневой [`template/init.sh`](template/init.sh) — переносимый сценарий начальной
-настройки для `mise`, вложенных репозиториев Git и `direnv`, если соответствующие
-файлы есть в проекте. После установки адаптируйте `./init.sh` под реальные
-команды установки зависимостей, подготовки базы данных и запуска служб; сценарий
-намеренно не переносит файлы `.env`.
+## Справочные материалы
 
-## Внедрение в проект
+- [BDD, пользовательские истории и сценарии использования](docs/bdd-user-stories-and-use-cases.md)
+- [Владение и безопасные обновления](docs/ownership.md)
+- [Управляемый блок инструкций агента](docs/agent-instructions.md)
+- [Разработка репозитория](docs/development.md)
+- [Каноническая английская версия](README.md)
 
-В проект-получатель устанавливаются директория `memory-bank/` и сценарий
-`init.sh`. Исходники командной утилиты, модуль Go, непрерывная интеграция и
-настройки выпуска этого репозитория не входят в шаблон приложения. Безопасные
-автоматические обновления и проверки — необязательное расширение, а не условие
-базового внедрения.
+Модель управления применяет
+[принцип MECE](https://en.wikipedia.org/wiki/MECE_principle): категории не должны пересекаться и
+вместе должны покрывать объявленную область.
 
-Инструкция по внедрению охватывает:
-
-- адаптацию существующего проекта;
-- запуск нового проекта;
-- настройку агента;
-- локальную проверку и проверки проекта-получателя в непрерывной интеграции.
-
-Следуйте [инструкции по внедрению](docs/adoption.md).
-
-## Выбор рабочего процесса
-
-Каждая задача сначала проходит [маршрутизацию](template/memory-bank/flows/routing.md). Она направляет работу в процесс обработки инцидента, исправления дефекта, исследования, небольшого изменения, крупной инициативы, рефакторинга или функционального изменения либо передаёт выбор человеку.
-
-Корневой README даёт только обзор. Условия входа, жизненные циклы, обязательные документы и критерии завершения принадлежат каноническим документам в [`memory-bank/flows/`](template/memory-bank/flows/README.md) и не дублируются здесь.
-
-## Документация репозитория
-
-| Документ | Для кого и зачем |
-| --- | --- |
-| [Быстрый старт](docs/quick-start.md) | Для установки Memory Bank и запуска первой реальной задачи через Codex |
-| [Внедрение Memory Bank](docs/adoption.md) | Для команд, подключающих шаблон к существующему или новому проекту |
-| [Протокол адаптации существующего проекта](docs/brownfield-adaptation-protocol.md) | Для основанной на фактах адаптации репозитория до и после установки Memory Bank |
-| [Протокол создания нового проекта](docs/greenfield-integration-protocol.md) | Для копирования шаблона, извлечения фактов из README и документации, адаптации Memory Bank и создания исходного описания продукта |
-| [Использование Memory Bank](docs/usage.md) | Для повседневной работы с задачами и ИИ-агентами после внедрения |
-| [Подготовка контекста](docs/context-priming.md) | Для подготовки ИИ-агента к конкретной задаче и сбора уместного контекста |
-| [Пользовательские истории, варианты использования и BDD-сценарии](docs/bdd-user-stories-and-use-cases.md) | Для разделения устойчивого сценария, поставляемой части функции и проверяемых примеров поведения |
-| [Необязательная автоматизация через CLI](docs/memory-bank.md) | Для безопасных обновлений и проверок проекта-получателя в непрерывной интеграции |
-| [Symphony и задачи GitHub](docs/symphony-github-issues.md) | Для автоматического запуска Codex по выбранным задачам GitHub |
-| [Словарь](docs/glossary.md) | Для терминов управления знаниями и структуры документации |
-| [Владение и безопасные обновления](docs/ownership.md) | Для понимания схемы блокировки, границ владения и правил разрешения конфликтов |
-| [Управляемый блок инструкций агента](docs/agent-instructions.md) | Для служебных меток, диагностики и выбора единственного файла инструкций агента |
-| [Разработка репозитория](docs/development.md) | Для разработчиков шаблона |
-
-Необязательная утилита `memory-bank-cli` добавляет безопасные обновления,
-проверку ссылок и диагностику правил. Она разрабатывается и выпускается отдельно
-в [`dapi/memory-bank-cli`](https://github.com/dapi/memory-bank-cli).
-
-## Развитие шаблона
-
-### Методические основания
-
-- **First Principles Framework (FPF)** — основание для принятия решений от явных фактов, ограничений и проверяемых следствий;
-- [принцип MECE](https://en.wikipedia.org/wiki/MECE_principle) — непересекающиеся категории, которые вместе покрывают заявленную область;
-- Dan North, [*Introducing BDD*](https://dannorth.net/blog/introducing-bdd/) — первичный источник разработки через поведение: уточнение требований через ценность для бизнеса, конкретные примеры и исполняемые сценарии приёмки в форме `Given / When / Then`;
-- Philippe Kruchten, [*Architectural Blueprints — The “4+1” View Model of Software Architecture*](https://arxiv.org/abs/2006.04975) — первичный источник проверки архитектуры через логическое представление, процессы, разработку и физическое размещение, связанные ключевыми сценариями; [краткий обзор](https://en.wikipedia.org/wiki/4%2B1_architectural_view_model);
-- Nenad Medvidovic, Richard N. Taylor, [*A Classification and Comparison Framework for Software Architecture Description Languages*](https://ics.uci.edu/~taylor/documents/2000-ADLs-TSE.pdf) — источник архитектурной модели компонентов, связей и конфигураций.
-
-### Проекты, в которых развивается практика
-
-Эти репозитории используют и адаптируют Memory Bank под конкретные проекты.
-Опыт их эксплуатации может становиться источником обобщаемых правил для
-шаблона, но сведения о конкретном проекте остаются в его собственной копии
-Memory Bank.
-
-- [`dapi/zelma`](https://github.com/dapi/zelma);
-- [`brandymint/merchantly`](https://github.com/brandymint/merchantly);
-- [`alfagen/mercury`](https://github.com/alfagen/mercury).
-
-Добавляйте в шаблон только обобщаемые правила. Названия продуктов,
-инфраструктурные подробности и другие сведения о конкретном проекте должны
-оставаться в его собственной копии `memory-bank/`.
+Необязательная командная утилита разрабатывается отдельно в
+[`dapi/memory-bank-cli`](https://github.com/dapi/memory-bank-cli). Шаблон доступен по лицензии
+[Apache License 2.0](LICENSE).