Skip to content

docs: streamline README onboarding #129

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dapi merged 2 commits into from
Aug 24, 2026
Merged

docs: streamline README onboarding #129

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0fd9fd2
docs: streamline README onboarding
dapi Aug 24, 2026
3b17fe8
Merge branch 'main' into docs/readme-onboarding
dapi Aug 24, 2026
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
11 changes: 11 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`. При изменениях:
Expand Down
236 changes: 157 additions & 79 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,101 +6,165 @@

**A version-controlled development system that gives coding agents durable knowledge, explicit governance, and repeatable delivery flows.**

[Русская версия](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
Expand All @@ -109,23 +173,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

Expand All @@ -144,23 +223,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).
Loading
Loading