Feature extension

Workflow Feature extension

agent starscribe

tags

workflowfeature

context

agents/starscribe/feature.createagents/starscribe/flow.create

Extends an existing feature document with new requirements, flows, acceptance criteria, or API entries. Features consume domain behaviour — every addition must trace back to a domain action, event, or operation.

Phase 1 — Load Current State

Fetch the feature and its referenced domains:

get_document("feature/{id}")
get_document("domain/{domain-id}")    ← for each domain in the feature's `domains` attribute

Inventory the existing:

• Requirements: which are declared, with what priorities?
• Flows: which standalone flow files reference this feature?
• Acceptance criteria: which requirements have linked criteria, which don’t?
• API: which actions and events does the feature expose?
• Roles: which roles use this feature?

Phase 2 — Classify the Change

Determine what type of extension is needed. A single request may span multiple types — work through them in this order.

Change type	Entry point	Key constraint
New requirement	Phase 3	Must be derived from domain actions or explicitly new user need
New flow	Phase 4	Must be a standalone file via flow.create
New acceptance criterion	Phase 5	Must link to an existing requirement
New API action/event	Phase 6	Must exist in a referenced domain’s API first
New role association	Phase 6	Role must exist in content/roles/

If the user asks to “add a feature” that sounds like it belongs in a different feature document, flag this before proceeding — it may need its own feature.create run instead.

Phase 3 — Requirements

For each new requirement:

1. Derive from domain — check the referenced domains’ API. Is the requirement already implied by a domain action the feature doesn’t yet consume? If so, the requirement is documenting an existing capability, not inventing a new one.
2. Assign metadata:
   • id: kebab-case, descriptive (e.g. req:bulk-delete)
   • priority: must, should, could, or wont
   • tags: non-functional categories if applicable (performance, security, accessibility)
3. Link criteria — every requirement needs at least one acceptance criterion (Phase 5). If the user provides the requirement without criteria, draft them and confirm.

Phase 4 — Flows

Each new use case becomes a standalone flow file. Never embed flow content in the feature document.

1. Run starspec/agents/starscribe/flow.create for each new flow
2. After the flow file is written, add a reference from the feature document
3. Verify the flow’s domain actions match actions declared in the feature’s referenced domains

If the user describes steps that fit into an existing flow rather than a new one, point this out — it may be a flow extension rather than a new flow.

Phase 5 — Acceptance Criteria

For each new (or existing but uncovered) requirement:

1. Write at least one Gherkin criterion: Given [precondition], when [action], then [outcome]
2. Link via the requirement attribute to the requirement’s id
3. Cover both the happy path and at least one failure/edge case where applicable

If adding criteria to requirements that were previously uncovered, present the new criteria grouped by requirement for clarity.

Phase 6 — API and Roles

API additions:

• Verify the action or event exists in a referenced domain’s {% api %} block
• If it doesn’t exist in the domain, the domain must be extended first (run domain.extend)
• Add the action/event to the feature’s API section

Role additions:

• Verify the role exists in content/roles/
• If it doesn’t, run role.create first
• Add the role to the feature’s roles attribute

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 or modified
• Where it was placed relative to existing content
• Any new standalone files created (flows)

Write the updated file only after explicit confirmation.

Output: content/features/{id}.feature.mdoc (overwrite)

---

Do’s and Don’ts

Do:

• Fetch the existing feature and its referenced domains before proposing any changes
• Derive requirements from domain actions first, then elicit truly new ones
• Use the flow.create workflow for every new flow — always standalone files
• Link every acceptance criterion to its requirement via the requirement attribute
• Verify API additions exist in the referenced domain before adding them to the feature
• Present only changed sections as a minimal diff for confirmation

Don’t:

• Don’t rewrite unchanged sections or reformat existing content
• Don’t add requirements without linking them to at least one acceptance criterion
• Don’t add flows inline; flows are always standalone .flow.mdoc files
• Don’t add API entries that don’t exist in a referenced domain — extend the domain first
• Don’t skip the domain verification step for new API entries
• Don’t conflate extending this feature with creating a new one — flag if the scope diverges

Definition of Done

• Existing feature and referenced domains loaded and inventoried
• Draft diff presented to user for confirmation
• Updated document written with only changed sections modified
• Every new requirement has at least one Gherkin acceptance criterion
• New flows created as standalone .flow.mdoc files
• All API additions verified against referenced domains
• All cross-references resolve to existing documents
• pnpm compile succeeds

linktag > feature