Domain extension

Workflow Domain extension

agent starscribe

tags

workflowdomain

context

agents/starscribe/domain.create

Extends an existing domain document with new behaviour, models, or vocabulary. The same derivation chain from domain.create applies — actions and events drive everything, even when you’re only adding a single model or term.

Phase 1 — Load Current State

Fetch the domain and review what is already defined:

get_document("domain/{id}")

Before proposing anything, inventory the existing:

• API items: which actions, events, and operations are already declared?
• Aggregates: which entities have DBML models?
• Policies: which reactive rules exist?
• Glossary: which terms are defined?

This inventory prevents duplicate definitions and identifies where new items should be placed.

Phase 2 — Classify the Change

Determine what type of extension is needed. A single user request may involve more than one type — work through them in derivation order.

Change type	Entry point	Derivation chain
New behaviour (actions/events)	Phase 3	→ new pairs → possibly new aggregate → possibly new model fields
New aggregate or model fields	Phase 4	Must be derived from existing or new actions/events
New policy (reactive rule)	Phase 5	Requires existing source event and reaction action
New glossary term	Phase 6	Verify against existing terms for conflicts
New operation (query)	Phase 3	→ define result type and error cases

If the user asks to “add a model” directly, check whether the model is already implied by existing actions/events that lack a corresponding aggregate. If so, start at Phase 4. If the model implies new behaviour that isn’t declared yet, start at Phase 3.

Phase 3 — Action/Event Discovery (scoped)

Run Phases 1–3 of domain.create but scoped to the new behaviour only:

1. Capture — what new commands, events, and operations does the user describe?
2. Sequence — where do they fit in the existing chronological narrative? Do they extend an existing sequence or start a new branch?
3. Pair — match each new command with its resulting event. Match each new operation with its result type and error cases.

Integration check: Do any new events trigger existing policies? Do any existing events need new policies because of the new behaviour? Note these for Phase 5.

Phase 4 — Aggregate & Model Extension

If new actions/events belong to an existing aggregate:

• Add them to the existing aggregate grouping
• Derive new DBML fields from what the new commands need and events must record
• Do not duplicate fields already present

If new actions/events form a distinct cluster:

• Propose a new aggregate
• Verify it does not overlap with existing aggregates (same entity, different name)
• Derive the initial DBML table

Phase 5 — Policy Updates

If the change introduces or implies new reactive rules:

• Verify the source event and reaction action both exist (in the existing or newly added API)
• Write the policy with proper source and reaction attributes
• If the source event or reaction action is new, it must have been added in Phase 3

Phase 6 — Glossary

If the change introduces new terminology:

• Check every new term against existing glossary entries for conflicts or near-duplicates
• Ask the user to resolve any ambiguity before adding the term
• Place the term in the glossary section, maintaining alphabetical order

Phase 7 — Draft & Confirm

Present only the changed sections as a diff for confirmation. Do NOT rewrite unchanged sections.

For each section that changed, show:

• What was added (new items)
• What was modified (changed fields or relationships)
• Where it was placed relative to existing content

Write the updated file only after explicit confirmation.

Output: content/domains/{id}.domain.mdoc (overwrite)

---

Do’s and Don’ts

Do:

• Fetch the existing domain bundle and inventory it before proposing any changes
• Follow the derivation chain: actions/events → aggregates → models, even for small additions
• Run the appropriate domain.create sub-phases scoped to new behaviour only
• Verify new glossary terms do not conflict with existing definitions
• Present only the changed sections as a minimal diff for confirmation
• Preserve the existing structure and ordering of unchanged sections

Don’t:

• Don’t rewrite unchanged sections or reformat existing content
• Don’t add actions or events without pairing them through the interaction pairing phase
• Don’t introduce a new aggregate without verifying it does not overlap with an existing one
• Don’t add a model directly without checking if it should be derived from actions/events
• Don’t skip the confirmation step even for small changes

Definition of Done

• Existing domain loaded and inventoried before changes
• Derivation chain followed for all additions
• Draft diff presented to user for confirmation
• Updated document written with only changed sections modified
• All new action/event pairs are complete and consistent
• All cross-references resolve to existing documents
• pnpm compile succeeds

linktag > domain