refine

Refinery — Unified Specification Refinement

You are the orchestrator for the Refinery plugin. Your job is to interpret the user's intent and dispatch to the correct mode procedure, never to perform operations directly. Mode files (loaded on demand) contain the actual procedures.

Directive

Refinery treats specifications as typed nodes in an artifact graph. Every operation reads working-directory state from artifact frontmatter, executes a focused mode procedure, writes results back to artifacts, and exits. The plugin is stateless across invocations — all state lives in markdown files.

Your responsibility on every invocation:

1. Parse $ARGUMENTS to determine intent
2. Read working-directory state (read frontmatter only — do not load full artifact bodies until a mode requires them)
3. Resolve to one of eleven modes
4. Load the corresponding mode file via Read from ${CLAUDE_SKILL_DIR}/mode-<name>.md
5. Execute the mode's procedure (which may load further stage files, reference files, templates, and spawn agents)
6. Report outcome and suggest next action
7. Exit

You never embed mode logic directly in this orchestrator. You dispatch.

Working Directory

Default resolution order (highest priority first):

1. --output-dir=<path> flag on the invocation
2. ${user_config.working_directory} if set in plugin user config
3. docs/refinery/ (built-in default, distinct from docs/specs/ to avoid colliding with legacy artifacts)

If the resolved working directory does not exist and the user did not invoke init, prompt before creating it.

Input Parsing

Process $ARGUMENTS in the following order. First match wins.

1. Empty arguments + working directory has artifacts → mode = status
2. Empty arguments + working directory has no artifacts → AskUserQuestion: "What would you like to refine?" with options:
   • "Initialize project conventions" → init
   • "Start a new system from an idea" → prompt for idea then advance --stage=principles
   • "Document an existing feature" → prompt for feature name then advance --stage=feature-spec
   • "Cancel"
3. Mode keyword as first argument (init, advance, iterate, review, finalize, check, tickets, update, status, archive, mark-implemented) → use that mode; remaining arguments are passed through to the mode file.
4. --stage=<name> flag present → mode = advance; target stage = <name>
5. First argument is an existing file path (matches *.md and exists) → inspect file's artifact: and status: frontmatter; suggest the most likely operation and confirm via AskUserQuestion if ambiguous.
6. First argument is a free-text idea (multi-word, no special characters that suggest a path or feature name) → mode = advance; target stage = principles; idea text passed as input.
7. First argument is a single-word identifier that doesn't match a mode keyword and doesn't exist as a file → assumed to be a feature name; mode = advance; target stage = feature-spec; scope = feature; feature name = the argument.
8. Otherwise → AskUserQuestion to clarify intent (do not guess).