Initial commit

2026-05-25 05:47:28 +00:00
commit 4d6495ffda
97 changed files with 13403 additions and 0 deletions
@@ -0,0 +1,143 @@
+# Design Artifact Structure
+
+This is the current artifact layout for real feature work.
+Use this structure for feature discovery, bounded-context decomposition, workflow-slice design, implementation tracking, and handoff between agents or humans.
+
+## Top-level idea
+
+- **Feature discovery** happens once per feature.
+- **Decomposition** maps the feature into bounded contexts and workflow slices.
+- **Slice design and implementation** happen one workflow slice at a time.
+- **F# blueprint artifacts** are the frozen contract that implementation translates from.
+
+## Feature-level artifacts
+
+Store feature-level documents in:
+
+```text
+design/feature/<feature-slug>/
+├── discovery.md
+├── design.md
+└── status.md
+```
+
+### `discovery.md`
+
+Capture:
+
+- feature story
+- commands and events at feature level
+- business rules and invariants at feature level
+- edge cases at feature level
+- candidate bounded contexts
+- candidate workflow slices
+- feature-level shared language notes
+
+### `design.md`
+
+Capture:
+
+- bounded context inventory
+- feature-step to workflow-slice map
+- cross-context handoffs
+- recommended slice order
+- orchestration notes
+- open questions
+
+### `status.md`
+
+Track:
+
+- current feature phase
+- current workflow slice
+- decomposition completion
+- per-slice gate status
+- blockers and handoff notes
+
+Use [design-status-template.md](design-status-template.md) as the base template.
+
+## Workflow-level artifacts
+
+Store workflow-slice documents in:
+
+```text
+design/workflows/<bounded-context-slug>/
+├── shared-language.md
+├── shared-model.fs            # optional, when the context has reusable F# domain pieces
+└── <workflow-slug>/
+    ├── 01-decomposition.md
+    ├── 02-discovery.md
+    ├── 03-core-sketch.md
+    └── 04-blueprint.fs
+```
+
+### `shared-language.md`
+
+Capture bounded-context-local ubiquitous language:
+
+- what the context owns
+- preferred terms
+- rejected synonyms
+- notes about overlap with project-wide language in [shared-language.md](shared-language.md)
+
+### `01-decomposition.md`
+
+Capture:
+
+- owning bounded context
+- trigger
+- purpose and success outcome
+- inputs owned by this context
+- observed inputs from other contexts
+- downstream handoffs
+- dependencies on other slices
+- explicit note that decision logic stays inside the owning context
+
+### `02-discovery.md`
+
+Capture:
+
+- happy path
+- edge cases
+- business rules and invariants
+- decisions owned by this context
+- handoff assumptions
+- open questions
+
+### `03-core-sketch.md`
+
+Capture:
+
+- command
+- required owned state
+- observed external inputs
+- pseudo policy signature
+- events
+- boundary notes about what remains feature-level orchestration
+
+### `04-blueprint.fs`
+
+This is the frozen F# contract for one workflow slice.
+It should include:
+
+- domain primitives
+- commands
+- events
+- states / aggregates
+- `decide`
+- `apply`
+- workflow contract signature
+
+## Rules of use
+
+- One workflow slice belongs to one bounded context.
+- No cross-context decision logic belongs inside a workflow slice.
+- Cross-context behavior belongs in feature-level handoff and orchestration notes.
+- Shared language should exist both globally and per bounded context.
+- Implementation should proceed one slice at a time from the frozen F# blueprint.
+
+## Relationship to the by-hand docs
+
+The [../by-hand/README.md](../by-hand/README.md) material keeps the simpler 5-phase human practice flow.
+Use that to build judgment.
+Use this page for the actual repository artifact structure.