Scaffold Mode — Import an Application Description

Workflow

agent starscribe

Phase 1 — Parse & Inventory

Read the source file in full. Do not truncate. Extract and catalogue:

Category	What to look for
App identity	Name, tagline, purpose statement, target audience
Roles / actors	Any person or system that performs an action or is acted upon
Domains	Bounded concerns, nouns that “own” data or behaviour
Features	Verbs in user-goal form (“user can…”, “system allows…”)
Flows	Numbered steps, “when … then …” sequences, scenario descriptions
Values / principles	Stated beliefs, design philosophies, non-negotiable rules
Goals	Success criteria, launch targets, metrics
NFRs	Performance, security, accessibility, availability constraints
Glossary terms	Domain-specific vocabulary, acronyms, defined concepts
Policies	Automatic reactions, “whenever X, automatically Y” rules
Data entities	Tables, models, attributes, relationships mentioned

After extraction, produce a Document Plan — a flat list of every file to be created with its type, proposed id, and one-line purpose — and output it before writing any file. This is the contract; do not deviate from it silently.

DOCUMENT PLAN
─────────────────────────────────────────────────────
manifest   product              Product identity, values, goals, NFRs
role       user                 End-user actor
role       admin                Administrator actor
domain     auth                 Authentication and session management
domain     billing              Subscription and payment handling
feature    sign-in              User authentication flow
feature    manage-subscription  Billing portal access
flow       sign-in-flow         Credential submission and session creation
...

Phase 2 — Scaffold Manifests

Create content/manifests/{id}.manifest.mdoc for each manifest identified in Phase 1.

Rules:

One manifest for product identity (values, principles, goals, NFRs) unless the source clearly separates concerns
Map stated beliefs → \{% value %\} entries (id: SCREAMING_SNAKE)
Map design rules / constraints → \{% principle %\} entries (id: kebab-case)
Map success criteria / metrics → \{% goal %\} entries (id: kebab-case, status="pending")
Map performance / security / accessibility constraints → \{% requirement %\} entries (id: kebab-case, priority="must" or "should")
If information is absent, infer reasonable defaults from the domain and note them as inferred in the import report
Do NOT invent values or principles not supportable from the source text

Phase 3 — Scaffold Roles

Create content/roles/{id}.role.mdoc for each role.

Rules:

Extract stated goals and responsibilities from the prose
If the source only names the role without detail, create a minimal document with a \{% tldr %\} stub and note as low-completeness
Follow naming: {job-title-kebab}.role.mdoc

Phase 4 — Scaffold Domains

Create content/domains/{id}.domain.mdoc for each domain.

Rules:

Populate \{% glossary %\} with every domain term found in the source
Derive \{% api %\} entries:
- Imperative phrases → \{% action %\} or \{% operation %\}
- “When … then …” reactions → \{% policy %\}
- Named failure modes → \{% error %\}
Derive \{% model %\} DBML from any mentioned entities, attributes, and relationships; mark speculative fields with a [note: "inferred"] comment
If an entity is mentioned but its schema is not described, create the table with id only and a Note: "Schema not specified in source" comment

Phase 5 — Scaffold Features

Create content/features/{id}.feature.mdoc for each feature.

Rules:

Link domains= and roles= using cross-document ref format (domain/id, role/id)
Derive \{% requirement %\} entries from stated capabilities; assign priority by MoSCoW signal words in the source (“must”, “should”, “nice to have”, “out of scope”)
Write at least one \{% criterion %\} per requirement if acceptance language exists in the source
Emit \{% api %\} only for feature-level orchestration actions/events that are not already in the domain
Set status="draft" on all scaffolded documents

Phase 6 — Scaffold Flows

Create content/flows/{id}.flow.mdoc for each identified use-case sequence.

Rules:

Link feature= using cross-document ref format (feature/id)
Extract preconditions and postconditions from source prose (“given”, “assuming”, “result:”, “outcome:”)
Map each described step to a \{% step %\} — include action= only when it maps to a named domain action/operation; omit for narrative or UI steps
Create \{% branch %\} blocks for every described decision point
If the source gives only a happy path, scaffold that and note in the import report that error paths are unspecified

Phase 7 — Completeness Assessment

After writing all files, produce a structured completeness estimate. Score each document on a 0–100% scale using these heuristics:

Score	Meaning
80–100%	All fields present; content is specific and actionable
50–79%	Most fields present; some stubs or inferred content
20–49%	Skeleton only; key fields missing or entirely inferred
0–19%	Placeholder; source gave name only

Then:

List up to 5 areas that would benefit most from additional specification (name the file and what is missing)
List up to 5 next-step proposals in priority order — each as a concrete new {type} {id} or extend {type} {id}: {what} command

Phase 8 — Write Import Report

Write a complete report to docs/{source-filename}.import.md.

The report must contain:

# Import Report — {AppName}

**Source:** {relative path to source file}
**Date:** {ISO 8601 date}
**Agent:** scaffold mode

## Document Plan

| File | Type | Completeness | Notes |
|------|------|-------------|-------|
| content/manifests/product.manifest.mdoc | manifest | 72% | Goals inferred from tagline |
| content/roles/user.role.mdoc | role | 55% | Responsibilities partially stated |
| ...                          | ...  | ...  | ... |

## Completeness Summary

| Category | Score | Gap |
|----------|-------|-----|
| Manifests | 72% | NFRs for security not stated |
| Roles | 55% | Admin responsibilities not detailed |
| Domains | 61% | billing model schema not described |
| Features | 68% | Acceptance criteria sparse |
| Flows | 45% | Error paths unspecified for 3 of 4 flows |

## Areas Needing More Specification

1. **{file}** — {what is missing and why it matters}
2. ...

## Proposed Next Steps

1. `extend domain/{id}: add error cases for {operation}`
2. `new flow {id}: {what it would cover}`
3. ...

## All Created Files

{bulleted list of every file written with one-line description}

Do’s and Don’ts

Do:

Infer missing information and document uncertainty in the import report
Preserve the source document’s vocabulary and phrasing in \{% tldr %\} blocks and descriptions
Apply naming conventions exactly — wrong id formats cause compiler errors
Include a root document tag matching the file type in every .mdoc file
Ensure all cross-document references point to files that scaffold mode created or that already exist in content/

Don’t:

Ask clarifying questions during scaffold — the user’s goal is a complete first-pass content tree, not a dialogue
Paraphrase source language into generic spec-speak
Write production code — scaffold mode writes .mdoc files only (no packages/, src/, or instructions/)
Create files without a root tag (\{% domain %\}, \{% feature %\}, \{% flow %\}, \{% role %\}, \{% manifest %\}, \{% blueprint %\}, \{% story %\}, \{% milestone %\})
Write dangling cross-document references

Definition of Done

Document plan reviewed and confirmed by user
All planned documents created with correct frontmatter and root tags
Cross-references between documents are bidirectional and valid
Import report written to docs/{source-filename}.import.md
User confirmed the scaffold output