Stage 2: a concepts page, and a docs site with a Development section

AGENTS.md

@@ -22,6 +22,11 @@ This repo has two layers, easy to confuse:
 - **Developer support**: AGENTS.md. It supports plugin development and is not
   part of the installed plugin.
 
+## Concepts
+
+[`docs/concepts.md`](docs/concepts.md) says what the words for dream's domain
+mean. Use its words and no others, in the skills, the documents and the issues.
+
 ## Development notes
 
 The collaborative product management skills, `dream:sift`, `dream:spark`,
@@ -195,12 +200,12 @@ it via `astral-sh/setup-uv`.
 
 ## Documentation site
 
-The documentation site is one page, built with MkDocs and the Material theme.
-The page text is in `docs/index.md`, and the headline and lede are in its front
-matter. The hero, including a sample `dream:smith` session, is in
-`overrides/home.html`, and the styling is in `docs/assets/dream.css`. The `docs`
-workflow builds the site on every pull request that touches it, and publishes it
-to GitHub Pages from main.
+The documentation site is built with MkDocs and the Material theme. `mkdocs.yml`
+sets the navigation, so add every new page to it. The home page text is in
+`docs/index.md`, and the headline and lede are in its front matter. The hero,
+including a sample `dream:smith` session, is in `overrides/home.html`, and the
+styling is in `docs/assets/dream.css`. The `docs` workflow builds the site on
+every pull request that touches it, and publishes it to GitHub Pages from main.
 
 When you add a skill, remove one, or change what one does, update
 `docs/index.md`, because it describes every skill. Keep each skill to one row in

docs/concepts.md

