Skip to content

m3dcodie/eng-flow / .claude/skills/eng-flow-domain-model

eng-flow-domain-model

Verified

Production Stage 2 — takes a saved eng-flow spec and turns its named domains into a domain model, data flows, and a conceptual system diagram. No tech stack, no deployment, no API shape — that's Stage 3. Run by an "architect" persona, after eng-flow-spec, before eng-flow-architecture.

eng-flow domain model

Stage 2 of the production track. Translates a spec's plain-language requirements into structure — entities, relationships, flows — while staying strictly conceptual. If a question about tech stack, database choice, deployment, or API shape comes up here, defer it explicitly: "that's Stage 3 (architecture), not this stage" — don't answer it now even if you know the answer.

Analytics

At the start of every numbered step below (including Step 0), run python3 "${CLAUDE_PLUGIN_ROOT}/.claude/skills/lib/bin/eng-flow-analytics-checkpoint" eng-flow-domain-model "<step name>" "<dated-slug>". As the last action of Step 10, run python3 "${CLAUDE_PLUGIN_ROOT}/.claude/skills/lib/bin/eng-flow-analytics-finish" eng-flow-domain-model "<dated-slug>". See eng-flow-spec's Analytics section for what this logs and why; rollup via eng-flow-analytics (Stage 10).

Decision Ledger

Check $ARGUMENTS for a --guide token; if present, every decision point below gets an explicit AskUserQuestion instead of a silent default, and Step 10's report adds a "Decisions I made / decisions you made" summary. Log every decision point via python3 "${CLAUDE_PLUGIN_ROOT}/.claude/skills/lib/bin/eng-flow-decision-log" eng-flow-domain-model "<step>" <reason> <mode> <owner> "<description>" "<dated-slug>". See eng-flow-spec's Decision Ledger section for the taxonomy and why. Rollup/analysis: eng-flow-retro Step 1 (Stage 9).

Also check $ARGUMENTS for --review-model=<opus|sonnet|haiku|fable> — see Step 7 for what it controls.

Drafts

