Design creation

Workflow Design creation

agent starscribe

tags

workflowblueprint

context

agents/starscribe/feature.create

A design session translates existing specifications into architectural decisions. The inputs are feature and domain bundles; the output is one or more .blueprint.mdoc files that document approach, components, wiring, and rules.

Design documents do NOT restate requirements — they answer: “Given these requirements, how will we build it?”

Dependency Check

Before starting, fetch all referenced specs:

get_document("feature/{id}")   — for each feature in scope
get_document("domain/{id}")    — for each domain in scope
get_document("manifest/{id}")  — if NFRs or values are referenced

Verify the specs are complete enough to design against (status review or ready). If they are draft, flag the gaps before proceeding.

Phase 1 — Design Scope

Ask:

1. Which features and/or domains does this design cover?
2. What concern does this design address? (e.g. persistence layer, API surface, deployment topology, security model)
3. Will this be one design document or several?

Splitting rule: Create one design per distinct architectural concern. Common splits:

• By layer: api-layer, data-layer, worker-layer
• By system boundary: internal-service, external-integration
• By feature cluster: one design per feature if they have different implementation approaches

Name each design now: id will be {name}.blueprint.mdoc under content/blueprints/.

Phase 2 — Approach

For each design document, select the overarching architectural approach:

Ask:

• What architectural pattern fits? (layered service stack, event-driven, CQRS, hexagonal, pipeline, …)
• What drove this choice — which requirements or constraints made alternatives unacceptable?
• What are the known trade-offs?

Produce one approach block per design. The prose must justify the choice, not just name it.

Phase 3 — Component Discovery

Enumerate the components needed to realise the approach.

For each component ask:

• What is its single responsibility?
• Which layer does it belong to? (controller, service, repository, worker, gateway, store, surface, adapter, infrastructure, orchestrator, contract)
• What technology or framework implements it?
• Does it already exist in the codebase, or is it new?

Produce a candidate component list. Group by layer to spot missing layers or overlapping responsibilities.

Phase 4 — Wiring

Map dependencies between components.

For each component ask:

• Which other components does it call or depend on?
• What is the nature of the dependency? (sync call, async event, read-only, write-only)
• Does this dependency cross a layer boundary it should not?

Express as uses children inside each component. Flag any dependency that violates the chosen approach (these become rules in Phase 5).

Phase 5 — Rules

Derive implementation constraints from the approach, wiring decisions, and manifest NFRs.

For each rule:

• State it imperatively: “No component above the repository layer may access the database directly.”
• Assign force="must" or force="should".
• Link to the motivating requirement via ref="manifest/{id}#req:{id}" if one exists.

Rules should be enforceable — if a rule cannot be verified in code review or tests, it is guidance, not a rule.

Phase 6 — Diagrams

Produce at least one Mermaid diagram per design document.

Choose the diagram type that best expresses the concern:

• Component topology → classDiagram or graph
• Request flow → sequenceDiagram
• State machine → stateDiagram-v2
• Deployment → graph TD with node shapes

The diagram must be consistent with the components and wiring documented in phases 3–4. If they diverge during drafting, fix the prose, not the diagram.

Phase 7 — Links

Add link entries for:

• Features implemented by this design: ref="feature/{id}"
• Source code repositories or ADRs: url="..."
• Related designs in this session: ref="design/{id}"

Phase 8 — Multi-Document Decision

If multiple design documents were scoped in Phase 1, review them as a set before writing:

• Are the component ids unique within each design? (they only need to be unique per document)
• Are cross-design dependencies explicit as link entries?
• Does each design document have a clear, non-overlapping concern?

Adjust scope or split further if two designs feel like one, or merge if separation is artificial.

Phase 9 — Draft & Confirm

Present each design draft for confirmation before writing. Output: content/blueprints/{id}.blueprint.mdoc

Draft and confirm each document separately. Write only after the user confirms.

---

Do’s and Don’ts

Do:

• Fetch all referenced feature, domain, and manifest bundles before starting design
• Verify specs are review or ready status before designing against them
• Create one design document per distinct architectural concern
• Ensure every rule is enforceable in code review or tests
• Produce at least one Mermaid diagram per design document that is consistent with the prose

Don’t:

• Don’t restate requirements — design documents answer “how”, not “what”
• Don’t design against draft specs without flagging the gaps first
• Don’t create overlapping design documents; split by concern cleanly
• Don’t write rules that cannot be verified — those are guidance, not rules
• Don’t let diagrams diverge from the component and wiring prose; fix the prose if they conflict

Definition of Done

• Draft presented to user for confirmation (each document separately)
• Document(s) written as content/blueprints/{id}.blueprint.mdoc with correct frontmatter and root tag
• All components have a single responsibility and assigned layer
• Wiring dependencies are explicit and do not violate the chosen approach
• At least one Mermaid diagram per document, consistent with the prose
• All cross-references resolve to existing documents
• pnpm compile succeeds

linktag > blueprintlinktag > diagramlinktag > manifest