steering-specs-generator

# 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" at end of description Pattern: Q: I found {finding}. How should {convention question}? A) {Option} — {rationale} B) {Option} — {rationale} ⭐ Recommended C) {Option} — {rationale} D) {Option} — {rationale} ### 3. Conduct Interview If interviewMode is "fast": - Present all questions in a single markdown code block - User responds with all answers at once (e.g., "A, B, A, C, B") If interviewMode is "interactive": - Present via `ASK_USER(...)` (max 4 questions per call if your runtime supports batching) ### 4. Classify Responses For each response, classify as: - CONVENTION: Timeless, future-focused ("When implementing X, do Y") - ACTION_ITEM: Temporal, fixes current state ("Replace X", "Fix X") ### 5. Extract and Save Results Extract rules immediately (not full Q&A) and write to {sessionsPath}{sessionId}/{packId}.md: - CONVENTION items → "## Conventions" section - ACTION_ITEM items → "## Action Items" section with severity - Optionally preserve raw Q&A in collapsed "## Raw Interview" section ``` **Session structure:** ``` {sessionsPath} └── {sessionId}/ ├── codebase-topology-ownership.md ├── architecture-design-invariants.md ├── {custom-pack-id}.md └── ... ``` **Pack file format:** ```markdown # {Pack Name} **Pack ID:** {id} ## Conventions - Q1: {extracted rule} - Q2: {extracted rule} ## Action Items - Q3: {action item with severity} ## Raw Interview (optional, for reference) Preserve Q&A in collapsed detail if needed for debugging. ``` ### Step 4: Await Pack Interviews Wait for all pack interview agents to complete. Each writes its results to `{sessionsPath}{sessionId}/{packId}.md` with classifications already included. **Note:** Pack agents use existing explore reports - no additional explores are run. ### Step 5: Generate Outputs Delegate to general-purpose subagent (use the strongest available model in your runtime): ```yaml subagent_type: "general-purpose" description: "Generate steerings and action items" prompt: | Generate steerings AND action items from interview sessions. Session directory: {sessionsPath}{sessionId}/ (contains one .md file per pack with classifications) Docs report: {docsConventionsReportPath} Repo report: {repoContextReportPath} Template: steering-template.md Output paths: {steeringsPath}, {backlogPath} Instructions: 1. Read all pack files from session directory 2. Extract CONVENTION items → generate steering files 3. Extract ACTION_ITEM items → generate backlog file 4. Generate index.md for steerings ``` **Steering filenames:** | Pack ID | Filename | |---------|----------| | codebase-topology-ownership | code-ownership.md | | architecture-design-invariants | architecture-invariants.md | | business-domain-contracts | domain-invariants.md | | quality-style-assurance | quality-and-style.md | | testing-verification-strategy | testing-strategy.md | | risk-historical-landmines | risk-registry.md | | security-data-compliance | security-and-compliance.md | | delivery-lifecycle-change-flow | delivery-lifecycle.md | | {custom-pack-id} | {custom-pack-id}.md | **Rule style:** - ✅ "When implementing X, do Y" / "Use X for Y" / "New features require X" - ❌ "Proactively refactor X" / "Continue using X" / "Add X to existing code" **Action items file:** `{backlogPath}steering-specs-action-items.md` Severity: 🔴 CRITICAL (data loss, security) → 🟡 HIGH → 🟢 MEDIUM → 🔵 LOW → ⏸️ DEFERRED ### Step 6: Present Results ``` Generated steerings: - {steeringsPath}*.md (N rules, M practices each) - {steeringsPath}index.md Action Items: {backlogPath}steering-specs-action-items.md - 🔴 Critical: N | 🟡 High: N | 🟢 Medium: N Session: {sessionsPath}{sessionId}/ - {packId-1}.md - {packId-2}.md - ... ``` --- ## Review Mode (Step R) Transform existing steerings to standard format. ### R1: Locate Steerings Auto-detect or ask: `steerings/`, `docs/steerings/`, `.steerings/` ### R2: Analyze with Explore ```yaml subagent_type: "Explore" prompt: | Analyze steering files in {steeringsPath}: - Structure: Intent → Rules → Practices → Meta? - Rules: numbered, prescriptive, no metadata? - Code examples: 5-15 lines? - File size: <200 lines? Report compliant vs non-compliant files with specific issues. ``` ### R3: Present Summary ``` ✅ Compliant: file1.md, file2.md ⚠️ Need transformation: - file3.md: Missing Intent, verbose rules - file4.md: Code examples too long