commission

Files (5)

• SKILL.md
• decomposed-snippets.md · references/
• development.md · references/templates/
• experiment.md · references/templates/
• refinement.md · references/templates/

SKILL.md (first lines)

# 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 in mission text or Q1 answers | Lands on |
|---|---|
| "implement / build / ship / PR / merge / feature / refactor / land code" | `development` |
| "hypothesis / experiment / test / learn / accept / promote / tier / probation / A/B / eval" | `experiment` |
| "track / iterate / draft / refine / publish / send / outreach / lead / contact / sync / ingest" — or no strong signal | `refinement` |
| Within `refinement`: "contact / lead / send / followup", "ingest / sync / external", "publish / blog / article", "PRD / RFC / design doc" | refinement + suggest the matching variant from the refinement template's Adoption section |

#### Cue → layer (independent of template)

| Cue | Layer fires |
|---|---|
| Any stage modifies the repo (write code, edit files, generate artifacts in-tree) | repo-mutation layer (worktree on those stages; pr-merge mod offered if shipping ritual is PR review) |
| Any stage waits on external response, evidence accumulation, or time passing | parked-stages layer (parked flag on the waiting stages; silence-watcher idle-mod offered if timeout/nudge semantics apply) |

#### 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.

From spacedock-dev/spacedock, Apache-2.0.

More from spacedock-dev/spacedock