bmad-module-skill-forge 1.3.0 → 1.4.1

package/src/skf-brief-skill/steps-c/step-01-gather-intent.md

@@ -1,6 +1,13 @@
 ---
 nextStepFile: './step-02-analyze-target.md'
 forgeTierFile: '{sidecar_path}/forge-tier.yaml'
+descriptionVoiceExamplesFile: 'assets/description-voice-examples.md'
+headlessArgsFile: 'references/headless-args.md'
+headlessSourceAuthorityDetectionFile: 'references/headless-source-authority-detection.md'
+portfolioSimilarityCheckFile: 'references/portfolio-similarity-check.md'
+draftCheckpointFile: 'references/draft-checkpoint.md'
+validateBriefInputsScript: '{project-root}/src/shared/scripts/skf-validate-brief-inputs.py'
+emitBriefEnvelopeScript: '{project-root}/src/shared/scripts/skf-emit-brief-result-envelope.py'
 ---
 
 # Step 1: Gather Intent
@@ -14,6 +21,7 @@ To initialize the brief-skill workflow by discovering the forge tier configurati
 - Focus only on gathering intent — do not analyze the repo yet (Step 02)
 - Do not examine source code or list exports in this step
 - Open-ended discovery facilitation — collect target repo, user intent, scope hints, skill name
+- All user-facing output in `{communication_language}`
 
 ## MANDATORY SEQUENCE
 
@@ -21,6 +29,16 @@ To initialize the brief-skill workflow by discovering the forge tier configurati
 
 ### 1. Discover Forge Tier
 
+**Pre-flight write probe.** Before any conversational state accumulates, verify `{forge_data_folder}` is writable. A read-only mount, full disk, or permissions-denied path otherwise only surfaces at step-05's atomic write — by then the user has invested 5–15 minutes. Run a single-byte write-and-remove probe:
+
+```bash
+mkdir -p "{forge_data_folder}" && \
+  printf 'probe' > "{forge_data_folder}/.skf-write-probe" && \
+  rm "{forge_data_folder}/.skf-write-probe"
+```
+
+`mkdir -p` succeeds on a pre-existing read-only mount, but the `printf > file` redirect actually attempts a write — that catches read-only, disk-full, and permissions-denied uniformly. **On any non-zero exit:** HALT (exit code 4, `halt_reason: "write-failed"`) — `"**Error:** {forge_data_folder} is not writable: {captured stderr}. Verify the path exists, the mount is writable, and there is free disk space, then re-run."` In headless mode, emit the error envelope per **step-05 §4b** with `halt_reason: "write-failed"` (skill_name is not yet resolved here — use the placeholder convention documented in §4b). On success, continue silently to the forge-tier load below.
+
 Attempt to load `{forgeTierFile}`:
 
 **If found:**
@@ -29,9 +47,13 @@ Attempt to load `{forgeTierFile}`:
 
 **Apply tier override:** Read `{sidecar_path}/preferences.yaml`. If `tier_override` is set and is a valid tier value (Quick, Forge, Forge+, or Deep), use it instead of the detected tier.
 
+**If found but the YAML cannot be parsed (corrupted or truncated):**
+- Display: "**Cannot read forge-tier.yaml** at `{forgeTierFile}` — the file exists but failed to parse: `{parser error message}`. The setup workflow can rewrite it cleanly. Until then, the brief workflow falls back to **Quick** tier (no extra tools assumed)."
+- Continue with `tier = "Quick"` and `tools = {}` — do not HALT. Record `tier_source: "fallback-corrupted-config"` for later diagnostics.
+
 **If not found:**
-- "**Cannot proceed.** forge-tier.yaml not found at `{forgeTierFile}`. Please run the **setup** workflow first to configure your forge tier (Quick/Forge/Forge+/Deep)."
-- HALT — do not proceed.
+- "**Cannot proceed.** forge-tier.yaml not found at `{forgeTierFile}`. Run the **setup** workflow first to configure your forge tier (Quick/Forge/Forge+/Deep)."
+- HALT (exit code 3, `halt_reason: "forge-tier-missing"`) — do not proceed.
 
 ### 2. Welcome and Explain
 
@@ -46,14 +68,22 @@ We'll work through this together:
 4. **Finally:** Confirm and write the brief
 
 {If tier override was applied:}
-**Your forge tier:** {override tier} (overridden from {original tier}) — this determines what compilation capabilities are available.
+**Your forge tier:** {override tier} (overridden from {original tier}) — {tier_gloss}
 {Else:}
-**Your forge tier:** {detected tier} — this determines what compilation capabilities are available.
+**Your forge tier:** {detected tier} — {tier_gloss}
+
+(Substitute `{tier_gloss}` with the matching one-liner so the user knows what the tier label means: `Quick` → "text-only extraction"; `Forge` → "AST-grep on, semantic discovery off"; `Forge+` → "AST-grep + ccc semantic discovery"; `Deep` → "full pipeline — AST + ccc + qmd portfolio search + LLM re-ranking". The tier sets the ceiling for what the downstream create-skill workflow can do; you can re-run setup later to change it.)
+
+**Wanted something different?** This workflow *creates* a new brief — a YAML scoping document for a skill that doesn't yet exist. If you meant to compile an existing brief into a skill (`/skf-create-skill`), package one for distribution (`/skf-export-skill`), or just ask SKF a question, type `cancel` at any prompt and run that workflow instead.
 
 Let's get started."
 
 ### 3. Gather Target Repository
 
