From dba132bd9882a2f2a354ced7d429dae59be78e64 Mon Sep 17 00:00:00 2001 From: David Spencer <1526975+DecisionNerd@users.noreply.github.com> Date: Tue, 14 Jul 2026 12:33:29 -0600 Subject: [PATCH] docs: remove unintended rendered line breaks (#25) * docs: fix DDD sentence line break * docs: remove unintended rendered line breaks --- docs/DESIGN.md | 58 +++------- docs/PRODUCT.md | 87 ++++---------- docs/README.md | 22 +--- docs/REQUIREMENTS.md | 10 +- docs/engineering/ARCHITECTURE.md | 75 ++++-------- docs/engineering/OBSERVABILITY.md | 22 +--- docs/engineering/PUBLISHING.md | 44 +++---- docs/engineering/README.md | 5 +- docs/engineering/TESTING.md | 67 ++++------- .../adrs/0001-embed-templates-in-binary.md | 38 ++---- docs/engineering/adrs/README.md | 9 +- docs/experience/README.md | 46 +++----- docs/index.md | 109 ++++++------------ docs/lifecycle.md | 97 ++++++---------- docs/skills.md | 40 ++----- docs/strategy/README.md | 15 +-- package.json | 2 +- scripts/check-rendered-line-breaks.mjs | 36 ++++++ 18 files changed, 265 insertions(+), 517 deletions(-) create mode 100644 scripts/check-rendered-line-breaks.mjs diff --git a/docs/DESIGN.md b/docs/DESIGN.md index 652eeb2..e3665ce 100644 --- a/docs/DESIGN.md +++ b/docs/DESIGN.md @@ -1,43 +1,27 @@ # Design -DocSlime has no graphical app today, but it still has a product experience: the CLI, the -generated Markdown, the agent skills, and the way those docs later publish through -`docmd.io`. This file is the design context that tools like `impeccable` can load from -`docs/`. +DocSlime has no graphical app today, but it still has a product experience: the CLI, the generated Markdown, the agent skills, and the way those docs later publish through `docmd.io`. This file is the design context that tools like `impeccable` can load from `docs/`. ## Design Principles -- **Useful before decorative:** the first run should leave the user with a clear, fillable - docs tree and obvious next action. -- **Opinionated, not heavy:** DocSlime should make strong defaults feel helpful, not like a - governance framework. -- **Agent-readable and human-readable:** templates should guide an agent without making a - human feel like they are reading internal machinery. -- **Traceable by design:** requirements, BDD scenarios, tests, architecture, and ADRs should - naturally point at each other. -- **Learning continues in production:** user outcomes and system health should be observable, - not assumed once a release deploys. -- **Small command surface:** CLI commands stay memorable; judgment-heavy work belongs in - skills. +- **Useful before decorative:** the first run should leave the user with a clear, fillable docs tree and obvious next action. +- **Opinionated, not heavy:** DocSlime should make strong defaults feel helpful, not like a governance framework. +- **Agent-readable and human-readable:** templates should guide an agent without making a human feel like they are reading internal machinery. +- **Traceable by design:** requirements, BDD scenarios, tests, architecture, and ADRs should naturally point at each other. +- **Learning continues in production:** user outcomes and system health should be observable, not assumed once a release deploys. +- **Small command surface:** CLI commands stay memorable; judgment-heavy work belongs in skills. ## Brand And Voice - **Product name:** use `DocSlime` for the product and `docslime` for the binary/command. -- **Tone:** practical, direct, and lightly playful when the name earns it. The product can - carry the integrated "slime" idea without turning docs into a joke. -- **Mascot:** use the blue anime slime as a product signal. It can appear in the homepage - hero and brand surfaces, but it should support the repo/docs artifact rather than replacing - developer credibility. -- **Terminology:** use "docs tree," "product context," "design context," "requirements," - "BDD," "Domain Driven Design," "ADR," "template," "skill," and "agent" consistently. -- **Writing rules:** generated guidance should be specific and interview-driven. Prefer - "ask the user," "trace this to a requirement," and "record the decision" over vague advice. +- **Tone:** practical, direct, and lightly playful when the name earns it. The product can carry the integrated "slime" idea without turning docs into a joke. +- **Mascot:** use the blue anime slime as a product signal. It can appear in the homepage hero and brand surfaces, but it should support the repo/docs artifact rather than replacing developer credibility. +- **Terminology:** use "docs tree," "product context," "design context," "requirements," "BDD," "Domain Driven Design," "ADR," "template," "skill," and "agent" consistently. +- **Writing rules:** generated guidance should be specific and interview-driven. Prefer "ask the user," "trace this to a requirement," and "record the decision" over vague advice. ## Impeccable Workflow -`impeccable` should treat `docs/PRODUCT.md` and `docs/DESIGN.md` as the current product and -design context. UI work should begin by loading those files, critiquing the actual surface, -and then changing the smallest set of docs/site files that makes the critique more true. +`impeccable` should treat `docs/PRODUCT.md` and `docs/DESIGN.md` as the current product and design context. UI work should begin by loading those files, critiquing the actual surface, and then changing the smallest set of docs/site files that makes the critique more true. For the homepage, the desired direction is: @@ -45,20 +29,15 @@ For the homepage, the desired direction is: - show the repo/docs tree as the credibility anchor; - include the blue slime mascot as a memorable brand moment; - keep CTAs developer-native and direct; -- avoid pink/purple gradient text, decorative grid backgrounds, oversized cards, and claims - that `docslime-kiss` is a CLI command. +- avoid pink/purple gradient text, decorative grid backgrounds, oversized cards, and claims that `docslime-kiss` is a CLI command. ## Markdown Experience -- `docs/PRODUCT.md` and `docs/DESIGN.md` are top-level context files so design and coding - agents can discover them from the docs directory. -- Semantic folders separate strategy, continuous discovery, and engineering while - `docs/README.md` keeps the lifecycle explicit without encoding navigation into filenames. -- Tables are useful for traceability, requirements, component lists, and ADR logs; prose - should stay short enough to scan. +- `docs/PRODUCT.md` and `docs/DESIGN.md` are top-level context files so design and coding agents can discover them from the docs directory. +- Semantic folders separate strategy, continuous discovery, and engineering while `docs/README.md` keeps the lifecycle explicit without encoding navigation into filenames. +- Tables are useful for traceability, requirements, component lists, and ADR logs; prose should stay short enough to scan. - Templates may contain `` guidance, but filled docs should remove it. -- Avoid generic motivational copy. Every paragraph should help a future human or agent make - a better change. +- Avoid generic motivational copy. Every paragraph should help a future human or agent make a better change. ## CLI Experience @@ -74,8 +53,7 @@ For the homepage, the desired direction is: - Requirements should be testable and carry stable IDs. - Testing docs should map requirements and experiences to Given/When/Then behavior coverage. - Architecture docs should describe domain concepts and boundaries when the project has them. -- Publishing docs should distinguish built, deployed, and verified artifacts and include a - safe rollback path. +- Publishing docs should distinguish built, deployed, and verified artifacts and include a safe rollback path. - Observability should cover user outcomes as well as logs, metrics, traces, SLOs, and alerts. - Significant product or technical decisions should be captured as ADRs. - KISS review should cut bloat, stale contradictions, generic AI prose, and weak traceability. diff --git a/docs/PRODUCT.md b/docs/PRODUCT.md index 5d0f953..03f6084 100644 --- a/docs/PRODUCT.md +++ b/docs/PRODUCT.md @@ -1,51 +1,29 @@ # Product -DocSlime is an opinionated documentation system for codebases. It gives a repo a consistent -`docs/` tree, a `docslime` CLI, and agent skills that help teams turn product intent into -filled-in, version-controlled Markdown. +DocSlime is an opinionated documentation system for codebases. It gives a repo a consistent `docs/` tree, a `docslime` CLI, and agent skills that help teams turn product intent into filled-in, version-controlled Markdown. -It exists so services and user-facing products can carry product context, continuous -discovery, requirements, design guidance, architecture, tests, delivery, observability, and -decisions next to the code. Agents working in the repo can read that context directly -instead of guessing from implementation details alone. +It exists so services and user-facing products can carry product context, continuous discovery, requirements, design guidance, architecture, tests, delivery, observability, and decisions next to the code. Agents working in the repo can read that context directly instead of guessing from implementation details alone. ## Problem -Project knowledge usually lives away from the work: in tickets, chats, wikis, docs tools, -and memory. That is painful for humans and worse for AI coding agents, which often see the -code but not the intent behind it. Teams also reinvent documentation structure per repo, so -there is no familiar shape for agents to read, fill, tighten, or publish. +Project knowledge usually lives away from the work: in tickets, chats, wikis, docs tools, and memory. That is painful for humans and worse for AI coding agents, which often see the code but not the intent behind it. Teams also reinvent documentation structure per repo, so there is no familiar shape for agents to read, fill, tighten, or publish. -The result is predictable: missing context, stale decisions, requirements that do not map to -tests, and architecture docs that sound polished but do not guide the next change. +The result is predictable: missing context, stale decisions, requirements that do not map to tests, and architecture docs that sound polished but do not guide the next change. ## Vision -DocSlime makes the repo the product and engineering context container. A team runs -`docslime init`, answers focused agent questions, records ADRs as decisions happen, and uses -`docslime-kiss` to keep the tree lean and honest. +DocSlime makes the repo the product and engineering context container. A team runs `docslime init`, answers focused agent questions, records ADRs as decisions happen, and uses `docslime-kiss` to keep the tree lean and honest. -The system is playful in name but serious in method: it gathers the scattered pieces of a -project into one integrated docs body, then gives humans and agents more power because the -context is complete, local, and testable. +The system is playful in name but serious in method: it gathers the scattered pieces of a project into one integrated docs body, then gives humans and agents more power because the context is complete, local, and testable. ## Product Shape - **CLI:** `docslime init`, `docslime add`, and `docslime list` manage the scaffold. -- **Skills:** `docslime-install`, `docslime-init`, `docslime-fill`, `docslime-adr`, and - `docslime-kiss` drive the human-in-the-loop documentation lifecycle. -- **Impeccable integration:** `docs/PRODUCT.md` and `docs/DESIGN.md` are discoverable product - and design context files without needing root-level duplicates, so `impeccable` can critique - and polish product surfaces from the same docs tree agents use. -- **Lifecycle:** discovery evidence becomes requirements, architecture and tests implement - the contract, publishing carries verified artifacts to users, and observability closes the - learning loop. -- **Publishing path:** the docs stay plain Markdown and can publish through `docmd.io`; the - engineering publishing template also covers software artifacts, promotion, deployment, - verification, and rollback. -- **Quality stance:** requirements should trace to BDD scenarios and tests, architecture - should use Domain Driven Design language where it clarifies the system, and significant - choices should become ADRs. +- **Skills:** `docslime-install`, `docslime-init`, `docslime-fill`, `docslime-adr`, and `docslime-kiss` drive the human-in-the-loop documentation lifecycle. +- **Impeccable integration:** `docs/PRODUCT.md` and `docs/DESIGN.md` are discoverable product and design context files without needing root-level duplicates, so `impeccable` can critique and polish product surfaces from the same docs tree agents use. +- **Lifecycle:** discovery evidence becomes requirements, architecture and tests implement the contract, publishing carries verified artifacts to users, and observability closes the learning loop. +- **Publishing path:** the docs stay plain Markdown and can publish through `docmd.io`; the engineering publishing template also covers software artifacts, promotion, deployment, verification, and rollback. +- **Quality stance:** requirements should trace to BDD scenarios and tests, architecture should use Domain Driven Design language where it clarifies the system, and significant choices should become ADRs. ## Quality Method @@ -63,54 +41,39 @@ flowchart LR Observe --> Strategy ``` -- **TDD+BDD:** requirements get stable IDs, behavior is written in Given/When/Then language, - and tests prove observable behavior before the docs call it done. -- **Domain Driven Design:** architecture docs name the domain concepts, boundaries, and - language that matter for the project; small projects can stay light, but they should still - know their core nouns and responsibilities. -- **ADRs:** durable choices live in `engineering/adrs/` so future humans and agents can see - why the current shape exists. -- **Observability:** production health and user-outcome signals trace back to requirements - and discovery, so learning continues after release. +- **TDD+BDD:** requirements get stable IDs, behavior is written in Given/When/Then language, and tests prove observable behavior before the docs call it done. +- **Domain Driven Design:** architecture docs name the domain concepts, boundaries, and language that matter for the project; small projects can stay light, but they should still know their core nouns and responsibilities. +- **ADRs:** durable choices live in `engineering/adrs/` so future humans and agents can see why the current shape exists. +- **Observability:** production health and user-outcome signals trace back to requirements and discovery, so learning continues after release. ## Goals - Give every repo a consistent, agent-readable documentation structure. - Make first-run value fast: `docslime init` should create useful next steps immediately. -- Keep product, design, discovery, requirements, engineering, delivery, observability, and - ADR context local and version-controlled. +- Keep product, design, discovery, requirements, engineering, delivery, observability, and ADR context local and version-controlled. - Support both services and user-facing products without splitting into separate doc systems. - Make docs easier to fill, review, tighten, and publish than to let drift. ## Non-goals -- DocSlime does not replace the human conversation. Agents fill docs by interviewing the - team, not by inventing facts. +- DocSlime does not replace the human conversation. Agents fill docs by interviewing the team, not by inventing facts. - DocSlime does not add a runtime service or database to the target project. -- DocSlime does not turn the CLI into a publishing host; publication belongs to the - `docmd.io` system. -- DocSlime does not make `kiss` a CLI command. KISS review is an agent skill because it - depends on judgment over filled docs. +- DocSlime does not turn the CLI into a publishing host; publication belongs to the `docmd.io` system. +- DocSlime does not make `kiss` a CLI command. KISS review is an agent skill because it depends on judgment over filled docs. ## Success Metrics - **Docs get filled:** scaffolded documents are completed, with no leftover `LLM:` guidance. -- **Traceability improves:** requirements, behavior scenarios, tests, and ADRs point to each - other clearly enough for a future agent to act. -- **The loop closes:** published artifacts carry verification steps, and observability links - production signals back to product outcomes and experience hypotheses. -- **Design context improves:** `impeccable` resolves `docs/PRODUCT.md` and `docs/DESIGN.md` - as the current product/design source without bridge files that can drift. +- **Traceability improves:** requirements, behavior scenarios, tests, and ADRs point to each other clearly enough for a future agent to act. +- **The loop closes:** published artifacts carry verification steps, and observability links production signals back to product outcomes and experience hypotheses. +- **Design context improves:** `impeccable` resolves `docs/PRODUCT.md` and `docs/DESIGN.md` as the current product/design source without bridge files that can drift. - **Low friction:** short time from `docslime init` to a useful first filled document. - **Adoption:** installs through Homebrew, shell installer, source builds, and skill-pack use. - **Publication readiness:** docs remain clean Markdown that can flow into `docmd.io`. ## Stakeholders -- **Maintainer (DecisionNerd):** owns DocSlime's direction, release process, templates, and - skill pack. +- **Maintainer (DecisionNerd):** owns DocSlime's direction, release process, templates, and skill pack. - **Engineering teams:** adopt the tree across repos to keep intent close to code. -- **Product and design collaborators:** use `PRODUCT.md` and `DESIGN.md` as compact context - for shaping user-facing work. -- **AI coding agents:** fill, consume, critique, and maintain the docs while working in the - repo. +- **Product and design collaborators:** use `PRODUCT.md` and `DESIGN.md` as compact context for shaping user-facing work. +- **AI coding agents:** fill, consume, critique, and maintain the docs while working in the repo. diff --git a/docs/README.md b/docs/README.md index e3ae924..f6292a1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,29 +1,19 @@ # Documentation -DocSlime dogfoods the documentation lifecycle it scaffolds. Product and design context feed -continuous discovery, requirements translate that evidence into a build contract, and the -engineering docs carry the contract through architecture, testing, publishing, and -production observability. +DocSlime dogfoods the documentation lifecycle it scaffolds. Product and design context feed continuous discovery, requirements translate that evidence into a build contract, and the engineering docs carry the contract through architecture, testing, publishing, and production observability. -Start with the [lifecycle guide](lifecycle.md) for the full UX → DDD → TDD+BDD trace and -day-to-day tool usage. +Start with the [lifecycle guide](lifecycle.md) for the full UX → DDD → TDD+BDD trace and day-to-day tool usage. ## Adapt the scaffold -The generated tree is a starting template, not a requirement to keep every file. Projects -should retain only the docs that help their humans or agents make better decisions, link to -authoritative organization-level context, and update the index when files are removed or -merged. +The generated tree is a starting template, not a requirement to keep every file. Projects should retain only the docs that help their humans or agents make better decisions, link to authoritative organization-level context, and update the index when files are removed or merged. -For example, a backend API service in a large organization may omit local product strategy -and visual design docs when those concerns are owned elsewhere. It can still keep -`experience/` for developer experience (DX), operator and integration journeys, and agent -experience for coding agents or automated consumers of the API. +For example, a backend API service in a large organization may omit local product strategy and visual design docs when those concerns are owned elsewhere. It can still keep `experience/` for developer experience (DX), operator and integration journeys, and agent experience for coding agents or automated consumers of the API. ## Lifecycle | Document | Question it answers | -|---|---| +| --- | --- | | [`PRODUCT.md`](PRODUCT.md) | What is DocSlime, who is it for, and why does it exist? | | [`DESIGN.md`](DESIGN.md) | What should stay consistent across its CLI, templates, skills, and site? | | [`experience/`](experience/) | What user evidence, journeys, and behaviors inform the product? | @@ -36,7 +26,7 @@ experience for coding agents or automated consumers of the API. Supporting detail lives in: | Folder | Contents | -|---|---| +| --- | --- | | [`strategy/`](strategy/) | Market, positioning, roadmap, and strategic bets beyond `PRODUCT.md`. | | [`experience/`](experience/) | Continuous-discovery practice and user-centered evidence. | | [`engineering/`](engineering/) | Technical lifecycle and operational documentation. | diff --git a/docs/REQUIREMENTS.md b/docs/REQUIREMENTS.md index 0f5c861..3f6d24a 100644 --- a/docs/REQUIREMENTS.md +++ b/docs/REQUIREMENTS.md @@ -1,15 +1,11 @@ # Requirements -DocSlime must scaffold a fixed, standardized `docs/` tree into a git repo, add individual -documents (including auto-numbered ADRs) on demand, and report what exists without -destroying existing work. The templates must carry the inline guidance that lets an AI agent -fill them in, while the tree stays plain Markdown for design-context loading, continuous -discovery, delivery, publication, and production learning. +DocSlime must scaffold a fixed, standardized `docs/` tree into a git repo, add individual documents (including auto-numbered ADRs) on demand, and report what exists without destroying existing work. The templates must carry the inline guidance that lets an AI agent fill them in, while the tree stays plain Markdown for design-context loading, continuous discovery, delivery, publication, and production learning. ## Functional requirements | ID | Requirement | Traces to | -|---|---|---| +| --- | --- | --- | | FR-1 | The system shall create the full standardized `docs/` tree with `README.md`, `PRODUCT.md`, `DESIGN.md`, `REQUIREMENTS.md`, `strategy/`, `experience/`, and engineering architecture, testing, publishing, observability, and ADR docs via `docslime init`. | Scaffold the docs tree | | FR-2 | The system shall skip any file that already exists during `init` and `add`, and overwrite only when `--force` is given. | Non-destructive by default | | FR-3 | The system shall add a single named document via `docslime add `, resolving the name leniently (case-insensitive, with or without the `.md` extension). | Add a single document | @@ -36,7 +32,7 @@ discovery, delivery, publication, and production learning. ## Non-functional requirements | ID | Requirement | Target / constraint | -|---|---|---| +| --- | --- | --- | | NFR-1 | Portability | Runs on macOS (arm64, x86_64) and Linux (arm64, x86_64); no runtime dependencies. | | NFR-2 | Performance | Commands complete near-instantly (well under a second) on a typical repo. | | NFR-3 | Distribution | Installable via Homebrew tap, shell installer script, and `cargo install`. | diff --git a/docs/engineering/ARCHITECTURE.md b/docs/engineering/ARCHITECTURE.md index 0bc979d..3cbea8a 100644 --- a/docs/engineering/ARCHITECTURE.md +++ b/docs/engineering/ARCHITECTURE.md @@ -1,15 +1,8 @@ # Architecture -DocSlime is a small monorepo with three shippable surfaces: a self-contained Rust CLI, a -`docmd.io`-built documentation site, and a bundled set of agent skills. The CLI has no -server, no database, and no runtime dependencies: the entire template tree is compiled into -the binary, and every command operates directly on the filesystem relative to the current -directory. +DocSlime is a small monorepo with three shippable surfaces: a self-contained Rust CLI, a `docmd.io`-built documentation site, and a bundled set of agent skills. The CLI has no server, no database, and no runtime dependencies: the entire template tree is compiled into the binary, and every command operates directly on the filesystem relative to the current directory. -The design is deliberately small: parse a command, resolve a template, write files without -clobbering existing ones, and leave judgment-heavy work to skills. `docs/PRODUCT.md` and -`docs/DESIGN.md` are part of the generated tree so tools like `impeccable` can discover -context from `docs/`; publication remains outside the binary in the `docmd.io` system. +The design is deliberately small: parse a command, resolve a template, write files without clobbering existing ones, and leave judgment-heavy work to skills. `docs/PRODUCT.md` and `docs/DESIGN.md` are part of the generated tree so tools like `impeccable` can discover context from `docs/`; publication remains outside the binary in the `docmd.io` system. ## Context diagram @@ -23,14 +16,12 @@ flowchart LR Docs --> Docmd["docmd.io publishes Markdown"] ``` -Inside the CLI boundary: argument parsing, template resolution, and file writing. Outside: -the git repo's filesystem, the AI agent skills that fill and review docs, `impeccable` -context loading, and `docmd.io` publication. +Inside the CLI boundary: argument parsing, template resolution, and file writing. Outside: the git repo's filesystem, the AI agent skills that fill and review docs, `impeccable` context loading, and `docmd.io` publication. ## Components | Component | Responsibility | Depends on | -|---|---|---| +| --- | --- | --- | | `cli` | Define the command surface (`init`, `add`, `list`) and arguments via clap derive. KISS is intentionally not a CLI subcommand. | clap | | `main` | Parse args, resolve the working directory, dispatch to a command, map errors to an exit code. | cli, commands | | `commands::init` | Scaffold the full template tree into `docs/`, skipping current or legacy-equivalent existing files. | templates, scaffold | @@ -43,25 +34,19 @@ context loading, and `docmd.io` publication. ## Data model -DocSlime is essentially stateless — it stores nothing of its own. The only persistent artifacts -are: +DocSlime is essentially stateless — it stores nothing of its own. The only persistent artifacts are: -- **Embedded templates** — a read-only directory tree (`templates/`) plus the standalone ADR - template (`assets/adr.md`), baked into the binary at build time. -- **The output `docs/` tree** — plain Markdown files written into the user's repo, including - `PRODUCT.md` and `DESIGN.md` for product/design context discovery. +- **Embedded templates** — a read-only directory tree (`templates/`) plus the standalone ADR template (`assets/adr.md`), baked into the binary at build time. +- **The output `docs/` tree** — plain Markdown files written into the user's repo, including `PRODUCT.md` and `DESIGN.md` for product/design context discovery. -The one piece of derived state computed at runtime is the **next ADR number**, obtained by -scanning the ADR directory for the highest `NNNN-*` prefix. +The one piece of derived state computed at runtime is the **next ADR number**, obtained by scanning the ADR directory for the highest `NNNN-*` prefix. ## Domain language and boundaries -DocSlime uses Domain Driven Design language lightly. The useful domain is not "documents" in -the abstract; it is the lifecycle of turning repo knowledge into agent-readable, testable -context. +DocSlime uses Domain Driven Design language lightly. The useful domain is not "documents" in the abstract; it is the lifecycle of turning repo knowledge into agent-readable, testable context. | Domain concept | Meaning in DocSlime | Boundary | -|---|---|---| +| --- | --- | --- | | Docs tree | The fixed `docs/` structure written into the target repo. | CLI scaffold | | Template catalog | The embedded Markdown files and ADR template that define the default tree. | CLI scaffold | | Filled document | A scaffolded file after an agent removes `LLM:` guidance and writes project facts. | Agent skill lifecycle | @@ -74,12 +59,9 @@ The main bounded contexts are: - **CLI scaffold context:** create, add, list, and write files safely. - **Agent skill context:** interview, fill, critique, and record decisions with human input. -- **Publishing context:** build, version, promote, verify, and recover the CLI, skill, and - documentation artifacts through their external distribution systems. -- **Observation context:** verify artifacts through user-facing paths and turn failures, - feedback, and adoption signals into discovery evidence. -- **Site context:** render this repository's docs and homepage from the same Markdown source - users receive from the CLI templates. +- **Publishing context:** build, version, promote, verify, and recover the CLI, skill, and documentation artifacts through their external distribution systems. +- **Observation context:** verify artifacts through user-facing paths and turn failures, feedback, and adoption signals into discovery evidence. +- **Site context:** render this repository's docs and homepage from the same Markdown source users receive from the CLI templates. ## Key flows @@ -88,9 +70,7 @@ The main bounded contexts are: 1. `main` resolves the current working directory as the root — `main` 2. Dispatch to the init command — `commands::init` 3. Enumerate every embedded template in the tree, including `PRODUCT.md` and `DESIGN.md` — `templates` -4. For each, compute `docs/` and skip it when the current path or a mapped - legacy equivalent exists, unless `--force` explicitly writes the current template — - `templates`, `scaffold` +4. For each, compute `docs/` and skip it when the current path or a mapped legacy equivalent exists, unless `--force` explicitly writes the current template — `templates`, `scaffold` 5. Report a summary of created vs. skipped files — `commands::init` ### `docslime add adr ` (create an ADR) @@ -100,21 +80,15 @@ The main bounded contexts are: 3. Scan `docs/engineering/adrs/` for the highest `NNNN` prefix and add one — `commands::add` 4. Write `NNNN-.md` from the embedded ADR template, non-destructively — `scaffold` -These line up with the "Scaffold the docs tree" and "Record an architecture decision" -journeys in [`../experience/README.md`](../experience/README.md). +These line up with the "Scaffold the docs tree" and "Record an architecture decision" journeys in [`../experience/README.md`](../experience/README.md). ## Cross-cutting concerns -- **Error handling:** `anyhow` propagates errors up to `main`, which prints `error: …` and - returns a non-zero `ExitCode`. Unknown template names produce a helpful error listing valid - names (FR-8). -- **Configuration:** none — behavior is fixed by the embedded templates and a small set of - flags (`--force`). No config file (see open questions in [`../REQUIREMENTS.md`](../REQUIREMENTS.md)). -- **Security:** `docslime` only writes within `docs/` under the current directory and never - overwrites without `--force` (NFR-4). No network access. +- **Error handling:** `anyhow` propagates errors up to `main`, which prints `error: …` and returns a non-zero `ExitCode`. Unknown template names produce a helpful error listing valid names (FR-8). +- **Configuration:** none — behavior is fixed by the embedded templates and a small set of flags (`--force`). No config file (see open questions in [`../REQUIREMENTS.md`](../REQUIREMENTS.md)). +- **Security:** `docslime` only writes within `docs/` under the current directory and never overwrites without `--force` (NFR-4). No network access. - **Observability:** plain stdout/stderr; `list` uses `owo-colors` for readable status output. -- **External tools:** `impeccable` and `docmd.io` consume the Markdown tree; they are not - runtime dependencies of the CLI. +- **External tools:** `impeccable` and `docmd.io` consume the Markdown tree; they are not runtime dependencies of the CLI. ## Decisions @@ -122,11 +96,6 @@ journeys in [`../experience/README.md`](../experience/README.md). ## Risks & trade-offs -- **Editing a template requires a rebuild.** Because templates are embedded via `include_dir`, - content changes only ship with a new binary. Accepted: it's the price of a no-dependency - single binary, and templates change rarely. -- **Fixed tree layout.** DocSlime doesn't accept a custom structure, which keeps it simple but - limits teams that want a different shape. Tracked as an open question in the requirements. -- **Current-directory assumption.** All commands act on the current directory; running from - the wrong place scaffolds in the wrong place. Mitigation: the `docslime-init` skill confirms - the working directory first. +- **Editing a template requires a rebuild.** Because templates are embedded via `include_dir`, content changes only ship with a new binary. Accepted: it's the price of a no-dependency single binary, and templates change rarely. +- **Fixed tree layout.** DocSlime doesn't accept a custom structure, which keeps it simple but limits teams that want a different shape. Tracked as an open question in the requirements. +- **Current-directory assumption.** All commands act on the current directory; running from the wrong place scaffolds in the wrong place. Mitigation: the `docslime-init` skill confirms the working directory first. diff --git a/docs/engineering/OBSERVABILITY.md b/docs/engineering/OBSERVABILITY.md index f833803..a7c74f9 100644 --- a/docs/engineering/OBSERVABILITY.md +++ b/docs/engineering/OBSERVABILITY.md @@ -1,14 +1,11 @@ # Observability -DocSlime needs evidence at two levels: whether released artifacts work and whether the -documentation lifecycle improves the user and agent experience. Workflow success, a deployed -site, or an available formula is configured state; verification requires observing the -artifact through the path users take. +DocSlime needs evidence at two levels: whether released artifacts work and whether the documentation lifecycle improves the user and agent experience. Workflow success, a deployed site, or an available formula is configured state; verification requires observing the artifact through the path users take. ## Observable outcomes | Outcome / requirement | Signal | Current source | Interpretation | -|---|---|---|---| +| --- | --- | --- | --- | | Safe scaffolding / FR-1, FR-2 | End-to-end CLI tests and throwaway-repo release smoke | `tests/cli.rs`, release verification | The CLI emits the expected tree without overwriting work. | | Installability / NFR-3 | Release assets, Homebrew formula, installed version smoke | GitHub Releases, Homebrew | Users can obtain the current artifact through supported channels. | | Skill usability / FR-9, FR-16 | Structural validation and fresh-install inspection | CI, `npx skills add` smoke | Agents receive the intended lifecycle guidance. | @@ -18,8 +15,7 @@ artifact through the path users take. ## Service and release health -DocSlime has no persistent application service today. Its operational health is therefore -artifact-oriented: +DocSlime has no persistent application service today. Its operational health is therefore artifact-oriented: - CI is green for the exact source revision being promoted. - Release artifacts exist for every supported target and match the tagged version. @@ -29,15 +25,12 @@ artifact-oriented: ## Telemetry and privacy -The CLI does not collect product telemetry. Do not add tracking that sends repository paths, -document contents, command arguments, or other local project data without an explicit product -decision, privacy review, and user consent. Prefer aggregate public distribution signals and -direct feedback when evaluating adoption. +The CLI does not collect product telemetry. Do not add tracking that sends repository paths, document contents, command arguments, or other local project data without an explicit product decision, privacy review, and user consent. Prefer aggregate public distribution signals and direct feedback when evaluating adoption. ## Alerts and response | Signal | Trigger | Response | -|---|---|---| +| --- | --- | --- | | CI | Required job fails | Block promotion and fix the owning surface. | | Release | Expected artifact or formula missing | Stop verification; inspect the release workflow and credentials. | | Install smoke | Installed version or scaffold differs | Treat the release as unverified and repair distribution before announcing it. | @@ -45,7 +38,4 @@ direct feedback when evaluating adoption. ## Production learning loop -Maintainer and user feedback, issues, adoption signals, release failures, and observed agent -confusion should be reviewed as discovery evidence. Material findings update -[`../experience/`](../experience/), then flow through requirements, architecture, tests, -publishing, and a new production check. Dashboards are not a substitute for this review. +Maintainer and user feedback, issues, adoption signals, release failures, and observed agent confusion should be reviewed as discovery evidence. Material findings update [`../experience/`](../experience/), then flow through requirements, architecture, tests, publishing, and a new production check. Dashboards are not a substitute for this review. diff --git a/docs/engineering/PUBLISHING.md b/docs/engineering/PUBLISHING.md index 318488c..f40a623 100644 --- a/docs/engineering/PUBLISHING.md +++ b/docs/engineering/PUBLISHING.md @@ -5,14 +5,12 @@ description: "How verified DocSlime CLI, skill, and documentation artifacts reac # Publishing -DocSlime publishes three related surfaces: the Rust CLI, the reusable agent-skill pack, and -the static documentation site. A build or deployment is not complete until its expected -artifact and user-facing behavior are verified. +DocSlime publishes three related surfaces: the Rust CLI, the reusable agent-skill pack, and the static documentation site. A build or deployment is not complete until its expected artifact and user-facing behavior are verified. ## Artifacts and destinations | Artifact | Destination | Version / identity | -|---|---|---| +| --- | --- | --- | | Rust CLI binaries and installer | GitHub Release | SemVer tag matching `Cargo.toml` | | Homebrew formula | `DecisionNerd/homebrew-tap` | Release version and artifact checksums | | Agent skills | GitHub repository via `npx skills add DecisionNerd/DocSlime` | Repository revision/release | @@ -20,23 +18,16 @@ artifact and user-facing behavior are verified. ## Recommended conventions, not mandates -DocSlime recommends considering two complementary standards when they fit a project's release -model: +DocSlime recommends considering two complementary standards when they fit a project's release model: -- **Semantic Versioning** communicates compatibility through `MAJOR.MINOR.PATCH`. DocSlime - uses SemVer for CLI releases because the CLI has a public command and template contract. -- **Conventional Commits** use `type(scope): description` to make change intent readable by - people and release tooling. `fix` commonly corresponds to a patch, `feat` to a minor change, - and a declared breaking change to a major change when SemVer applies. +- **Semantic Versioning** communicates compatibility through `MAJOR.MINOR.PATCH`. DocSlime uses SemVer for CLI releases because the CLI has a public command and template contract. +- **Conventional Commits** use `type(scope): description` to make change intent readable by people and release tooling. `fix` commonly corresponds to a patch, `feat` to a minor change, and a declared breaking change to a major change when SemVer applies. -These are suggestions, not requirements. A project should document and preserve an existing -convention that already works. DocSlime guidance must not introduce commit linting, rewrite -history, or change version automation without explicit team agreement. +These are suggestions, not requirements. A project should document and preserve an existing convention that already works. DocSlime guidance must not introduce commit linting, rewrite history, or change version automation without explicit team agreement. ## Continuous integration -`.github/workflows/ci.yml` validates the CLI, site, agent skills, and branch policy. Only -`staging` may open a pull request to `main`; feature branches target `staging`. +`.github/workflows/ci.yml` validates the CLI, site, agent skills, and branch policy. Only `staging` may open a pull request to `main`; feature branches target `staging`. Before publishing, run: @@ -50,9 +41,7 @@ npm run build ## CLI and Homebrew release -Distribution is configured through `cargo-dist`. A SemVer tag runs -`.github/workflows/release.yml`, builds macOS/Linux artifacts, creates the GitHub Release, -publishes the installer, and updates the Homebrew tap. +Distribution is configured through `cargo-dist`. A SemVer tag runs `.github/workflows/release.yml`, builds macOS/Linux artifacts, creates the GitHub Release, publishes the installer, and updates the Homebrew tap. Verify more than workflow completion: @@ -63,9 +52,7 @@ Verify more than workflow completion: ## Skill distribution -The `.agents/skills/docslime-*` directories are the canonical source. Validate them before -release, then verify a fresh `npx skills add DecisionNerd/DocSlime` install contains the same -skill set and instructions. +The `.agents/skills/docslime-*` directories are the canonical source. Validate them before release, then verify a fresh `npx skills add DecisionNerd/DocSlime` install contains the same skill set and instructions. ## Documentation site @@ -73,18 +60,13 @@ skill set and instructions. npm run build ``` -`docmd` reads `docs/` and writes the static site to `site/`. Deployment configuration is -outside the CLI; current build and runtime status must be verified through the configured -host rather than inferred from generated files alone. +`docmd` reads `docs/` and writes the static site to `site/`. Deployment configuration is outside the CLI; current build and runtime status must be verified through the configured host rather than inferred from generated files alone. ## Rollback -- Revert or supersede a bad documentation/site deployment from the last known-good source - commit and rebuild. -- For a bad CLI release, stop promotion, document the impact, and issue a corrected version; - do not move an immutable published tag. -- For a bad Homebrew formula, restore the last known-good formula or publish the corrected - release, then verify installation through Homebrew. +- Revert or supersede a bad documentation/site deployment from the last known-good source commit and rebuild. +- For a bad CLI release, stop promotion, document the impact, and issue a corrected version; do not move an immutable published tag. +- For a bad Homebrew formula, restore the last known-good formula or publish the corrected release, then verify installation through Homebrew. ## Official references diff --git a/docs/engineering/README.md b/docs/engineering/README.md index 9e15443..569117b 100644 --- a/docs/engineering/README.md +++ b/docs/engineering/README.md @@ -1,12 +1,11 @@ # Engineering -Engineering carries DocSlime's [`requirements contract`](../REQUIREMENTS.md) through system -design, pre-release evidence, artifact delivery, and production learning. +Engineering carries DocSlime's [`requirements contract`](../REQUIREMENTS.md) through system design, pre-release evidence, artifact delivery, and production learning. ## Lifecycle | Document | Responsibility | -|---|---| +| --- | --- | | [`ARCHITECTURE.md`](ARCHITECTURE.md) | Rust CLI boundaries, embedded templates, skills, and site architecture. | | [`TESTING.md`](TESTING.md) | Unit, integration, skill, and site checks plus CI gates. | | [`PUBLISHING.md`](PUBLISHING.md) | CLI release, Homebrew publication, skill distribution, site build, deployment verification, and rollback. | diff --git a/docs/engineering/TESTING.md b/docs/engineering/TESTING.md index 8bb656d..e1c278b 100644 --- a/docs/engineering/TESTING.md +++ b/docs/engineering/TESTING.md @@ -1,26 +1,20 @@ # Testing -DocSlime is verified behavior-first: the things a user actually does — scaffold a tree, add a -document, create an ADR, list templates — are exercised end-to-end by running the real -compiled binary against throwaway directories and asserting on the files it produces. Small, -fiddly logic (slug normalization, ADR numbering) is covered by fast unit tests. The bar for -shippable is simple: the full suite is green, `impeccable` can discover docs context, and the -binary's observable behavior matches the experiences and requirements. +DocSlime is verified behavior-first: the things a user actually does — scaffold a tree, add a document, create an ADR, list templates — are exercised end-to-end by running the real compiled binary against throwaway directories and asserting on the files it produces. Small, fiddly logic (slug normalization, ADR numbering) is covered by fast unit tests. The bar for shippable is simple: the full suite is green, `impeccable` can discover docs context, and the binary's observable behavior matches the experiences and requirements. ## Strategy | Layer | What it verifies | Tools | -|---|---|---| +| --- | --- | --- | | Unit | Pure logic in isolation — slug normalization, next-ADR-number computation, filename prefix parsing. | Rust `#[test]` in `src/` | | End-to-end / behavior | User-visible CLI behavior from [`../experience/README.md`](../experience/README.md) — running the actual binary and asserting on exit codes, output, and files written. | `assert_cmd`, `predicates`, `tempfile` | -There is no separate integration layer: the codebase is small and the components are best -verified together through the CLI, so the black-box tests double as integration coverage. +There is no separate integration layer: the codebase is small and the components are best verified together through the CLI, so the black-box tests double as integration coverage. ## Behavior coverage | Experience / Requirement | Scenario (Given/When/Then) | Test | -|---|---|---| +| --- | --- | --- | | Scaffold the docs tree / FR-1, FR-11, FR-15, FR-18, FR-19 | Given an empty dir, When `init`, Then the full 12-file lifecycle tree exists, including product/design context, requirements, publishing, and observability | `tests/cli.rs::init_creates_full_tree` | | Self-explaining templates | Given a scaffolded tree, When inspected, Then every template carries `` guidance | `tests/cli.rs::every_template_carries_llm_guidance` | | Mermaid flowcharts / FR-20 | Given a scaffolded tree, When diagram guidance and examples are inspected, Then flowcharts use Mermaid and reject ASCII-art guidance | `tests/cli.rs::flowcharts_use_mermaid_in_generated_docs` | @@ -44,11 +38,10 @@ verified together through the CLI, so the black-box tests double as integration ## Traceability contract -DocSlime's TDD+BDD bar is that every important behavior can be followed from intent to -proof: +DocSlime's TDD+BDD bar is that every important behavior can be followed from intent to proof: | Link | Evidence | -|---|---| +| --- | --- | | Product goal -> experience | `../PRODUCT.md` explains why the docs tree exists; `../experience/README.md` captures the evidence and journeys. | | Experience -> requirement | `../REQUIREMENTS.md` gives each behavior a stable FR/NFR ID and names the evidence it serves. | | Requirement -> BDD scenario | This file records Given/When/Then coverage for the visible behavior. | @@ -56,31 +49,19 @@ proof: | Requirement -> architecture/ADR | `ARCHITECTURE.md` names the domain boundary; durable choices link to `adrs/`. | | Release -> production evidence | `PUBLISHING.md` defines verification; `OBSERVABILITY.md` links production signals back to outcomes and discovery. | -The DDD evidence is intentionally lightweight: docs should name the domain concepts and -boundaries that affect behavior, then use ADRs for hard-to-reverse decisions. If a project -has no meaningful domain split, the architecture doc should say that instead of inventing -bounded contexts. +The DDD evidence is intentionally lightweight: docs should name the domain concepts and boundaries that affect behavior, then use ADRs for hard-to-reverse decisions. If a project has no meaningful domain split, the architecture doc should say that instead of inventing bounded contexts. ## Evaluation against product goals -Tests prove correctness; they don't prove the product is working. The product-level signals from -[`../PRODUCT.md`](../PRODUCT.md) are evaluated qualitatively: - -- **Docs get filled** — judged by whether scaffolded docs in real repos end up complete (no - leftover `` guidance), rather than abandoned as templates. DocSlime dogfoods this - by filling in its own `docs/` tree. -- **Low friction** — judged by the time and number of steps from `docslime init` to a first - useful, filled-in document. -- **Agent context quality** — judged by whether agents working in a DocSlime-backed repo give less - speculative answers because product context, requirements, and ADRs are present. -- **Impeccable context quality** — judged by whether `impeccable` resolves `docs/PRODUCT.md` - and `docs/DESIGN.md` without duplicate root files. -- **Delivery quality** — judged by whether each CLI, skill, and site artifact is verified - through its user-facing distribution path rather than inferred from workflow completion. -- **Production learning** — judged by whether release failures, feedback, and adoption - signals update discovery evidence or requirements when they reveal a material gap. -- **Skill robustness** — judged by whether skill files validate structurally and give agents - enough setup, guardrails, verification, and failure handling to act without guessing. +Tests prove correctness; they don't prove the product is working. The product-level signals from [`../PRODUCT.md`](../PRODUCT.md) are evaluated qualitatively: + +- **Docs get filled** — judged by whether scaffolded docs in real repos end up complete (no leftover `` guidance), rather than abandoned as templates. DocSlime dogfoods this by filling in its own `docs/` tree. +- **Low friction** — judged by the time and number of steps from `docslime init` to a first useful, filled-in document. +- **Agent context quality** — judged by whether agents working in a DocSlime-backed repo give less speculative answers because product context, requirements, and ADRs are present. +- **Impeccable context quality** — judged by whether `impeccable` resolves `docs/PRODUCT.md` and `docs/DESIGN.md` without duplicate root files. +- **Delivery quality** — judged by whether each CLI, skill, and site artifact is verified through its user-facing distribution path rather than inferred from workflow completion. +- **Production learning** — judged by whether release failures, feedback, and adoption signals update discovery evidence or requirements when they reveal a material gap. +- **Skill robustness** — judged by whether skill files validate structurally and give agents enough setup, guardrails, verification, and failure handling to act without guessing. - **Adoption** — tracked via Homebrew and `npx skills` installs and repos using the tree. ## Running the tests @@ -96,24 +77,16 @@ npm run build # docmd site build (expected: site/ output updates c DocSlime is now a monorepo with three CI-owned surfaces: | Workflow job | Surface | Gate | -|---|---|---| +| --- | --- | --- | | `Branch policy` | Release flow | Fails pull requests to `main` unless the source branch is `staging`; all feature work targets `staging`. | | `CLI` | Rust binary and embedded templates | `cargo fmt --check`, `cargo test`, and `cargo clippy --all-targets -- -D warnings`. | | `Site` | `docmd.io` documentation site | `npm ci` followed by `npm run build`. | | `Agent skills` | Bundled `.agents/skills/docslime-*` package | Frontmatter, OpenAI metadata, guardrail, verification, and failure-handling checks. | -The daily CI workflow lives in `.github/workflows/ci.yml` and runs on pull requests to -`staging` or `main`, pushes to those branches, and manual dispatches. The release workflow -(`.github/workflows/release.yml`, generated by `cargo-dist`) remains tag-driven: it builds -and packages the CLI for all target platforms, creates the GitHub Release, and publishes the -Homebrew formula. +The daily CI workflow lives in `.github/workflows/ci.yml` and runs on pull requests to `staging` or `main`, pushes to those branches, and manual dispatches. The release workflow (`.github/workflows/release.yml`, generated by `cargo-dist`) remains tag-driven: it builds and packages the CLI for all target platforms, creates the GitHub Release, and publishes the Homebrew formula. -GitHub also has an active repository ruleset named "Protect main and staging from deletion". -It targets `refs/heads/main` and `refs/heads/staging` with the `deletion` rule so the two -release branches cannot be removed accidentally. +GitHub also has an active repository ruleset named "Protect main and staging from deletion". It targets `refs/heads/main` and `refs/heads/staging` with the `deletion` rule so the two release branches cannot be removed accidentally. ## Test data & environments -End-to-end tests run the real binary inside a fresh `tempfile::TempDir` per test, so each one -gets an isolated throwaway directory that is cleaned up automatically — no shared state, no -fixtures to seed, and no risk of touching the working repo. +End-to-end tests run the real binary inside a fresh `tempfile::TempDir` per test, so each one gets an isolated throwaway directory that is cleaned up automatically — no shared state, no fixtures to seed, and no risk of touching the working repo. diff --git a/docs/engineering/adrs/0001-embed-templates-in-binary.md b/docs/engineering/adrs/0001-embed-templates-in-binary.md index ac98251..9027672 100644 --- a/docs/engineering/adrs/0001-embed-templates-in-binary.md +++ b/docs/engineering/adrs/0001-embed-templates-in-binary.md @@ -6,45 +6,31 @@ ## Context -DocSlime's job is to write a tree of Markdown templates into a user's repo. Those templates -have to reach the user's machine somehow. The tool's requirements call for a portable, -zero-runtime-dependency binary that works offline (NFR-1, FR-7) and installs cleanly via -Homebrew, a shell script, or `cargo install` (NFR-3). Whatever mechanism delivers the -templates must not require the user to also have a separate templates directory present, or -network access, at runtime. +DocSlime's job is to write a tree of Markdown templates into a user's repo. Those templates have to reach the user's machine somehow. The tool's requirements call for a portable, zero-runtime-dependency binary that works offline (NFR-1, FR-7) and installs cleanly via Homebrew, a shell script, or `cargo install` (NFR-3). Whatever mechanism delivers the templates must not require the user to also have a separate templates directory present, or network access, at runtime. ## Options considered ### Option A — Embed templates in the binary at compile time -- **Pros:** Single self-contained artifact; works offline; nothing to locate or install - alongside the binary; trivial to distribute via Homebrew / shell installer / `cargo install`. -- **Cons:** Editing a template requires recompiling and re-releasing; templates can't be - customized by the user without a rebuild. + +- **Pros:** Single self-contained artifact; works offline; nothing to locate or install alongside the binary; trivial to distribute via Homebrew / shell installer / `cargo install`. +- **Cons:** Editing a template requires recompiling and re-releasing; templates can't be customized by the user without a rebuild. ### Option B — Ship templates as separate data files installed next to the binary + - **Pros:** Templates editable in place; could allow user overrides without recompiling. -- **Cons:** Must reliably locate the data directory across platforms and install methods; - packaging is more complex; risk of the binary and its templates getting out of sync or the - data files going missing. +- **Cons:** Must reliably locate the data directory across platforms and install methods; packaging is more complex; risk of the binary and its templates getting out of sync or the data files going missing. ### Option C — Fetch templates from a remote source at runtime + - **Pros:** Templates updatable without releasing a new binary. -- **Cons:** Requires network access (violates the offline requirement); adds latency and a - failure mode; introduces a hosting dependency for a tool that should be instant and local. +- **Cons:** Requires network access (violates the offline requirement); adds latency and a failure mode; introduces a hosting dependency for a tool that should be instant and local. ## Decision -We will embed the entire template tree in the binary at compile time, using `include_dir!` -for the `init` tree and `include_str!` for the standalone ADR template. This makes DocSlime a -single self-contained binary with no runtime dependencies, satisfying the portability, -offline, and distribution requirements directly. +We will embed the entire template tree in the binary at compile time, using `include_dir!` for the `init` tree and `include_str!` for the standalone ADR template. This makes DocSlime a single self-contained binary with no runtime dependencies, satisfying the portability, offline, and distribution requirements directly. ## Consequences -- **Positive:** DocSlime ships as one artifact that runs anywhere with no setup, no network, - and nothing to locate at runtime — which keeps installation and usage friction low. -- **Negative:** Any template change requires recompiling and cutting a new release; users - cannot customize the templates without rebuilding from source. -- **Follow-up:** If user-customizable layouts become a requirement (tracked as an open - question in `../../REQUIREMENTS.md`), revisit with a new ADR that supersedes this one — - e.g. allowing an external template directory to override the embedded default. +- **Positive:** DocSlime ships as one artifact that runs anywhere with no setup, no network, and nothing to locate at runtime — which keeps installation and usage friction low. +- **Negative:** Any template change requires recompiling and cutting a new release; users cannot customize the templates without rebuilding from source. +- **Follow-up:** If user-customizable layouts become a requirement (tracked as an open question in `../../REQUIREMENTS.md`), revisit with a new ADR that supersedes this one — e.g. allowing an external template directory to override the embedded default. diff --git a/docs/engineering/adrs/README.md b/docs/engineering/adrs/README.md index 4462407..6da514f 100644 --- a/docs/engineering/adrs/README.md +++ b/docs/engineering/adrs/README.md @@ -1,8 +1,6 @@ # Architecture Decision Records -An **Architecture Decision Record (ADR)** captures one significant decision — the context, -the choice made, and its consequences — so the reasoning lives in the repo alongside the -code. Decisions are immutable once accepted: to change one, add a new ADR that supersedes it. +An **Architecture Decision Record (ADR)** captures one significant decision — the context, the choice made, and its consequences — so the reasoning lives in the repo alongside the code. Decisions are immutable once accepted: to change one, add a new ADR that supersedes it. ## Creating an ADR @@ -10,8 +8,7 @@ code. Decisions are immutable once accepted: to change one, add a new ADR that s docslime add adr ``` -This creates the next-numbered record, e.g. `0001-.md`. Fill it in (the file -carries inline guidance), then add a row to the log below. +This creates the next-numbered record, e.g. `0001-.md`. Fill it in (the file carries inline guidance), then add a row to the log below. ## Status values @@ -23,5 +20,5 @@ carries inline guidance), then add a row to the log below. ## Decision log | ADR | Title | Status | Date | -|---|---|---|---| +| --- | --- | --- | --- | | [0001](0001-embed-templates-in-binary.md) | Embed templates in the binary at compile time | Accepted | 2026-06-02 | diff --git a/docs/experience/README.md b/docs/experience/README.md index 4d25dbf..2d2bfc9 100644 --- a/docs/experience/README.md +++ b/docs/experience/README.md @@ -1,34 +1,23 @@ # Experience -This folder is DocSlime's continuous-discovery and experience-design workspace. It connects -observed user needs to requirements without turning research notes into an untraceable -feature backlog. +This folder is DocSlime's continuous-discovery and experience-design workspace. It connects observed user needs to requirements without turning research notes into an untraceable feature backlog. ## Discovery practice -DocSlime is maintainer-led today. Product learning comes from direct maintainer and user -feedback, issues and pull requests, real repositories using the scaffold and skills, CLI -behavior observed during development, and whether agents can act accurately from the -generated docs. Claims that lack evidence remain hypotheses rather than being written as -validated user facts. +DocSlime is maintainer-led today. Product learning comes from direct maintainer and user feedback, issues and pull requests, real repositories using the scaffold and skills, CLI behavior observed during development, and whether agents can act accurately from the generated docs. Claims that lack evidence remain hypotheses rather than being written as validated user facts. -A finding becomes a requirement when it identifies an observable behavior or measurable -quality the product must provide. A requirement remains solution-neutral; implementation -choices belong in architecture or an ADR. +A finding becomes a requirement when it identifies an observable behavior or measurable quality the product must provide. A requirement remains solution-neutral; implementation choices belong in architecture or an ADR. ## Primary participants -- **Team developer:** wants a familiar in-repo documentation system without inventing one - for every project. -- **Product or design collaborator:** needs concise product and design context that tools can - discover without maintaining duplicate files. -- **AI coding agent:** needs evidence, requirements, boundaries, and decisions close to the - code so it can ask focused questions instead of fabricating context. +- **Team developer:** wants a familiar in-repo documentation system without inventing one for every project. +- **Product or design collaborator:** needs concise product and design context that tools can discover without maintaining duplicate files. +- **AI coding agent:** needs evidence, requirements, boundaries, and decisions close to the code so it can ask focused questions instead of fabricating context. ## Core journeys | Journey | Desired outcome | Requirements | -|---|---|---| +| --- | --- | --- | | Scaffold a repo | One safe command creates the complete lifecycle-oriented docs tree. | FR-1, FR-2, FR-7 | | Add one missing document | A partial tree can gain one known template without overwriting work. | FR-2, FR-3, FR-8 | | Record a decision | The next collision-free ADR is created with a normalized memorable slug. | FR-4, FR-5 | @@ -39,22 +28,16 @@ choices belong in architecture or an ADR. ## Experience principles -- **Non-destructive by default:** existing user-authored files are never overwritten or - migrated implicitly. -- **Evidence before assertion:** agents ask rather than inventing users, systems, metrics, or - decisions. -- **Opinionated, not ceremonial:** the lifecycle is complete, but documents stay as small as - the project permits. -- **Traceable quality:** a user need can be followed to a requirement, test, decision, - release, and production signal. +- **Non-destructive by default:** existing user-authored files are never overwritten or migrated implicitly. +- **Evidence before assertion:** agents ask rather than inventing users, systems, metrics, or decisions. +- **Opinionated, not ceremonial:** the lifecycle is complete, but documents stay as small as the project permits. +- **Traceable quality:** a user need can be followed to a requirement, test, decision, release, and production signal. - **Fast and local:** the CLI works offline against the current repository. -- **Discoverable context:** standard names and a semantic tree make important context easy - for humans, agents, and publishing tools to find. +- **Discoverable context:** standard names and a semantic tree make important context easy for humans, agents, and publishing tools to find. ## Continuous-discovery artifact shape -Create one focused lowercase-kebab-case file when an opportunity, study, journey, or product -slice needs more evidence than this index can hold. Use only the sections the evidence earns: +Create one focused lowercase-kebab-case file when an opportunity, study, journey, or product slice needs more evidence than this index can hold. Use only the sections the evidence earns: ```markdown # Opportunity or experience @@ -87,5 +70,4 @@ flowchart LR ## Index -No separate discovery artifacts exist yet. Add them when evidence for a meaningful -opportunity or journey should outlive the issue or conversation where it surfaced. +No separate discovery artifacts exist yet. Add them when evidence for a meaningful opportunity or journey should outlive the issue or conversation where it surfaced. diff --git a/docs/index.md b/docs/index.md index 8abde1c..c4a6afe 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,9 +10,7 @@ image: /assets/images/docslime-hero.png # Turn your repo into living docs. -DocSlime makes repo knowledge stick. It connects product intent and continuous discovery to -requirements, architecture, tests, delivery, observability, and decisions in one local docs -body that humans and agents can use. +DocSlime makes repo knowledge stick. It connects product intent and continuous discovery to requirements, architecture, tests, delivery, observability, and decisions in one local docs body that humans and agents can use. ```sh brew install DecisionNerd/tap/docslime @@ -22,18 +20,13 @@ brew install DecisionNerd/tap/docslime ::: -DocSlime is a small CLI plus a skill pack for creating, filling, reviewing, and publishing an -opinionated `docs/` tree. The name is silly on purpose; the method is not. It pulls the -scattered parts of a project into one integrated body, then gives future humans and AI agents -better context for the next change. +DocSlime is a small CLI plus a skill pack for creating, filling, reviewing, and publishing an opinionated `docs/` tree. The name is silly on purpose; the method is not. It pulls the scattered parts of a project into one integrated body, then gives future humans and AI agents better context for the next change. [Read the full lifecycle guide](lifecycle/){.docmd-button .docmd-button-secondary} ## How to Use DocSlime -DocSlime separates **scaffolding** (CLI) from **judgment** (agent skills). You run commands -to create files; you use skills to interview the team, fill documents, record decisions, and -review for bloat. +DocSlime separates **scaffolding** (CLI) from **judgment** (agent skills). You run commands to create files; you use skills to interview the team, fill documents, record decisions, and review for bloat. ### Quick start @@ -48,7 +41,7 @@ Then fill `docs/PRODUCT.md` with `docslime-fill` and work through the tree in li ### Day-to-day commands | What you need | Command or skill | -|---|---| +| --- | --- | | See what exists | `docslime list` | | Add one missing doc | `docslime add ` | | Create the next ADR | `docslime add adr ` then `docslime-adr` | @@ -56,8 +49,7 @@ Then fill `docs/PRODUCT.md` with `docslime-fill` and work through the tree in li | Review for bloat | `docslime-kiss` (agent skill) | | Publish the site | `docmd build` (see [engineering/PUBLISHING](engineering/PUBLISHING/)) | -`init`, `add`, and `list` are CLI commands. `docslime-kiss` is intentionally a skill — it -requires judgment over filled docs, not a flag. +`init`, `add`, and `list` are CLI commands. `docslime-kiss` is intentionally a skill — it requires judgment over filled docs, not a flag. ### Recommended fill order @@ -68,8 +60,7 @@ requires judgment over filled docs, not a flag. 5. `engineering/TESTING.md` — Given/When/Then scenarios mapped to tests 6. `engineering/PUBLISHING.md` and `engineering/OBSERVABILITY.md` — delivery and learning loop -Each template includes `` guidance. Skills follow those prompts, ask one -focused question at a time, and remove scaffolding when a section is complete. +Each template includes `` guidance. Skills follow those prompts, ask one focused question at a time, and remove scaffolding when a section is complete. ## UX, DDD, and TDD+BDD in One Trace @@ -77,24 +68,15 @@ DocSlime encodes three practices as **links in one chain**, not separate ceremon ### UX — continuous discovery -The `experience/` folder captures **evidence before solutions**: observed needs, journeys, -opportunities, and hypotheses. Findings become requirements only when they describe -observable behavior the product must provide. This keeps UX research connected to the build -contract instead of rotting in a backlog. +The `experience/` folder captures **evidence before solutions**: observed needs, journeys, opportunities, and hypotheses. Findings become requirements only when they describe observable behavior the product must provide. This keeps UX research connected to the build contract instead of rotting in a backlog. ### DDD — domain language and decisions -Architecture docs name the **domain concepts, boundaries, and invariants** that matter for -the project. Significant, hard-to-reverse choices become ADRs in `engineering/adrs/`. DocSlime -uses Domain Driven Design lightly — enough vocabulary to guide the next change, without -forcing bounded-context diagrams on every repo. +Architecture docs name the **domain concepts, boundaries, and invariants** that matter for the project. Significant, hard-to-reverse choices become ADRs in `engineering/adrs/`. DocSlime uses Domain Driven Design lightly — enough vocabulary to guide the next change, without forcing bounded-context diagrams on every repo. ### TDD+BDD — proof before promotion -Requirements get stable IDs. Behavior is written as **Given/When/Then** scenarios in -`engineering/TESTING.md`. Automated tests prove observable behavior; CI gates block promotion -when the contract is broken. In this repo, `tests/cli.rs` runs the real `docslime` binary -against throwaway directories and maps every FR to a test case. +Requirements get stable IDs. Behavior is written as **Given/When/Then** scenarios in `engineering/TESTING.md`. Automated tests prove observable behavior; CI gates block promotion when the contract is broken. In this repo, `tests/cli.rs` runs the real `docslime` binary against throwaway directories and maps every FR to a test case. ### The trace @@ -108,8 +90,7 @@ flowchart LR Observation --> Evidence ``` -When production contradicts an assumption, update `experience/` or `REQUIREMENTS.md` — the -loop only works if docs stay as honest as the code. +When production contradicts an assumption, update `experience/` or `REQUIREMENTS.md` — the loop only works if docs stay as honest as the code. ## Why It Sticks @@ -126,19 +107,12 @@ flowchart LR Observation --> Strategy ``` -- **Product and design context** flows into `PRODUCT.md` and `DESIGN.md`, so agents stop - guessing what the code is for. -- **Continuous discovery** lives in `experience/`, where evidence and journeys become - solution-neutral requirements rather than an untraceable feature backlog. -- **Requirements and behavior** flow into `REQUIREMENTS.md` and `engineering/TESTING.md`, so - TDD+BDD work can trace back to evidence. -- **Domain shape and tradeoffs** flow into `engineering/ARCHITECTURE.md` and `engineering/adrs/`, so - Domain Driven Design language stays close to decisions. -- **Human judgment** flows through `docslime-fill`, `docslime-adr`, and `docslime-kiss`, so - docs get filled, decisions get recorded, and bloat gets cut. -- **Delivery and observation close the loop**: `engineering/PUBLISHING.md` defines promotion, - verification, and rollback; `engineering/OBSERVABILITY.md` connects production health and - user outcomes back to discovery. +- **Product and design context** flows into `PRODUCT.md` and `DESIGN.md`, so agents stop guessing what the code is for. +- **Continuous discovery** lives in `experience/`, where evidence and journeys become solution-neutral requirements rather than an untraceable feature backlog. +- **Requirements and behavior** flow into `REQUIREMENTS.md` and `engineering/TESTING.md`, so TDD+BDD work can trace back to evidence. +- **Domain shape and tradeoffs** flow into `engineering/ARCHITECTURE.md` and `engineering/adrs/`, so Domain Driven Design language stays close to decisions. +- **Human judgment** flows through `docslime-fill`, `docslime-adr`, and `docslime-kiss`, so docs get filled, decisions get recorded, and bloat gets cut. +- **Delivery and observation close the loop**: `engineering/PUBLISHING.md` defines promotion, verification, and rollback; `engineering/OBSERVABILITY.md` connects production health and user outcomes back to discovery. ## Install DocSlime @@ -149,9 +123,7 @@ brew install DecisionNerd/tap/docslime ``` ::: callout tip "Safe by default" -`docslime init` creates missing docs and reports what was created or skipped. It will not -overwrite existing files unless `--force` is explicit. The slime eats context, not your -worktree. +`docslime init` creates missing docs and reports what was created or skipped. It will not overwrite existing files unless `--force` is explicit. The slime eats context, not your worktree. ::: Other install paths stay available when Homebrew is not the right fit. @@ -173,6 +145,7 @@ cargo install \ ::: grids ::: grid ::: card "1. Initialize" icon:terminal + ```sh docslime init ``` @@ -183,6 +156,7 @@ Create the standard docs tree and leave clear next steps in the repo. ::: grid ::: card "2. Fill" icon:messages-square + ```sh npx skills add DecisionNerd/DocSlime ``` @@ -193,6 +167,7 @@ Use `docslime-fill` to interview the team and replace scaffold guidance with rea ::: grid ::: card "3. Decide" icon:scroll-text + ```sh docslime add adr choose-storage-boundary ``` @@ -203,14 +178,12 @@ Record significant product and technical choices while they are still fresh. ::: grid ::: card "4. Keep It Lean" icon:scissors -Run `docslime-kiss` as an agent skill to find bloat, contradictions, stale placeholders, and -weak traceability before docs become ceremony. +Run `docslime-kiss` as an agent skill to find bloat, contradictions, stale placeholders, and weak traceability before docs become ceremony. ::: ::: ::: -The recommended happy path is short: install the CLI, run `docslime init`, add the skill -pack, fill `docs/PRODUCT.md`, then use `docslime-kiss` once the first useful context exists. +The recommended happy path is short: install the CLI, run `docslime init`, add the skill pack, fill `docs/PRODUCT.md`, then use `docslime-kiss` once the first useful context exists. ## What DocSlime Creates @@ -231,38 +204,24 @@ docs/ `-- adrs/README.md ``` -`docs/PRODUCT.md` and `docs/DESIGN.md` are deliberately discoverable from the docs tree so -tools like `impeccable` can load product and design context without duplicate root files. +`docs/PRODUCT.md` and `docs/DESIGN.md` are deliberately discoverable from the docs tree so tools like `impeccable` can load product and design context without duplicate root files. -This is a starting template, not a compliance checklist. Tailor it to the project and keep -only the artifacts that reduce ambiguity for its actual consumers. A backend API in a large -organization may link to product strategy and design context owned elsewhere while retaining -`experience/` for developer experience, integration journeys, and agent experience. +This is a starting template, not a compliance checklist. Tailor it to the project and keep only the artifacts that reduce ambiguity for its actual consumers. A backend API in a large organization may link to product strategy and design context owned elsewhere while retaining `experience/` for developer experience, integration journeys, and agent experience. -- **Product + design:** `PRODUCT.md`, `DESIGN.md`, and `strategy/` capture purpose, - voice, principles, and success measures. -- **Experience + requirements:** `experience/` captures evidence, opportunities, journeys, - and hypotheses; `REQUIREMENTS.md` translates them into a testable build contract. -- **Architecture + ADRs:** `engineering/ARCHITECTURE.md` and `engineering/adrs/` keep domain - boundaries and decisions explicit. +- **Product + design:** `PRODUCT.md`, `DESIGN.md`, and `strategy/` capture purpose, voice, principles, and success measures. +- **Experience + requirements:** `experience/` captures evidence, opportunities, journeys, and hypotheses; `REQUIREMENTS.md` translates them into a testable build contract. +- **Architecture + ADRs:** `engineering/ARCHITECTURE.md` and `engineering/adrs/` keep domain boundaries and decisions explicit. - **Testing:** `engineering/TESTING.md` ties TDD and BDD coverage back to requirements and journeys. -- **Publishing + observability:** [`engineering/PUBLISHING.md`](engineering/PUBLISHING/) and - [`engineering/OBSERVABILITY.md`](engineering/OBSERVABILITY/) carry verified artifacts to - users and feed production evidence back into discovery. +- **Publishing + observability:** [`engineering/PUBLISHING.md`](engineering/PUBLISHING/) and [`engineering/OBSERVABILITY.md`](engineering/OBSERVABILITY/) carry verified artifacts to users and feed production evidence back into discovery. ## Agent Skills -DocSlime keeps judgment-heavy work in skills instead of pretending every review belongs in a -CLI subcommand. - -- `docslime-install` and `docslime-init` verify the CLI and scaffold the docs tree without - overwriting existing work. -- `docslime-fill` interviews the user, replaces scaffold guidance, and keeps facts anchored - in the repo. -- `docslime-adr` creates the next-numbered ADR and writes the decision in the project - vocabulary. -- `docslime-kiss` reviews for contradictions, generic AI prose, weak traceability, and - overgrown docs. +DocSlime keeps judgment-heavy work in skills instead of pretending every review belongs in a CLI subcommand. + +- `docslime-install` and `docslime-init` verify the CLI and scaffold the docs tree without overwriting existing work. +- `docslime-fill` interviews the user, replaces scaffold guidance, and keeps facts anchored in the repo. +- `docslime-adr` creates the next-numbered ADR and writes the decision in the project vocabulary. +- `docslime-kiss` reviews for contradictions, generic AI prose, weak traceability, and overgrown docs. ## Read Next diff --git a/docs/lifecycle.md b/docs/lifecycle.md index 2d7bbcd..b551ed9 100644 --- a/docs/lifecycle.md +++ b/docs/lifecycle.md @@ -5,12 +5,9 @@ description: "How DocSlime connects continuous discovery, Domain Driven Design, # Documentation Lifecycle -DocSlime is not just a folder generator. It encodes a full product-and-engineering loop: -learn from users, write a testable contract, shape the domain, prove behavior, ship verified -artifacts, and feed production evidence back into discovery. +DocSlime is not just a folder generator. It encodes a full product-and-engineering loop: learn from users, write a testable contract, shape the domain, prove behavior, ship verified artifacts, and feed production evidence back into discovery. -The CLI scaffolds the tree. Agent skills do the judgment-heavy work. Your job is to keep the -trace honest: every important behavior should be followable from evidence to proof. +The CLI scaffolds the tree. Agent skills do the judgment-heavy work. Your job is to keep the trace honest: every important behavior should be followable from evidence to proof. ## The closed loop @@ -28,7 +25,7 @@ flowchart LR ``` | Phase | Question | Primary docs | Methods | -|---|---|---|---| +| --- | --- | --- | --- | | Strategy | Where are we playing and why? | `strategy/`, `PRODUCT.md` | Positioning, bets, audience | | Product & design | What are we building and how should it feel? | `PRODUCT.md`, `DESIGN.md` | Product intent, design principles | | Continuous discovery (UX) | What do users actually need? | `experience/` | Evidence, journeys, hypotheses | @@ -48,15 +45,9 @@ docslime init # once per repo npx skills add DecisionNerd/DocSlime # once per agent environment ``` -`docslime init` creates the lifecycle-oriented `docs/` tree and skips anything you already -wrote. Use `docslime list` to see what exists and `docslime add ` to add one missing -document. +`docslime init` creates the lifecycle-oriented `docs/` tree and skips anything you already wrote. Use `docslime list` to see what exists and `docslime add ` to add one missing document. -Treat that tree as a starting template. Before filling it, identify the project type and its -human and agent consumers, then remove or merge irrelevant files and update `docs/README.md`. -For example, a backend API in a large organization may not own product strategy or visual -design, but `experience/` can still capture developer experience, integration friction, -operator journeys, and agent experience. +Treat that tree as a starting template. Before filling it, identify the project type and its human and agent consumers, then remove or merge irrelevant files and update `docs/README.md`. For example, a backend API in a large organization may not own product strategy or visual design, but `experience/` can still capture developer experience, integration friction, operator journeys, and agent experience. ### 2. Fill durable context first @@ -67,25 +58,21 @@ Use `docslime-fill` (or `/docslime-fill` in a skill-aware agent) in this order: 3. `strategy/` — only when positioning or roadmap needs more room than `PRODUCT.md` 4. `experience/` — evidence, journeys, opportunities, and behavior hypotheses -Each template carries `` guidance. The skill interviews you, replaces -prompts with real facts, and removes scaffolding comments when a section is done. +Each template carries `` guidance. The skill interviews you, replaces prompts with real facts, and removes scaffolding comments when a section is done. ### 3. Translate evidence into a build contract -Fill `REQUIREMENTS.md` after product, design, and discovery context exist. Requirements must -be: +Fill `REQUIREMENTS.md` after product, design, and discovery context exist. Requirements must be: - **Solution-neutral** — say what must be true, not how to implement it - **Testable** — each FR/NFR should be provable - **Traceable** — link back to journeys or evidence in `experience/` -When a finding in `experience/` identifies observable behavior the product must provide, it -becomes a requirement. Implementation choices belong in architecture or an ADR. +When a finding in `experience/` identifies observable behavior the product must provide, it becomes a requirement. Implementation choices belong in architecture or an ADR. ### 4. Shape the domain and record decisions (DDD) -Fill `engineering/ARCHITECTURE.md` to name the components, data, and boundaries that satisfy -the requirements. DocSlime uses Domain Driven Design **lightly**: +Fill `engineering/ARCHITECTURE.md` to name the components, data, and boundaries that satisfy the requirements. DocSlime uses Domain Driven Design **lightly**: - Name the **domain concepts** that affect behavior (not abstract "document management") - Draw **boundaries** between CLI scaffold, agent skills, publishing, and observation @@ -98,38 +85,29 @@ When a choice is hard to reverse, record it: docslime add adr choose-storage-boundary ``` -Then use `docslime-adr` to write the decision in project vocabulary with context, -consequences, and links to requirements. +Then use `docslime-adr` to write the decision in project vocabulary with context, consequences, and links to requirements. ### 5. Prove behavior (TDD+BDD) Fill `engineering/TESTING.md` to define how the contract is verified: | Layer | Purpose | DocSlime example | -|---|---|---| +| --- | --- | --- | | **BDD scenarios** | Given/When/Then behavior from requirements | "Given empty dir, When `init`, Then full tree exists" | | **TDD tests** | Automated proof tied to scenarios | `tests/cli.rs` black-box CLI tests | | **CI gates** | Block promotion without proof | `.github/workflows/ci.yml` | -The traceability bar: every important FR should map to at least one scenario and one test (or -an explicit reason why automation is not appropriate). +The traceability bar: every important FR should map to at least one scenario and one test (or an explicit reason why automation is not appropriate). ### 6. Ship and verify -Fill `engineering/PUBLISHING.md` with the real promotion path: artifacts, versioning, CI -gates, deployment verification, and rollback. DocSlime itself promotes `staging` → `main` -for the site and uses tag-driven releases for the CLI. +Fill `engineering/PUBLISHING.md` with the real promotion path: artifacts, versioning, CI gates, deployment verification, and rollback. DocSlime itself promotes `staging` → `main` for the site and uses tag-driven releases for the CLI. -As optional defaults, consider Semantic Versioning when public compatibility needs a clear -`MAJOR.MINOR.PATCH` contract and Conventional Commits when structured change intent would help -reviews, changelogs, or release automation. Preserve an effective existing workflow; do not -add enforcement or rewrite history without explicit team agreement. +As optional defaults, consider Semantic Versioning when public compatibility needs a clear `MAJOR.MINOR.PATCH` contract and Conventional Commits when structured change intent would help reviews, changelogs, or release automation. Preserve an effective existing workflow; do not add enforcement or rewrite history without explicit team agreement. ### 7. Learn from production -Fill `engineering/OBSERVABILITY.md` to connect system health and user-outcome signals back to -requirements and discovery hypotheses. When production contradicts an assumption, update -`experience/` or `REQUIREMENTS.md` — do not let stale docs pretend the old world is still true. +Fill `engineering/OBSERVABILITY.md` to connect system health and user-outcome signals back to requirements and discovery hypotheses. When production contradicts an assumption, update `experience/` or `REQUIREMENTS.md` — do not let stale docs pretend the old world is still true. ### 8. Keep it lean @@ -142,8 +120,7 @@ Run `docslime-kiss` before merging documentation-heavy changes. It looks for: ## UX: continuous discovery in practice -The `experience/` folder is DocSlime's UX and product-discovery workspace. It is **not** a -feature backlog dump. +The `experience/` folder is DocSlime's UX and product-discovery workspace. It is **not** a feature backlog dump. **What belongs here:** @@ -159,26 +136,22 @@ feature backlog dump. - Committed behavior (that lives in `REQUIREMENTS.md`) - Unvalidated assumptions written as facts -When evidence earns its own file, create a focused lowercase-kebab-case markdown file under -`experience/` using the artifact shape documented on the [Experience](experience/) page. +When evidence earns its own file, create a focused lowercase-kebab-case markdown file under `experience/` using the artifact shape documented on the [Experience](experience/) page. ## DDD: domain language without ceremony -DocSlime does not force heavyweight Domain Driven Design. It asks architecture docs to make -the system's nouns and boundaries explicit enough that the next human or agent can reason -about change. +DocSlime does not force heavyweight Domain Driven Design. It asks architecture docs to make the system's nouns and boundaries explicit enough that the next human or agent can reason about change. **Minimum useful DDD evidence:** | Artifact | What to capture | -|---|---| +| --- | --- | | Domain concepts | The words the team actually uses (`docs tree`, `template`, `ADR`, `skill`) | | Boundaries | What the CLI owns vs. what agents, CI, or publishing own | | Aggregates / invariants | Rules that must stay true (e.g. "never overwrite without `--force`") | | ADRs | Durable decisions with consequences | -If a project has no meaningful domain split, say so in architecture instead of inventing -bounded contexts. +If a project has no meaningful domain split, say so in architecture instead of inventing bounded contexts. ## TDD+BDD: from intent to proof @@ -195,34 +168,30 @@ flowchart LR **Requirements** (`REQUIREMENTS.md`) hold stable IDs and observable statements. -**BDD scenarios** live in `engineering/TESTING.md` (and optionally in `experience/` while -still hypothesis-level) as Given/When/Then prose. +**BDD scenarios** live in `engineering/TESTING.md` (and optionally in `experience/` while still hypothesis-level) as Given/When/Then prose. -**TDD tests** are the automated proof — in DocSlime's own repo, Rust integration tests run the -compiled `docslime` binary against throwaway directories and assert on files and exit codes. +**TDD tests** are the automated proof — in DocSlime's own repo, Rust integration tests run the compiled `docslime` binary against throwaway directories and assert on files and exit codes. **CI** is the promotion gate — if tests fail, the behavior contract is not met. -Dogfooding example: DocSlime's [`engineering/TESTING.md`](engineering/TESTING/) maps every FR -to a `tests/cli.rs` case. The site build and agent-skill validation run in CI alongside the -CLI suite. +Dogfooding example: DocSlime's [`engineering/TESTING.md`](engineering/TESTING/) maps every FR to a `tests/cli.rs` case. The site build and agent-skill validation run in CI alongside the CLI suite. ## Command and skill reference -| Task | CLI | Agent skill | -|---|---|---| -| Install binary | `brew install …` | `docslime-install` | -| Scaffold tree | `docslime init` | `docslime-init` | -| Add one doc | `docslime add ` | — | -| Add ADR shell | `docslime add adr ` | `docslime-adr` | -| List templates | `docslime list` | — | -| Fill a document | — | `docslime-fill` | -| Review for bloat | — | `docslime-kiss` | +| Task | CLI | Agent skill | +| ---------------- | ------------------------- | ------------------ | +| Install binary | `brew install …` | `docslime-install` | +| Scaffold tree | `docslime init` | `docslime-init` | +| Add one doc | `docslime add ` | — | +| Add ADR shell | `docslime add adr ` | `docslime-adr` | +| List templates | `docslime list` | — | +| Fill a document | — | `docslime-fill` | +| Review for bloat | — | `docslime-kiss` | ## When to update what | Change type | Update | -|---|---| +| --- | --- | | New user evidence | `experience/` → then `REQUIREMENTS.md` if behavior changes | | New behavior commitment | `REQUIREMENTS.md` → `engineering/TESTING.md` → tests | | New durable technical choice | `docslime add adr …` → link from architecture | diff --git a/docs/skills.md b/docs/skills.md index c275f56..a307b44 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -5,12 +5,9 @@ description: "Teach AI coding agents to install, initialize, fill, review, and m # Agent Skills -DocSlime ships agent skills so Codex, Claude Code, ChatGPT, and other skill-aware tools can -drive the documentation lifecycle with the same product rules the CLI scaffolds. +DocSlime ships agent skills so Codex, Claude Code, ChatGPT, and other skill-aware tools can drive the documentation lifecycle with the same product rules the CLI scaffolds. -The CLI creates files. The skills do the judgment-heavy work: check installation, scaffold a -repo, interview the user, fill documents, create ADRs, and review the result for KISS -problems. +The CLI creates files. The skills do the judgment-heavy work: check installation, scaffold a repo, interview the user, fill documents, create ADRs, and review the result for KISS problems. ## Install @@ -28,7 +25,7 @@ npx skills add DecisionNerd/DocSlime --agent claude-code ## Skills | Skill | What it does | -|---|---| +| --- | --- | | `docslime-install` | Verifies the `docslime` binary and installs it if missing. | | `docslime-init` | Confirms the current repo and scaffolds the standard `docs/` tree. | | `docslime-fill` | Interviews the user and fills one scaffolded document. | @@ -37,17 +34,14 @@ npx skills add DecisionNerd/DocSlime --agent claude-code ## Skill Quality Bar -DocSlime skills are intentionally closer to small operating procedures than prompt snippets. -Each bundled skill should tell an agent: +DocSlime skills are intentionally closer to small operating procedures than prompt snippets. Each bundled skill should tell an agent: - **When to use it** and when to hand off to another DocSlime skill. - **Prerequisites** such as an installed `docslime` binary, a repo root, or an existing docs tree. - **Steps** that preserve user work and ask for missing facts instead of inventing them. -- **Guardrails** for the command surface: `init`, `add`, and `list` are CLI commands; - `docslime-kiss` is a skill. +- **Guardrails** for the command surface: `init`, `add`, and `list` are CLI commands; `docslime-kiss` is a skill. - **Verification** commands or checks that prove the work finished. -- **Failure handling** for missing binaries, missing docs, ambiguous targets, dirty context, or - unfinished `LLM:` guidance. +- **Failure handling** for missing binaries, missing docs, ambiguous targets, dirty context, or unfinished `LLM:` guidance. ## How it works at runtime @@ -61,25 +55,19 @@ Once installed, invoke the skills from inside the agent: /docslime-kiss ``` -Each skill follows the docs tree instead of maintaining a separate source of truth. Product -context lives in `docs/PRODUCT.md`, design context lives in `docs/DESIGN.md`, and decisions -live in `docs/engineering/adrs/`. +Each skill follows the docs tree instead of maintaining a separate source of truth. Product context lives in `docs/PRODUCT.md`, design context lives in `docs/DESIGN.md`, and decisions live in `docs/engineering/adrs/`. -See the [lifecycle guide](lifecycle/) for how skills fit into continuous discovery, Domain -Driven Design, and TDD+BDD traceability. +See the [lifecycle guide](lifecycle/) for how skills fit into continuous discovery, Domain Driven Design, and TDD+BDD traceability. -The same files feed design work: `impeccable` loads `docs/PRODUCT.md` and `docs/DESIGN.md` -for homepage/product critique, so skill-driven doc updates improve future UI iteration too. +The same files feed design work: `impeccable` loads `docs/PRODUCT.md` and `docs/DESIGN.md` for homepage/product critique, so skill-driven doc updates improve future UI iteration too. ## Recommended flow 1. Run `docslime init`. 2. Fill `PRODUCT.md` with `docslime-fill`. -3. Capture discovery in `experience/`, translate it into `REQUIREMENTS.md`, then work through - architecture, testing, publishing, and observability. +3. Capture discovery in `experience/`, translate it into `REQUIREMENTS.md`, then work through architecture, testing, publishing, and observability. 4. Use `docslime-adr` whenever a durable technical or product decision is made. -5. Run `docslime-kiss` before merging documentation-heavy changes and whenever production - learning exposes stale assumptions. +5. Run `docslime-kiss` before merging documentation-heavy changes and whenever production learning exposes stale assumptions. ## Validation @@ -89,8 +77,4 @@ Run the repo-native checks before release or after changing skill metadata: cargo test ``` -The repository tests inspect the bundled skills for required sections, so skill robustness -stays part of the normal test loop. CI also has a dedicated `Agent skills` job that checks -every bundled `docslime-*` skill for frontmatter, OpenAI metadata, guardrails, verification, -and failure handling. When working in a harness that ships the Agent Skills validator, also -run `quick_validate.py .agents/skills/` for each changed skill. +The repository tests inspect the bundled skills for required sections, so skill robustness stays part of the normal test loop. CI also has a dedicated `Agent skills` job that checks every bundled `docslime-*` skill for frontmatter, OpenAI metadata, guardrails, verification, and failure handling. When working in a harness that ships the Agent Skills validator, also run `quick_validate.py .agents/skills/` for each changed skill. diff --git a/docs/strategy/README.md b/docs/strategy/README.md index 759f00b..9056645 100644 --- a/docs/strategy/README.md +++ b/docs/strategy/README.md @@ -1,22 +1,17 @@ # Strategy -This folder expands [`../PRODUCT.md`](../PRODUCT.md) with strategic context that changes at a -different cadence from the durable product definition. +This folder expands [`../PRODUCT.md`](../PRODUCT.md) with strategic context that changes at a different cadence from the durable product definition. ## Current strategic frame - **Audience:** engineering teams using AI agents across services and user-facing products. -- **Alternative:** wikis, generic doc generators, tickets, and ad hoc `docs/` conventions - that do not give agents a predictable, fillable, traceable context structure. -- **Positioning:** a small opinionated CLI plus agent skills that make living in-repo docs - easier to create, fill, review, and maintain. +- **Alternative:** wikis, generic doc generators, tickets, and ad hoc `docs/` conventions that do not give agents a predictable, fillable, traceable context structure. +- **Positioning:** a small opinionated CLI plus agent skills that make living in-repo docs easier to create, fill, review, and maintain. - **Distribution:** Homebrew, install script, source build, and reusable agent skills. - **Business model:** free and open source today. -Requirements do not live here. Validated product needs become stable commitments in -[`../REQUIREMENTS.md`](../REQUIREMENTS.md). +Requirements do not live here. Validated product needs become stable commitments in [`../REQUIREMENTS.md`](../REQUIREMENTS.md). ## Index -No additional strategy documents exist yet. Add one focused file when market evidence, -positioning, roadmap, or another strategic bet needs more detail than `PRODUCT.md`. +No additional strategy documents exist yet. Add one focused file when market evidence, positioning, roadmap, or another strategic bet needs more detail than `PRODUCT.md`. diff --git a/package.json b/package.json index 716faa3..6801f3a 100644 --- a/package.json +++ b/package.json @@ -5,7 +5,7 @@ "type": "module", "scripts": { "dev": "docmd dev", - "build": "docmd build", + "build": "docmd build && node scripts/check-rendered-line-breaks.mjs", "preview": "npx serve site" }, "dependencies": { diff --git a/scripts/check-rendered-line-breaks.mjs b/scripts/check-rendered-line-breaks.mjs new file mode 100644 index 0000000..bed322c --- /dev/null +++ b/scripts/check-rendered-line-breaks.mjs @@ -0,0 +1,36 @@ +import { readdir, readFile } from "node:fs/promises"; +import { join, relative } from "node:path"; + +const siteRoot = new URL("../site/", import.meta.url); +const allowedHeroBreak = /docslime-hero-wordmark-light"[^>]*>
\s*]*docslime-hero-wordmark-dark/g; +const failures = []; + +async function checkDirectory(directory) { + for (const entry of await readdir(directory, { withFileTypes: true })) { + const path = join(directory, entry.name); + + if (entry.isDirectory()) { + await checkDirectory(path); + continue; + } + + if (!entry.name.endsWith(".html")) continue; + + const html = await readFile(path, "utf8"); + const unexpectedBreaks = html.replace(allowedHeroBreak, "").match(/
/g)?.length ?? 0; + + if (unexpectedBreaks > 0) { + failures.push(`${relative(siteRoot.pathname, path)}: ${unexpectedBreaks} unexpected
element(s)`); + } + } +} + +await checkDirectory(siteRoot.pathname); + +if (failures.length > 0) { + console.error("Rendered documentation contains source-wrapped prose:"); + for (const failure of failures) console.error(`- ${failure}`); + process.exit(1); +} + +console.log("Verified rendered documentation has no unintended line breaks.");