---
name: support-system-guide
description: "Use when the user opens a fresh session, asks 'what should I run', 'where do I start', 'which command for X', 'is this a /feature or /greenfield', or describes intent without naming a command. Routes them to the right command (/feature, /greenfield, /bugfix, /parallel, etc.) and explains the phase model. Skip if the user has already invoked a specific command."
---

# Support: System Guide

## Overview

This skill governs how the forge system itself is used. It is the meta-skill that ensures skills are invoked when they apply, commands are chosen appropriately, and the `.forge/` working directory is managed properly.

**Core principle — deterministic skill loading.** Load a skill when **either** of these conditions is met:

1. **Match condition** — the user's task explicitly matches the skill's trigger phrases (the `description:` field in the skill's frontmatter). The match should be on the user's stated intent, not on a peripheral keyword.
2. **Required condition** — the active command (or active phase of an active command) names the skill in a `REQUIRED SUB-SKILL:` directive or a phase contract from `references/common/phases.md`.

Neither condition met → don't load the skill. Use the rules-only flow (auto-loaded common rules are sufficient for general guidance), or suggest `/triage` / `/discover` if the task doesn't fit any workflow. Do **not** load skills heuristically "just in case" — that biases toward over-invocation, pollutes context, and trains the system to fire on coincidence.

## Instruction Priority

forge skills override default system prompt behavior, but **user instructions always take precedence**:

1. **User's explicit instructions** (CLAUDE.md, direct requests) -- highest priority
2. **forge skills** -- override default system behavior where they conflict
3. **Default system prompt** -- lowest priority

If CLAUDE.md says "don't use TDD" and a skill says "always use TDD," follow the user's instructions. The user is in control.

## How to Access Skills and Agents

**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you -- follow it directly. Never use the Read tool on skill files.

### Dispatch Reference

When command or skill files use these directives, here is what they mean:

| Directive | Action |
|---|---|
| **REQUIRED SUB-SKILL: Use X** | You MUST call the `Skill` tool with `skill: "X"`. Do NOT act on the task without loading the skill first. |
| **Dispatch the X subagent** | You MUST call the `Agent` tool with `subagent_type: "forge:X"`. Do NOT perform the review yourself. |

**Why this matters:** Skills contain detailed process constraints (e.g., build-tdd has 500 lines of TDD discipline). The one-line summary in the command file is NOT a substitute. If you skip loading the skill, you will miss critical constraints and produce lower-quality output.

**Agent dispatch ownership:** Skills own their agents. Each skill that needs an agent dispatches it as part of its process. Commands chain skills — they do not manage agent dispatch directly. When a skill says "Dispatch the **X** subagent", that is a mandatory dispatch, not a suggestion.

**When dispatching agents:** Provide the task objective, scope, and success criteria in the prompt. Agents have file access and will explore the codebase for details — see `references/common/agent-coordination.md` for role-based handling (producers need review, reviewers don't).

## The Rule

Load a skill only when the **match condition** OR the **required condition** above is satisfied. Decision flow:

```
User message received
  |
  +-- Does message invoke a COMMAND (e.g. /feature, /bugfix)? --Yes--> Route to the command.
  |                                                                    The command names every
  |                                                                    REQUIRED SUB-SKILL inline
  |                                                                    (the "required condition").
  |
  +-- No command invocation
       |
       +-- Does the task explicitly match a skill's trigger phrases   ----Yes----> Load that skill.
       |   (frontmatter `description:`)?
       |
       +-- No match --> Respond using rules-only flow. If the task
                        doesn't fit any workflow, suggest `/triage`
                        or `/discover` instead of guessing a skill.
```

If you load a skill and it turns out to be a poor fit after reading it, abandon it — don't follow a wrong skill out of obligation. The match condition is a lookup, not a contract.

## Command Routing

When the user describes what they want to do, route them to the correct command. Commands orchestrate skills into end-to-end workflows.

| User Intent | Command | What It Does |
|---|---|---|
| "What does this project have?" / "Show me forge" / "What can I run?" | `/discover` | One-screen discovery — installed capabilities, active work, suggested next |
| "Capture this thought" / "Note this for later" / "Save this research" | `/note <text>` | Append to `aiwiki/raw/{date}.md` — for Phase 1-2 research, ad-hoc brainstorm, anything not yet a typed page |
| "Add a feature" / "Implement X" / "Build Y" | `/feature` | Lightweight by default: build -> tests -> review -> PR. Extended phases (concept / wireframe / prototype / codify) opt-in at preflight |
| "New project" / "Start from scratch" / "Greenfield" | `/greenfield` | Scaffold + full lifecycle for a new project |
| "Fix this bug" / "Something is broken" / "Error when..." | `/bugfix` | Debug -> fix -> test -> PR |
| "Clean up" / "Refactor" / "Improve code quality" | `/refactor` | Analyze -> refactor -> review -> PR |
| "Production is down" / "Emergency fix" / "Critical bug" | `/hotfix` | Emergency: debug -> fix -> test -> deploy (expedited gates) |
| "Improve the skills" / "Update a skill" / "System enhancement" | `/forge-evolve` | Self-improvement: review skills, propose changes, validate |
| "Check consistency" / "Validate skills" / "Run validator" | `/validate` | Validate all skills/rules for contradictions and gaps |
| Prompt does not fit any workflow above (research / monitoring / explanation / ad-hoc exploration / debug-without-fix / data pipeline / other) | `/triage` | Escape hatch: classify the work and offer rules-only, escalate-to-`/feature`-with-most-phases-skipped, or document-gap-for-`/forge-evolve` |

### Command vs. Direct Skill Use

- **Commands** are for workflows (multi-skill, gated sequences)
- **Direct skill invocation** is for single capabilities ("just review this code", "just generate a test plan")
- When in doubt, suggest the command -- it provides the full quality pipeline

## Skill Groups

Skills are organized by function using prefix groups. Understanding the groups helps identify which skills to invoke.

### Prototype-driven phases
The full prototype-driven path runs concept → wireframe → prototype → iterate → codify. These skills are the canonical path for new flows and unsettled designs; they are **opt-in for `/feature`** (the lightweight default skips them) and the default for `/greenfield`. The `discover-` and `plan-` groups below are non-prototype fallback for refactors and library work.

| Skill | When to Use |
|---|---|
| `concept-slides` | Phase 1 — produce low-fidelity marp concept deck (hook + sub-concepts + journey) |
| `build-wireframe` | Phase 2 — single-HTML annotated wireframe with click-through demos |
| `build-prototype` | Phase 3 — scaffold the prototype, stack selected per work item (`vite-react` default, or `nextjs` / `existing-repo` / `python-fastapi` / `cli` / `go-service` / `none`) |
| `iterate-prototype` | Phase 4 — polish loop on the prototype; small tweaks driven by `pocs/.../.forge/feedback.md` |
| `harden` | Phase 5 — codify the locked prototype into `aiwiki/architecture/`, ADRs, slice graph |

### discover- (Understand) — non-prototype fallback
Skills that gather and structure information about what needs to be built when the prototype-driven flow does not apply.

| Skill | When to Use |
|---|---|
| `discover-requirements` | User has raw input (notes, emails, screenshots) that needs structuring |
| `discover-codebase-analysis` | Working on existing code, need to understand what exists |

### plan- (Decide) — non-prototype fallback
Skills that determine how to approach the work when the prototype-driven flow does not apply.

| Skill | When to Use |
|---|---|
| `plan-brainstorm` | Need to decide HOW to approach a feature (design discussion) |
| `plan-architecture` | Need technical artifacts: API contracts, DB schema, diagrams |
| `plan-design-system` | Frontend feature needs visual direction (theme, colors, spacing, typography) |
| `plan-task-decompose` | Need to break work into implementable units |

### build- (Implement)
Skills that produce code and artifacts.

| Skill | When to Use |
|---|---|
| `build-scaffold` | New project needs directory structure, tooling, Docker setup |
| `build-tdd` | Writing code (strict RED-GREEN-REFACTOR) |
| `build-pr-workflow` | Need branches, worktrees, or pull requests |

### quality- (Verify)
Skills that verify work meets standards.

| Skill | When to Use |
|---|---|
| `quality-code-review` | Code needs review — orchestrates the safety → craft → reachability → gotcha-hunter chain |
| `quality-test-plan` | Need comprehensive test strategy (all test types) |
| `quality-test-execution` | Need to execute tests from the test plan |
| `quality-security-audit` | Need security review (OWASP, secrets, dependencies) |
| `quality-uiux` | Frontend work needs UX review |

### deliver- (Ship)
Skills that deliver work to users.

| Skill | When to Use |
|---|---|
| `deliver-deploy` | All tests pass, review done, ready to ship |
| `deliver-db-migration` | Feature needs database schema changes |
| `deliver-onboarding` | Need to create or update newcomer documentation |

### support- (Maintain)
Skills that maintain the system and handle problems.

| Skill | When to Use |
|---|---|
| `support-system-guide` | (This skill) How to use the system |
| `support-debug` | Something is broken, need systematic debugging |
| `support-dream` | Phase-close auto-fire — consolidate `aiwiki/` drafts (gotchas, conventions, raw notes) into proposed wiki updates for user review |
| `support-gotcha` | Lesson learned that should be recorded for prevention |
| `support-parallel` | User pasted a punch list (≥3 independent tasks) or invoked `/parallel` — classify, team-per-task, dispatch in parallel |
| `support-runtime-reachability` | Pre-merge gate that proves new code is actually wired in (CLI/route/import) — guards against the dead-code-passes-tests failure mode |
| `support-skill-validator` | Validate skills/rules for consistency |
| `support-wiki-bootstrap` | Scaffold `aiwiki/` (idempotently) before a command writes typed pages — used by `/feature`, `/greenfield`, etc. at preflight |
| `support-wiki-lint` | Validate an `aiwiki/` page against its schema (frontmatter, sections, line caps) and detect stale citation hashes — runs on every `aiwiki/**` write and surfaces findings for the next edit (PostToolUse hook can't reject the write itself) |

## Skill Priority

When multiple skills could apply, use this order:

1. **Process skills first** (support-debug, plan-brainstorm) -- these determine HOW to approach the task
2. **Implementation skills second** (build-tdd, quality-code-review) -- these guide execution

**Route by mode.** Detect repo state per `rules/common/skill-selection.md`:
- Prototype mode (`.claude/CLAUDE.md`'s `project.mode: prototype` OR `greenfield`, OR work-item path under `pocs/`, OR manifest declares `phase_plan.prototype: active` + `phase_plan.codify: skipped`): use `iterate-prototype` for tweaks; do NOT load `plan-brainstorm` or `build-tdd`.
- Production mode (`project.mode: production`, OR manifest declares `phase_plan.codify: active` + `phase_plan.production-build: active`): use `build-tdd` for code changes; `plan-*` skills are non-prototype fallback only.

Examples:
- "Fix this bug" -> `support-debug` first, then domain-specific skills
- "Deploy this" -> `deliver-deploy` (which checks gates from earlier skills)

## Skill Types

**Rigid skills** (build-tdd, support-debug): Follow exactly. Do not adapt away the discipline. These skills exist because shortcuts cause failures.

**Flexible skills** (deliver-onboarding, quality-uiux): Adapt principles to context. The output format and depth should match the project.

The skill itself indicates which type it is by its language. "MUST" and "NEVER" indicate rigid. "Consider" and "adapt" indicate flexible.

## .forge/ Directory Management

### Auto-Creation

When starting any work item (via `/feature`, `/bugfix`, etc.), auto-create the directory structure:

```
.forge/
  work/
    {type}/                    # feature | bugfix | refactor | hotfix | greenfield
      {name}/
        manifest.yaml          -> Initialize from .claude/templates/manifests/{type}.yaml
        requirements.md        -> Populated by discover-requirements (where applicable)
        architecture/          -> Populated by plan-architecture (where applicable)
        tasks.md               -> Populated by plan-task-decompose (where applicable)
        test-plan.md           -> Populated by quality-test-plan (where applicable)
        test-results.md        -> Populated by quality-test-execution (where applicable)
```

**Note on architecture/ and decisions/ placement:** The `architecture/` directory under `.forge/work/{type}/{name}/` is a working draft used by the non-prototype fallback flow. In the prototype-driven flow, final architecture pages land in `aiwiki/architecture/` (written by `harden`). Decisions (ADRs) ALWAYS land in `aiwiki/decisions/`; the `.forge/work/.../decisions/` directory is retired.

### Manifest Initialization

```yaml
schema_version: "6"
name: "{name}"
type: "{type}"  # feature | bugfix | refactor | hotfix | greenfield
description: "{what this work is for}"
status: in-progress  # in-progress | paused | completed | escalated
created: "{YYYY-MM-DD}"
command: "{command}"  # the slash command that created this manifest, e.g. "feature"
phase_plan:        # Plan-status per workflow milestone; set at preflight.
  concept: active  # active | active-light | active-commit-only | skipped | as-discovered | complete-inline
  wireframe: active
  prototype: active
  iterate: active
  codify: active
  production-build: active
  deliver: active
phases:            # Gate state per phase; mutated by skills during execution.
  # Shape per work type — see templates/manifests/{type}.yaml.
```

Phase names in `phase_plan` are canonical per `.claude/references/common/phases.md`; full schema in `.claude/templates/manifests/v6/SCHEMA.md`. Phases are defaults, not requirements — set `phase_plan.{phase}: skipped` (or any other plan-status) at preflight to capture deviations.

### Document Versioning

When a skill updates an artifact in `.forge/`:

1. If the artifact has been approved by the user, do NOT overwrite it silently
2. If rework is needed, create a new version: `architecture-v2/` or note the revision in the file
3. The manifest tracks which version is current
4. Never delete previous versions -- they provide audit trail

### Directory Hygiene

- `.forge/` should be in `.gitignore` (working files, not source)
- Exception: `manifest.yaml` may be committed for team visibility (project preference)
- Gotchas live in `aiwiki/gotchas/` per the aiwiki typed-page model, see `aiwiki/CLAUDE.md`
- Clean up completed feature directories only when user explicitly requests it

## When You Have Loaded a Skill — Follow It

Once a skill is loaded (because the match or required condition fired), don't substitute judgment for the loaded process. These thoughts mean you are about to drift away from a skill that legitimately applies:

| Thought | Reality |
|---|---|
| "I remember this skill" | Skills evolve. Use the loaded version, not your memory of it. |
| "The skill is overkill" | If you loaded it via the match or required condition, follow it. If it truly does not apply on read, abandon it explicitly — don't half-follow. |
| "I'll just do this one thing first" | Whatever the loaded skill instructs comes first. Side trips break the process. |
| "I know what that means" | Knowing the concept is not the same as following the loaded steps. |

These thoughts are NOT red flags — they are the deterministic rule working correctly:

- "No skill matches this task" → respond with rules-only flow. Skills are not the only way to do work.
- "This is just a simple question" → answering directly is fine if the task doesn't match a skill trigger.
- "I can check git/files quickly to answer this" → read-only exploration to answer a user question doesn't need a skill unless the task triggers `support-debug`, `discover-codebase-analysis`, etc.

## User Instructions

User instructions say WHAT to do, not HOW to do it. "Add X" or "Fix Y" does not mean skip the skill workflow.

- "Add a payment feature" -> still use `/feature` (discover -> plan -> build -> quality -> deliver)
- "Fix the login bug" -> still use `support-debug` (four-phase process)
- "Deploy to production" -> still use `deliver-deploy` (full pipeline)

The only exception is when the user **explicitly** says to skip a skill or step: "Skip brainstorming, just implement it." Even then, note what was skipped in the manifest.

## Session Start Behavior

When a new session begins:

1. **Check for in-progress work**
   - Walk `.forge/work/*/` for any manifests with `status: in-progress` or `status: paused`
   - Skip `status: completed` and `status: escalated` items — they are terminal states
   - If found, summarize: "You have in-progress work: {type}/{name}, currently in {phase}. Want to continue?"
   - When multiple in-progress items exist, use `{type}/{name}` as the canonical identifier (names can collide across types)

2. **Lightweight validation**
   - Run `support-skill-validator` quick check (I/O graph only)
   - Report any issues found

3. **Check for recent gotchas**
   - Read `aiwiki/gotchas/` for entries relevant to current work (and `~/.claude/gotchas/` for global entries)
   - If a gotcha's frontmatter has a `proposed_rule:` block, surface it as a hard-interrupt per `support-gotcha` Step 6

## I/O Contract

| Field | Value |
|---|---|
| **Requires** | -- (meta-skill, always available) |
| **Produces** | Guidance, `.forge/` directory structure, command routing |
| **Feeds into** | All other skills (by ensuring they are invoked correctly) |

## Quick Reference

| Situation | Action |
|---|---|
| User wants to build something | Route to `/feature` or `/greenfield` |
| Something is broken | Route to `/bugfix` or invoke `support-debug` |
| Code needs review | Invoke `quality-code-review` |
| Ready to deploy | Invoke `deliver-deploy` |
| New session, existing feature | Resume from last phase in manifest |
| Not sure which skill | Check this guide's Skill Groups table |
| User says "skip X" | Note in manifest, proceed without that step |
| Thought: "skill is overkill" | STOP. Invoke the skill. |