Skip to content
Merlon Docs

Getting-started workflow

Product capability: the getting-started workflow of the merlon-docs skill bootstraps Merlon Docs in a greenfield or brownfield repository — config, four-tier guide layout, and initial shards — then optionally walks a first feature through design → feature → UX → doc-only so teams learn the full workflow circuit.

Workflow file: skills/merlon-docs/references/workflows/getting-started.md (tutorial script: skills/merlon-docs/references/workflows/first-feature-tutorial.md). Skill workflows covers the shared workflow contract: intake, guide placement, and the glossary.

End-user value

Section titled “End-user value”

Contributors get a working Merlon Docs layout (guides, compile/check scripts, glossary hooks) without inventing structure from scratch. Brownfield repos keep legacy docs until review instead of destructive overwrite. The project’s glossary inclusion bar is recorded up front so later workflows know which terms belong. An optional first-feature tutorial shows how the day-to-day workflows fit together before handing off to normal delivery.

What this workflow is for

Section titled “What this workflow is for”
Obligation As-built expectation
Bootstrap intake Collect FEATURE, PERSONA, and EXPERIENCE (novice vs expert); ask only when someone can answer, else default to expert
Inspect repo state Detect greenfield vs brownfield; discover package manager and existing docs before scaffolding
Install toolchain Add CLI/presets with the repo’s package manager; wire merlon compile / merlon check into scripts
Scaffold four-tier guides Create docs/features/, docs/client/, docs/developer/, docs/glossary/ with indexes and starter shards
Glossary inclusion bar With the end user, record the project inclusion bar in the glossary index preamble (what terms do / do not belong)
Seed domain terms Add initial glossary entries that the inclusion bar allows; link from starter shards
Brownfield migration Scaffold alongside legacy docs; mark migrated legacy files ready to archive, never auto-delete
Experience-adaptive depth Novice: tutorial shards and concept pauses; expert: concise FEATURE starters only
Validate Run merlon compile / merlon check until clean; with Vale installed and no prose linting asked for, add a placeholder .vale.ini
First-feature tutorial After bootstrap, offer walkthrough (default yes for novice); resolve EXAMPLE_MODE; run workflow phases in order
EXAMPLE_MODE recommended (hello-greeting) or bring-your-own (user FEATURE / PERSONA; one small slice)
Hand off when tutorial skip State next steps for feature-level, doc-only, design-architecture, or UX

What this workflow is not

Section titled “What this workflow is not”
  • Day-to-day feature delivery outside the optional tutorial — use the feature-level workflow directly after onboarding.
  • Docs-only cleanup with no bootstrap — use the doc-only workflow.
  • Architecture-as-shards / ADR drafting alone — use the design-architecture workflow.
  • End-user / client journey design alone — use the ux workflow.
  • Engineering process during bootstrap scaffold, such as code TDD rituals or atomic commit groups. Scaffold leaves these out. When the first-feature tutorial runs, each phase follows the matching day-to-day workflow.
  • Inventing the inclusion bar without the end user — the bar is project judgment recorded with the people who own the docs, not a one-size-fits-all list.
  • Auto-running all four workflows without user pauses — phases require “go” between steps.

When the user asks for ongoing feature or docs work in the same session as bootstrap, this workflow MUST finish setup (or ask to narrow scope), then either run the first-feature tutorial or state next steps for the matching day-to-day workflow.

Acceptance (as-built)

Section titled “Acceptance (as-built)”

A successful getting-started session typically:

  1. Leaves a configured docs root (merlon.config.json, compile/check scripts)
  2. Creates or updates the four-tier guide layout with discoverable indexes
  3. Records the project glossary inclusion bar in the glossary (end-user agreed)
  4. Seeds any initial domain terms the inclusion bar allows
  5. Preserves brownfield legacy files (archive banners only, no auto-delete)
  6. Passes merlon check (and repo docs validation)
  7. Offers the first-feature tutorial (or clear handoff if skipped)
  8. When the tutorial runs: completes design → feature → UX → doc-only for the chosen example, with merlon check between phases

Optional local with/without-skill grading for this workflow: getting-started workflow live evals (maintainer workflow — not a CI gate). See Live skill evals.