steering-specs-generator

What this skill does

# Steering Specs Generator

Conducts context-aware interviews to extract tacit engineering knowledge and generate agent-readable steerings. Format: **Intent (Why) → Rules (What) → Practices (How) → Meta**.

Supports **predefined packs** (8 areas) and **custom topics** (user-specified).

**Flow overview:** See [flow-diagram.md](flow-diagram.md) for visual representation.

## Prerequisites

- [pack-reference.md](pack-reference.md) — Topic areas and questions
- [steering-template.md](steering-template.md) — Output format
- Access to an "ask user" tool and a "run subagent task" tool

## Tooling Compatibility (Claude Code ↔ Codex CLI)

This skill was originally authored for **Claude Code** tool names (e.g. `AskUserQuestion`, `Task`). To keep it portable, treat these as *capabilities* and map them to your runtime:

- **Ask user (blocking input)**
  - Claude Code: `AskUserQuestion`
  - Codex CLI: `request_user_input`
  - If choice options aren't supported by your tool, present choices in text and ask for an index/label.
- **Run subagents / parallel work**
  - Claude Code: `Task` (+ its output/wait mechanism)
  - Codex CLI: `spawn_agent` + `wait` (+ optionally `send_input` to clarify) + `close_agent` when done
- **Repo scanning / file IO**
  - Claude Code: `Read` / `Write` / `Glob`
  - Codex CLI: `exec_command` for search/listing, `apply_patch` for edits (or your runtime’s native file tools)

In the rest of this doc:
- `ASK_USER(...)` means "use your environment’s ask-user tool".
- "Task agent" means "spawn a subagent and wait for its output".

## Mode Selection

| Keywords | Mode |
|----------|------|
| "review steerings", "transform steerings", "fix format" | → Review Mode (Step R) |
| "continue steerings", "continue session", "resume interview" | → Interview Mode (Step 0) with session check |
| "steerings", "tacit knowledge", "interview", "conventions" | → Interview Mode (Step 0) |

---

## Interview Flow

### Step 0: Check for Existing Sessions

Before configuring paths, check if sessions already exist in the repo:

1. **Scan common session directories:**
   - `.sessions/`
   - `sessions/`
   - `docs/sessions/`

2. **If sessions found**, present `ASK_USER(...)`:
```yaml
questions:
  - question: "Found existing session(s). Continue or start fresh?"
    header: "Session"
    options:
      - label: "Continue {sessionId}"
        description: "Resume incomplete session ({N} of {M} packs done)"
      - label: "Start new session"
        description: "Create fresh session with new ID"
```

3. **If continuing existing session:**
   - Set `sessionsPath` to parent directory of found session
   - Set `sessionId` to selected session name
   - Scan `{sessionsPath}{sessionId}/` for completed pack files
   - **Completed pack detection:** A pack is complete if:
     - File `{packId}.md` exists AND
     - Contains `## Interview` section with at least one `### Q` entry
   - Store `completedPacks[]` list (pack IDs to skip)
   - Read `explore-docs-conventions.md` and `explore-repo-context.md` paths if they exist
   - Skip to Step 3 (Pack Interview Loop), filtering out completed packs

4. **If starting new or no sessions found** → Continue to Step 0a

### Step 0a: Configure Output Paths

Ask user to confirm paths using `ASK_USER(...)`:

```yaml
questions:
  - question: "Where should steering files be saved?"
    header: "Steerings"
    options: ["./steerings/", "docs/steerings/", ".memory-bank/steerings/", "Custom"]
  - question: "Where should session files be saved?"
    header: "Sessions"
    options: ["./sessions/", ".sessions/", "docs/sessions/", "Custom"]
  - question: "Where should action items be saved?"
    header: "Backlog"
    options: ["./backlog/", "Same as steerings parent", ".backlog/", "Custom"]
```


**Store:** `steeringsPath`, `sessionsPath`, `backlogPath`. Create directories if needed.

**Defaults:** `steerings/`, `sessions/`, `backlog/`

### Step 0b: Generate `sessionId` - short words id

### Step 1: Define Topics