@@ -0,0 +1,204 @@
+# Concepts
+
+This page names the things dream deals with and says what the words mean. It
+defines the domain that dream works in, not dream itself.
+
+Each entry uses only words defined before it. An entry ends with the words that
+its concept replaces, where it replaces any, in a line that begins "Replaces:".
+A replaced word is not used for its concept in the skills, the documents or the
+issues.
+
+## Definitions
+
+### Coding agent
+
+A **coding agent** is a language model that works on software by using tools in
+a loop, such as reading files, running commands and editing code, and that
+decides for itself which tool to use next.
+
+### Context
+
+A coding agent's **context** is the sequence of tokens from which its language
+model generates its next output. It includes every earlier input to the model
+and every output from it.
+
+### Compaction
+
+**Compaction** is an operation that replaces earlier parts of a coding agent's
+context with a summary of them.
+
+### Agent harness
+
+An **agent harness** is a program that turns a language model into a coding
+agent. It supplies the tools, runs the loop and manages the context. Claude Code
+and Codex are agent harnesses.
+
+Replaces: "host".
+
+### Skill
+
+A **skill** is a folder of instructions or information that an agent harness
+gives its coding agent. Its one required file, `SKILL.md`, holds a name, a
+description and a body. The name and description are in the agent's context from
+the start. The body loads into the agent's context only when the skill is
+invoked, by a person or by the agent itself. The folder can also bundle scripts
+and other files, which the agent reads or runs only when the body points it at
+them.
+
+### User
+
+The **user** is the person who gives a coding agent its input, and on whose
+behalf the agent works.
+
+### Harness session
+
+A **harness session** is one conversation between a user and a coding agent, run
+by an agent harness, with a context of its own.
+
+### Turn
+
+A **turn** is a coding agent's whole response to one input, from when the input
+arrives until the agent answers without asking for another tool. A harness
+session is a sequence of turns.
+
+### Subagent
+
+A **subagent** is a coding agent that another coding agent starts inside its
+harness session to do a delegated task. It has a context of its own, and its
+final output returns to the agent that started it.
+
+### Subagent file
+
+A **subagent file** is a Markdown file that defines a kind of subagent. Its
+frontmatter holds a name and a description, and its body holds the instructions
+the subagent starts from.
+
+Replaces: "agent prompt", "named agent".
+
+### Plugin
+
+A **plugin** is a bundle of skills, subagent files and other extensions that an
+agent harness installs as one unit.
+
+### Repository
+
+A **repository** is the git repository that a coding agent works in.
+
+### Issue
+
+An **issue** is a GitHub issue on the repository. It can record anything worth
+tracking, such as a bug, a maintenance chore, a small enhancement or an epic
+describing a major new feature.
+
+### Sub-issue and parent issue
+
+A **sub-issue** is an issue that GitHub links beneath another issue, its
+**parent issue**. A parent issue can have many sub-issues, and a sub-issue can
+be a parent issue in turn.
+
+Replaces: "child", "child issue".
+
+### Pull request
+
+A **pull request** is a GitHub pull request on the repository: a proposal to
+merge the changes on one branch into another, where the changes can be reviewed
+and discussed before they merge.
+
+### Default branch and base branch
+
+The **default branch** is the branch on GitHub that a new pull request merges
+into unless another is chosen. A pull request's **base branch** is the branch it
+would merge into.
+
+### Implementation plan and implementation step
+
+An **implementation plan** is an ordered list of **implementation steps** that
+delivers a change in one pull request. Each implementation step is one idea and
+one commit.
+
+Replaces: "task", for an implementation step.
+
+### Review and finding
+
+A **review** is a reading of a change, or of code or documents, that reports
+each way the work could be better as a **finding**. A finding is one claim about
+the work read, with the evidence for it. For example, a finding can name a bug,
+a simpler form, a fact kept in two places, something a reader is missing, or a
+departure from the repository's instructions.
+
+### Review lens
+
+A **review lens** is one narrow question that a review asks of the work it
+reads. For example, whether a change introduces races, or whether each fact has
+one home.
+
+### Specification and specification folder
+
+A **specification** is a document in the repository that records thinking about
+a piece of work before it is built. For example, a requirements specification, a
+reading guide, a design specification or a roadmap. The specifications for one
+piece of work are kept together in a **specification folder**.
+
+Replaces: "spec", for a specification.
+
+### Requirements specification
+
+A **requirements specification** describes what the user wants and why, without
+a solution. It says what the user wants to be able to do, what is wrong or
+missing today, what has to be true of anything they would accept, what
+constraints any solution must work within, how they will know it worked, and
+what is still open.
+
+Replaces: "requirements brief", "brief".
+
+### Reading guide
+
+A **reading guide** is a specification that leads a reader through the existing
+code behind a piece of work. It recommends what to read and in what order, gives
+the background that makes the code make sense, and names the code's awkward
+parts.
+
+### Design specification
+
+A **design specification** describes what a piece of work will create: the
+architecture and algorithms of the result, in enough detail to plan the build
+from, without the implementation. It says what is being built, how it works,
+what changes and what goes away, why it takes this shape and not another, and
+what is still open.
+
+Replaces: "design", for a design specification.
+
+### Roadmap and stage
+
+A **roadmap** is a specification that breaks a piece of work too large for one
+pull request into ordered **stages**, each delivered by one pull request. It
+describes what each stage will deliver, how to tell it is done, what it leaves
+for later, and which earlier stages it needs.
+
+Replaces: "plan" and "campaign plan", for a roadmap.
+
+### Issue triage and triage outcome
+
+**Issue triage** is deciding what should happen next to an issue. The decision
+is its **triage outcome**: the issue needs information, needs discussion, is
+ready to implement, waits on something outside the repository, or is closed.
+
+### Change type
+
+A **change type** says what kind of change some work makes. An **enhancement**
+adds a capability that doesn't exist yet. **Maintenance** improves coherence,
+naming or structure, without changing behaviour. A **bug fix** repairs incorrect
+behaviour.
+
+Replaces: "issue type", "session type", "category".
+
+### dreamcatcher
+
+**dreamcatcher** is a program that dispatches coding agents to work autonomously
+on a repository's issues, with the user steering them from GitHub. Some of
+dream's skills are designed to be compatible with it, so dreamcatcher can use
+them to drive and direct that work. Words for what dreamcatcher does, such as
+dispatch label, dispatch route, agent assignment, issue conversation, campaign
+and agent round, mean what
+[dreamcatcher's concepts page](https://alimanfoo.github.io/dreamcatcher/concepts/)
+says they mean.

mkdocs.yml

@@ -6,6 +6,9 @@ repo_name: alimanfoo/dream
 edit_uri: ""
 copyright: MIT License
 
+validation:
+  omitted_files: warn
+
 theme:
   name: material
   custom_dir: overrides
@@ -33,9 +36,13 @@ theme:
         name: Switch to dark mode
   features:
     - content.code.copy
+    - navigation.sections
+    - toc.follow
 
-# One short page needs no search.
-plugins: []
+nav:
+  - Home: index.md
+  - Development:
+      - concepts.md
 
 markdown_extensions:
   - tables

specs/2026-11-01-engineering-standard/design.md

@@ -138,9 +138,9 @@ and writes the section from them.
 3. Measure every criterion in the standard, and replace `docs/measurement.md`
    with the results.
 4. Bring the open issues up to date. Search them for each word that a
-   "Replaces:" line on the concepts page has retired, such as an old skill name.
-   Rewrite each issue that uses one, and close each whose work is done or no
-   longer applies, saying why.
+   "Replaces:" line on the concepts page has retired, such as "host". Rewrite
+   each issue that uses one, and close each whose work is done or no longer
+   applies, saying why.
 5. File an issue for each finding and shortfall that no open issue already owns.
    None of them holds the release back. A failing check does.
 6. Write the changelog section and set the version, then merge, tag, publish,
@@ -240,13 +240,13 @@ from a concept.
 
 ### Intent written down
 
-`docs/concepts.md` names dream's concepts and says what each word means.
-`docs/stories.md` says what the user and the agents do with dream, why, and what
-they see, organised by the practices that `docs/index.md` already uses: handing
-off a task, running skills from labelled issues, thinking it through together,
-reviewing a change, and planning and writing. dream's stories cover the
-practices. dreamcatcher's stories cover the mechanics of running them
-unattended.
+`docs/concepts.md` names the concepts of the domain dream works in and says what
+each word means. `docs/stories.md` says what the user and the agents do with
+dream, why, and what they see, organised by the practices that `docs/index.md`
+already uses: handing off a task, running skills from labelled issues, thinking
+it through together, reviewing a change, and planning and writing. dream's
+stories cover the practices. dreamcatcher's stories cover the mechanics of
+running them unattended.
 
 Both pages are for developers and agents. They sit in the docs site's
 Development section, as the other two projects' do. `docs/index.md` stays the

specs/2026-11-01-engineering-standard/roadmap.md

@@ -51,10 +51,10 @@ short page needs no search" setting revisited, and the note in `AGENTS.md` that
 the site is one page removed.
 
 Then `docs/concepts.md`, worked out with the user, in the form of the other two
-projects' concepts pages. Each term has an entry that uses only terms defined
-before it and ends with the words it replaces. Old skill names go in those
-"Replaces:" lines, such as craft and shape for weave, lead for big, and state
-for scout. `AGENTS.md` points at the page and says to use its words.
+projects' concepts pages. It defines the domain dream works in, not dream
+itself, so dream's own skills and files have no entries. Each term has an entry
+that uses only terms defined before it and ends with the words it replaces.
+`AGENTS.md` points at the page and says to use its words.
 
 **Done when.** The user has agreed every entry, the site builds in strict mode
 with Concepts under Development, and the home page looks as it does today.