spacedock-dev/spacedock/commission

Commission a Plain Text Workflow

You are commissioning a plain text workflow. A plain text workflow is a directory of markdown files with YAML frontmatter, where each file is a work entity that moves through stages. The directory's README is the single source of truth for schema and stages, and the Spacedock plugin provides the plugin-shipped status viewer and plugin-shipped PR merge mod at runtime.

This is a v0 shuttle-mode workflow: an ensign agent handles all stages, with optional mods that inject behavior at lifecycle points (e.g., PR creation at merge time). You will walk {captain} through interactive design, generate all workflow files, then launch a pilot run.

Follow these three phases in order. Do not skip or combine phases.

Batch Mode

If the user provides design inputs in their message (some or all of: mission, entity type, stages, approval gates, seed entities, location):

1. Extract all provided inputs
2. For any missing inputs, infer reasonable defaults based on the mission
3. Skip directly to Confirm Design with the assembled inputs
4. If the user says to skip confirmation or auto-approve gates, proceed without asking

This allows non-interactive use: all inputs in one message, straight to generation.

Phase 1: Interactive Design

Before asking Question 1, greet {captain} with the following (skip this greeting entirely in batch mode):

Welcome to Spacedock! We're going to design a plain text workflow together.

I'll walk you through three phases:

1. Design — a few questions to shape the workflow

2. Generate — I'll create all the workflow files

3. Pilot run — I'll launch the workflow to process your seed entities

Throughout this workflow, you'll be addressed as {captain} (the workflow operator).

Let's start designing.

Args Extraction

If the user's invocation message contains text beyond the command name (e.g., /spacedock:commission product idea to simulated customer interview), treat that text as the mission statement.

• Extract {mission} from the args
• Proceed to Question 1 but present the extracted mission for confirmation

rather than asking from scratch:

> I'll use this as the workflow mission: "{extracted_mission}" > > What does each work item represent?

This skips the "what's this workflow for?" half of Q1 and goes straight to the entity-type follow-up.

Ask {captain} the remaining questions one at a time. Wait for each answer before asking the next question. Do not batch questions.

Question 1 — Mission + Entity

Ask:

What's this workflow for, and what does each work item represent?

Example: "Track design ideas through review stages" — the workflow is for tracking, each item is a design idea.

Extract {mission} and {entity_description} from the answer. If the answer clearly covers both mission and entity, proceed. If only the mission is clear, ask a brief follow-up:

Got it. What does each work item in this workflow represent? (e.g., "a design idea", "a bug report", "a candidate feature")

Derive the entity label from {entity_description}:

1. Strip leading articles ("a", "an", "the")
2. Take the last word (the head noun in English) — this is {entity_label} (lowercase, singular)
3. Derive {entity_label_plural} by appending "s" to {entity_label}
4. Derive {entity_type} as the full description (after stripping articles) in snake_case (e.g., "a design idea" → design_idea)

Examples:

• "a design idea" → label: idea, plural: ideas, type: design_idea
• "a bug report" → label: report, plural: reports, type: bug_report
• "an implementation task" → label: task, plural: tasks, type: implementation_task
• "a PR" → label: pr, plural: prs, type: pr

Trait Detection

Before Question 2 (Stages), apply trait detection to the mission text and the Q1 answers. The goal is to land the workflow on one of three captain-facing templates (or fall back to layer-assembly when no template fits cleanly), and to surface layer activations that drive scaffolding decisions and mod offers. Trait detection sits here because it needs Q1's mission and entity description as input, and because its output pre-fills the stage list Q2 then proposes.

Cue → captain-facing template

Cue → layer (independent of template)

Inference strategy: silent-with-confirmation, or explicit-ask

• Strong signal in mission text or Q1: infer silently and surface as a one-shot confirmation. Example: "This looks like a development workflow (you mentioned shipping code via PR). I'll use the development template, which sets up backlog → ideation → implementation → validation → done with worktrees on the build tiers and the pr-merge mod for the PR step. Sound right?"
• Ambiguous or no signal: ask explicitly. Example: "Is this workflow about (a) shipping code through review, (b) testing a hypothesis through tiers of evidence, or (c) iterating on an artifact until it is good enough? Or something else — describe and I will assemble the stages from the cues."