**Custom topic detected** (patterns: "steerings for X", "document X conventions"):
- If clear → Generate `packId`, `packName`, `packType: "custom"`, `customTopicDescription`
- If broad → Clarify with `ASK_USER(...)` (aspects, level, scope)

**No custom topic** → Present 8 predefined packs as multi-select:

### Step 1a: Choose Interview Mode

Ask user to select interview mode using `ASK_USER(...)`:

```yaml
questions:
  - question: "Interview mode preference?"
    header: "Mode"
    options:
      - label: "Interactive (default)"
        description: "Answer questions one-by-one with discussion"
      - label: "Fast mode"
        description: "Answer all questions at once, faster execution"
```

**Store:** `interviewMode` ("interactive" or "fast")

| Pack | ID |
|------|----|
| Codebase Topology & Ownership | `codebase-topology-ownership` |
| Architecture & Design Invariants | `architecture-design-invariants` |
| Business Domain Contracts | `business-domain-contracts` |
| Quality & Style Assurance | `quality-style-assurance` |
| Testing & Verification Strategy | `testing-verification-strategy` |
| Risk & Historical Landmines | `risk-historical-landmines` |
| Security, Data & Compliance | `security-data-compliance` |
| Delivery Lifecycle & Change Flow | `delivery-lifecycle-change-flow` |

### Step 2: Discovery (Parallel Explore)

Run TWO Explore agents in parallel. Each writes report to `{sessionsPath}{sessionId}` and returns path.

**Explore #1 - Docs & Conventions:**
```
Analyze repository for: steering files, CONVENTIONS.md, ARCHITECTURE.md,
CLAUDE.md, README conventions, eslint/prettier/tsconfig.

OUTPUT: Write to `{sessionsPath}{sessionId}/explore-docs-conventions.md`, return path.
```

**Explore #2 - Repo Context:**
```
Analyze: project purpose, tech stack, directory structure, main modules, patterns.

OUTPUT: Write to `{sessionsPath}{sessionId}/explore-repo-context.md`, return path.
```

**Capture paths:** `docsConventionsReportPath`, `repoContextReportPath`

### Step 3: Pack Interview Loop

**Filter packs:** If `completedPacks[]` exists (from session continuation), exclude those pack IDs from processing.

**Show progress when continuing:**
```
Continuing session: {sessionId}
✅ Completed: {completedPacks.join(', ')}
⏳ Remaining: {remainingPacks.join(', ')}
```

**When running packs in parallel:**
- Launch all pack agents as background tasks
- Capture all task IDs
- Wait for all to complete (Claude: Task output/wait; Codex: `wait`)
- Display progress as packs finish

Spawn a **Task agent per pack** - run all in parallel for faster execution.
Claude Code: use `run_in_background: true` for each `Task` call, then wait for all to complete.

Codex CLI: `spawn_agent` for each pack, capture agent IDs, then `wait` for completion (optionally streaming progress as each finishes).

```yaml
subagent_type: "general-purpose"
description: "Interview for {packName}"
prompt: |
  Conduct interview for a single pack and save results.

  ## Pack Info
  - Pack ID: {packId}
  - Pack Name: {packName}
  - Pack Type: {packType}  # "predefined" or "custom"
  - Custom Description: {customTopicDescription}  # only if custom

  ## Context Files
  - Pack Reference: pack-reference.md
  - Repo Context: {repoContextReportPath}
  - Docs & Conventions: {docsConventionsReportPath}

  ## Output
  - Path: {sessionsPath}{sessionId}/{packId}.md

  ## Instructions

  ### 1. Read Context
  Read pack-reference.md to get question themes for this pack.

  Read repoContextReportPath and docsConventionsReportPath for grounding.
  These reports contain ALL necessary findings - do NOT run additional explores.

  ### 2. Generate Questions
  Question count:
  - Predefined: 5
  - Custom (narrow): 3-4
  - Custom (medium): 5
  - Custom (broad): 6-7

  Guidelines:
  - Ground ONLY in the provided explore reports + existing docs
  - Reference actual code: "I see X in Y file..." (from reports)
  - Ask about conventions, not roadmap
  - Offer 4 options (A/B/C/D)
  - Mark one as "⭐ Recommended"