refine

What this skill does

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

## Mode Dispatch

Once mode is resolved, load its procedure file via the `Read` tool:

| Mode | File |
|------|------|
| init | `${CLAUDE_SKILL_DIR}/mode-init.md` |
| advance | `${CLAUDE_SKILL_DIR}/mode-advance.md` |
| iterate | `${CLAUDE_SKILL_DIR}/mode-iterate.md` |
| review | `${CLAUDE_SKILL_DIR}/mode-review.md` |
| finalize | `${CLAUDE_SKILL_DIR}/mode-finalize.md` |
| check | `${CLAUDE_SKILL_DIR}/mode-check.md` |
| tickets | `${CLAUDE_SKILL_DIR}/mode-tickets.md` |
| update | `${CLAUDE_SKILL_DIR}/mode-update.md` |
| status | **inline fast-path below** (only loads `${CLAUDE_SKILL_DIR}/mode-status.md` when `--verbose` is set) |
| archive | `${CLAUDE_SKILL_DIR}/mode-archive.md` |
| mark-implemented | `${CLAUDE_SKILL_DIR}/mode-mark-implemented.md` |

Mode files are **procedural instructions, not skills.** Use `Read` (not `Skill`) to load them. Skills are reserved for invocable capabilities like the preloaded `specification-writing` reference (loaded by the spec-writer agent).

After reading the mode file, follow its procedure to completion. The mode file may load further stage files, reference files, templates, and spawn specialist agents — do so on demand.

### Fast-Path: `status` (default, terse)

`status` is read-only (FR-040), produces no file changes, and is the most frequently invoked mode. The orchestrator runs a compressed in-line procedure for the default case to avoid the full ~110-line `mode-status.md` load. Only load `mode-status.md` when the user passes `--verbose`.

**Procedure:**

1. Scan working directory per §"State Detection" above (frontmatter-only reads).
2. If working directory does not exist → print `no working directory; run /refine init` and exit.
3. Build the artifact graph: for each `*.md` file with an `artifact:` field, record `{path, artifact_type, scope, status, iteration, parent, children, last_updated, convergence}`. Skip pointer files (`pointer: true`) and non-Refinery files.
4. Apply the suggested-next-action priority order in `${CLAUDE_SKILL_DIR}/references/state-detection.md §4` to pick the top 1–3 suggestions.
5. Print a compact report (symbols: `✓` finalized/implemented, `⚠` draft/iterating/reviewed/drifted/stale, `✗` missing, `■` archived/superseded):

   ```
   REFINERY STATUS
   ===============
   Working directory: <path>
   Artifacts: <N> total (<breakdown by type>)

   Pipeline:
     Stage 1: principles    [<sym> <status>]    <path>
     ... (one line per expected stage; show `[✗ missing]` for absent stages)

   Features:
     <feature>              [<sym> <status>]    <path>
     ... (one line per feature-spec; indent nested sub-features with `└─`)

   Drift:         (section omitted if no drifted artifacts)
     <artifact>             <last-check summary>

   Open Work:     (section omitted if no open questions)
     <artifact>             <N open questions, high_confidence_ratio: <R>>

   Suggested next:
     <1-3 suggestions from step 4>
   ```

6. Exit. **No file changes.** No agents spawned. No further stage/reference files loaded.

**When to fall back to full `mode-status.md`:** if `--verbose` is set, the inline fast-path is skipped entirely; load and follow `${CLAUDE_SKILL_DIR}/mode-status.md` instead (adds per-artifact convergence metrics, time-since-update, validation warnings, nested hierarchy trees, and priority-rule tracing).

If the fast-path hits a validation error it cannot express compactly (e.g., malformed frontmatter that prevents building the graph), escalate to the full mode by reading `${CLAUDE_SKILL_DIR}/mode-status.md` and continuing from its Phase 1.

## State Detection

Before any non-`init` operation, scan the working directory:

```
Glob: <working-dir>/**/*.md
For each file:
  Read frontmatter (first YAML block between --- markers)
  If "artifact:" field is present:
    Record path, artifact type, scope, status, iteration, parent, children, last_updated, convergence
  Else:
    Skip (not a Refinery artifact)
```

This produces an artifact graph used by all modes. If the working directory does not exist, treat as empty.

For the full state-detection algorithm (validation rules, needs-attention flags, graph integrity checks), see `${CLAUDE_SKILL_DIR}/references/state-detection.md`.

## Universal Conventions

These conventions apply to every operation. Mode files **reference** but do not override them.

- **Document format:** Every artifact uses the universal frontmatter and trailing sections defined in `${CLAUDE_SKILL_DIR}/references/document-format.md`.
- **Requirement syntax:** EARS for functional requirements, Given/When/Then for acceptance criteria, RFC 2119 for system specs. Per `${CLAUDE_SKILL_DIR}/references/requirement-syntax.md`.
- **Convergence metrics:** Per `${CLAUDE_SKILL_DIR}/references/convergence.md`.
- **Agent handoffs:** Specialist agents exchange structured YAML han