speclan-engineering:hlrd-authoring

What this skill does

# HLRD Authoring Pipeline

Transform an unstructured High-Level Requirements Document (HLRD) into a structured SPECLAN specification hierarchy through an interactive, multi-phase pipeline.

This skill is a faithful adaptation of the VSCode `hlrd-wizard` ([`apps/vscode-extension/src/services/hlrd-agent.service.ts`](https://github.com/digital-dividend/speclan)) for Claude Code — replacing MCP tool calls with native file operations (Read/Write/Edit/Glob/Grep) and replacing the webview multi-choice UI with `AskUserQuestion` prompts.

## Pipeline at a glance

```
Preflight       → Input resolution, speclan detection, entry point, complexity
Phase 0         → Vision & Mission  (speclan/vision.md, speclan/mission.md)
Phase 1         → Planning          (Goals + Features plan, with clarifications)
Phase 2         → Entity Creation   (Goals → Features, create & modify)
Phase 2.5       → Requirements      (per feature, testable + traceable)
Phase 3         → Cross-Referencing (inline markdown links + goal contributions)
Summary         → Report what was created / modified / failed
```

Each phase is described in full below. Details that would otherwise bloat this file live in the `references/` directory — consult them when running the corresponding phase.

## Prerequisites

Before running any phase, verify the environment:

1. **speclan plugin must be loaded.** Look for the `speclan-format`, `speclan-id-generator`, and `speclan-query` skills in the available skills list. If any are missing, stop and tell the user to install the `speclan` plugin (this skill reuses them rather than duplicating their logic).

2. **`speclan/` directory.** Detect it by looking for `speclan/goals/` or `speclan/features/` under `$CLAUDE_PROJECT_DIR`. If none is found, ask the user via AskUserQuestion:
   - `Create speclan/ now (goals/, features/, templates/)` — proceed and `mkdir -p` the structure
   - `Use a different path` — ask for the path in a follow-up
   - `Cancel` — stop the pipeline

3. **Never** run this pipeline against a speclan directory that contains only `released`, `in-development`, `under-test`, or `deprecated` entities unless the user is operating in create-only mode. These statuses are locked and require Change Requests rather than direct edits — the `speclan-format` skill has the full lifecycle rules.

## Preflight

### Step 1 — Resolve HLRD content

The command passes `$ARGUMENTS` verbatim. Auto-detect the input form:

- **Path**: if the argument ends in `.md`, `.txt`, `.markdown`, or is an existing file path under the project, Read it. Treat the file as read-only (never modify the HLRD source).
- **Inline text**: if the argument is non-empty text that isn't a path (contains spaces or newlines, or no existing file matches), treat it as inline HLRD content.
- **Empty**: use AskUserQuestion to ask the user how they want to provide the HLRD. Offer: `Provide a file path`, `Paste inline content`. On "file path", ask for the path in a follow-up. On "paste inline", tell the user to reply with the full HLRD text in their next message, then continue the pipeline once they do.
- **Path given but missing**: AskUserQuestion reporting the missing file and asking for a corrected path.

Compute the word count of the resolved content — you need it for Step 4.

### Step 2 — Confirm the speclan directory

Having detected the `speclan/` location in the prerequisites, remember its absolute path. Every subsequent file operation uses paths relative to this root.

### Step 2.5 — Resolve the owner value

Every spec this pipeline creates or modifies gets its `owner` frontmatter field set to the current git user email, resolved once and cached in pipeline state. Follow the **Owner field resolution** procedure in `references/entity-content.md` — primary: `git config user.email`, fallback: `git config --global user.email`, finally `AskUserQuestion`. Store the result as `owner_value` and reuse it for every entity created in this run.

Report the resolved owner to the user in the initial status message: *"Running HLRD import as owner: `<owner_value>`"*, so they know what will be stamped on every produced spec.

### Step 3 — Entry point

Use AskUserQuestion to ask where the import should land:

- `Import at project root` — new top-level goals/features
- `Nest under an existing feature` — imports a subtree; requires picking a parent feature

If the user picks "Nest under an existing feature", list candidate features. Delegate to the `speclan-query` skill to enumerate features by status (prefer `draft` / `review` / `approved`, skip locked statuses). If `speclan-query` is unavailable, fall back to `Glob` `speclan/features/**/F-*.md` and Read each file's frontmatter for its `title` and `status`.

`AskUserQuestion` supports up to 4 options per question. If there are more than 4 candidates, present them in pages of 4 with an explicit "Show more candidates" option on each page until the user picks one or explicitly cancels.

Record the decision as:
- `{ mode: 'root' }` — top-level import
- `{ mode: 'subtree', parentFeatureId: 'F-####', parentFeatureTitle: '...' }` — subtree import

### Step 4 — Complexity recommendation

Compute the recommended complexity level from the word count using `references/complexity-levels.md` (word-count → level index → feature range). Then use AskUserQuestion to confirm, presenting all five options with the recommendation marked. Read `references/complexity-levels.md` now if you haven't yet — it has the exact thresholds, feature ranges, and the guidance text to inject into the planning prompt.

Store the chosen level index; subsequent phases use it to shape the plan.

## Phase 0 — Vision & Mission

**Goal:** Create or update `speclan/vision.md` and `speclan/mission.md` based on the HLRD, so the project has a strategic foundation before feature planning begins.

This phase always runs — even for subtree imports — because the AI is instructed to leave a file "unchanged" when the existing content is already comprehensive, so the cost of running it when it's unnecessary is minimal. Refusing to run it, by contrast, would silently skip a chance to align the project's north star with the newly imported scope.

**Read `references/vision-mission.md` now.** It contains the full extraction procedure, the aspirational-vs-operational tone rules, word counts, anti-implementation guardrails, and the create/update/unchanged decision logic.

After the phase completes, report to the user: `Vision {created|updated|unchanged}, Mission {created|updated|unchanged}`.

## Phase 1 — Planning

**Goal:** Produce a lightweight plan of Goals and Features to create or modify — NOT full entity content, and NOT requirements (those come in Phase 2.5).

### Step 1 — Explore existing specs

Before producing a plan, explore what already exists so the plan can reference existing entities instead of duplicating them:

1. `Glob` `speclan/goals/G-*.md` and Read each file's frontmatter (`id`, `title`, `status`).
2. `Glob` `speclan/features/**/F-*.md` and build a lightweight in-memory feature tree (id, title, parent-id inferred from directory nesting, status).
3. `Grep` the HLRD's key domain nouns across `speclan/` to find semantically related entities.
4. If a `speclan-query` skill call gives you richer filtering, prefer it.

### Step 2 — Draft the plan

Produce an internal plan listing each proposed entity with these fields:

- `type`: `goal` or `feature`
- `action`: `create` or `modify` or `reference` (`reference` means the HLRD item maps to an existing entity — record it but take no action this phase)
- `title`: 3–6 words for goals, capability name for features
- `summary`: 1–2 sentences describing what this entity covers
- `existingId`: required for `modify` and `reference`
- `parentHint`: for features — the parent feature title/ID or `null` for root (subtree imports default the parent to the selected entry-point feature)
- `isLeaf`: features only — whether this feature will have child features beneath it