+This section has three sub-flows. Execute exactly one branch — 3.2 *or* 3.3 — based on the user's response in 3.1, then end with the shared confirmation. Do not mix branches.
+
+#### 3.1 Collect target
+
 "**What repository or documentation do you want to create a skill for?**
 
 Provide one of:
@@ -61,33 +91,61 @@ Provide one of:
 - A **local path** (e.g., `/path/to/project`)
 - **Documentation URLs** for a docs-only skill (e.g., `https://docs.stripe.com/api`) — use this when no source code is available (SaaS, closed-source)
 
+Or type `cancel` / `exit` / `[X]` to leave without writing anything.
+
 **Target:**"
 
-Wait for user response.
+Wait for user response. Branch on the response:
+
+- Empty input, `cancel`, `exit`, `[X]`, `q`, or `:q` → Display `"Cancelled — no brief was written."` and HALT (exit code 6, `halt_reason: "user-cancelled"`). Cancellation here is non-destructive — no files have been written yet by step-01. Headless mode never reaches this branch (the GATE in §8 short-circuits the interactive sub-flows).
+- Documentation URLs only (no source location) → §3.2
+- GitHub URL or local filesystem path → §3.3
+- Any other free-form question (e.g. "what is this?", "show me an example", "how does SKF work?") → answer briefly, re-display the prompt
+
+#### 3.2 Branch — Documentation URLs (docs-only)
 
-**If user provides documentation URLs (not a repo):**
 - Set `source_type: "docs-only"` in the brief data
 - Collect one or more doc URLs with optional labels
-- Note: `source_authority` will be forced to `community` (T3 external documentation)
+- HEAD-check the collected URLs in parallel — do not loop sequentially. Issue all N `curl -sI {url}` (or equivalent) calls in a **single message with N parallel Bash calls**, then process the responses together. Each call must use a 5-second timeout (`curl -sI --max-time 5 {url}`) to bound worst-case wall-time on hung hosts. Per response:
+  - On 2xx/3xx: silently accept.
+  - On 4xx/5xx, DNS failure, or timeout: warn `"Could not reach {url} — {status or error}. Confirm the URL is correct, or proceed anyway."` Interactive: re-prompt for a corrected URL or `[K] Keep anyway`. Headless: keep the URL and log the warning — the brief still records it but the failure is now visible at brief-creation time instead of materializing hours later in skf-create-skill.
+- Set `source_authority: "community"` (forced for docs-only — T3 external documentation; the §3.3 source-authority prompt is skipped)
 - Note: `source_repo` becomes optional (can be set to the main doc site URL for reference)
 
-**If user provides a GitHub URL or local path:**
+Skip §3.3 and continue at "Confirm the target" below.
+
+#### 3.3 Branch — Source (GitHub URL or local path)
+
 - Set `source_type: "source"` (default)