This stage saves as it goes to eng-flow/.drafts/domain-model--<dated-slug>.json (<dated-slug> is the spec folder's), so a crash loses at most the step in progress — in Steps 1 and 8, only the domain or finding in progress. The shared rules (Resume, Review, Discard, in_progress loops, input drift) are in ${CLAUDE_PLUGIN_ROOT}/.claude/skills/lib/draft-resume.md — Read it before resuming, reviewing or discarding. Every save in this file is this call, with the step's JSON on stdin — agreed answers in short form, JSON-escaped:

python3 "${CLAUDE_PLUGIN_ROOT}/.claude/skills/lib/bin/eng-flow-draft" save eng-flow-domain-model "<dated-slug>" <step> <<'EOF'
{"status": "done", "name": "<step name>", "answers": {…}}
EOF

Degrades silently like the analytics scripts — a failed save prints a warning and the run carries on.

Step 0 — Find the spec

Look for eng-flow/specs/*/spec.md. If none exist, tell the user to run eng-flow-spec first — this stage has nothing to model without one. Then check for drafts: python3 "${CLAUDE_PLUGIN_ROOT}/.claude/skills/lib/bin/eng-flow-draft" list eng-flow-domain-model — one line per draft, starting with the spec folder's <dated-slug>. If more than one spec exists, ask which spec this run is for; a spec with a draft gets "draft: stopped after Step n, age" in its option description. If exactly one, use it. If the chosen spec has a draft → Resume (draft-resume.md) — no further Step 0 questions.

Read the spec's Domains Touched list and User Journeys — these are the inputs to everything below. If the spec has no domains list (e.g. it used the lightweight feature/story template), ask the user directly: "Which domains/functional areas does this touch?" Log it: risk open_question user_confirmed "domains list: <what was named>".

As the last action of this step (new run only), save step 0 ("name": "Find the spec") with topic (the spec's title), spec_folder, domains and journeys (lists, as read or as the user named them), then record the input:

python3 "${CLAUDE_PLUGIN_ROOT}/.claude/skills/lib/bin/eng-flow-draft" inputs eng-flow-domain-model "<dated-slug>" "eng-flow/specs/<dated-slug>/spec.md"

Stale on review: an answer from Steps 1–5 changed after Step 6 was saved — the draft text and its review are out of date. truncate ... 5, re-save the changed steps, continue at Step 6.


Step 1 — Domain model, per domain

For each domain named in the spec, ask (don't invent):

  1. What are the core entities in this domain? (the nouns the business actually uses — pull from the spec's own language, don't rename them into something more "technical")
  2. What are the key relationships between these entities, and between entities in this domain and entities in other named domains?
  3. Is there any term here that means something different to different stakeholders? (surface ubiquitous-language conflicts now — cheap to fix here, expensive once code exists)

Keep this at the conceptual level: entity names, relationships, cardinality if it's non-obvious. No fields, no types, no persistence — that's implementation, not modeling.

Log it: knowledge_asymmetry open_question user_confirmed "domain '<name>': entities/relationships/language conflicts" — the business's own vocabulary for its entities isn't something the AI can infer, it has to be asked per domain.

After each domain, save step 1 as {"status": "in_progress", "name": "Domains", "answers": {"domains": [...]}} — every domain finished so far, each with name, entities, relationships, language_notes. After the last domain, save it once more as "done".


Step 2 — Data flow

Using the spec's user journeys and functional requirements: for each journey, trace which domains it touches and in what order. Ask the user to confirm or correct the sequence rather than asserting it — the spec describes user-facing behavior, not internal flow, so this is genuinely new information, not a restatement.

Log it: risk open_question <user_confirmed|user_revised> "journey '<name>' flow: <domain sequence>".

Represent as a simple flow list or diagram (mermaid flowchart is fine if the host renders it, otherwise plain ordered steps):

User action → Domain A (does X) → Domain B (does Y) → outcome

As the last action of this step, save step 2 ("name": "Data flow") with flows — one entry per journey with journey and the confirmed sequence.


Step 3 — Conceptual system diagram

One diagram showing how the named domains/subsystems relate — a context map, not a deployment diagram. Boxes are domain names from Step 1 (e.g. "Checkout," "Inventory," "Billing"), arrows show which domain calls/depends on which. Do not label boxes with technology (no "Postgres," "React," "Lambda") — if a box needs a technology label to make sense, that's a sign the diagram has drifted into Stage 3's territory; pull it back to domain names only.

Draft it as mermaid first — that's what goes in the saved file. Then ask once: "Want this rendered as a diagram you can actually see, or is the mermaid source in the saved file enough?" Default to skipping if the user doesn't ask. If yes, load the artifact-diagramming skill and publish via the Artifact tool; note the artifact URL alongside the saved diagram source in Step 6/7 so it isn't lost.

Log it: risk silent_decide ai_default "diagram rendering: skipped, mermaid source only" if the default applies, otherwise open_question user_confirmed.

As the last action of this step, save step 3 ("name": "System diagram") with mermaid (the diagram source) and artifact_url (or null).


Step 4 (optional) — Mockups / wireframes

Ask: "Would a rough wireframe help validate any of these journeys?" Default: skip unless the user asks or a journey is genuinely hard to follow in text. If yes, keep it low-fidelity — boxes and labels showing flow and content, not visual design (no colors, no branding, no component library references). If produced, offer the same Artifact-rendering treatment as Step 3.

Log it: risk silent_decide ai_default "wireframes: skipped" if the default applies, otherwise open_question user_confirmed.

As the last action of this step, save step 4 ("name": "Wireframes") with wireframes — one entry per journey with journey, wireframe and artifact_url (or null). If skipped: {"status": "skipped", "name": "Wireframes", "reason": "user declined wireframes"}.


Step 5 — Refinement Q&A

While modeling, gaps in the spec surface that weren't visible when it was pure prose — e.g. "the spec's journey says a user cancels an order, but doesn't say what happens to reserved inventory." Collect these as explicit questions, ask the user, and note the answer here rather than silently amending the spec file itself (the spec stays the record of what was agreed at Stage 1; this stage's answers extend it, they don't retroactively rewrite it).

Log each gap: risk open_question user_confirmed "spec gap: <question> → <answer>".

As the last action of this step, save step 5 ("name": "Refinement") with gaps — one entry per gap with question and answer (an empty list if none surfaced).


Step 6 — Draft and confirm

# Domain Model: [Name]
(source spec: eng-flow/specs/<dated-slug>/spec.md)

## Domains

### [Domain name]
**Entities:** [...]
**Relationships:** [...]
**Ubiquitous language notes:** [...]

(repeat per domain)

## Data Flow

[Per-journey flow traces from Step 2]

## System Diagram

[Conceptual diagram from Step 3 — domain names only, no tech]
[Artifact URL, if rendered; omit line otherwise]

## Wireframes

[If Step 4 ran; omit section otherwise. Artifact URL if rendered.]

## Open Questions From Modeling

[Step 5 gaps + answers, or "none surfaced" if genuinely none]

Show the draft, ask: "Does this match how you think about the domains, or anything to correct?" Log it: risk open_question <user_confirmed|user_revised> "draft accepted|draft revised: <what changed>".

As the last action of this step, once the user has confirmed, save step 6 ("name": "Draft") with domain_model_markdown — the full confirmed text, JSON-escaped — and revisions (empty if accepted as-is).


Step 7 — Independent subagent review

Steps 1-6 ran in this conversation, built up interactively, one domain/journey at a time — good for capturing the user's mental model, bad at catching things that only show up when you look at the whole doc at once: a domain named in the spec but dropped from the model, a relationship asserted from one side but not the other, a diagram box with no corresponding prose section. Counter it with one blind pass, same pattern Stage 3.5 (eng-flow-eng-review) uses on architecture.md.

Spawn a single Agent call (foreground — its output feeds Step 8, so wait for it) with subagent_type: "eng-flow:eng-flow-doc-reviewer" — a read-only plugin agent (Read, Grep, Glob only) that carries the consistency criteria. Give it only the run-specific inputs, not this conversation's context or Steps 1-6's findings:

"Review: domain-model. Files: eng-flow/specs/<dated-slug>/spec.md and the just-drafted domain-model.md" — followed by the draft's full content, since it isn't saved until Step 9.

Fallback: if eng-flow:eng-flow-doc-reviewer isn't in the Agent tool's list (the plugin agents didn't load — e.g. the skills are running from a checkout, not an installed plugin), read ${CLAUDE_PLUGIN_ROOT}/agents/eng-flow-doc-reviewer.md (agents/eng-flow-doc-reviewer.md in an eng-flow checkout), and send its body below the frontmatter, followed by the same inputs, as the prompt of a general-purpose Agent call. Log it: risk silent_decide ai_default "agent eng-flow-doc-reviewer unavailable: general-purpose fallback". Never skip the review because the agent is missing.

Reviewer model: omit model on the Agent call by default — the agent file sets model: inherit, so it runs on whichever model is running this conversation, the same convention eng-flow-eng-review and eng-flow-code-review use. The same applies to the general-purpose fallback. If $ARGUMENTS carries --review-model=<opus|sonnet|haiku|fable>, pass that as the call's model instead — e.g. --review-model=haiku for a cheap pass on a small/low-risk domain model, --review-model=opus when the domain model is large or the spec flagged this as high-risk. Log the choice: risk silent_decide ai_default "review model: inherited (no override)" when no override was given, or risk open_question user_confirmed "review model: <name> (--review-model override)" when one was.

Fold the subagent's findings into Step 8. If it turns up nothing, say so — a clean pass is a valid outcome, don't manufacture findings to fill the step.

As the last action of this step, save step 7 ("name": "Independent review") with review_model and findings — one entry per finding with title, section, issue and fix — so a resume doesn't spawn the reviewer again.


Step 8 — Issue resolution

For each finding from Step 7, call AskUserQuestion individually — one finding per call, never batched. Name the issue, ground it in the specific domain-model.md section it reacts to (quote or point to the actual text — a finding that can't be tied to real doc content doesn't get raised), state options, give an opinionated recommendation, explain why.

Stop and wait for the user's answer before raising the next finding. Every finding gets an explicit accept/change/reject, same discipline as every other stage in this track.

Log each: risk open_question <user_confirmed|user_revised> "finding '<title>': accepted|changed|rejected".

For anything accepted or changed, update the draft directly before Step 9 — domain-model.md gets saved once, already reflecting the review, not saved-then-patched.

After each finding, save step 8 as {"status": "in_progress", "name": "Findings", "answers": {"resolved": [...], "domain_model_markdown": "…"}} — resolved lists every finding answered so far (title, resolution: accepted/changed/rejected, note), and domain_model_markdown is the current text with those resolutions applied, so a resume doesn't apply them twice. After the last finding (or straight away if Step 7 found none), save it as "done" with the same fields.


Step 9 — Save

Write to the same spec's folder: eng-flow/specs/<dated-slug>/domain-model.md — from step 8's saved domain_model_markdown when resuming.

As the last action of this step, once the file is written, delete the draft: python3 "${CLAUDE_PLUGIN_ROOT}/.claude/skills/lib/bin/eng-flow-draft" clear eng-flow-domain-model "<dated-slug>". If the write failed, skip this and keep the draft; tell the user.


Step 10 — Report back

Confirm the saved path. Tell the user this feeds Stage 3 (architecture — tech stack, deployment, API shape), not yet run.

If this run was in guide mode, add a "Decisions I made / decisions you made" summary here, drawn from this run's eng-flow-decision-log calls.

Run the Step 10 analytics-finish call (see Analytics section above) before ending.

writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 321kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall