kingmadoc 0.3.0.dev16__tar.gz → 0.3.0.dev17__tar.gz

{kingmadoc-0.3.0.dev16 → kingmadoc-0.3.0.dev17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: kingmadoc
-Version: 0.3.0.dev16
+Version: 0.3.0.dev17
 Summary: Feature docs for AI coding agents: a plan with C4 diagrams before the code, a verification doc after.
 Project-URL: Homepage, https://github.com/ATkingma/KingmaDoc
 Project-URL: Issues, https://github.com/ATkingma/KingmaDoc/issues

{kingmadoc-0.3.0.dev16 → kingmadoc-0.3.0.dev17}/examples/verify-mode-plan.md

@@ -11,7 +11,7 @@ files_expected: ["src/kingmadoc/cli.py", "src/kingmadoc/verify"]
 |---|---|
 | **Project** | KingmaDoc |
 | **Status** | Draft |
-| **Generated** | 2026-09-28T10:44+00:00 by KingmaDoc 0.1.0.dev50 |
+| **Generated** | 2026-09-28T12:54+00:00 by KingmaDoc 0.1.0.dev50 |
 
 > Generated before implementation. Fill in every _TODO_ and review everything marked
 > _(inferred)_: it comes from the codebase analysis and is a starting point, not the truth.
@@ -97,6 +97,18 @@ _Disabled in `.featuredoc.yml` (`diagrams`)._
 
 _Disabled in `.featuredoc.yml` (`diagrams`)._
 
+## Data flow diagram (Mermaid)
+
+Where the feature's data comes from, what transforms it and where it is stored.
+
+_Disabled in `.featuredoc.yml` (`diagrams`)._
+
+## State diagram (Mermaid)
+
+The states of the object whose lifecycle the feature changes.
+
+_Disabled in `.featuredoc.yml` (`diagrams`)._
+
 ## Open questions
 
 - [ ] _TODO: anything else that must be decided before implementation._
@@ -121,12 +133,12 @@ _Disabled in `.featuredoc.yml` (`diagrams`)._
 | python | 113 |
 | markdown | 28 |
 | jinja | 6 |
+| json | 4 |
 | yaml | 3 |
-| json | 2 |
 | toml | 1 |
 
 <details>
-<summary>File tree (230 files)</summary>
+<summary>File tree (236 files)</summary>
 
 ```text
 KingmaDoc/
@@ -149,6 +161,7 @@ KingmaDoc/
 │   │   ├── 0b0dfdcede5596e1
 │   │   ├── 1b81a71a7607fbf6
 │   │   ├── 2003bed8cb6acdf2
+│   │   ├── 27972aa85104d731
 │   │   ├── 2e00d1a2bca2c453
 │   │   ├── 390efa9697d4e1bf
 │   │   ├── 429e7d227d43fa43
@@ -189,6 +202,7 @@ KingmaDoc/
 │   │   ├── c7c62939844fec2e
 │   │   ├── cc4dfad2dc9d75e2
 │   │   ├── cd82d38bc12deabd
+│   │   ├── d1d54a4302c7359c
 │   │   ├── d6e5d66b09a82b49
 │   │   ├── da39a3ee5e6b4b0d
 │   │   ├── e36626a891f1bf04
@@ -200,6 +214,11 @@ KingmaDoc/
 │   │   └── 14.0.0/
 │   │       └── …
 │   └── .gitignore
+├── .import_linter_cache/
+│   ├── .gitignore
+│   ├── 3516dc116b537972f63cac11b7ceb5fffe116986.data.json
+│   ├── CACHEDIR.TAG
+│   └── kingmadoc.meta.json
 ├── docs/
 │   ├── conventions.md
 │   ├── index.md

{kingmadoc-0.3.0.dev16 → kingmadoc-0.3.0.dev17}/skill/SKILL.md

@@ -52,8 +52,8 @@ brackets); ignore the file if it is absent:
 - `analyzer.exclude_dirs` [`.git`, `node_modules`, `.venv`, `venv`, `__pycache__`,
   `dist`, `build`, `*.egg-info`, tool caches], `analyzer.max_files` [`5000`],
   `analyzer.tree_depth` [`3`].
-- `diagrams` [`c4_context`, `c4_container`, `class`, `sequence`]: which sections get
-  a diagram.
+- `diagrams` [`c4_context`, `c4_container`, `class`, `sequence`, `data_flow`, `state`]:
+  which sections get a diagram.
 - `diagrams_png` [`embed`]: `embed`, `file` or `off`; see
   [Rendering](reference/diagram-rules.md#rendering).
 - `language` [`en`]: language of fixed sentences, notes and captions (headings stay English).

{kingmadoc-0.3.0.dev16 → kingmadoc-0.3.0.dev17}/skill/codex.md

@@ -52,8 +52,8 @@ brackets); ignore the file if it is absent:
 - `analyzer.exclude_dirs` [`.git`, `node_modules`, `.venv`, `venv`, `__pycache__`,
   `dist`, `build`, `*.egg-info`, tool caches], `analyzer.max_files` [`5000`],
   `analyzer.tree_depth` [`3`].
-- `diagrams` [`c4_context`, `c4_container`, `class`, `sequence`]: which sections get
-  a diagram.
+- `diagrams` [`c4_context`, `c4_container`, `class`, `sequence`, `data_flow`, `state`]:
+  which sections get a diagram.
 - `diagrams_png` [`embed`]: `embed`, `file` or `off`; see
   [Rendering](#rendering).
 - `language` [`en`]: language of fixed sentences, notes and captions (headings stay English).
@@ -239,7 +239,7 @@ Show the user the path, the number of deviations, and any failing check.
 - **Always labeled**:
   - C4 and `sequenceDiagram`: the first line after the diagram type is `title <text>`
     (`System Context: <project>`, `Containers: <project>`);
-  - `classDiagram`, `erDiagram` and `flowchart` have no `title` line; put frontmatter
+  - `classDiagram`, `erDiagram`, `flowchart` and `stateDiagram-v2` have no `title` line; put frontmatter
     before the diagram type instead: `---`, `title: "<text>"`, `---` (quote the
     title: an unquoted `:` breaks the YAML and the render);
   - every element has a quoted label: `Person(alias, "Label", "Description")`,
@@ -285,10 +285,73 @@ C4Context
     Rel(shop, sendgrid, "Sends email via")
 ```
 
-`diagrams` in `.featuredoc.yml` [`c4_context`, `c4_container`, `class`, `sequence`]
+`diagrams` in `.featuredoc.yml` [`c4_context`, `c4_container`, `class`, `sequence`,
+`data_flow`, `state`]
 selects the diagrams. If one is disabled, keep its section and replace the diagram with
 this line: _Disabled in `.featuredoc.yml` (`diagrams`)._
 
+## Data flow diagram
+
+Yourdon/DeMarco style (Gane-Sarson draws the same with other shapes) as a `flowchart LR`:
+
+- **External entity** (person or system outside the scope): rectangle `user[User]`.
+- **Process** (transforms data): circle with a number and a verb phrase,
+  `p1((1. Validate order))`.
+- **Data store** (data at rest): `d1[("D1 Orders")]`, named with a noun, numbered `D1`.
+- **Data flow**: an arrow labelled with the **data** (a noun: `order`, `invoice`), never an
+  action; every arrow has a label.
+- Rules: every flow starts or ends at a process (never entity → entity, entity → store
+  or store → store); every process has at least one input and one output (no black
+  holes, no miracles) and its output can be made from its input (no grey holes); a
+  store is both written and read somewhere, or it is outside the feature; no control
+  flow, loops or decisions (that is the sequence or state diagram).
+- **Levels**: the Context diagram is level 0; this is level 1 for the feature. The flows
+  in and out must balance with the Context diagram (same external systems, same data).
+- Mark new or changed processes and flows _(inferred)_ or from the answers, as usual.
+
+```mermaid
+---
+title: "Data flow: place order"
+---
+flowchart LR
+    user[Customer] -- order --> p1((1. Validate order))
+    p1 -- valid order --> p2((2. Store order))
+    p2 -- order --> d1[("D1 Orders")]
+    p2 -- confirmation --> user
+```
+
+## State diagram
+
+UML 2 state machine as `stateDiagram-v2`, for the one object whose lifecycle the feature
+changes (an order, a job, a document):
+
+- **States** are conditions, named with an adjective or past participle (`Draft`,
+  `Paid`, `Cancelled`), never an action (`Pay`).
+- One initial `[*] --> <state>` (unlabelled); final `<state> --> [*]` only where the
+  object's life really ends.
+- **Transitions**: `A --> B : event [guard] / action`; event, guard and action are each
+  optional, but every transition has at least the event. Guards leaving the same state
+  on the same event must not overlap; use `state check <<choice>>` for a decision.
+- Every state is reachable from the initial state, and every non-final state has a way
+  out (no dead ends unless intended).
+- Composite states (`state Active { … }`) only when they remove repeated transitions;
+  keep it to about ten states.
+- New states and transitions from the answers or "Planned changes"; existing ones from
+  the code are _(inferred)_.
+
+```mermaid
+---
+title: "States: Order"
+---
+stateDiagram-v2
+    [*] --> Draft
+    Draft --> Placed : submit [cart not empty]
+    Placed --> Paid : payment received / send receipt
+    Placed --> Cancelled : cancel
+    Paid --> [*]
+    Cancelled --> [*]
+```
+
 ## Rendering
 
 `diagrams_png` in `.featuredoc.yml` [`embed`]: `embed` (below), `file` (the PNG goes to
@@ -306,7 +369,8 @@ or `off` (no image; the ` ```mermaid ` block stays in the document).
   `<output_dir>/diagrams/<slug>-<diagram>.mmd`.
 
 1. Write each diagram to `<output_dir>/diagrams/<slug>-<diagram>.mmd` (`<diagram>`:
-   `c4-context`, `c4-container`, `class`, `sequence-current`, `sequence-new`) and run:
+   `c4-context`, `c4-container`, `class`, `sequence-current`, `sequence-new`,
+   `data-flow`, `state`) and run:
    `npx -y @mermaid-js/mermaid-cli -i <that>.mmd -o <tmp>.png -s 2 -b white -t default -p <puppeteer.json>`
    (`-t default`: Mermaid's normal theme; newer versions otherwise colour every shape).
 2. Set `PUPPETEER_SKIP_DOWNLOAD=true`, and let `puppeteer.json` point at an installed
@@ -423,6 +487,18 @@ The classes this feature touches and their direct collaborators.
 
 <sequenceDiagram of the flow after the change>
 
+## Data flow diagram (Mermaid)
+
+Where the feature's data comes from, what transforms it and where it is stored.
+
+<flowchart DFD, or _Not applicable: <reason>._>
+
+## State diagram (Mermaid)
+
+The states of <the object whose lifecycle the feature changes>.
+
+<stateDiagram-v2, or _Not applicable: <reason>._>
+
 ## Open questions
 
 - [ ] <each unanswered clarifying question>
@@ -470,6 +546,9 @@ Omit "**Answered while planning**" when nothing was answered.
   result, with real classes as participants and real method names as messages;
   `activate`/`deactivate` for nested calls, `alt`/`opt` for branches. In **Current**,
   a `Note` marks where it goes wrong.
+- **Data flow diagram** and **State diagram**: rules in
+  [diagram-rules.md](diagram-rules.md#data-flow-diagram); _Not applicable: <reason>._ when
+  the feature moves no data between parts, or has no object with a lifecycle.
 - **Open changes**: when an uncommitted change or stash touches the feature, also list
   it under Open questions.
 - `language` in `.featuredoc.yml` [`en`]: headings stay English (the CLI's), but fixed

{kingmadoc-0.3.0.dev16 → kingmadoc-0.3.0.dev17}/skill/copilot.md

@@ -52,8 +52,8 @@ brackets); ignore the file if it is absent:
 - `analyzer.exclude_dirs` [`.git`, `node_modules`, `.venv`, `venv`, `__pycache__`,
   `dist`, `build`, `*.egg-info`, tool caches], `analyzer.max_files` [`5000`],
   `analyzer.tree_depth` [`3`].
-- `diagrams` [`c4_context`, `c4_container`, `class`, `sequence`]: which sections get
-  a diagram.
+- `diagrams` [`c4_context`, `c4_container`, `class`, `sequence`, `data_flow`, `state`]:
+  which sections get a diagram.
 - `diagrams_png` [`embed`]: `embed`, `file` or `off`; see
   [Rendering](#rendering).
 - `language` [`en`]: language of fixed sentences, notes and captions (headings stay English).
@@ -239,7 +239,7 @@ Show the user the path, the number of deviations, and any failing check.
 - **Always labeled**:
   - C4 and `sequenceDiagram`: the first line after the diagram type is `title <text>`
     (`System Context: <project>`, `Containers: <project>`);
-  - `classDiagram`, `erDiagram` and `flowchart` have no `title` line; put frontmatter
+  - `classDiagram`, `erDiagram`, `flowchart` and `stateDiagram-v2` have no `title` line; put frontmatter
     before the diagram type instead: `---`, `title: "<text>"`, `---` (quote the
     title: an unquoted `:` breaks the YAML and the render);
   - every element has a quoted label: `Person(alias, "Label", "Description")`,
@@ -285,10 +285,73 @@ C4Context
     Rel(shop, sendgrid, "Sends email via")
 ```
 
-`diagrams` in `.featuredoc.yml` [`c4_context`, `c4_container`, `class`, `sequence`]
+`diagrams` in `.featuredoc.yml` [`c4_context`, `c4_container`, `class`, `sequence`,
+`data_flow`, `state`]
 selects the diagrams. If one is disabled, keep its section and replace the diagram with
 this line: _Disabled in `.featuredoc.yml` (`diagrams`)._
 
+## Data flow diagram
+
+Yourdon/DeMarco style (Gane-Sarson draws the same with other shapes) as a `flowchart LR`:
+
+- **External entity** (person or system outside the scope): rectangle `user[User]`.
+- **Process** (transforms data): circle with a number and a verb phrase,
+  `p1((1. Validate order))`.
+- **Data store** (data at rest): `d1[("D1 Orders")]`, named with a noun, numbered `D1`.
+- **Data flow**: an arrow labelled with the **data** (a noun: `order`, `invoice`), never an
+  action; every arrow has a label.
+- Rules: every flow starts or ends at a process (never entity → entity, entity → store
+  or store → store); every process has at least one input and one output (no black
+  holes, no miracles) and its output can be made from its input (no grey holes); a
+  store is both written and read somewhere, or it is outside the feature; no control
+  flow, loops or decisions (that is the sequence or state diagram).
+- **Levels**: the Context diagram is level 0; this is level 1 for the feature. The flows
+  in and out must balance with the Context diagram (same external systems, same data).
+- Mark new or changed processes and flows _(inferred)_ or from the answers, as usual.
+
+```mermaid
+---
+title: "Data flow: place order"
+---
+flowchart LR
+    user[Customer] -- order --> p1((1. Validate order))
+    p1 -- valid order --> p2((2. Store order))
+    p2 -- order --> d1[("D1 Orders")]
+    p2 -- confirmation --> user
+```
+
+## State diagram
+
+UML 2 state machine as `stateDiagram-v2`, for the one object whose lifecycle the feature
+changes (an order, a job, a document):
+
+- **States** are conditions, named with an adjective or past participle (`Draft`,
+  `Paid`, `Cancelled`), never an action (`Pay`).
+- One initial `[*] --> <state>` (unlabelled); final `<state> --> [*]` only where the
+  object's life really ends.
+- **Transitions**: `A --> B : event [guard] / action`; event, guard and action are each
+  optional, but every transition has at least the event. Guards leaving the same state
+  on the same event must not overlap; use `state check <<choice>>` for a decision.
+- Every state is reachable from the initial state, and every non-final state has a way
+  out (no dead ends unless intended).
+- Composite states (`state Active { … }`) only when they remove repeated transitions;
+  keep it to about ten states.
+- New states and transitions from the answers or "Planned changes"; existing ones from
+  the code are _(inferred)_.
+
+```mermaid
+---
+title: "States: Order"
+---
+stateDiagram-v2
+    [*] --> Draft
+    Draft --> Placed : submit [cart not empty]
+    Placed --> Paid : payment received / send receipt
+    Placed --> Cancelled : cancel
+    Paid --> [*]
+    Cancelled --> [*]
+```
+
 ## Rendering
 
 `diagrams_png` in `.featuredoc.yml` [`embed`]: `embed` (below), `file` (the PNG goes to
@@ -306,7 +369,8 @@ or `off` (no image; the ` ```mermaid ` block stays in the document).
   `<output_dir>/diagrams/<slug>-<diagram>.mmd`.
 
 1. Write each diagram to `<output_dir>/diagrams/<slug>-<diagram>.mmd` (`<diagram>`:
-   `c4-context`, `c4-container`, `class`, `sequence-current`, `sequence-new`) and run:
+   `c4-context`, `c4-container`, `class`, `sequence-current`, `sequence-new`,
+   `data-flow`, `state`) and run:
    `npx -y @mermaid-js/mermaid-cli -i <that>.mmd -o <tmp>.png -s 2 -b white -t default -p <puppeteer.json>`
    (`-t default`: Mermaid's normal theme; newer versions otherwise colour every shape).
 2. Set `PUPPETEER_SKIP_DOWNLOAD=true`, and let `puppeteer.json` point at an installed
@@ -423,6 +487,18 @@ The classes this feature touches and their direct collaborators.
 
 <sequenceDiagram of the flow after the change>
 
+## Data flow diagram (Mermaid)
+
+Where the feature's data comes from, what transforms it and where it is stored.
+
+<flowchart DFD, or _Not applicable: <reason>._>
+
+## State diagram (Mermaid)
+
+The states of <the object whose lifecycle the feature changes>.
+
+<stateDiagram-v2, or _Not applicable: <reason>._>
+
 ## Open questions
 
 - [ ] <each unanswered clarifying question>
@@ -470,6 +546,9 @@ Omit "**Answered while planning**" when nothing was answered.
   result, with real classes as participants and real method names as messages;
   `activate`/`deactivate` for nested calls, `alt`/`opt` for branches. In **Current**,
   a `Note` marks where it goes wrong.
+- **Data flow diagram** and **State diagram**: rules in
+  [diagram-rules.md](diagram-rules.md#data-flow-diagram); _Not applicable: <reason>._ when
+  the feature moves no data between parts, or has no object with a lifecycle.
 - **Open changes**: when an uncommitted change or stash touches the feature, also list
   it under Open questions.
 - `language` in `.featuredoc.yml` [`en`]: headings stay English (the CLI's), but fixed

{kingmadoc-0.3.0.dev16 → kingmadoc-0.3.0.dev17}/skill/cursor.md

@@ -53,8 +53,8 @@ brackets); ignore the file if it is absent:
 - `analyzer.exclude_dirs` [`.git`, `node_modules`, `.venv`, `venv`, `__pycache__`,
   `dist`, `build`, `*.egg-info`, tool caches], `analyzer.max_files` [`5000`],
   `analyzer.tree_depth` [`3`].
-- `diagrams` [`c4_context`, `c4_container`, `class`, `sequence`]: which sections get
-  a diagram.
+- `diagrams` [`c4_context`, `c4_container`, `class`, `sequence`, `data_flow`, `state`]:
+  which sections get a diagram.
 - `diagrams_png` [`embed`]: `embed`, `file` or `off`; see
   [Rendering](#rendering).
 - `language` [`en`]: language of fixed sentences, notes and captions (headings stay English).
@@ -240,7 +240,7 @@ Show the user the path, the number of deviations, and any failing check.
 - **Always labeled**:
   - C4 and `sequenceDiagram`: the first line after the diagram type is `title <text>`
     (`System Context: <project>`, `Containers: <project>`);
-  - `classDiagram`, `erDiagram` and `flowchart` have no `title` line; put frontmatter
+  - `classDiagram`, `erDiagram`, `flowchart` and `stateDiagram-v2` have no `title` line; put frontmatter
     before the diagram type instead: `---`, `title: "<text>"`, `---` (quote the
     title: an unquoted `:` breaks the YAML and the render);
   - every element has a quoted label: `Person(alias, "Label", "Description")`,
@@ -286,10 +286,73 @@ C4Context
     Rel(shop, sendgrid, "Sends email via")
 ```
 
-`diagrams` in `.featuredoc.yml` [`c4_context`, `c4_container`, `class`, `sequence`]
+`diagrams` in `.featuredoc.yml` [`c4_context`, `c4_container`, `class`, `sequence`,
+`data_flow`, `state`]
 selects the diagrams. If one is disabled, keep its section and replace the diagram with
 this line: _Disabled in `.featuredoc.yml` (`diagrams`)._
 
+## Data flow diagram
+
+Yourdon/DeMarco style (Gane-Sarson draws the same with other shapes) as a `flowchart LR`:
+
+- **External entity** (person or system outside the scope): rectangle `user[User]`.
+- **Process** (transforms data): circle with a number and a verb phrase,
+  `p1((1. Validate order))`.
+- **Data store** (data at rest): `d1[("D1 Orders")]`, named with a noun, numbered `D1`.
+- **Data flow**: an arrow labelled with the **data** (a noun: `order`, `invoice`), never an
+  action; every arrow has a label.
+- Rules: every flow starts or ends at a process (never entity → entity, entity → store
+  or store → store); every process has at least one input and one output (no black
+  holes, no miracles) and its output can be made from its input (no grey holes); a
+  store is both written and read somewhere, or it is outside the feature; no control
+  flow, loops or decisions (that is the sequence or state diagram).
+- **Levels**: the Context diagram is level 0; this is level 1 for the feature. The flows
+  in and out must balance with the Context diagram (same external systems, same data).
+- Mark new or changed processes and flows _(inferred)_ or from the answers, as usual.
+
+```mermaid
+---
+title: "Data flow: place order"
+---
+flowchart LR
+    user[Customer] -- order --> p1((1. Validate order))
+    p1 -- valid order --> p2((2. Store order))
+    p2 -- order --> d1[("D1 Orders")]
+    p2 -- confirmation --> user
+```
+
+## State diagram
+
+UML 2 state machine as `stateDiagram-v2`, for the one object whose lifecycle the feature
+changes (an order, a job, a document):
+
+- **States** are conditions, named with an adjective or past participle (`Draft`,
+  `Paid`, `Cancelled`), never an action (`Pay`).
+- One initial `[*] --> <state>` (unlabelled); final `<state> --> [*]` only where the
+  object's life really ends.
+- **Transitions**: `A --> B : event [guard] / action`; event, guard and action are each
+  optional, but every transition has at least the event. Guards leaving the same state
+  on the same event must not overlap; use `state check <<choice>>` for a decision.
+- Every state is reachable from the initial state, and every non-final state has a way
+  out (no dead ends unless intended).
+- Composite states (`state Active { … }`) only when they remove repeated transitions;
+  keep it to about ten states.
+- New states and transitions from the answers or "Planned changes"; existing ones from
+  the code are _(inferred)_.
+
+```mermaid
+---
+title: "States: Order"
+---
+stateDiagram-v2
+    [*] --> Draft
+    Draft --> Placed : submit [cart not empty]
+    Placed --> Paid : payment received / send receipt
+    Placed --> Cancelled : cancel
+    Paid --> [*]
+    Cancelled --> [*]
+```
+
 ## Rendering
 
 `diagrams_png` in `.featuredoc.yml` [`embed`]: `embed` (below), `file` (the PNG goes to
@@ -307,7 +370,8 @@ or `off` (no image; the ` ```mermaid ` block stays in the document).
   `<output_dir>/diagrams/<slug>-<diagram>.mmd`.
 
 1. Write each diagram to `<output_dir>/diagrams/<slug>-<diagram>.mmd` (`<diagram>`:
-   `c4-context`, `c4-container`, `class`, `sequence-current`, `sequence-new`) and run:
+   `c4-context`, `c4-container`, `class`, `sequence-current`, `sequence-new`,
+   `data-flow`, `state`) and run:
    `npx -y @mermaid-js/mermaid-cli -i <that>.mmd -o <tmp>.png -s 2 -b white -t default -p <puppeteer.json>`
    (`-t default`: Mermaid's normal theme; newer versions otherwise colour every shape).
 2. Set `PUPPETEER_SKIP_DOWNLOAD=true`, and let `puppeteer.json` point at an installed
@@ -424,6 +488,18 @@ The classes this feature touches and their direct collaborators.
 
 <sequenceDiagram of the flow after the change>
 
+## Data flow diagram (Mermaid)
+
+Where the feature's data comes from, what transforms it and where it is stored.
+
+<flowchart DFD, or _Not applicable: <reason>._>
+
+## State diagram (Mermaid)
+
+The states of <the object whose lifecycle the feature changes>.
+
+<stateDiagram-v2, or _Not applicable: <reason>._>
+
 ## Open questions
 
 - [ ] <each unanswered clarifying question>
@@ -471,6 +547,9 @@ Omit "**Answered while planning**" when nothing was answered.
   result, with real classes as participants and real method names as messages;
   `activate`/`deactivate` for nested calls, `alt`/`opt` for branches. In **Current**,
   a `Note` marks where it goes wrong.
+- **Data flow diagram** and **State diagram**: rules in
+  [diagram-rules.md](diagram-rules.md#data-flow-diagram); _Not applicable: <reason>._ when
+  the feature moves no data between parts, or has no object with a lifecycle.
 - **Open changes**: when an uncommitted change or stash touches the feature, also list
   it under Open questions.
 - `language` in `.featuredoc.yml` [`en`]: headings stay English (the CLI's), but fixed

{kingmadoc-0.3.0.dev16 → kingmadoc-0.3.0.dev17}/skill/reference/diagram-rules.md

@@ -8,7 +8,7 @@
 - **Always labeled**:
   - C4 and `sequenceDiagram`: the first line after the diagram type is `title <text>`
     (`System Context: <project>`, `Containers: <project>`);
-  - `classDiagram`, `erDiagram` and `flowchart` have no `title` line; put frontmatter
+  - `classDiagram`, `erDiagram`, `flowchart` and `stateDiagram-v2` have no `title` line; put frontmatter
     before the diagram type instead: `---`, `title: "<text>"`, `---` (quote the
     title: an unquoted `:` breaks the YAML and the render);
   - every element has a quoted label: `Person(alias, "Label", "Description")`,
@@ -54,10 +54,73 @@ C4Context
     Rel(shop, sendgrid, "Sends email via")
 ```
 
-`diagrams` in `.featuredoc.yml` [`c4_context`, `c4_container`, `class`, `sequence`]
+`diagrams` in `.featuredoc.yml` [`c4_context`, `c4_container`, `class`, `sequence`,
+`data_flow`, `state`]
 selects the diagrams. If one is disabled, keep its section and replace the diagram with
 this line: _Disabled in `.featuredoc.yml` (`diagrams`)._
 
+## Data flow diagram
+
+Yourdon/DeMarco style (Gane-Sarson draws the same with other shapes) as a `flowchart LR`:
+
+- **External entity** (person or system outside the scope): rectangle `user[User]`.
+- **Process** (transforms data): circle with a number and a verb phrase,
+  `p1((1. Validate order))`.
+- **Data store** (data at rest): `d1[("D1 Orders")]`, named with a noun, numbered `D1`.
+- **Data flow**: an arrow labelled with the **data** (a noun: `order`, `invoice`), never an
+  action; every arrow has a label.
+- Rules: every flow starts or ends at a process (never entity → entity, entity → store
+  or store → store); every process has at least one input and one output (no black
+  holes, no miracles) and its output can be made from its input (no grey holes); a
+  store is both written and read somewhere, or it is outside the feature; no control
+  flow, loops or decisions (that is the sequence or state diagram).
+- **Levels**: the Context diagram is level 0; this is level 1 for the feature. The flows
+  in and out must balance with the Context diagram (same external systems, same data).
+- Mark new or changed processes and flows _(inferred)_ or from the answers, as usual.
+
+```mermaid
+---
+title: "Data flow: place order"
+---
+flowchart LR
+    user[Customer] -- order --> p1((1. Validate order))
+    p1 -- valid order --> p2((2. Store order))
+    p2 -- order --> d1[("D1 Orders")]
+    p2 -- confirmation --> user
+```
+
+## State diagram
+
+UML 2 state machine as `stateDiagram-v2`, for the one object whose lifecycle the feature
+changes (an order, a job, a document):
+
+- **States** are conditions, named with an adjective or past participle (`Draft`,
+  `Paid`, `Cancelled`), never an action (`Pay`).
+- One initial `[*] --> <state>` (unlabelled); final `<state> --> [*]` only where the
+  object's life really ends.
+- **Transitions**: `A --> B : event [guard] / action`; event, guard and action are each
+  optional, but every transition has at least the event. Guards leaving the same state
+  on the same event must not overlap; use `state check <<choice>>` for a decision.
+- Every state is reachable from the initial state, and every non-final state has a way
+  out (no dead ends unless intended).
+- Composite states (`state Active { … }`) only when they remove repeated transitions;
+  keep it to about ten states.
+- New states and transitions from the answers or "Planned changes"; existing ones from
+  the code are _(inferred)_.
+
+```mermaid
+---
+title: "States: Order"
+---
+stateDiagram-v2
+    [*] --> Draft
+    Draft --> Placed : submit [cart not empty]
+    Placed --> Paid : payment received / send receipt
+    Placed --> Cancelled : cancel
+    Paid --> [*]
+    Cancelled --> [*]
+```
+
 ## Rendering
 
 `diagrams_png` in `.featuredoc.yml` [`embed`]: `embed` (below), `file` (the PNG goes to
@@ -75,7 +138,8 @@ or `off` (no image; the ` ```mermaid ` block stays in the document).
   `<output_dir>/diagrams/<slug>-<diagram>.mmd`.
 
 1. Write each diagram to `<output_dir>/diagrams/<slug>-<diagram>.mmd` (`<diagram>`:
-   `c4-context`, `c4-container`, `class`, `sequence-current`, `sequence-new`) and run:
+   `c4-context`, `c4-container`, `class`, `sequence-current`, `sequence-new`,
+   `data-flow`, `state`) and run:
    `npx -y @mermaid-js/mermaid-cli -i <that>.mmd -o <tmp>.png -s 2 -b white -t default -p <puppeteer.json>`
    (`-t default`: Mermaid's normal theme; newer versions otherwise colour every shape).
 2. Set `PUPPETEER_SKIP_DOWNLOAD=true`, and let `puppeteer.json` point at an installed

{kingmadoc-0.3.0.dev16 → kingmadoc-0.3.0.dev17}/skill/reference/formats.md

@@ -93,6 +93,18 @@ The classes this feature touches and their direct collaborators.
 
 <sequenceDiagram of the flow after the change>
 
+## Data flow diagram (Mermaid)
+
+Where the feature's data comes from, what transforms it and where it is stored.
+
+<flowchart DFD, or _Not applicable: <reason>._>
+
+## State diagram (Mermaid)
+
+The states of <the object whose lifecycle the feature changes>.
+
+<stateDiagram-v2, or _Not applicable: <reason>._>
+
 ## Open questions
 
 - [ ] <each unanswered clarifying question>
@@ -140,6 +152,9 @@ Omit "**Answered while planning**" when nothing was answered.
   result, with real classes as participants and real method names as messages;
   `activate`/`deactivate` for nested calls, `alt`/`opt` for branches. In **Current**,
   a `Note` marks where it goes wrong.
+- **Data flow diagram** and **State diagram**: rules in
+  [diagram-rules.md](diagram-rules.md#data-flow-diagram); _Not applicable: <reason>._ when
+  the feature moves no data between parts, or has no object with a lifecycle.
 - **Open changes**: when an uncommitted change or stash touches the feature, also list
   it under Open questions.
 - `language` in `.featuredoc.yml` [`en`]: headings stay English (the CLI's), but fixed

{kingmadoc-0.3.0.dev16 → kingmadoc-0.3.0.dev17}/src/kingmadoc/config.py

@@ -35,7 +35,9 @@ DEFAULT_EXCLUDE_DIRS: tuple[str, ...] = (
 # Hard ceiling on analyzed files, so huge repos cannot make `plan` run away.
 MAX_FILES_LIMIT = 5000
 
-SUPPORTED_DIAGRAMS: frozenset[str] = frozenset({"c4_context", "c4_container", "class", "sequence"})
+SUPPORTED_DIAGRAMS: frozenset[str] = frozenset(
+    {"c4_context", "c4_container", "class", "sequence", "data_flow", "state"}
+)
 # How the skill embeds a rendered PNG below each Mermaid block (the CLI writes none).
 DIAGRAMS_PNG_MODES: tuple[str, ...] = ("embed", "file", "off")
 # Models each extra design document can contain, in document order. Must match the
@@ -184,7 +186,9 @@ class FeatureDocConfig:
     max_questions: int = 5
     project: ProjectConfig = field(default_factory=ProjectConfig)
     analyzer: AnalyzerConfig = field(default_factory=AnalyzerConfig)
-    diagrams: tuple[str, ...] = ("c4_context", "c4_container", "class", "sequence")
+    diagrams: tuple[str, ...] = (
+        "c4_context", "c4_container", "class", "sequence", "data_flow", "state",
+    )
     diagram_format: str = "mermaid"
     diagrams_png: str = "embed"
     language: str = "en"
@@ -424,6 +428,8 @@ diagrams:
   - c4_container
   - class
   - sequence
+  - data_flow
+  - state
 
 # Diagram language: mermaid, plantuml (C4-PlantUML) or d2.
 diagram_format: mermaid

{kingmadoc-0.3.0.dev16 → kingmadoc-0.3.0.dev17}/src/kingmadoc/plan/generator.py

@@ -105,6 +105,8 @@ class PlanContext:
         c4_container: Fenced C4 Container block ("" if disabled in the config).
         class_diagram: Whether the class diagram section is enabled.
         sequence_diagram: Whether the sequence diagram sections are enabled.
+        data_flow_diagram: Whether the data flow diagram section is enabled.
+        state_diagram: Whether the state diagram section is enabled.
         generated_at: When the doc was generated.
         version: KingmaDoc version that generated it.
         project_name: Project name (config, or the root directory name).
@@ -133,6 +135,8 @@ class PlanContext:
     files_expected: tuple[str, ...] = ()
     class_diagram: bool = True
     sequence_diagram: bool = True
+    data_flow_diagram: bool = True
+    state_diagram: bool = True
 
 
 def build_questions(analysis: CodebaseReport, config: FeatureDocConfig) -> list[str]:
@@ -217,6 +221,8 @@ def build_plan_context(
         files_expected=files_from_answers(answers, report),
         class_diagram="class" in config.diagrams,
         sequence_diagram="sequence" in config.diagrams,
+        data_flow_diagram="data_flow" in config.diagrams,
+        state_diagram="state" in config.diagrams,
     )