Apply the same strategy to layers: if the cue is strong, fold the layer activation (and any tied mod offer, framed per the template's Adoption section) into the template confirmation prose; if ambiguous, ask explicitly during Q2.

Template loading

Once the template is selected, `Read` the template file at references/templates/{template}.md (resolve relative to the commission skill directory). Then follow the template's `## Adoption` section directly — that section tells you what stages to pre-fill, what layers to fire, what mods to offer with what framing prose, what entity-template snippet to inject, what variants to surface, and what confirmation prose to show in Phase 1.

When a selected template's pre-fill declares context-sections, treat each selector and its matching named section as one generation unit: preserve the selector on every declaring stage and copy the complete section into the generated README. Never emit only one half. For the development template this atomically carries the implementation/validation Review-finding disposition selectors and the complete ## Review-finding disposition section.

The three templates available are refinement, development, and experiment — each at references/templates/{name}.md. The commission skill itself owns trait detection (this section), the Stage Naming Convention (Q2), the layer-assembly fallback (below), and the generic per-layer mod-framing reference (bottom of this file). Template-specific behavior — the development template's pr-merge stages-stay-clean framing, the experiment template's smoke/holdout teaching prose and silence-watcher offer, the refinement template's variant menu — lives in each template's Adoption section. Adding a fourth template later means dropping a new file in references/templates/ with an Adoption section, not editing this skill.

Generic mod offer mechanism

When a layer fires during trait detection and a corresponding mod exists, surface the offer as part of the Phase 1 confirmation. The framing prose comes from the selected template's Adoption section — the development template carries the pr-merge stages-stay-clean prose, the experiment template carries the silence-watcher prose. When no template was selected (layer-assembly fallback), use the generic per-layer framing from the Layer framing reference at the bottom of this file.

The Phase 2c y/n confirmations remain — that is the file-generation install step, separate from the Phase 1 design-time framing.

Layer-assembly fallback

When trait detection fires layer cues but no template matches cleanly (e.g., a mission that mixes repo-mutation with parked stages and does not look like development or experiment), do not force-fit a template. Instead:

1. Skip the template Read.
2. Use the Decomposed snippets reference at skills/commission/references/decomposed-snippets.md as the source list of base scaffolding + layer snippets.
3. Assemble the suggested stage list from base scaffolding plus the layer snippets the cues fired.
4. Use the generic per-layer framing from the Layer framing reference at the bottom of this file when surfacing mod offers.

The fallback exists so commission gracefully handles novel intents instead of pushing every workflow into one of three boxes.

Question 2 — Stages

If a template was selected during Trait Detection, use the template's Adoption-section pre-fill as the suggested stage list (with any layer-driven adjustments already applied per the template's framing). Otherwise (layer-assembly fallback), assemble the suggested list from the Decomposed snippets reference. Present the suggestion as an itemized list and ask {captain} to review:

Based on your workflow mission, here are the stages I'd suggest:

{for each stage: "1. {stage_name} — {one-line description}"}

Would you like to modify, add, or remove any stages? (confirm or describe changes)

Apply the Stage Naming Convention (below) when proposing the default list and when accepting captain edits. Push back gently if the captain proposes a name that violates the convention; show the convention rule and offer the corrected name.

Store the confirmed stages as {stages}. The first stage is {first_stage} and the last is {last_stage}.

Gate timing: An initial approval gate reviews the committed seed, not completed work assigned to that stage. No worker runs for that initial stage before seed approval. Approval advances to its successor. A later approval gate reviews its stage's completed, committed report and required artifacts.

Separate permission to start research from permission to build from research results. When both approvals are requested, propose a seed stage, a research stage, then the next work stage. Put seed approval on the initial stage and result approval on the research stage. Name the reviewed artifact and successor work for each approval. Do not describe seed approval as review of research that has not run. If the supplied stages conflict with these decisions, explain the conflict and propose the separated route during Confirm Design.

Stage Naming Convention

Stage names describe the bucket the entity is sitting in. The bucket can be activity-flavored (implementation, validation, analysis, draft, review) when the captain is actively working, or state-flavored (proposed, evaluated, sent, published, triaged, accepted) when the entity has reached a state of having been X-ed. Both pass the test "the entity is in {name}."

Avoid pleonasm: when the bucket already implies sitting/in-progress, do not prefix it with awaiting_, in_, pending_, or being_. The bucket itself is the verb-of-being. Examples to push back on: