How to Run

Generate or update a HOW-TO-RUN.md at the project (or workspace) root that teaches a new developer who has just cloned the repo how to set up their environment and run the project locally — covering OS/hardware prerequisites, toolchain & SDKs, source dependencies (submodules, sibling repos), language-level install, external services, env config, build, run, and tests.

Write scope: The only file this skill is ever permitted to create or modify is HOW-TO-RUN.md. It never modifies README.md, CONTRIBUTING.md, docs/*, BUILDING.md, INSTALL.md, or any other file — not even to add a link. Existing docs are input only: the skill learns from them but always verifies every fact against the actual codebase before using it. The optional guided in-chat walkthrough (Step 3a) is display-only — it never executes commands; the user runs every step locally. The walkthrough procedure lives in references/guided-walkthrough.md.

Step 1: Detect Full Project Context (agent-assisted)

Delegate project scanning to a detection agent to keep the main context clean for content generation.

Read $CLAUDE_PLUGIN_ROOT/skills/how-to-run/agents/shared-constraints.md for agent constraints. Read $CLAUDE_PLUGIN_ROOT/skills/how-to-run/agents/project-environment-detector.md for the full prompt template, detection tasks, and return format for the Project Environment Detector Agent.

Read these reference files and provide their content to the agent as context before the agent prompt:

• $CLAUDE_PLUGIN_ROOT/skills/init/references/multi-repo-detection.md — workspace detection
• $CLAUDE_PLUGIN_ROOT/skills/init/references/project-detection.md — monorepo/single-project detection
• $CLAUDE_PLUGIN_ROOT/skills/init/references/tech-stack-detection.md — manifest → tech stack + package manager
• $CLAUDE_PLUGIN_ROOT/skills/how-to-run/references/how-to-run-sections.md — signal-to-section mapping, build-system signals, source-dependency signals

The detector only needs to set Triggered: yes when no manifest or build-system signal matches; it does NOT execute the fallback procedure. The procedure itself is loaded by the main SKILL context only when the trigger fires (see Step 1 Checkpoint).

Launch 1 general-purpose Agent tool call using the prompt from project-environment-detector.md, prepended with the shared constraints and reference file contents above. The agent detects: build system & toolchain, source dependencies, SDKs & system packages, hardware/OS requirements, tech stack, package manager, project structure, external services, env config, infrastructure signals, and dev workflow signals.

Wait for the agent to complete. Use the agent's Context Detection Results to populate the Step 1 Checkpoint below.

Step 1 Checkpoint

Print a Context Summary from the agent's Context Detection Results. The External-service-default-endpoints bullet below states how to derive the Endpoint semantics label per row.

• Build system & toolchain (e.g., CMake >= 3.20 with MSVC, cargo, npm scripts, Gradle 8.x)
• Tech stack(s) and package manager(s)
• Project structure (single / monorepo with subprojects / multi-repo with repos)
• Source dependencies (git submodules from .gitmodules, sibling repos detected in build/CI files, CMake FetchContent / ExternalProject)
• SDKs & system packages (Vulkan, CUDA, Qt, JDK, .NET SDK, MSVC Build Tools, etc. — only if detected)
• External services detected (list each service with a trailing (candidate) marker when the detector's Confidence column is candidate, and its source — e.g., "PostgreSQL — source: docker-compose.yml; OpenIdConnect (candidate) — source: appsettings.development.json:42"). Compose-confirmed services render with no marker; Task 5b framework-config candidates render with (candidate).
• External service default endpoints (per service: raw default endpoint from the referenced config file + one Endpoint semantics label. For database-type services: the row's value from the detector (see project-environment-detector.md §External Services). For non-database services: local-default for localhost / empty / unknown, remote for any other hostname/FQDN, ambiguous if the config file is missing or unreadable.) Flag values that trigger a Pre-Conditions Block (per external-services-docker.md §Pre-Conditions Block §Trigger) so a misclassification can be corrected via the "Correct first" flow.
• Environment config files found — list each file reported by the detector's Environment Setup table with its format appended in brackets (e.g., src/Web/config/appsettings.development.json [json], config/application.yml [yaml], .env.example [dotenv]).
• Schema bootstrap scripts (list the detector's Schema Bootstrap table entries with their invocation hint — e.g., "db/DatabaseNew.sql (sqlcmd -i db/DatabaseNew.sql), db/seeds.rb (rails db:seed)" — or "none" when the detector reports none).
• Recommended developer tools (list the detector's Recommended Developer Tools entries — e.g., "Google Chrome, SSMS, Visual Studio" — or "none" when empty).
• Runtime version constraints (e.g., "Node.js >=18 (engines.node), Python >=3.11 (python_requires)")
• Hardware / OS requirements (GPU, USB/serial, OS version — only if detected)
• Dev workflow signals (Docker-based, Makefile-based, script-based, process runner, etc.)

Detector-internal fields (Workspace kind, Components table, Runtime Ports table) are read by Step 4 directly from the detector's return-format tables — do NOT print them as user-facing Context Summary bullets.

Use AskUserQuestion — header "Context review", question "Does this capture the project correctly?":

• Looks good — "Proceed with detected context"
• Correct first — "Some details are wrong or missing"

If "Correct first": use AskUserQuestion — header "Corrections", question "What should be changed?" (free text). Apply the corrections to the Context Detection Results in memory, recomputing the Unsupported-Stack Fallback → Triggered flag if the correction changes the detected language or stack, and re-print the updated Context Summary. Re-confirm.

Unsupported-Stack Fallback. If the Context Detection Results show Unsupported-Stack Fallback → Triggered: yes, read $CLAUDE_PLUGIN_ROOT/skills/init/references/unsupported-stack-fallback.md and run its 5-step procedure here, using the reported Detected language(s) and Evidence as input. Use WebSearch for step 2 (research); enforce the step 3 validation rules before presenting any command; use AskUserQuestion for step 4 (approval). Commands approved here feed Step 4 content generation as if from a recognized stack; commands skipped (search failed or user declined) render as "not found" in the affected sections.

LLM-knowledge fallback (how-to-run only). If WebSearch is unavailable or returns no results for the detected language, use general knowledge to propose standard install/build/run/test commands for that language. Mark these commands as "inferred (not web-verified)" when presenting them for user approval in step 4. If the user declines, treat as a graceful skip.

Step 2: Scan Existing Instructions (agent-assisted)

Delegate documentation scanning to an audit agent that cross-checks existing docs against the detected project state.

Framing: The auditor treats findings in every file except HOW-TO-RUN.md as hypotheses. Every fact will be verified against the detector's Context Detection Results before being used in generated content. Facts that contradict the codebase are logged as outdated and will be reported in Step 6 — they are NOT corrected in their source files.

Read $CLAUDE_PLUGIN_ROOT/skills/how-to-run/agents/shared-constraints.md for agent constraints. Read $CLAUDE_PLUGIN_ROOT/skills/how-to-run/agents/how-to-run-auditor.md for the full prompt template, audit tasks, and return format for the How-to-Run Auditor Ag