diff --git a/AGENTS.md b/AGENTS.md index 6c5d760f..0ef6f850 100644 --- a/AGENTS.md +++ b/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 diff --git a/docs/concepts.md b/docs/concepts.md new file mode 100644 index 00000000..04c0d5f8 --- /dev/null +++ b/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. diff --git a/mkdocs.yml b/mkdocs.yml index 74611b51..a547d29d 100644 --- a/mkdocs.yml +++ b/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 diff --git a/specs/2026-11-01-engineering-standard/design.md b/specs/2026-11-01-engineering-standard/design.md index 42cb889b..93763300 100644 --- a/specs/2026-11-01-engineering-standard/design.md +++ b/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 diff --git a/specs/2026-11-01-engineering-standard/roadmap.md b/specs/2026-11-01-engineering-standard/roadmap.md index 3ffec429..297aec10 100644 --- a/specs/2026-11-01-engineering-standard/roadmap.md +++ b/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.