File Conventions

Fragment

reference

File Conventions

Content Documents

Document type	File pattern	Folder	Design loop
Manifest	`*.manifest.mdoc`	`content/manifests/`	`starspec/agents/starscribe/brainstorm.create`
Role	`*.role.mdoc`	`content/roles/`	`starspec/agents/starscribe/role.create`
Domain	`*.domain.mdoc`	`content/domains/`	`starspec/agents/starscribe/domain.create`
Feature	`*.feature.mdoc`	`content/features/`	`starspec/agents/starscribe/feature.create`
Flow	`*.flow.mdoc`	`content/flows/`	`starspec/agents/starscribe/flow.create`
Surface	`*.ui.mdoc`	`content/surfaces/`	`starspec/agents/stardesign/surface.create`
Blueprint	`*.blueprint.mdoc`	`content/blueprints/`	`starspec/agents/starscribe/blueprint.create`
Story	`*.story.mdoc`	`content/stories/`	`starspec/agents/starscribe/story.create`
Milestone	`*.milestone.mdoc`	`content/milestones/`	`starspec/agents/starscribe/milestone.create`

Surface documents (.ui.mdoc) may contain \{% interactions %\} blocks after all \{% surface %\} blocks to define interactive prototype flows. Surface authoring is owned by stardesign.

Workflow File Naming

Workflow files in instructions/agents/{agent}/ follow the pattern {target}.{verb}.mdoc — target noun first, verb second:

domain.create.mdoc      ✓   target first, verb second
create-domain.mdoc      ✗   verb-first (old convention)

The target is the thing being acted upon. The verb is what is done to it. This groups all workflows for a given target together when sorted alphabetically.

Canonical Verbs

Verb	Meaning
`create`	Produce a new document from scratch or input material
`extend`	Add content to an existing document
`audit`	Structured quality check, gap analysis, produce report
`import`	Bring external content in, convert to StarSpec format
`rewrite`	Transform existing content (style, structure)
`extract`	Pull structured data from unstructured assets
`clarify`	Interactive Q&A loop to resolve ambiguity
`sanitize`	Fix semantic model quality issues
`lint`	Detect/fix schema validation errors
`verify`	Visual or functional verification loop
`delete`	Remove a document (reserved — no workflow yet)

When adding a new workflow, pick from the canonical verbs above. If none fits, propose a new verb and add it to this table.

Scope

This convention applies to type: workflow files. It does not apply to:

Agent specs — {agent}.agent.mdoc (e.g. starscribe.agent.mdoc)
Fragments — type: fragment files keep their own naming (e.g. elements-of-style.prose.mdoc)
Reference docs — non-workflow files like test-suite.mdoc, update-checklist.mdoc