diff --git a/.agents/skills/docslime-adr/SKILL.md b/.agents/skills/docslime-adr/SKILL.md index 6568bc2..07f0cbe 100644 --- a/.agents/skills/docslime-adr/SKILL.md +++ b/.agents/skills/docslime-adr/SKILL.md @@ -23,7 +23,7 @@ The `docs/` tree must exist (run **docslime-init** if not) and `docslime` must b - Record one decision per ADR. Do not use an ADR to relitigate the whole system. - Keep accepted ADRs immutable; create a new superseding ADR for changed decisions. -- Tie context back to requirement IDs, domain boundaries, constraints, or forces when they are known. +- Tie context back to requirement IDs, modeled concepts, relationships, rules, constraints, workflows, responsibility boundaries, or forces when they are known. - Ask the user what options were actually considered; do not invent alternatives for polish. ## Steps diff --git a/.agents/skills/docslime-fill/SKILL.md b/.agents/skills/docslime-fill/SKILL.md index 1f6f04a..1022a84 100644 --- a/.agents/skills/docslime-fill/SKILL.md +++ b/.agents/skills/docslime-fill/SKILL.md @@ -35,12 +35,13 @@ This is a menu and a common order, not a mandatory checklist. First identify whi ## Guardrails +- Use practical domain modeling: understand the real-world problem before designing the solution, establish preferred terminology, and carry meaningful concepts, relationships, constraints, rules, workflows, and lifecycle states through product decisions, implementation, and verification. - Do not invent product facts, requirements, architecture, tests, decisions, users, or metrics. - Do not fill or preserve a document merely because the template created it. Recommend removing, merging, or replacing irrelevant docs with a link to the authoritative source. - Treat developers, operators, integrators, and coding agents as real users when they consume a service, library, SDK, CLI, or API; retain `experience/` when DX or agent experience matters. - Ask one focused question at a time when facts are missing. - Preserve existing user-written content unless it conflicts with a correction the user gives. -- Keep requirements testable and solution-neutral, architecture grounded in real domain boundaries, and testing mapped to Given/When/Then behavior. +- Keep requirements testable and solution-neutral, architecture grounded in the real-world concepts, relationships, constraints, rules, workflows, lifecycle states, responsibility boundaries, and preferred terminology that matter, and testing mapped to Given/When/Then behavior. - Keep publishing grounded in actual artifacts, gates, promotion, verification, and rollback. - Present Semantic Versioning and Conventional Commits as optional publishing practices. Read the existing workflow first; never impose enforcement, rewrite history, or change release automation without explicit team agreement. - Keep observability tied to user outcomes as well as system health; never invent telemetry. @@ -60,7 +61,7 @@ Read all of them before asking anything, so you understand the whole document. Follow the guidance comments. Ask **one focused question at a time**, reflect the user's answer back in your own words, and confirm before writing. Don't dump every question at once and don't invent facts — if the user doesn't know something, note it and move on. -Pull context from the applicable lifecycle: when filling `REQUIREMENTS.md`, ground it in the retained local docs, experience evidence, and linked organization-level sources. When filling observability, trace signals back to requirements and discovery hypotheses. +Pull context from the applicable lifecycle: real-world problem -> shared terminology and model -> product decisions -> implementation -> verification. When filling `REQUIREMENTS.md`, ground it in the retained local docs, experience evidence, and linked organization-level sources. When filling observability, trace signals back to requirements and discovery hypotheses so new evidence can refine the model. ### 3 — Write each section diff --git a/.agents/skills/docslime-init/SKILL.md b/.agents/skills/docslime-init/SKILL.md index 3515bb1..7edd393 100644 --- a/.agents/skills/docslime-init/SKILL.md +++ b/.agents/skills/docslime-init/SKILL.md @@ -54,7 +54,7 @@ docs/ ├── experience/ # continuous discovery and experience design └── engineering/ ├── README.md # engineering lifecycle index - ├── ARCHITECTURE.md # domain and system design + ├── ARCHITECTURE.md # problem model and system design ├── TESTING.md # testing strategy and CI evidence ├── PUBLISHING.md # continuous delivery and rollback ├── OBSERVABILITY.md # production health and product learning @@ -81,7 +81,7 @@ docslime list ### 5 — Orient and hand off -The docs form a lifecycle: strategy -> product/design -> discovery -> requirements -> architecture -> testing -> publishing -> observability -> discovery. Each template contains inline `` guidance for interviewing the user and filling the sections. +The docs connect real-world problem -> shared terminology and model -> product decisions -> implementation -> verification, within the broader strategy -> product/design -> discovery -> requirements -> architecture -> testing -> publishing -> observability -> discovery lifecycle. Each template contains inline `` guidance for interviewing the user and filling the sections. Tell the user the tailored tree is ready, and offer to start filling the first applicable document with the **docslime-fill** skill. Begin with `docs/PRODUCT.md` only when project-level product context belongs in this repo; otherwise start with the most relevant experience, requirements, or architecture document. diff --git a/.agents/skills/docslime-kiss/SKILL.md b/.agents/skills/docslime-kiss/SKILL.md index fa2c735..b6f6b7d 100644 --- a/.agents/skills/docslime-kiss/SKILL.md +++ b/.agents/skills/docslime-kiss/SKILL.md @@ -37,7 +37,7 @@ Answer with evidence from the files, not vibes. - Lead with concrete findings and file references. - Prefer deleting filler over rewriting it into prettier filler. - Distinguish current behavior from target architecture or future ideas. -- Do not invent missing strategy, requirements, domain boundaries, tests, or ADRs. +- Do not invent missing strategy, requirements, concepts, relationships, rules, workflows, responsibility boundaries, tests, or ADRs. - Do not penalize a project for intentionally removing irrelevant template files. Judge whether the retained tree serves its actual users, including developers and agents. - Do not rewrite accepted ADRs except for path/index maintenance; create a superseding ADR when a decision changes. @@ -57,6 +57,7 @@ Good DocSlime docs are: - **Fit for purpose:** retain only docs that help this project's humans or agents make better decisions; omissions are explicit and authoritative external context is linked. - **Short enough to maintain:** no filler sections kept only because the template had them. - **Traceable:** requirements serve evidence; architecture serves requirements; tests prove behavior; publishing delivers verified artifacts; observability feeds production evidence back into discovery. +- **Terminology-aligned:** the same preferred names for meaningful concepts, relationships, rules, workflows, and lifecycle states appear across product docs, requirements, interfaces, code, and tests unless a distinction is documented. - **Checkable:** requirements and testing claims can be verified. - **Current-state honest:** distinguish implemented behavior from target architecture or future ideas. - **Decision-light:** major durable choices live in ADRs; ordinary implementation detail does not. diff --git a/.impeccable/critique/2026-07-09T20-59-43Z__docs-index-md.md b/.impeccable/critique/2026-07-09T20-59-43Z__docs-index-md.md index 6173b72..abb7e52 100644 --- a/.impeccable/critique/2026-07-09T20-59-43Z__docs-index-md.md +++ b/.impeccable/critique/2026-07-09T20-59-43Z__docs-index-md.md @@ -9,6 +9,8 @@ slug: docs-index-md Method: dual-agent (A: 019f48a8-cfba-77c2-9f76-630962df1a34 · B: 019f48a8-f6e0-7a10-9c31-fd531f345f45) +> Historical context: This timestamped critique records the homepage's former methodology wording. Current DocSlime guidance uses practical domain modeling. + ## Design Health Score | # | Heuristic | Score | Key Issue | diff --git a/.impeccable/critique/2026-07-09T21-58-35Z__docs-index-md.md b/.impeccable/critique/2026-07-09T21-58-35Z__docs-index-md.md index 332496e..f5ab8f2 100644 --- a/.impeccable/critique/2026-07-09T21-58-35Z__docs-index-md.md +++ b/.impeccable/critique/2026-07-09T21-58-35Z__docs-index-md.md @@ -9,6 +9,8 @@ slug: docs-index-md Method: dual-agent (A: 019f48db-2792-7db3-8b40-dfec3def1718 · B: 019f48db-5277-75b1-a137-fa0fdf79d6ce) +> Historical context: This timestamped critique records the homepage's former methodology wording. Current DocSlime guidance uses practical domain modeling. + # DocSlime Homepage Completion Critique ## Design Health Score diff --git a/Cargo.toml b/Cargo.toml index 1056a18..05cf28b 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,7 +3,7 @@ name = "docslime" version = "0.3.0" edition = "2021" rust-version = "1.74" -description = "Opinionated DocSlime docs scaffolding for AI agents, TDD+BDD, DDD, and ADRs" +description = "Traceable documentation lifecycle scaffolding for AI agents, domain modeling, TDD+BDD, and ADRs" license = "MIT" homepage = "https://docmd.io" repository = "https://github.com/DecisionNerd/DocSlime" diff --git a/README.md b/README.md index 98ac6a0..37ec9a0 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ DocSlime is an opinionated CLI and agent-skill system for turning a repo into a living, agent-ready documentation workspace. It scaffolds a standardized docs tree that coding agents can fill in with you, then tighten through skills like `docslime-fill`, `docslime-adr`, and `docslime-kiss`. -The point is to keep a complete product-and-engineering learning loop in the repo: strategy, product/design context, continuous discovery, requirements, architecture, TDD/BDD evidence, delivery, observability, and decisions. DocSlime is built for services and user-facing products with user-driven Domain Driven Design and explicit traceability from evidence to production learning. +The point is to keep a complete product-and-engineering learning loop in the repo: strategy, product/design context, continuous discovery, requirements, architecture, TDD/BDD evidence, delivery, observability, and decisions. DocSlime uses domain modeling to bring the concepts, relationships, constraints, and workflows of the real-world problem into the development cycle, with explicit traceability from evidence to production learning. ## The tree it creates @@ -18,7 +18,7 @@ docs/ │ └── README.md # continuous discovery and experience design └── engineering/ ├── README.md # engineering lifecycle index - ├── ARCHITECTURE.md # domain and system design + ├── ARCHITECTURE.md # problem model and system design ├── TESTING.md # TDD/BDD strategy and CI evidence ├── PUBLISHING.md # continuous delivery, verification, rollback ├── OBSERVABILITY.md # production health and user-outcome learning diff --git a/docs/DESIGN.md b/docs/DESIGN.md index e3665ce..94f2acc 100644 --- a/docs/DESIGN.md +++ b/docs/DESIGN.md @@ -16,7 +16,7 @@ DocSlime has no graphical app today, but it still has a product experience: the - **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. +- **Terminology:** use "docs tree," "product context," "design context," "requirements," "domain modeling," "BDD," "ADR," "template," "skill," and "agent" consistently across docs, interfaces, code, and tests. - **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 @@ -52,7 +52,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. +- Architecture docs should model the real-world concepts, relationships, constraints, rules, workflows, lifecycle states, and responsibility boundaries that matter to the project. - 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. diff --git a/docs/PRODUCT.md b/docs/PRODUCT.md index 03f6084..8a7e802 100644 --- a/docs/PRODUCT.md +++ b/docs/PRODUCT.md @@ -23,7 +23,7 @@ The system is playful in name but serious in method: it gathers the scattered pi - **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 stance:** requirements should trace to BDD scenarios and tests, architecture should carry a practical model of the problem into implementation, and significant choices should become ADRs. ## Quality Method @@ -31,18 +31,15 @@ DocSlime's quality method is a trace, not a ceremony: ```mermaid flowchart LR - Strategy["Strategy"] --> ProductDesign["Product / design"] - ProductDesign --> Discovery["Discovery"] - Discovery --> Requirement["Requirement"] - Requirement --> Architecture["Architecture"] - Architecture --> Test["Test"] - Test --> Publish["Publish"] - Publish --> Observe["Observe"] - Observe --> Strategy + Problem["Real-world problem"] --> Model["Shared terminology and model"] + Model --> Decisions["Product decisions"] + Decisions --> Implementation["Implementation"] + Implementation --> Verification["Verification"] + Verification -. "Refine understanding" .-> Problem ``` - **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. +- **Domain modeling:** DocSlime uses domain modeling to bring the concepts, relationships, constraints, and workflows of the real-world problem into the development cycle. Model the problem clearly, use the same terminology throughout the project, and ensure the software reflects the meaningful concepts, rules, and workflows of that problem. - **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. diff --git a/docs/README.md b/docs/README.md index f6292a1..b3267c3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,7 +2,7 @@ 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 problem → model → product decisions → implementation → verification trace and day-to-day tool usage. ## Adapt the scaffold diff --git a/docs/REQUIREMENTS.md b/docs/REQUIREMENTS.md index 3f6d24a..c3e9bd1 100644 --- a/docs/REQUIREMENTS.md +++ b/docs/REQUIREMENTS.md @@ -19,7 +19,7 @@ DocSlime must scaffold a fixed, standardized `docs/` tree into a git repo, add i | FR-11 | The generated tree shall include `docs/PRODUCT.md` and `docs/DESIGN.md` so `impeccable` can discover product and design context from the docs directory without duplicate root files. | Integrate with impeccable | | FR-12 | KISS review shall remain an agent skill rather than a `docslime` CLI subcommand. | Tighten docs after filling | | FR-13 | Documentation guidance shall make the lifecycle trace explicit: strategy -> product/design -> discovery -> requirement -> architecture -> test -> publish -> observe -> discovery, with ADRs linked when a durable decision explains the design. | Trace intent through production | -| FR-14 | Architecture guidance shall ask for domain language and boundaries when useful, without forcing heavyweight Domain Driven Design ceremony on small projects. | Domain Driven Design | +| FR-14 | Architecture guidance shall ask teams to model the real-world problem through its meaningful concepts, relationships, constraints, rules, workflows, lifecycle states, preferred terminology, and responsibility boundaries without requiring ceremonial abstractions. | Domain modeling | | FR-15 | Publishing guidance shall cover artifacts, versioning, CI gates, promotion, deployment verification, rollback, and official platform references without copying volatile provider instructions. | Publish verified artifacts | | FR-16 | Each bundled DocSlime skill shall include clear prerequisites, steps, guardrails, verification, and failure handling. | Robust agent skills | | FR-17 | When a legacy numbered path exists, `init` and `list` shall recognize it as satisfying the corresponding current template and shall not create a duplicate renamed file unless `--force` is explicit. | Preserve existing documentation during upgrades | @@ -40,7 +40,7 @@ DocSlime must scaffold a fixed, standardized `docs/` tree into a git repo, add i | NFR-5 | Maintainability | Templates are plain Markdown files in the repo, editable without touching Rust logic (rebuild required). | | NFR-6 | Toolchain | Builds with Rust 1.74+ (2021 edition). | | NFR-7 | Publication | Generated docs remain plain Markdown suitable for the `docmd.io` publishing system. | -| NFR-8 | Quality stance | Docs support TDD+BDD traceability, Domain Driven Design framing where useful, and ADR-backed decisions. | +| NFR-8 | Quality stance | Docs connect the real-world problem and shared model to product decisions, implementation, TDD+BDD verification, and ADR-backed decisions. | | NFR-9 | Skill maintainability | Skill instructions stay compact enough for agents to follow while still naming setup, verification, and blocked-state behavior. | | NFR-10 | Design context | `impeccable` context loading should be verified from `docs/PRODUCT.md` and `docs/DESIGN.md` whenever homepage or design docs change. | | NFR-11 | Privacy | The default observability guidance must not normalize collecting sensitive repository or user data without an explicit decision, consent, and controls. | diff --git a/docs/engineering/ARCHITECTURE.md b/docs/engineering/ARCHITECTURE.md index 3cbea8a..326b478 100644 --- a/docs/engineering/ARCHITECTURE.md +++ b/docs/engineering/ARCHITECTURE.md @@ -41,27 +41,30 @@ DocSlime is essentially stateless — it stores nothing of its own. The only per 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 +## Problem model and terminology -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 modeling to bring the concepts, relationships, constraints, and workflows of the real-world problem into the development cycle. Model the problem clearly, use the same terminology throughout the project, and ensure the software reflects the meaningful concepts, rules, and workflows of that problem. -| Domain concept | Meaning in DocSlime | Boundary | +| Concept | Meaning in DocSlime | Relationships, states, and rules | | --- | --- | --- | -| 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 | -| Lifecycle trace | Links from discovery evidence through requirements, architecture, tests, publishing, observability, and back to discovery. | Docs content | -| Design context | `docs/PRODUCT.md` and `docs/DESIGN.md` loaded by tools like `impeccable`. | External tool integration | -| Publishing | Promotion of verified CLI, skill, and documentation artifacts to users. | Engineering delivery boundary | -| Observability | Release verification plus system-health and user-outcome evidence that feeds discovery. | Engineering/product feedback boundary | - -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. +| Target project | The repository where DocSlime writes documentation. | Owns one generated docs tree; existing files are preserved unless `--force` is explicit. | +| Template catalog | The embedded Markdown tree and ADR template available to scaffold. | Supplies initial documents; it is read-only at runtime and changes only when the binary is rebuilt. | +| Docs tree | The project-specific documentation workspace under `docs/`. | Begins as a template, may omit irrelevant areas, and connects product context, experience evidence, requirements, architecture, verification, decisions, publication, and production learning. | +| Document lifecycle | The progression from scaffold guidance to project-specific content and later maintenance. | A document is scaffolded, filled, reviewed, published when applicable, and refined as understanding changes; existing user files remain untouched by default. | +| Write outcome | The result of attempting to write a template or ADR. | `Created`, `Skipped`, and `Overwritten` are explicit outcomes; overwrite requires `--force`. | +| Lifecycle trace | The connection from a real-world problem through a shared model, product decisions, implementation, and verification. | Preferred terminology, rules, workflows, requirements, interfaces, tests, decisions, and production evidence should remain linked and consistent. | +| Decision record | A numbered ADR explaining a significant product or technical choice. | Created from the next available number, linked to affected requirements or concepts, and retained as durable rationale. | +| Publication artifact | A verified CLI release, skill package, or rendered documentation site delivered to users. | Must pass its gates, follow the applicable promotion path, and be verified through a user-facing path. | + +The CLI does not persist a runtime model or lifecycle database. These concepts clarify the files, states, rules, and workflows already present in the product. + +### Responsibility boundaries + +- **CLI scaffold:** resolve templates, create or list documents, and report non-destructive write outcomes. +- **Agent skills:** interview people, turn project knowledge into documentation, review quality, and record decisions with human input. +- **Project documentation:** hold the shared terminology, model, product decisions, requirements, implementation guidance, verification evidence, and learning trace. +- **Publishing systems:** build, version, promote, verify, and recover CLI, skill, and documentation artifacts through their distribution paths. +- **Observation practice:** turn verification failures, feedback, health signals, and outcomes into evidence that refines the problem model and future decisions. ## Key flows diff --git a/docs/engineering/TESTING.md b/docs/engineering/TESTING.md index e1c278b..e533172 100644 --- a/docs/engineering/TESTING.md +++ b/docs/engineering/TESTING.md @@ -46,10 +46,10 @@ DocSlime's TDD+BDD bar is that every important behavior can be followed from int | 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. | | Scenario -> test | `tests/cli.rs` runs the compiled binary against throwaway directories and asserts on output files, exit codes, and help text. | -| Requirement -> architecture/ADR | `ARCHITECTURE.md` names the domain boundary; durable choices link to `adrs/`. | +| Model / requirement -> architecture or ADR | `ARCHITECTURE.md` names the affected concepts, rules, workflows, lifecycle states, and responsibility boundaries; 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. +Domain modeling connects problem understanding to verification: docs use consistent terminology for meaningful concepts, relationships, constraints, rules, workflows, and lifecycle states; product decisions and interfaces carry that model into implementation; Given/When/Then scenarios and tests prove the resulting behavior. The model should be refined when verification exposes a mistaken assumption or missing rule. ## Evaluation against product goals diff --git a/docs/experience/README.md b/docs/experience/README.md index ca8144a..798f3e8 100644 --- a/docs/experience/README.md +++ b/docs/experience/README.md @@ -56,7 +56,7 @@ Create one focused lowercase-kebab-case file when an opportunity, study, journey ## Given / When / Then scenarios -## Constraints and domain language +## Concepts, terminology, and constraints ## Success signals and telemetry diff --git a/docs/index.md b/docs/index.md index c4a6afe..4a62f08 100644 --- a/docs/index.md +++ b/docs/index.md @@ -56,13 +56,13 @@ Then fill `docs/PRODUCT.md` with `docslime-fill` and work through the tree in li 1. `PRODUCT.md` and `DESIGN.md` — durable product and design context 2. `experience/` — user evidence, journeys, and hypotheses 3. `REQUIREMENTS.md` — testable build contract derived from evidence -4. `engineering/ARCHITECTURE.md` and `engineering/adrs/` — domain shape and decisions +4. `engineering/ARCHITECTURE.md` and `engineering/adrs/` — problem model, system design, and decisions 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. -## UX, DDD, and TDD+BDD in One Trace +## UX, Domain Modeling, and TDD+BDD in One Trace DocSlime encodes three practices as **links in one chain**, not separate ceremonies. @@ -70,9 +70,9 @@ DocSlime encodes three practices as **links in one chain**, not separate ceremon 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 +### Domain modeling — concepts, rules, and workflows -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. +DocSlime uses domain modeling to bring the concepts, relationships, constraints, and workflows of the real-world problem into the development cycle. Model the problem clearly, use the same terminology throughout the project, and ensure the software reflects the meaningful concepts, rules, and workflows of that problem. Significant, hard-to-reverse choices become ADRs in `engineering/adrs/`. ### TDD+BDD — proof before promotion @@ -82,12 +82,11 @@ Requirements get stable IDs. Behavior is written as **Given/When/Then** scenario ```mermaid flowchart LR - Evidence["Evidence"] --> Requirement["Requirement"] - Requirement --> BDD["BDD scenario"] - BDD --> Test["Test"] - Test --> Release["Release"] - Release --> Observation["Observation"] - Observation --> Evidence + Problem["Real-world problem"] --> Model["Shared terminology and model"] + Model --> Decisions["Product decisions"] + Decisions --> Implementation["Implementation"] + Implementation --> Verification["Verification"] + Verification -. "Refine understanding" .-> Problem ``` When production contradicts an assumption, update `experience/` or `REQUIREMENTS.md` — the loop only works if docs stay as honest as the code. @@ -110,7 +109,7 @@ flowchart LR - **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. +- **Concepts, relationships, rules, workflows, and tradeoffs** flow into `engineering/ARCHITECTURE.md` and `engineering/adrs/`, so the shared model stays connected to product decisions and implementation. - **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. @@ -210,7 +209,7 @@ This is a starting template, not a compliance checklist. Tailor it to the projec - **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. +- **Architecture + ADRs:** `engineering/ARCHITECTURE.md` and `engineering/adrs/` keep the shared problem model, responsibility 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. @@ -228,7 +227,7 @@ DocSlime keeps judgment-heavy work in skills instead of pretending every review ::: grids ::: grid ::: card "Lifecycle" icon:workflow -[How UX, DDD, and TDD+BDD connect](lifecycle/){.docmd-button .docmd-button-secondary} +[How UX, domain modeling, and TDD+BDD connect](lifecycle/){.docmd-button .docmd-button-secondary} ::: ::: diff --git a/docs/lifecycle.md b/docs/lifecycle.md index b551ed9..36d4885 100644 --- a/docs/lifecycle.md +++ b/docs/lifecycle.md @@ -1,11 +1,11 @@ --- title: "Documentation Lifecycle" -description: "How DocSlime connects continuous discovery, Domain Driven Design, and TDD+BDD into one traceable docs body." +description: "How DocSlime connects continuous discovery, domain modeling, and TDD+BDD into one traceable documentation lifecycle." --- # 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: understand the real-world problem, establish shared terminology and a useful model, make product decisions, implement and verify behavior, ship validated artifacts, and feed production evidence back into understanding. 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. @@ -30,7 +30,7 @@ flowchart LR | 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 | | Requirements | What must the system demonstrably do? | `REQUIREMENTS.md` | Solution-neutral FR/NFR IDs | -| Architecture (DDD) | How is the domain shaped? | `engineering/ARCHITECTURE.md`, `engineering/adrs/` | Domain language, boundaries, ADRs | +| Architecture / domain modeling | Which concepts, relationships, rules, workflows, states, and responsibilities shape the solution? | `engineering/ARCHITECTURE.md`, `engineering/adrs/` | Shared model, terminology, responsibility boundaries, ADRs | | Testing (TDD+BDD) | How do we prove it before release? | `engineering/TESTING.md` | Given/When/Then, test mapping | | Publishing | How do verified artifacts reach users? | `engineering/PUBLISHING.md` | CI gates, promotion, rollback | | Observability | What does production teach us? | `engineering/OBSERVABILITY.md` | Signals, SLOs, learning loop | @@ -70,14 +70,16 @@ Fill `REQUIREMENTS.md` after product, design, and discovery context exist. Requi 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) +### 4. Model the problem and record decisions -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 carry the team's understanding of the real-world problem into the system design. DocSlime uses domain modeling to bring the concepts, relationships, constraints, and workflows of the real-world problem into the development cycle. -- Name the **domain concepts** that affect behavior (not abstract "document management") -- Draw **boundaries** between CLI scaffold, agent skills, publishing, and observation -- Keep **ubiquitous language** consistent across requirements, architecture, and ADRs -- Stay light on small projects — say when a bounded context is not worth formalizing +- Model the problem before prematurely designing the solution +- Use the same preferred terminology across product docs, requirements, interfaces, code, and tests +- Represent meaningful concepts, relationships, rules, workflows, and lifecycle states explicitly +- Keep important rules close to the concepts they govern +- Name responsibility boundaries when they clarify ownership, without inventing abstractions +- Refine the model as evidence and implementation teach the team more When a choice is hard to reverse, record it: @@ -138,20 +140,30 @@ The `experience/` folder is DocSlime's UX and product-discovery workspace. It is 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 +## Domain modeling: problem understanding carried into software -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. +Model the problem clearly, use the same terminology throughout the project, and ensure the software reflects the meaningful concepts, rules, and workflows of that problem. This is a practical development habit, not a requirement to adopt a formal methodology or add layers to the code. -**Minimum useful DDD evidence:** +```mermaid +flowchart LR + Problem["Real-world problem"] --> Model["Shared terminology and model"] + Model --> Decisions["Product decisions"] + Decisions --> Implementation["Implementation"] + Implementation --> Verification["Verification"] + Verification -. "Refine understanding" .-> Problem +``` + +**Minimum useful model:** -| Artifact | What to capture | +| Area | 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 | +| Concepts and relationships | The things the project acts on and how they connect, using real project terms such as target project, template catalog, docs tree, document lifecycle, write outcome, lifecycle trace, decision record, and publication artifact | +| Constraints and rules | What must stay true, such as preserving existing documents unless `--force` is explicit | +| Workflows and lifecycle states | How concepts change or move through parsing, validation, generation, publication, and verification | +| Responsibility boundaries | What the CLI, agent skills, project docs, tests, and publishing systems each own | +| Decisions | Product or technical choices whose rationale and consequences should remain durable | -If a project has no meaningful domain split, say so in architecture instead of inventing bounded contexts. +Keep the model only as detailed as the decisions and behavior require. Refine it when evidence, implementation, or verification reveals that a term, relationship, rule, or workflow was incomplete. ## TDD+BDD: from intent to proof @@ -202,6 +214,6 @@ Dogfooding example: DocSlime's [`engineering/TESTING.md`](engineering/TESTING/) - [Experience](experience/) — continuous discovery practice and artifact shape - [Requirements](REQUIREMENTS/) — the behavior contract -- [Architecture](engineering/ARCHITECTURE/) — system shape and domain boundaries +- [Architecture](engineering/ARCHITECTURE/) — problem model, system shape, and responsibility boundaries - [Testing](engineering/TESTING/) — BDD scenarios and test mapping - [Agent Skills](skills/) — skill invocation and quality bar diff --git a/docs/skills.md b/docs/skills.md index a307b44..73a446d 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -57,7 +57,7 @@ Once installed, invoke the skills from inside the agent: 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, practical domain modeling, 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. diff --git a/src/cli.rs b/src/cli.rs index 3dfec54..f91895a 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -2,7 +2,7 @@ use clap::{Parser, Subcommand}; -/// Scaffold a standardized, BDD-oriented `docs/` tree into a repo. +/// Scaffold a traceable documentation lifecycle into a repo. /// /// The templates are designed to be filled in by an AI coding agent in conversation with /// the user, keeping the project's product context, experiences, requirements, design guidance, diff --git a/templates/DESIGN.md b/templates/DESIGN.md index 7e12225..c713450 100644 --- a/templates/DESIGN.md +++ b/templates/DESIGN.md @@ -20,7 +20,7 @@ _How should design critique or UI iteration use PRODUCT.md and DESIGN.md?_ ## Brand And Voice - + - **Tone:** _how the product should sound._ - **Terminology:** _preferred words and names._ diff --git a/templates/PRODUCT.md b/templates/PRODUCT.md index e22dbdb..37838a9 100644 --- a/templates/PRODUCT.md +++ b/templates/PRODUCT.md @@ -45,7 +45,7 @@ _Where are we headed?_ ## Quality stance - + - _Quality method / gate - why it matters_ diff --git a/templates/README.md b/templates/README.md index 613e860..804e18c 100644 --- a/templates/README.md +++ b/templates/README.md @@ -4,6 +4,17 @@ This folder holds the living documentation for this project. Product and design context feed continuous discovery, requirements translate that evidence into a build contract, and engineering docs carry the contract through architecture, testing, publishing, and production observability. The docs stay in-repo so people and coding agents can work from the same evidence without reaching for an external source. +DocSlime uses domain modeling to bring the concepts, relationships, constraints, and workflows of the real-world problem into the development cycle. Model the problem clearly, use the same terminology throughout the project, and ensure the software reflects the meaningful concepts, rules, and workflows of that problem. + +```mermaid +flowchart LR + Problem["Real-world problem"] --> Model["Shared terminology and model"] + Model --> Decisions["Product decisions"] + Decisions --> Implementation["Implementation"] + Implementation --> Verification["Verification"] + Verification -. "Refine understanding" .-> Problem +``` + ## Adapt this template to the project This tree is a broad starting template, not a compliance checklist. Keep the documents that help this project's humans or agents make better decisions; remove, merge, or replace the rest with links to authoritative organization-level context. Update this index and affected links whenever the shape changes. @@ -20,7 +31,7 @@ Follow this lifecycle rather than treating the filenames as a numbered checklist | [`DESIGN.md`](DESIGN.md) | What should stay consistent in product, docs, and UX experience? | | [`experience/`](experience/) | What have we learned from users, and what outcomes and behaviors do they need? | | [`REQUIREMENTS.md`](REQUIREMENTS.md) | What must the delivered system demonstrably do as a result? | -| [`engineering/ARCHITECTURE.md`](engineering/ARCHITECTURE.md) | How is the system built? | +| [`engineering/ARCHITECTURE.md`](engineering/ARCHITECTURE.md) | Which concepts, relationships, rules, workflows, states, responsibilities, and components shape the system? | | [`engineering/TESTING.md`](engineering/TESTING.md) | How do we prove it before release and gate continuous integration? | | [`engineering/PUBLISHING.md`](engineering/PUBLISHING.md) | How does a verified change reach users safely? | | [`engineering/OBSERVABILITY.md`](engineering/OBSERVABILITY.md) | How do we know it works in production and feed learning back into discovery? | @@ -38,7 +49,7 @@ Supporting detail lives in subfolders: - **Keep docs current.** When behavior changes, update the doc in the same change. - **Link, don't duplicate.** Reference detail in subfolders rather than copying it. -- **Trace evidence through delivery.** User evidence should lead to requirements, tests, architecture, telemetry, and production learning. +- **Trace the problem through verification.** Real-world evidence and a shared model should lead to product decisions, requirements, interfaces, implementation, Given/When/Then scenarios, tests, telemetry, and production learning. - **Decisions are recorded.** Significant choices get an ADR (see `engineering/adrs/`). - **Keep applicable context discoverable.** When retained, `PRODUCT.md` and `DESIGN.md` stay in `docs/` so design and coding agents can load them without duplicate root files. - **Close the loop.** Observability should measure both system health and the user outcomes named in product, experience, and requirements docs. diff --git a/templates/REQUIREMENTS.md b/templates/REQUIREMENTS.md index 8f0b9ea..8834d38 100644 --- a/templates/REQUIREMENTS.md +++ b/templates/REQUIREMENTS.md @@ -1,4 +1,4 @@ - + # Requirements diff --git a/templates/engineering/ARCHITECTURE.md b/templates/engineering/ARCHITECTURE.md index 6f7d0b0..2f0f977 100644 --- a/templates/engineering/ARCHITECTURE.md +++ b/templates/engineering/ARCHITECTURE.md @@ -30,13 +30,15 @@ flowchart LR _Key entities and relationships._ -## Domain language and boundaries +## Problem model and terminology - +Model the problem clearly, use the same terminology throughout the project, and ensure the software reflects the meaningful concepts, rules, and workflows of that problem. -| Domain concept | Meaning in this project | Boundary / owner | + + +| Concept | Meaning in this project | Relationships, states, rules, and owner | | --- | --- | --- | -| _Concept_ | _Definition in project language_ | _Component, team, module, or external system_ | +| _Concept_ | _Definition in project terminology_ | _Related concepts, lifecycle states, governing rules, and responsible component or team_ | ## Key flows diff --git a/templates/engineering/OBSERVABILITY.md b/templates/engineering/OBSERVABILITY.md index 08d2224..4d9b884 100644 --- a/templates/engineering/OBSERVABILITY.md +++ b/templates/engineering/OBSERVABILITY.md @@ -22,7 +22,7 @@ _How do we know the system is healthy, users are succeeding, and our product hyp ## Telemetry design - + - **Events:** _User-visible outcomes and product-learning signals._ - **Logs:** _Structured diagnostic facts and correlation identifiers._ diff --git a/templates/engineering/README.md b/templates/engineering/README.md index 6aebf78..1f56c0f 100644 --- a/templates/engineering/README.md +++ b/templates/engineering/README.md @@ -8,7 +8,7 @@ Engineering begins with the shared requirements contract and follows it through | Document | Responsibility | | --- | --- | -| [`ARCHITECTURE.md`](ARCHITECTURE.md) | How domain boundaries and system components satisfy the requirements. | +| [`ARCHITECTURE.md`](ARCHITECTURE.md) | How the problem model, responsibility boundaries, and system components satisfy the requirements. | | [`TESTING.md`](TESTING.md) | How tests and CI prove the system before release. | | [`PUBLISHING.md`](PUBLISHING.md) | How verified artifacts are versioned, promoted, deployed, and rolled back. | | [`OBSERVABILITY.md`](OBSERVABILITY.md) | How production health and user outcomes are measured and fed back into discovery. | diff --git a/templates/engineering/TESTING.md b/templates/engineering/TESTING.md index 2f66bec..a68e39b 100644 --- a/templates/engineering/TESTING.md +++ b/templates/engineering/TESTING.md @@ -26,7 +26,7 @@ _How do we know the system works?_ ## Traceability contract - + | Link | Evidence | | --- | --- | @@ -34,7 +34,7 @@ _How do we know the system works?_ | Experience -> requirement | _Requirement IDs from ../REQUIREMENTS.md_ | | Requirement -> BDD scenario | _Given/When/Then scenario_ | | Scenario -> test | _Test file, manual check, eval, or known gap_ | -| Requirement -> architecture/ADR | _Architecture section or ADR link when applicable_ | +| Model / requirement -> architecture or ADR | _Concept, rule, workflow, architecture section, or ADR link when applicable_ | ## Evaluation against product goals diff --git a/templates/experience/README.md b/templates/experience/README.md index d8252dc..b37ae50 100644 --- a/templates/experience/README.md +++ b/templates/experience/README.md @@ -44,7 +44,7 @@ _How does the team learn from users and decide what is worth building?_ ## Given / When / Then scenarios -## Constraints and domain language +## Concepts, terminology, and constraints ## Success signals and telemetry diff --git a/tests/cli.rs b/tests/cli.rs index a42a268..0d077a0 100644 --- a/tests/cli.rs +++ b/tests/cli.rs @@ -29,6 +29,55 @@ fn docslime(dir: &Path) -> Command { cmd } +fn deprecated_methodology_term(contents: &str) -> Option<&'static str> { + let lower = contents.to_lowercase(); + let has_ddd_token = lower + .split(|character: char| !character.is_alphanumeric()) + .any(|word| word == concat!("d", "dd")); + + if has_ddd_token { + return Some("deprecated acronym"); + } + + [ + concat!("domain", "-driven design"), + concat!("domain", " driven design"), + concat!("light ", "d", "dd"), + concat!("bounded", " context"), + concat!("ubiquitous", " language"), + concat!("business-shaped", " software"), + concat!("user-driven", " design"), + ] + .into_iter() + .find(|term| lower.contains(term)) +} + +fn assert_normative_tree_uses_current_methodology(path: &Path) { + if path.is_dir() { + for entry in fs::read_dir(path).unwrap() { + assert_normative_tree_uses_current_methodology(&entry.unwrap().path()); + } + return; + } + + let should_scan = path + .extension() + .and_then(|extension| extension.to_str()) + .is_some_and(|extension| { + matches!(extension, "md" | "rs" | "toml" | "json" | "yml" | "yaml") + }); + if !should_scan { + return; + } + + let contents = fs::read_to_string(path).unwrap(); + assert!( + deprecated_methodology_term(&contents).is_none(), + "{} contains deprecated methodology terminology", + path.display() + ); +} + #[test] fn init_creates_full_tree() { let tmp = TempDir::new().unwrap(); @@ -125,6 +174,51 @@ fn suggested_release_conventions_are_optional() { assert!(fill_skill.contains("never impose enforcement")); } +#[test] +fn domain_modeling_guidance_replaces_formal_methodology_framing() { + let tmp = TempDir::new().unwrap(); + docslime(tmp.path()).arg("init").assert().success(); + + let generated = tmp.path().join("docs"); + let readme = fs::read_to_string(generated.join("README.md")).unwrap(); + assert!(readme.contains("uses domain modeling to bring the concepts")); + assert!(readme.contains("Real-world problem")); + assert!(readme.contains("Shared terminology and model")); + assert!(readme.contains("Product decisions")); + assert!(readme.contains("Implementation")); + assert!(readme.contains("Verification")); + + let product = fs::read_to_string(generated.join("PRODUCT.md")).unwrap(); + assert!(product.contains("models the real-world problem")); + assert!(product.contains("keeps terminology consistent")); + + let architecture = fs::read_to_string(generated.join("engineering/ARCHITECTURE.md")).unwrap(); + assert!(architecture.contains("## Problem model and terminology")); + assert!(architecture.contains("concepts, relationships, constraints, and workflows")); + assert!(architecture.contains("meaningful concepts, rules, and workflows")); + assert!(architecture.contains("lifecycle states")); + + let testing = fs::read_to_string(generated.join("engineering/TESTING.md")).unwrap(); + assert!( + testing.contains("real-world problem -> shared terminology and model -> product decision") + ); + assert!(testing.contains("Given/When/Then scenario -> test")); + + assert_normative_tree_uses_current_methodology(&generated); + + let repo = Path::new(env!("CARGO_MANIFEST_DIR")); + for normative_root in [ + "README.md", + "Cargo.toml", + "src", + "templates", + "docs", + ".agents", + ] { + assert_normative_tree_uses_current_methodology(&repo.join(normative_root)); + } +} + #[test] fn init_skips_existing_files() { let tmp = TempDir::new().unwrap();