Starscribe User Guide

Fragment tutorial Starscribe User Guide

tags

agenttutorial

Starscribe — Quick-Start Guide

Starscribe turns natural-language descriptions into structured StarSpec documents (.mdoc files). You drive; it authors.

What Starscribe can do

Goal	What to say
Bootstrap a project from a description file	scaffold from path/to/description.md
Import a recorded conversation or monolog	import transcript path/to/file.md
List all actions, events, operations	api list or api list domain/session
Find behavioral gaps and inconsistencies	api audit or api audit feature/feedback
Discover implied actions from flows and surfaces	api derive or api derive domain/session
Apply API report findings to domain files	api apply docs/full-system.api-report.md
Kick off a new initiative	brainstorm <initiative-name>
Add a user persona	new role <name>
Model a bounded domain	new domain <name>
Specify a feature	new feature <name>
Design a use-case sequence	new flow <name>
Write an architectural spec	new blueprint <name>
Capture a user narrative	new story <name>
Plan a release	new milestone <name>
Record a batch of changes	new changeset
Extend an existing document	extend <type>/<id>
See a worked example	show example <type>
Look up a tag’s schema	ask about <tagname>

For linting, sanitizing, and naming audits → use the StarFix agent (lint, sanitize, audit naming, fix naming).

All commands are dispatched through the design loops in the MCP server — Starscribe fetches the right loop for each task at runtime.

Starting a new project

Three paths depending on what you have:

1. You have a prose description (a document, a README, a pitch deck export):

Scaffold command with description file

starscribescaffoldcommand starscribe-scaffold-command

scaffold from content/import/my-app.md

Starscribe reads the file, extracts all structure it can find, writes every document it can derive, and produces an import report at docs/my-app.import.md.

2. You have a rough idea (you want to think it through):

brainstorm <initiative-name>

Starscribe leads a structured discovery session — problem space, actors, values, goals, NFRs — and produces manifests plus a suggested backlog. No domain or feature files are written yet; that comes next.

3. You know what you need (skip straight to a specific document):

new domain auth
new feature user-registration

Starscribe fetches the relevant design loop and walks you through it phase by phase.

Typical sequence for a new project:

Typical new-project command sequence

starscribeworkflowsequence starscribe-typical-sequence

brainstorm my-app → manifest(s) new role user → role document new role admin → role document new domain auth → domain document new feature sign-in → feature document new flow sign-in-flow → flow document

How the writing loop works

Every design loop follows the same rhythm:

Phase-by-phase writing loop walkthrough

starscribeworkflowloop starscribe-writing-loop

Starscribe asks questions — one phase at a time You answer — in any level of detail; short answers are fine Starscribe shows a draft — the complete file You confirm or correct — say "looks good", "change X to Y", or "skip the API section" Starscribe writes — only after you confirm

You can interrupt any phase:

• skip <phase> — marks that section as TODO and moves on
• show draft — displays the current in-progress document at any point
• write — writes the confirmed draft to disk immediately

Document lifecycle

Every document starts at status: draft. Advance it manually when ready:

Status progression and extend command

starscribestatuslifecycle document-lifecycle-status

draft → pending → ready → qa → done

Scaffold mode — import report

When you run scaffold from <file>, Starscribe:

• Extracts all roles, domains, features, flows, values, goals, NFRs, policies, and glossary terms from the prose
• Writes all derivable .mdoc files in one pass
• Scores each document for completeness (0–100%)
• Flags up to 5 gaps and proposes up to 5 next steps
• Writes a full report to docs/{filename}.import.md

Scaffold does not ask questions — it infers, documents uncertainty, and proceeds. Review the import report afterward to see what was inferred and what needs refinement.

Tips for best results

Be specific about behaviour, not implementation. “Users can filter bookmarks by tag” → good. “Add a tag filter using a SELECT element with a CSS class” → Starscribe will redirect this to design.

Name things early. If you give a domain or feature a name in your description, Starscribe will use it throughout. Consistent naming produces coherent cross-document references automatically.

One flow per use case. Don’t describe the happy path and three error paths in one breath — Starscribe will model them as branches inside one flow. If they’re truly separate scenarios, say “make this a separate flow”.

Extend, don’t rewrite. When a document needs updating, use extend <type>/<id> rather than recreating it. Starscribe will fetch the current document and apply your changes surgically.

Check the import report. After scaffold, the report’s “Areas needing more specification” section is the fastest way to see where to invest specification effort next.

Quick-reference card

scaffold from <file>       Bootstrap everything from prose
import transcript <file>   Extract structured spec from a recorded transcript
api list [focus]           Inventory all actions, events, operations
api audit [focus]          Find behavioral gaps and missing events/policies
api derive [focus]         Discover implied API items from flows, surfaces, stories
api apply <report>         Apply report findings to domain files
brainstorm <name>          Start with values and goals
new <type> <name>          Create a single document
extend <type>/<id>         Add to or modify an existing document
show draft                 Display in-progress document
skip <phase>               Mark a phase TODO and continue
write                      Write confirmed draft to disk
help                       List all available instruction paths

lint / sanitize / audit naming / fix naming → StarFix agent

Starscribe fetches its authoring knowledge from the MCP server at runtime. If a command isn’t listed above, say what you want in plain English — Starscribe will route it or ask for clarification.