+- **Pre-validate the target before continuing.** Issue these probes in a single message with parallel Bash calls:
+  - **GitHub URL:** `curl -sI --max-time 5 {url}`. On a 4xx (typically 404 for a typo'd repo or org), warn `"GitHub returned {status} for {url} — confirm the URL is correct."` and re-prompt. On 2xx, accept.
+  - **GitHub URL, in parallel:** `gh api repos/{owner}/{repo} --jq .name` (5-second timeout via `gh api --hostname github.com --method GET ... ` or just rely on default). On 403/404, warn `"GitHub API returned {status} for {owner}/{repo} — the repo may be private or your token may not have access. Step-02 will HALT here if this is not resolved. Continue anyway, or fix and re-prompt?"` and offer `[K] Keep anyway` / re-prompt for a corrected URL. Do not HALT — the canonical HALT still happens in step-02 §1, but surfacing access failures at URL-entry time prevents 5+ minutes of intent investment getting lost. On any other error (network failure, missing binary), log silently and let `gh auth status` below catch it. On 2xx, accept silently.
+  - **GitHub URL, in parallel:** `gh auth status` — if it reports unauthenticated or the binary is missing, warn `"GitHub CLI not authenticated; step-02 will HALT when it tries to fetch the tree. Run 'gh auth login' before continuing, or supply a local clone path instead."` (Do not HALT here — let the user choose to fix or proceed; the canonical HALT still happens in step-02 §1's failure-class triage.)
+  - **Local path:** verify the directory exists (`test -d {path}`). If not, warn `"Local path {path} does not exist."` and re-prompt.
 - Optionally ask: "Are there any documentation URLs you'd like to include for supplemental context? (These will be fetched as T3 external references.)"
 - If yes: collect doc URLs into `doc_urls`
 
-**Source authority (for all source-type skills):**
+**Source authority (this branch only — docs-only forces `community` in §3.2):**
+
+**Interactive only** — skip this prompt entirely when `{headless_mode}` is true; the GATE in §8 resolves source_authority headlessly via the detection branch documented there.
+
 "**Are you the maintainer of this library, or creating a community skill?**"
 - If maintainer: set `source_authority: "official"`
 - If community user: set `source_authority: "community"` (default)
 - If internal/proprietary: set `source_authority: "internal"`
 
-Default to `"community"` if user does not specify or skips. For `docs-only` skills, `source_authority` is always forced to `"community"`.
+Default to `"community"` if user does not specify or skips.
+
+---
 
 Confirm the target.
 
 ### 3b. Gather Target Version
 
+This step only collects `target_version` and validates its shape with the regex below — auto-detection runs in step-02 and precedence/invariant resolution lands in step-05's writer script. The canonical precedence rules live in `references/version-resolution.md`; load it from step-02 / step-05 only when the relevant section needs it.
+
+**Headless:** if `target_version` was supplied as an argument, store it and skip the interactive prompt below. If `doc_urls` were also supplied, treat the version-vs-doc-URL confirmation prompt as auto-confirmed (Y).
+
 "**Are you targeting a specific version of this library?**
 (Leave blank to auto-detect from source)"
 
@@ -96,7 +154,7 @@ Confirm the target.
 
 Wait for user response.
 
-**If user provides a version:** Store as `target_version`. Set `version` to this value.
+**If user provides a version:** Validate the shape against `^v?\d+\.\d+\.\d+([.\-+][0-9A-Za-z][0-9A-Za-z.\-+]*)?$` (full X.Y.Z form, with optional `v` prefix and pre-release / build suffix; CalVer like `2024.04.01` accepted; partial forms like `1`, `1.2`, `v2`, `latest` rejected). On a match, store as `target_version` and set `version` to this value. On a non-match, warn `"'{value}' doesn't look like semver — write the explicit triple (e.g. 1.0.0). Fix it now or skip auto-detection?"` and re-prompt for a corrected value or blank to fall through to step-02 auto-detection.
 **If blank:** Proceed without `target_version` — version will be auto-detected in step 02.
 
 {If target_version was set AND doc_urls are being collected (either docs-only primary or supplemental):}
@@ -104,10 +162,22 @@ Wait for user response.
 "**You're targeting version {target_version}. Do these documentation URLs correspond to that version?** [Y/N]"
 
 - **If Y:** Proceed.
-- **If N:** "Please provide the correct documentation URLs for version {target_version}." Re-collect doc_urls.
+- **If N:** "Provide the correct documentation URLs for version {target_version}." Re-collect doc_urls.
 
 ### 4. Gather User Intent
 
+**First-timer rail (interactive only).** Before the intent prompt, check whether `{forge_data_folder}/` contains any prior briefs:
+
+```bash
+find "{forge_data_folder}" -maxdepth 2 -name "skill-brief.yaml" -print -quit
+```
+
+If the command produces any output, skip this rail silently — repeat users don't need the warm-up. If it produces no output (the user has never produced a brief), ask:
+
+"**Want to see a few example descriptions first?** [Y/N] (Helpful if this is your first time — I'll show the voices we use so you have an anchor for what 'good intent' produces.)"
+
+On `[Y]`: load `{descriptionVoiceExamplesFile}` and present the five examples verbatim with a one-line preface (`"Each example shows a different voice — yours doesn't have to match any specific one."`). On `[N]` or empty: proceed silently.
+
 "**What's your intent for this skill?**
 
 Help me understand:
@@ -140,6 +210,34 @@ This will be used for the output directory and file naming. Want to use this nam
 
 Wait for confirmation or alternative.
 
+**Collision check (interactive and headless):** before locking the name, check whether `{forge_data_folder}/{name}/skill-brief.yaml` already exists. If it does:
+
+- Interactive: generate 1–3 non-colliding candidate alternates by scanning sibling directories under `{forge_data_folder}/`. Apply each rule that fires; skip rules whose precondition isn't met:
+  1. `{name}-v{N}` where `N` is the smallest positive integer that doesn't collide (e.g. `{name}-v2`, `{name}-v3`) — always applies
+  2. `{name}-{target_version}` if `target_version` is set and the suffix wouldn't collide (e.g. `marked-1.2.3`)
+  3. `{name}-{source_authority}` if `source_authority` is not `community` (e.g. `marked-internal` for an internal fork)
+
+  Number the surviving alternates `[1] [2] [3]…` in the order produced (1 alternate for a community-authority brief with no `target_version`; 2–3 otherwise). Then present:
+
+  ```
+  **Heads up — a brief for `{name}` already exists at `{path}`.**
+
+  Suggested alternates (none collide):
+    [1] {alternate-1}
+    {if a second alternate was produced:} [2] {alternate-2}
+    {if a third alternate was produced:} [3] {alternate-3}
+
+  Pick a number to use that name, type a different name, or press Enter to keep `{name}` and let step-05 §2b handle the overwrite prompt.
+  ```
+
+  On a numbered choice, replace `{name}` with the chosen alternate. On Enter, fall through to step-05's overwrite gate. On any other input, treat as a new candidate name and re-run the collision check against it.
+
+- Headless: log `"warn: skill name '{name}' collides with existing brief at {path}"` and proceed; the existing-brief overwrite policy in step-05 §2b is the canonical gate (HALT with `overwrite-cancelled` unless `force` was supplied).
+
+**Portfolio-similarity check.** When the flow is interactive AND forge tier is `Deep` AND `tools.qmd` is true in `forge-tier.yaml`, load `{portfolioSimilarityCheckFile}` and follow the procedure there to catch semantic near-duplicates that exact-name collision misses. Otherwise (headless, or tier below Deep, or qmd unavailable) skip the load — the check does not run.
+
+**Draft-resume check.** When the flow is interactive AND `{forge_data_folder}/{name}/.brief-draft.json` exists AND no `skill-brief.yaml` sits beside it, load `{draftCheckpointFile}` and follow Half 1 (Resume Check). On `[Y]` resume, the procedure jumps directly to §8 with prior answers restored — **the rest of §6, all of §7, and all of §7b are skipped**. Otherwise (headless, or no draft file, or a finished brief sits beside the draft) skip the load and continue with §6 normally.
+
 ### 7. Summarize Gathered Intent
 
 "**Here's what I've captured:**
@@ -158,19 +256,71 @@ Wait for confirmation or alternative.
 
 Ready to analyze the target repository?"
 
+**Draft checkpoint.** When the flow is interactive, load `{draftCheckpointFile}` (or reuse it if already loaded for the §6 resume check) and follow Half 2 (Checkpoint Write) to persist the captured state atomically. Headless mode skips this — the run completes in a single invocation, no resume is meaningful.
+
+### 7b. Synthesize Skill Description
+
+The schema's `description` field is 1-3 sentences and surfaces in skill registries — it must exist by the time step-04 presents the brief. Synthesize it explicitly here, while the user's intent is fresh, instead of letting it fall out implicitly later.
+
+Compose a candidate 1-3 sentence description from the gathered material. **Write like a human library maintainer would** — what does an agent get from this skill, and when should it route here? Two facts must come through (what the skill is, when to use it); everything else is voice. Resist filling in the same skeleton every time.
+
+Load `{descriptionVoiceExamplesFile}` for the five voice examples (range of acceptable leads, structures, and trigger phrasings) and the "do not template-stamp" guidance, then compose in that spirit. The asset documents what "in that spirit" means; the gathered material to draw on is the target repo, the user's intent, the version if set, and any scope hints.
+
+Present:
+
+"**Proposed skill description:**
+
+> {synthesized description}
+
+This is the text agents read when deciding whether to route to your skill — it sits in the registry row alongside dozens of other skills. Specific triggers ('use when…', 'reach for this when…') help agents match real user requests; generic descriptions blend in and get skipped. Edit, replace, or accept as-is."
+
+Wait for user confirmation or alternative.
+
+**Soft sentence-count check (interactive only).** Before storing the accepted text, count terminal sentence punctuation (`.`, `!`, `?` followed by whitespace or end-of-string) — abbreviations like `e.g.` will inflate the count slightly but the check is a soft nudge, not a HALT. If the count exceeds 3, present:
+
+"**Heads up — that description reads as ~{N} sentences.** The conventional norm is 1-3 (it surfaces in registry rows alongside other skills, where length crowds out the trigger phrase). Tighten now, or accept as-is?"
+
+On `tighten` or a fresh edit: re-prompt for the description. On `accept` or any non-edit response: store the accepted text and proceed. Counts of 1-3 store silently.
+
+Store the accepted text as the brief's `description` field. The same field is re-presented in step-04 §3 for a final review pass — refinements there flow back to this value.
+
+**Headless:** if the `intent` argument was supplied, load `{descriptionVoiceExamplesFile}` and run the same synthesis against it (in `{document_output_language}`), then store the result. If `intent` was not supplied, fall back in priority order:
+
+1. **GitHub repo description** — when `target_repo` is a GitHub URL, fetch `gh api repos/{owner}/{repo} --jq .description` (5-second timeout). If a non-empty description comes back, load `{descriptionVoiceExamplesFile}` and synthesize using the GitHub description as the seed in place of `intent`. Write the synthesized description in `{document_output_language}` regardless of the seed's language (the seed may be in any language; the output's language is dictated by the workflow's document-output configuration). Log `"info: description seeded from GitHub repo description"`. (The full `gh api repos` response is fetched again in step-02 §1; this lightweight `--jq .description` call only retrieves the one field.)
+2. **Generic stub** — when no GitHub description is available (local-path target, GitHub repo with empty description, or `gh api` fails): derive from `target_repo` + `skill_name` (`"Use the {skill_name} skill to work with code or content from {target_repo}."`) — the generic fallback does not need the asset — and log `"warn: description synthesized without intent or repo description — narrow registry text."`
+
 ### 8. Present MENU OPTIONS
 
-Display: "**Select:** [C] Continue to Target Analysis"
+Display: "**Select:** [C] Continue to Target Analysis · [X] Cancel and exit"
 
 #### Menu Handling Logic:
 
 - IF C: Load, read entire file, then execute {nextStepFile}
+- IF X: Treat as user-cancellation. Display `"Cancelled — no brief was written."` and HALT (exit code 6, `halt_reason: "user-cancelled"`). When `{headless_mode}` is true the GATE auto-proceeds and never reaches this branch — `[X]` is interactive-only. Cancellation here is non-destructive: no files have been written yet by step-01.
 - IF Any other: Help user, then [Redisplay Menu Options](#8-present-menu-options)
 
 #### EXECUTION RULES:
 
 - ALWAYS halt and wait for user input after presenting menu
-- **GATE [default: use args]** — If `{headless_mode}`: consume pre-supplied arguments (target_repo, skill_name, scope_hint, language_hint) and auto-proceed. If required args missing, HALT: "headless mode requires target_repo and skill_name arguments."
+- **GATE [default: use args]** — If `{headless_mode}`, consume pre-supplied arguments and auto-proceed. The full argument set (required/optional, defaults, halt codes, enum values) is documented in `{headlessArgsFile}` — load it now if you need to look up a specific argument. Validation is delegated to `{validateBriefInputsScript}`; the table is the canonical operator-facing documentation, the script enforces it.
+
+  **Preset merge (before validation).** If the headless args include a `preset` field, load `{sidecar_path}/brief-presets/{preset}.yaml` and merge its contents as defaults — explicit args override preset values, key by key. The preset file is YAML; if it does not exist, log `"warn: preset '{name}' not found at {path} — proceeding without preset"` and continue (do not HALT). If it parses but contains unknown fields, log per-field warnings and pass through unchanged (the validator's KNOWN_FIELDS check will catch any that survive). Drop the `preset` key itself from the merged dict before passing to the validator (it is consumed at this level and is not a brief field).
+
+  **Delegate validation to `{validateBriefInputsScript}`** instead of reasoning through the table rules in prose:
+
+  ```bash
+  echo '<headless-args-as-json>' | uv run {validateBriefInputsScript}
+  ```
+
+  The script returns a JSON envelope: `{valid, errors[], warnings[], normalized, halt_reason}`. Apply the result deterministically:
+
+  - **`valid: false`** — emit the error envelope per **step-05 §4b** with the script's `halt_reason` (`"input-missing"` for absent required args / docs-only without doc_urls; `"input-invalid"` for enum violations, malformed semver, malformed kebab-case skill_name). Surface `errors[]` to the operator log so the failure is debuggable. HALT.
+  - **`valid: true`** — consume the `normalized` object as the source of truth (it has defaults applied per the table). Surface `warnings[]` to the operator log but do not HALT. Auto-proceed.
+
+  The script's `KNOWN_FIELDS` set must stay in sync with the table in `{headlessArgsFile}`.
+
+  **Headless source-authority detection.** After consuming `normalized`, if `source_authority` is absent AND `source_type=source` AND `target_repo` is a GitHub URL, load `{headlessSourceAuthorityDetectionFile}` and follow the procedure there. Otherwise (precondition unmet, value already supplied, docs-only, or local-path) skip the load — `community` is the implicit default for the unmet branches.
+
 - ONLY proceed to next step when user selects 'C'
 
 ## CRITICAL STEP COMPLETION NOTE

package/src/skf-brief-skill/steps-c/step-02-analyze-target.md

@@ -1,5 +1,9 @@
 ---
 nextStepFile: './step-03-scope-definition.md'
+versionResolutionFile: 'references/version-resolution.md'
+extractPublicApiScript: '{project-root}/src/shared/scripts/skf-extract-public-api.py'
+detectWorkspacesScript: '{project-root}/src/shared/scripts/skf-detect-workspaces.py'
+detectLanguageScript: '{project-root}/src/shared/scripts/skf-detect-language.py'
 ---
 
 # Step 2: Analyze Target
@@ -13,6 +17,7 @@ To analyze the target repository by resolving its location, reading its structur
 - Focus only on analysis — do not define scope yet (Step 03)
 - Do not make scoping decisions or recommendations
 - Do not hallucinate or guess about repository contents
+- All user-facing output in `{communication_language}`
 
 ## MANDATORY SEQUENCE
 
@@ -21,23 +26,68 @@ To analyze the target repository by resolving its location, reading its structur
 ### 1. Resolve Target Location
 
 **For GitHub URLs:**
-- Use `gh api repos/{owner}/{repo}` to verify the repository exists
-- Use `gh api repos/{owner}/{repo}/git/trees/HEAD?recursive=1` to get the file tree
+- Issue both probes in **one message with two parallel Bash calls** — they are independent:
+  - `gh api repos/{owner}/{repo}` (verify repo exists)
+  - `gh api repos/{owner}/{repo}/git/trees/HEAD?recursive=1` (fetch file tree)
+- If the repo-existence probe fails, fall through to the failure-class triage below; the tree response from the parallel call is discarded in that case.
 
 **Truncation detection:** After receiving the tree response, check the `truncated` field in the JSON output. If `truncated: true`:
 - Display: "Note: GitHub API returned a truncated tree response ({count} items). Full analysis may require a local clone."
 - Record in analysis summary: "Tree listing is partial — some files may not appear in the analysis."
-- For very large repos (>1000 files in tree response): suggest local clone for complete analysis.
+- For very large repos (>1000 files in tree response): offer a recovery path instead of just warning. Interactive — present:
+  ```
+  Tree is truncated. How would you like to proceed?
+    [L] Clone locally and re-analyze (slower but complete)
+    [P] Proceed with the partial tree (faster, may miss exports under deeper paths)
+  ```
+  On `[L]`: shallow-clone (`git clone --depth 1 {url} {tmp_dir}`), restart this section against the local path, and remove `{tmp_dir}` after the analysis summary in §5. On `[P]` (or under headless): record `tree_truncated: true` in the analysis summary and continue without HALT.
 
-- If inaccessible: **HALT** — "**Error:** Cannot access repository at {url}. Please verify the URL is correct and you have access. If private, ensure `gh auth` is configured."
+**On API failure (non-200 from `gh api`):**
+
+Distinguish the failure class before reporting:
+- Auto-run `gh auth status` and capture its output. If it reports an unauthenticated state or expired token: HALT (exit code 3, `halt_reason: "gh-auth-failed"`) — "**Error:** GitHub CLI is not authenticated. `gh auth status` says: `{captured output}`. Run `gh auth login` and retry."
+- If `gh auth status` reports authenticated but the call still failed (404/403): HALT (exit code 3, `halt_reason: "target-inaccessible"`) — "**Error:** Cannot access repository at `{url}`. The CLI is authenticated but the API returned `{status}`. Check the URL and that the account has access to private repositories if applicable."
+- If `gh auth status` itself fails to run (binary missing): HALT (exit code 3, `halt_reason: "gh-auth-failed"`) — "**Error:** `gh` CLI not found on PATH. Install it from <https://cli.github.com> and re-run."
 
 **For local paths:**
 - Verify the directory exists
 - List the directory tree
-- If path doesn't exist: **HALT** — "**Error:** Directory not found at {path}. Please verify the path is correct."
+- If path doesn't exist: **HALT** — "**Error:** Directory not found at {path}. Verify the path is correct."
 
 Display: "**Resolving target...**"
 
+### 1b. Detect Monorepo / Workspace Layout
+
+Delegate workspace detection to `{detectWorkspacesScript}` instead of reasoning through manifest rules in prose. Build a payload from the tree fetched in §1 plus the small set of root manifests the detector needs, then invoke the script:
+
+```bash
+echo '{"tree": [<flat list of repo-relative file paths>], "manifests": {"package.json": "<raw text>", "Cargo.toml": "<raw text>", "pnpm-workspace.yaml": "<raw text>", "lerna.json": "<raw text>"}}' | \
+  uv run {detectWorkspacesScript}
+```
+
+- **`tree`** — pass the flat list of repo-relative file paths already fetched in §1 (for GitHub: the `path` values from the `gh api .../git/trees/HEAD?recursive=1` response; for local: the equivalent listing).
+- **`manifests`** — only the root manifests need contents; child-workspace manifests are looked up from the tree by the script. Include any of `package.json`, `Cargo.toml`, `pnpm-workspace.yaml`, `lerna.json` that appears at the repo root. Fetch them in **one message with N parallel Bash calls** (`gh api .../contents/{path}` for GitHub, file reads for local), then base64-decode together. Per-workspace manifest contents (e.g. `packages/foo/package.json`) are optional — including them populates the workspace `name` field with the manifest's declared package name; omitting them falls back to the directory basename.
+
+The script returns a JSON envelope: `{is_monorepo, manifest_kind, workspaces[], warnings[]}`. Apply the result deterministically — see `src/shared/scripts/schemas/workspace-detection.v1.json` for the full contract.
+
+**If `is_monorepo: false`** — skip this section silently and continue to §2.
+
+**If `is_monorepo: true`** — present the discovered workspaces and prompt:
+
+```
+This looks like a monorepo ({manifest_kind}) with these workspaces:
+  1. {workspaces[0].name} ({workspaces[0].path})
+  2. {workspaces[1].name} ({workspaces[1].path})
+  ...
+Which one should the skill cover? Pick a number, type 'all' to scope at the repo root, or 'list' to keep listing more.
+```
+
+Interactive: wait for the user choice. On a numbered choice, store `monorepo_workspace: {path}` and rebase §2-§4b against that path. On `'all'`, leave `monorepo_workspace` unset and proceed at the repo root with a note in the analysis summary that scope is unfiltered.
+
+Headless: if the input contract supplied an `include` glob that begins with one of the workspace paths, auto-select that workspace (log `"headless: auto-selected workspace {name} from include glob"`). Otherwise default to repo root and log `"warn: monorepo detected ({manifest_kind}) but no workspace pre-selected — analyzing at repo root"`.
+
+Surface any non-empty `warnings[]` from the script to the operator log so a malformed root manifest is debuggable; the workflow does not HALT — falling back to repo-root analysis is always safe.
+
 ### 2. Read Repository Structure
 
 List the top-level directory structure:
@@ -54,53 +104,79 @@ List the top-level directory structure:
 
 ### 3. Detect Primary Language
 
-Examine file extensions and configuration files to detect the primary language:
+Delegate the rule walk to `{detectLanguageScript}` instead of evaluating manifest presence and extension frequency in prose:
+
+```bash
+echo '{"tree": [<flat list of repo-relative file paths from §1>]}' | uv run {detectLanguageScript}
+```
 
-**Detection signals (check in order):**
-1. `package.json` → JavaScript/TypeScript
-2. `tsconfig.json` → TypeScript
-3. `Cargo.toml` → Rust
-4. `pyproject.toml` or `setup.py` or `setup.cfg` → Python
-5. `go.mod` → Go
-6. `pom.xml` or `build.gradle` → Java
-7. `*.csproj` or `*.sln` → C#
-8. `Gemfile` → Ruby
-9. File extension frequency analysis as fallback
+The script returns `{language, confidence, detection_source, fallback_to_extension_frequency}` after walking the documented rule table (manifest presence first — package.json with tsconfig.json disambiguation, Cargo.toml, pyproject.toml/setup.py/setup.cfg, go.mod, pom.xml, build.gradle.kts, build.gradle Groovy with Java/Kotlin disambiguation, *.csproj/*.sln, Gemfile — then extension-frequency fallback over recognized source extensions). Use the returned values directly:
 
 "**Detected language:** {language}
-**Confidence:** {high/medium/low}
-**Detection source:** {what config file or pattern confirmed it}"
+**Confidence:** {confidence}
+**Detection source:** {detection_source}"
 
-If confidence is low or ambiguous: flag for user override in step 03.
+If `confidence` is `low` (or `unknown` is returned for `language`): flag for user override in step 03 §4.
 
 ### 4. List Top-Level Modules and Exports
 
-Based on detected language, identify public API surface:
+Identify the public API surface. **Delegate the parsing to `{extractPublicApiScript}` whenever the detected language is supported** — the script is the single source of truth for manifest parsing, export discovery, and version detection across the whole SKF pipeline. Hand-rolling these in prose creates drift seams the LLM cannot fully close.
 
-**For JavaScript/TypeScript:**
-- Check `package.json` for `main`, `exports`, `module` fields
-- Look for `index.ts`/`index.js` in `src/`
-- List directories under `src/` as potential modules
+**Script-supported languages** (use the script): `js`, `ts`, `javascript`, `typescript`, `python`, `rust`, `go`, `java`, `kotlin`.
 
-**For Python:**
-- Check `__init__.py` files for public exports
-- List top-level packages under the source directory
+This section runs exactly one of §4.1 (script path) or §4.2 (fallback path) based on the detected language, then always emits §4.3 (output format) and conditionally §4.4 (semantic signals).
 
-**For Rust:**
-- Check `lib.rs` for `pub mod` declarations
-- List modules from `src/` directory
+#### 4.1 Procedure — script-supported languages
 
-**For other languages:**
-- List top-level source directories as potential modules
-- Note any obvious entry points
+1. Read the relevant files into memory (no parsing yet — just collect content). For GitHub sources, issue **all N `gh api repos/{owner}/{repo}/contents/{file}` calls in a single message with N parallel Bash calls** (one per manifest + each entry point), then base64-decode the responses together — these are 2-4 independent fetches per typical run. For local sources read directly (also parallelisable, but local reads are fast enough that serial Read tool calls are acceptable).
+
+   | Language | Manifest | Entry points (mode=quick) |
+   |----------|----------|--------------------------|
+   | js / ts / javascript / typescript | `package.json` (root, or primary workspace package per `references/version-resolution.md`) | `index.{ts,js}` and/or `src/index.{ts,js}` if present |
+   | python | `pyproject.toml` (or `setup.py` / `setup.cfg` if no `pyproject.toml`) | top-level `__init__.py` of the package, plus `_version.py` if present |
+   | rust | `Cargo.toml` (`[package]` — workspace root if `version = { workspace = true }`) | `src/lib.rs` |
+   | go | `go.mod` | top-level `*.go` exporting the package surface |
+   | java | `pom.xml` | (manifest alone is sufficient for the modules listing) |
+   | kotlin | `build.gradle` / `build.gradle.kts` | (manifest alone) |
+
+2. Build a JSON payload matching the script contract:
+
+   ```json
+   {
+     "language": "<one of the supported values>",
+     "manifest": {"path": "<relative path>", "content": "<file contents>"},
+     "entries":  [{"path": "<relative path>", "content": "<file contents>"}, ...],
+     "mode":     "quick"
+   }
+   ```
+
+3. Invoke the script and parse its JSON stdout:
+
+   ```bash
+   echo '<payload-json>' | uv run {extractPublicApiScript} --language <lang> --mode quick
+   ```
+
+   On a non-zero exit (codes 1 or 2 per the script's docstring), capture stderr, log it, and fall through to §4.2 (the prose-fallback path) — never HALT just because the script choked on an unusual manifest.
+
+4. Render the returned `package_name`, `exports` (each entry's `name`/`type`/`source_file`), `dependencies`, and any `warnings` to the user. The script also returns `version` — feed that into §4b instead of re-deriving.
+
+5. The script does not enumerate directories under `src/`. The LLM still lists those as "Top-Level Modules/Directories" so the user sees structural context (Maven and Gradle are the exception — for those, the script returns a `modules` array which IS the list).
+
+#### 4.2 Procedure — fallback (not script-supported)
+
+Languages outside the script coverage (Ruby / C# / Swift / etc.) take this path. The §4.1 fall-through on script error also lands here.
+
+Fall back to ad-hoc inspection — `Gemfile` / `*.csproj` / `*.sln` / `Package.swift` / file extension frequency. List top-level source directories as potential modules and note any obvious entry points. Flag the limitation in the analysis summary so the user knows scoping is on coarser signals.
+
+#### 4.3 Output format (both paths)
 
 "**Top-Level Modules/Directories:**
 {numbered list of modules with brief description of each}
 
 **Detected Exports/Entry Points:**
-{numbered list of public-facing items found}"
+{numbered list of public-facing items found — from script output when available, ad-hoc inspection otherwise}"
 
-**Semantic Signals (Forge+ and Deep with ccc only):**
+#### 4.4 Semantic Signals (Forge+/Deep with ccc only)
 
 **Remote source guard:** If the target source was resolved via GitHub API (remote URL, not a local file path), skip this CCC subsection — CCC requires a local source index and cannot operate on remote-only sources. Note: "CCC semantic discovery skipped — target is remote. CCC discovery will run automatically during create-skill after the source is cloned."
 
@@ -124,29 +200,21 @@ If CCC is unavailable or returns no results: skip this subsection silently.
 
 ### 4b. Detect Source Version
 
-**If `target_version` was provided in step 01:**
-- Display: "**Target version:** {target_version} (user-specified)"
-- Still run auto-detection below for informational purposes.
+**When the language was script-supported (§4 took the script path):** the `version` field returned by `{extractPublicApiScript}` IS the detected version — do not re-derive it and do not load `{versionResolutionFile}`. The script already implements the language-specific lookups documented in that reference, so loading the reference here only burns context.
 
-Attempt to auto-detect the source version using the rules from the skill-brief-schema.md Version Detection section:
+**When the language was not script-supported:** load `{versionResolutionFile}` and follow the prose Detection Algorithm directly (Ruby / C# / Swift / etc. fall outside the script's coverage).
 
-**For Python:** Check `pyproject.toml` `[project] version` (static) → if `dynamic = ["version"]`, check `__init__.py` for `__version__` → `_version.py` if exists → `setup.py` `version=` → `git describe --tags --abbrev=0`
-**For JavaScript/TypeScript:** Check root `package.json` `"version"` field → if root has `"private": true` with a `"workspaces"` array or lacks a `"version"` field, fall back to a primary workspace package's `package.json` (e.g., `code/core/package.json`, or the first matching `packages/*/package.json`). For GitHub sources, prefer `gh api repos/{owner}/{repo}/releases/latest` → `tag_name` when a non-pre-release tag exists, over a default-branch pre-release. Treat a version containing `-alpha`, `-beta`, `-rc`, `-next`, or `-canary` as a pre-release.
-**For Rust:** Check `Cargo.toml` `[package] version` (static) → if `version = { workspace = true }`, resolve from workspace root `Cargo.toml` → `git describe --tags --abbrev=0`
-**For Go:** Check `go.mod` or `git describe --tags --abbrev=0`
+Surface the result regardless of which path produced it:
 
-**For GitHub repos:** Use `gh api repos/{owner}/{repo}/contents/{file}` to read version files (decode base64 content).
-**For local repos:** Read the file directly.
+**If `target_version` was provided in step 01:**
+- Display: "**Target version:** {target_version} (user-specified)"
 
 Display: "**Detected version:** {version or 'Not detected — will default to 1.0.0'}"
 
 {If target_version was provided AND auto-detected version differs:}
-"**Note:** Detected version ({detected_version}) differs from your target version ({target_version}). Using target version."
-
-{If target_version was provided:}
-Store `target_version` as the brief's `version` field (overrides auto-detection).
+"**Note:** Detected version ({detected_version}) differs from your target version ({target_version}). Using target version (per `references/version-resolution.md` precedence rules)."
 
-If detection fails or returns a non-semver value: note that version will default to `"1.0.0"` and the user can override in step 04.
+If detection fails or returns a non-semver value: note that version will default to `"1.0.0"` and the user can override in step 04. The actual write happens in step 05.
 
 ### 5. Report Analysis Summary