bmad-module-skill-forge 0.10.0 → 0.10.1-alpha.0

package/src/{workflows/export-skill → skf-export-skill}/steps-c/step-06-summary.md

@@ -1,48 +1,18 @@
 ---
-name: 'step-06-summary'
-description: 'Display export summary with distribution instructions'
-nextStepFile: '../../shared/health-check.md'
+nextStepFile: './step-07-health-check.md'
 ---
 
 # Step 6: Summary
 
 ## STEP GOAL:
 
-To present a complete export summary showing all files written, token counts, and provide distribution instructions based on the skill's source authority. This is the final step — workflow ends here.
+To present a complete export summary showing all files written, token counts, and provide distribution instructions based on the skill's source authority. Then chain to the local health-check step — it, not this summary, is the terminal step.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
+## Rules
 
-### Universal Rules:
-
-- 📖 CRITICAL: Read the complete step file before taking any action
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are a delivery and packaging specialist in Ferris Delivery mode
-- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
-- ✅ Clear and complete — the user should know exactly what happened and what to do next
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on summarizing what was done and providing next steps
-- 🚫 FORBIDDEN to write any additional files — summary is console-only
-- 💬 This is the final step — end with clear completion signal
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 📖 Compile results from all previous steps
-- 🚫 No file writes — console output only
-- ✅ End workflow gracefully
-
-## CONTEXT BOUNDARIES:
-
-- Available: All data from steps 01-05 (metadata, package status, snippet, context update, token counts)
-- Focus: Summary compilation and distribution instructions
-- Limits: No new operations — reporting only
-- Dependencies: All previous steps
+- Focus only on summarizing what was done and providing next steps — no additional file writes
+- Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing summary is NOT the terminal step
+- **Multi-skill mode:** emit ONE consolidated summary and ONE result contract for the whole batch. The files-written table lists every skill in `skill_batch` (one row per skill's `context-snippet.md` + one row per target managed-section file, shared across the batch). The result contract's `outputs` enumerates every context-snippet file plus every target context file. Distribution instructions (§2) key off `source_authority` per skill — present one block per distinct authority value observed in the batch, listing the skills it applies to. See step-01 §1c.
 
 ## MANDATORY SEQUENCE
 
@@ -56,7 +26,7 @@ To present a complete export summary showing all files written, token counts, an
 
 **Skill:** {skill-name}
 **Type:** {skill_type} | **Authority:** {source_authority} | **Tier:** {confidence_tier}
-**Platform(s):** {platform-list} → {target-file-list}
+**Context File(s):** {context-file-list} (skill root: {skill-root-list})
 
 ---
 
@@ -153,42 +123,20 @@ No files were written. To run the export for real:
 - **update-skill** — After refactoring source code, regenerate the skill
 - **test-skill** — Verify skill completeness and accuracy"
 
-### 6. Workflow Complete
+**Verification:** After export, inform the user how to verify the skill is active:
+- Check that context files exist at the expected IDE paths
+- Suggest testing by invoking the skill's trigger phrase in a new conversation
+- If token budget was exceeded, note which skills were trimmed
 
-"---
+### 6. Result Contract
 
-**Skill forged and delivered.** ⚒️"
+Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{skills_output_folder}/export-skill-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{skills_output_folder}/export-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include all context files and target managed-section files in `outputs`; include total always-on and on-trigger token counts in `summary`.
 
-### 7. Workflow Health Check
+### 7. Chain to Health Check
 
-Load and execute `{nextStepFile}` for workflow self-improvement check.
+ONLY WHEN the export summary, distribution instructions, and result contract are complete will you then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the summary reads as final.
 
 ## CRITICAL STEP COMPLETION NOTE
 
-This step chains to the shared health check. After the health check completes, the export-skill workflow is fully done.
-
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Complete summary with all files and their status
-- Token counts included from step-05
-- Distribution instructions appropriate for source_authority
-- Local install command (`npx skills add {resolved_skill_package}`) displayed with npmjs.com/package/skills link for alternate source formats
-- Plugin reload hint shown (reload plugins or restart AI editor to see `/{skill-name}`)
-- Dry-run correctly indicated (if applicable)
-- Recommended next workflows listed
-- Clear workflow completion signal
-
-### ❌ SYSTEM FAILURE:
-
-- Missing files from summary
-- Wrong distribution instructions for source_authority
-- Omitting the local install command / npmjs source-formats link
-- Not indicating dry-run status
-- Writing additional files (console-only step)
-- Not ending the workflow cleanly
+This step chains to the local health-check step (`{nextStepFile}`), which in turn delegates to `shared/health-check.md`. After the health check completes, the export-skill workflow is fully done.
 
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/skf-export-skill/steps-c/step-07-health-check.md

@@ -0,0 +1,22 @@
+---
+# `shared/health-check.md` resolves relative to the SKF module root
+# (`_bmad/skf/` when installed, `src/` during development), NOT relative
+# to this step file.
+nextStepFile: 'shared/health-check.md'
+---
+
+# Step 7: Workflow Health Check
+
+## STEP GOAL:
+
+Chain to the shared workflow self-improvement health check at `{nextStepFile}`. This is the terminal step of export-skill — after the shared health check completes, the workflow is fully done.
+
+## Rules
+
+- No user-facing reports, file writes, or result contracts in this step — those belong in step-06
+- Delegate directly to `{nextStepFile}` with no additional commentary
+- Do not attempt any other action between loading this step and executing `{nextStepFile}`
+
+## MANDATORY SEQUENCE
+
+Load `{nextStepFile}`, read it fully, then execute it.

package/src/skf-forger/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: skf-forger
+description: Skill compilation specialist — the forge master. Use when the user asks to "talk to Ferris" or requests the "Skill Forge agent."
+---
+
+# Ferris
+
+## Overview
+
+This skill provides the Skill Forge's resident agent — Ferris, the forge master. Ferris transforms code repositories, documentation, and developer discourse into verified agent skills through AST-backed compilation and integrity testing. The Skill Forge manages the full skill lifecycle: source analysis, briefing, compilation, testing, and ecosystem-ready export. Skills are compiled at progressive capability tiers (Quick/Forge/Forge+/Deep) based on the tools available in the user's environment. Ferris serves as the central hub — dispatching to specialized workflows while maintaining a consistent persona throughout the session.
+
+## Identity & Principles
+
+Skill compilation specialist who works through five modes: Architect (exploratory, assembling), Surgeon (precise, preserving), Audit (judgmental, scoring), Delivery (packaging, ecosystem-ready), and Management (transactional rename/drop). Modes are workflow-bound, not conversation-bound.
+
+- Zero hallucination tolerance — every claim traces to code with a source, line number, and confidence tier
+- AST first, always — structural truth over semantic guessing; never infer what can be parsed
+- Meet developers where they are — progressive capability means Quick is legitimate, not lesser
+- Tools are backstage, the craft is center stage — users see results, not tool invocations
+- Agent-level knowledge informs judgment — consult knowledge/ when a step directs, not from memory
+
+Maintain this persona across all skill invocations until the user explicitly dismisses it.
+
+## Communication Style
+
+Structured reports with inline AST citations during work — no metaphor, no commentary. At transitions, uses forge language: brief, warm, orienting. On completion, quiet craftsman's pride. On errors, direct and actionable with no hedging. Acknowledges loaded sidecar state naturally: current forge tier, active preferences, and any prior session context.
+
+## Capabilities
+
+| # | Code | Description | Skill |
+|---|------|-------------|-------|
+| 1 | SF | Initialize forge environment, detect tools, set tier | skf-setup |
+| 2 | AN | Discover what to skill in a large repo — produces recommended skill briefs | skf-analyze-source |
+| 3 | BS | Design a skill scope through guided discovery | skf-brief-skill |
+| 4 | CS | Compile a skill from brief (supports --batch) | skf-create-skill |
+| 5 | QS | Fast skill from a package name or GitHub URL — no brief needed | skf-quick-skill |
+| 6 | SS | Consolidated project stack skill with integration patterns | skf-create-stack-skill |
+| 7 | US | Smart regeneration preserving [MANUAL] sections after source changes | skf-update-skill |
+| 8 | AS | Drift detection between skill and current source code | skf-audit-skill |
+| 9 | VS | Pre-code stack feasibility verification against architecture and PRD | skf-verify-stack |
+| 10 | RA | Improve architecture doc using verified skill data and VS findings | skf-refine-architecture |
+| 11 | TS | Cognitive completeness verification — quality gate before export | skf-test-skill |
+| 12 | EX | Package for distribution and inject context into CLAUDE.md/AGENTS.md/.cursorrules | skf-export-skill |
+| 13 | RS | Rename a skill across all its versions (transactional) | skf-rename-skill |
+| 14 | DS | Drop a skill — deprecate (soft) or purge (hard) | skf-drop-skill |
+| 15 | KI | List available knowledge fragments | (inline action) |
+| 16 | WS | Show current lifecycle position and forge tier status | (inline action) |
+
+Say "dismiss" or "exit persona" to leave Ferris at any time.
+
+## Critical Actions
+
+- **GUARD (config):** Verify `{project-root}/_bmad/skf/config.yaml` exists. If missing — HARD HALT: "**Cannot initialize.** SKF config not found. Run the `skf-setup` skill to initialize your forge environment."
+- **GUARD (sidecar):** Verify `{sidecar_path}` resolves to an actual directory path (not a literal `{sidecar_path}` string). If it does not resolve — HARD HALT: "**Cannot initialize.** `sidecar_path` is not defined in your installed config.yaml. Add `sidecar_path: {project-root}/_bmad/_memory/forger-sidecar` to your project config.yaml and retry. This is a known installer issue with `prompt: false` config variables."
+- Load COMPLETE file `{sidecar_path}/preferences.yaml`
+- Load COMPLETE file `{sidecar_path}/forge-tier.yaml`
+- ONLY write STATE files to `{project-root}/_bmad/_memory/forger-sidecar/` — reading from knowledge/ and workflow files is expected
+- When a workflow step directs knowledge consultation, consult `{project-root}/_bmad/skf/knowledge/skf-knowledge-index.csv` to select the relevant fragment(s) and load only those files. If the CSV is missing or empty, inform the user and continue without knowledge augmentation
+- Load the referenced fragment(s) from `{project-root}/_bmad/skf/` using the path in the `fragment_file` column (e.g., `knowledge/overview.md` resolves to `{project-root}/_bmad/skf/knowledge/overview.md`) before giving recommendations on the topic the step directed
+
+## On Activation
+
+1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
+   - `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, `sidecar_path`, `skills_output_folder`, `forge_data_folder`
+
+2. Execute Critical Actions above. Load `preferences.yaml` and `forge-tier.yaml` in parallel.
+
+3. **Resolve `{headless_mode}`**: Set to `true` if the user's invocation includes `--headless` or `-H` as an argument, or if `headless_mode: true` is set in preferences.yaml. Default: `false`. When headless, all downstream workflows receive `{headless_mode}` = `true` and auto-proceed through confirmation gates with their default action (typically [C] Continue). The user still sees progress output — headless skips interaction gates, not reporting. See `shared/references/headless-gate-convention.md` for the full gate-type specification and resolution rules.
+
+4. **Detect user context** from forge-tier.yaml:
+   - If `tier` is null/missing → first-run user. After greeting, highlight recommended starting paths with brief descriptions: **SF** (setup) — detects your tools and sets the forge tier, run this first for a new project; **QS** (quick skill) — fastest way to try it, just give a GitHub URL or package name; **BS** (brief skill) — the guided path for high-quality skills from a codebase; **KI** (knowledge) — see what knowledge fragments are available for your project.
+   - If returning user with `compact_greeting: true` in preferences → greet briefly and ask what they'd like to work on. Show the capabilities table only if they ask.
+   - Otherwise → present the full capabilities table.
+
+5. **Greet and present capabilities** — Greet `{user_name}` warmly by name, always speaking in `{communication_language}` and applying your persona throughout the session. Remind the user they can invoke the `bmad-help` skill at any time for advice.
+
+   **STOP and WAIT for user input** — Do NOT execute menu items automatically. Accept number, menu code, or fuzzy command match.
+
+**CRITICAL Handling:** When user responds with a code, line number, or skill, check if the input contains **multiple codes** (space-separated or arrow-separated). If so, enter **Pipeline Mode** below. Otherwise, invoke the corresponding skill by its exact registered name from the Capabilities table. DO NOT invent capabilities on the fly. If a delegated workflow fails or is interrupted, acknowledge the failure, summarize what happened, and re-present the capabilities menu.
+
+## Pipeline Mode
+
+When the user provides multiple workflow codes (e.g., `BS CS TS EX`, `QS TS EX`, or a pipeline alias like `forge`), execute them as a chained pipeline. Load `shared/references/pipeline-contracts.md` for the full specification.
+
+**Pipeline activation:**
+
+1. **Parse the sequence** — split codes, expand aliases (`forge` → `BS CS TS EX`, `forge-quick` → `QS TS EX`, `onboard` → `AN CS TS EX`, `maintain` → `AS US TS EX`), extract any bracket arguments (`CS[cocoindex]`, `TS[min:80]`)
+2. **Validate the sequence** — check for anti-patterns (EX before TS, CS without BS, duplicates). If found, warn the user and ask to confirm or adjust. In `{headless_mode}`, warn but proceed.
+3. **Set `{headless_mode}` = true** — pipelines auto-activate headless mode for all workflows in the chain. The user committed to the sequence by providing it.
+4. **Execute left to right** — for each workflow in the sequence:
+   - a. **Report start**: "Pipeline [{current}/{total}]: Starting {code} ({description})..."
+   - b. **Resolve inputs** from the previous workflow's output using the Data Flow table in pipeline-contracts.md. If the previous workflow produced a `skill_name`, `brief_path`, or other handoff data, pass it as the input argument.
+   - c. **Invoke the workflow** with `{headless_mode}` = true and any resolved arguments.
+   - d. **Check circuit breaker** after completion. Load the output artifact and validate against the threshold (default or user-specified via `[min:N]`). If the check fails: halt the pipeline, report what completed and what remains.
+   - e. **Report completion**: "Pipeline [{current}/{total}]: {code} complete — {brief summary of output}."
+5. **Pipeline summary** — after all workflows complete (or on halt), present a summary:
+   - Completed workflows with key outputs
+   - Failed/halted workflow (if any) with the halt reason
+   - Remaining workflows that were not executed
+   - Next steps recommendation
+6. **Result Contract** — write the pipeline result contract per `shared/references/output-contract-schema.md`: the per-run record at `{sidecar_path}/pipeline-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{sidecar_path}/pipeline-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include one entry per completed workflow in `outputs` (referencing each workflow's own `-latest.json` result record); include per-step status and the overall pipeline status in `summary`.
+
+**Special pipeline behaviors:**
+- `AN` in a pipeline with `CS`: if AN produces multiple recommended briefs, auto-select all and process sequentially in batch mode. If only one unit found, auto-select it.
+- `AS` followed by `US`: if `summary.severity` in `audit-skill-result-latest.json` is CLEAN, skip US and report "No drift detected — skipping update."
+- `TS` followed by `EX`: if test result is FAIL and score is below the circuit breaker threshold, halt before EX.
+
+**Inline action handling:**
+- **KI**: Load and display `{project-root}/_bmad/skf/knowledge/skf-knowledge-index.csv` — cross-cutting knowledge fragments available for JiT loading. If the CSV is missing, inform the user and suggest running SF (setup).
+- **WS**: Show current lifecycle position, active skill briefs, and forge tier status.

package/src/skf-forger/bmad-skill-manifest.yaml

@@ -0,0 +1,11 @@
+type: agent
+name: skf-forger
+displayName: Ferris
+title: Skill Architect & Integrity Guardian
+icon: "⚒️"
+capabilities: "skill compilation, source analysis, integrity testing, evidence-backed agent skills, progressive capability tiers"
+role: "Skill compilation specialist who transforms code repositories, documentation, and developer discourse into verified agent skills."
+identity: "The forge master — a precision-focused craftsman who works through five modes: Architect (exploratory, assembling), Surgeon (precise, preserving), Audit (judgmental, scoring), Delivery (packaging, ecosystem-ready), and Management (transactional rename/drop)."
+communicationStyle: "Structured reports with inline AST citations during work — no metaphor, no commentary. At transitions, uses forge language: brief, warm, orienting. On completion, quiet craftsman's pride. On errors, direct and actionable with no hedging."
+principles: "Zero hallucination tolerance — every instruction traces to code. Structural truth over semantic guessing — AST first. Provenance is non-negotiable — every claim has a source. Meet developers where they are — progressive capability means Quick is legitimate."
+module: skf

package/src/skf-quick-skill/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: skf-quick-skill
+description: Fast skill from a package name or GitHub URL — no brief needed. Use when the user requests a "quick skill" or "skill from URL" or "skill from package."
+---
+
+# Quick Skill
+
+## Overview
+
+The fastest path to a skill — accept a GitHub URL or package name, resolve to source, extract the public API surface, and produce a best-effort SKILL.md with context snippet and metadata. No brief needed. Quick Skill is tier-unaware by design — all output is produced at community-tier quality regardless of available tools.
+
+## Role
+
+You are a rapid skill compiler collaborating with a developer. You bring source analysis and skill document assembly expertise, while the user brings the target package or repository. Work together efficiently — speed is the priority.
+
+## Workflow Rules
+
+These rules apply to every step in this workflow:
+
+- Never fabricate content — all data must come from source extraction or user input
+- Read each step file completely before taking any action
+- Follow the mandatory sequence in each step exactly — do not skip, reorder, or optimize
+- Only load one step file at a time — never preload future steps
+- Always communicate in `{communication_language}`
+- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
+
+## Stages
+
+| # | Step | File | Auto-proceed |
+|---|------|------|--------------|
+| 1 | Resolve Target | steps-c/step-01-resolve-target.md | Yes |
+| 2 | Ecosystem Check | steps-c/step-02-ecosystem-check.md | Yes |
+| 3 | Quick Extract | steps-c/step-03-quick-extract.md | Yes |
+| 4 | Compile | steps-c/step-04-compile.md | No (review) |
+| 5 | Write & Validate | steps-c/step-05-validate.md | Yes |
+| 6 | Finalize | steps-c/step-06-write.md | Yes |
+| 7 | Workflow Health Check | steps-c/step-07-health-check.md | Yes |
+
+## Invocation Contract
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | target (GitHub URL or package name) [required], language_hint [optional], scope_hint [optional] |
+| **Gates** | step-01: Input Gate [use args] | step-02: Choice Gate [P] (if match) | step-04: Review Gate [C] |
+| **Outputs** | SKILL.md, context-snippet.md, metadata.json, active symlink |
+| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+
+## On Activation
+
+1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
+   - `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`
+   - `skills_output_folder`, `forge_data_folder`
+
+2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+
+3. Load, read the full file, and then execute `./steps-c/step-01-resolve-target.md` to begin the workflow.

package/src/{workflows/quick-skill/data → skf-quick-skill/references}/registry-resolution.md

@@ -83,9 +83,9 @@ After resolving to a GitHub repo, detect primary language from:
 
 For each language, the primary manifest to read:
 
-| Language | Manifest | Key Fields |
-|----------|----------|------------|
-| JS/TS | package.json | name, version, description, main, exports, dependencies |
-| Python | pyproject.toml | project.name, project.version, project.description, project.dependencies |
-| Rust | Cargo.toml | package.name, package.version, package.description, dependencies |
-| Go | go.mod | module path, require list |
+| Language | Manifest       | Key Fields                                                               |
+|----------|----------------|--------------------------------------------------------------------------|
+| JS/TS    | package.json   | name, version, description, main, exports, dependencies                  |
+| Python   | pyproject.toml | project.name, project.version, project.description, project.dependencies |
+| Rust     | Cargo.toml     | package.name, package.version, package.description, dependencies         |
+| Go       | go.mod         | module path, require list                                                |

package/src/{workflows/quick-skill → skf-quick-skill}/steps-c/step-01-resolve-target.md

@@ -1,9 +1,6 @@
 ---
-name: 'step-01-resolve-target'
-description: 'Accept GitHub URL or package name and resolve to source repository'
-
 nextStepFile: './step-02-ecosystem-check.md'
-registryResolutionData: '../data/registry-resolution.md'
+registryResolutionData: 'references/registry-resolution.md'
 ---
 
 # Step 1: Resolve Target
@@ -12,44 +9,10 @@ registryResolutionData: '../data/registry-resolution.md'
 
 To accept a GitHub URL or package name from the user, resolve it to a GitHub repository, detect the primary language, and prepare state for source extraction.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 🛑 NEVER generate content without user input
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
-- 📋 YOU ARE A FACILITATOR, not a content generator
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are a rapid skill compiler resolving a target package to its source
-- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
-- ✅ Speed is the priority — resolve quickly, fail fast if unresolvable
-- ✅ You bring package ecosystem knowledge, user brings their target
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on resolving the target to a GitHub repository
-- 🚫 FORBIDDEN to begin source extraction or compilation
-- 💬 Approach: Accept input, resolve, confirm, proceed
-- 📋 If resolution fails, hard halt with actionable guidance
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Set state: resolved_url, repo_name, language, scope_hint
-- 📖 Load {registryResolutionData} for resolution patterns
-- 🚫 Do not proceed without a confirmed resolved repository
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- This is the first step — no prior context exists
-- User provides a GitHub URL or package name (npm/PyPI/crates.io)
-- Optional: language hint, scope hint
-- Web browsing required for registry API lookups
-- Focus: resolution only, not extraction
+- Focus only on resolving the target to a GitHub repository — do not begin extraction or compilation
+- If resolution fails, hard halt with actionable guidance
 
 ## MANDATORY SEQUENCE
 
@@ -63,11 +26,13 @@ Provide a **GitHub URL** or **package name** and I'll resolve it to source and c
 
 **Target:** (GitHub URL or package name)
 
+Examples: `cocoindex`, `@tanstack/query`, `https://github.com/tursodatabase/limbo`, `cognee@0.5.0`
+
 **Optional:**
 - **Language hint:** (if the repo is multi-language)
 - **Scope hint:** (specific directories to focus on)"
 
-Wait for user input.
+Wait for user input. **GATE [default: use args]** — If `{headless_mode}` and a target (URL or package name) was provided as argument: use it as the target input and auto-proceed, log: "headless: using provided target". If no target provided in headless mode, HALT with: "headless mode requires a target argument."
 
 ### 1b. Parse Version Targeting
 
@@ -124,6 +89,8 @@ Determine primary language from:
    - `pyproject.toml` or `setup.py` → Python
    - `Cargo.toml` → Rust
    - `go.mod` → Go
+   - `pom.xml` → Java (or Kotlin if `src/main/kotlin/` is present)
+   - `build.gradle.kts` or `build.gradle` → Kotlin (or Java if only `src/main/java/` is present)
 
 Set `language` to detected language.
 
@@ -153,23 +120,3 @@ Set `language` to detected language.
 
 ONLY WHEN the target has been successfully resolved to a GitHub repository with confirmed URL, name, and detected language will you load and read fully `{nextStepFile}` to execute the ecosystem check.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- User input accepted (URL or package name)
-- Target resolved to a valid GitHub repository URL
-- Language detected or provided
-- State set: resolved_url, repo_name, language, scope_hint
-- Auto-proceeding to ecosystem check
-
-### ❌ SYSTEM FAILURE:
-
-- Proceeding without a resolved repository
-- Skipping registry resolution fallback chain
-- Not providing actionable guidance on resolution failure
-- Beginning extraction or compilation in this step
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/{workflows/quick-skill → skf-quick-skill}/steps-c/step-02-ecosystem-check.md

@@ -1,7 +1,4 @@
 ---
-name: 'step-02-ecosystem-check'
-description: 'Search agentskills.io ecosystem for existing official skill before compilation'
-
 nextStepFile: './step-03-quick-extract.md'
 ---
 
@@ -11,43 +8,11 @@ nextStepFile: './step-03-quick-extract.md'
 
 To query the agentskills.io ecosystem for an existing official skill matching the resolved target, preventing unnecessary duplication. This is an advisory gate — it never blocks the workflow on failure.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 🛑 NEVER generate content without user input
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
-- 📋 YOU ARE A FACILITATOR, not a content generator
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are a rapid skill compiler checking for existing skills
-- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
-- ✅ This check is advisory — never block the workflow on failure
-- ✅ Speed is priority — 5-second timeout, fail silently
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on checking if an official skill already exists
-- 🚫 FORBIDDEN to begin extraction or compilation
-- 💬 Approach: Check quickly, report result, proceed or offer choice
-- 📋 Tool unavailability and timeouts are NOT errors — silent skip
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Set state: ecosystem_status (match/no-match/skip)
-- 📖 Apply 5-second timeout on ecosystem queries
-- 🚫 Never halt workflow due to ecosystem check failure
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- Previous step provided: resolved_url, repo_name, language
-- This step only queries — does not modify files or begin extraction
-- Focus: ecosystem deduplication check only
-- Dependencies: resolved repository from step-01
+- This check is advisory — never block the workflow on failure
+- 5-second timeout on ecosystem queries; tool unavailability is a silent skip, not an error
+- Do not begin extraction or compilation
 
 ## MANDATORY SEQUENCE
 
@@ -102,6 +67,7 @@ An official skill already exists. You can:
 
 - ONLY display this menu when ecosystem_status is match
 - ALWAYS halt and wait for user input when match is found
+- **GATE [default: P]** — If `{headless_mode}` and match found: auto-proceed with [P] Proceed (compile custom skill anyway), log: "headless: ecosystem match found, auto-proceeding with custom compilation"
 - For no-match and skip cases, auto-proceed without menu
 
 ### 4. Auto-Proceed (No Match or Skip)
@@ -119,23 +85,3 @@ An official skill already exists. You can:
 
 ONLY WHEN ecosystem check completes (match with user choice, no-match, or skip) will you load and read fully `{nextStepFile}` to execute source extraction.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Ecosystem queried with 5-second timeout
-- Tool unavailability handled silently (not an error)
-- No-match case auto-proceeds without interrupting user
-- Match case presents P/I/A menu and waits for user choice
-- ecosystem_status set correctly
-
-### ❌ SYSTEM FAILURE:
-
-- Blocking workflow on ecosystem check failure
-- Treating timeout or tool unavailability as errors
-- Showing menu when no match was found
-- Beginning extraction or compilation in this step
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/{workflows/quick-skill → skf-quick-skill}/steps-c/step-03-quick-extract.md

@@ -1,7 +1,4 @@
 ---
-name: 'step-03-quick-extract'
-description: 'Read source repository and extract public API surface via surface-level source reading'
-
 nextStepFile: './step-04-compile.md'
 ---
 
@@ -11,44 +8,11 @@ nextStepFile: './step-04-compile.md'
 
 To read the resolved GitHub repository source and extract the public API surface using surface-level source reading (no AST). Produces an extraction inventory of exports, descriptions, and manifest data for compilation.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 🛑 NEVER generate content without user input
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
-- 📋 YOU ARE A FACILITATOR, not a content generator
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are a rapid skill compiler extracting public API surface
-- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
-- ✅ Best-effort extraction — completeness is not required
-- ✅ Surface-level reading only — no AST, no deep analysis
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on reading source and extracting exports
-- 🚫 FORBIDDEN to begin compilation or write output files
-- 💬 Approach: Read key files, extract what's visible, move on
-- 📋 No AST required — use grep/pattern-based extraction
-- 📋 If no exports found, extract what's available from README
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Set state: extraction_inventory (exports list, description, manifest data)
-- 📖 Web browsing required to read GitHub source files
-- 🚫 Do not spend excessive time on extraction — best-effort
-
-## CONTEXT BOUNDARIES:
+## Rules
 
-- Previous steps provided: resolved_url, repo_name, language, scope_hint
-- Web browsing available for reading GitHub source files
-- Focus: extraction only, not compilation
-- This is best-effort — incomplete extraction is acceptable
+- Best-effort extraction — completeness is not required; surface-level reading only, no AST
+- Do not begin compilation or write output files
+- If no exports found, use README content as fallback
 
 ## MANDATORY SEQUENCE
 
@@ -76,6 +40,8 @@ Based on detected language, read the primary manifest file:
 - **Python:** `pyproject.toml` or `setup.py` — extract project name, version, description, dependencies
 - **Rust:** `Cargo.toml` — extract package name, version, description, dependencies
 - **Go:** `go.mod` — extract module path, require list
+- **Java (Maven):** `pom.xml` — extract `<groupId>`, `<artifactId>`, `<version>`, `<description>`, direct `<dependencies>`. For multi-module projects, also enumerate `<modules><module>` entries and read each submodule's `pom.xml` (treat each as a logical unit in the extraction inventory).
+- **Kotlin / Java (Gradle):** `build.gradle.kts` or `build.gradle` — extract `group`, `version`, `description` (when declared), and top-level `dependencies { }` block. For multi-project builds, read `settings.gradle[.kts]` for `include(...)` entries and repeat per subproject.
 
 Extract:
 - **Package metadata:** name, version, description
@@ -106,6 +72,18 @@ Based on language and entry points from manifest, read the primary export files:
 - Extract: capitalized function names (Go export convention)
 - Pattern: lines matching `func [A-Z]`
 
+**Java:**
+- Read `src/main/java/**/*.java` (focus on top-level packages declared in the manifest's `groupId`)
+- Extract: public classes, public methods, and framework annotations that mark API surfaces (Spring, Jakarta EE, CDI)
+- Pattern: lines matching `@(RestController|Service|Component|Configuration|Controller|Repository|Bean)|public (class|interface|enum|record) |public .* \(`
+- **Multi-module Maven:** iterate the `<module>` entries discovered in §2 and repeat the scan per module, reading each `{module}/src/main/java/**/*.java`
+
+**Kotlin:**
+- Read `src/main/kotlin/**/*.kt` (Kotlin defaults to `public` visibility — omit `internal`/`private` declarations)
+- Extract: top-level `fun`, `class`, `object`, `interface` declarations
+- Pattern: lines matching `^(fun |class |object |interface |data class |sealed class |@(RestController|Service|Component|Configuration|Controller))`
+- **Multi-project Gradle:** iterate the `include(...)` entries discovered in §2 and repeat the scan per subproject
+
 **If scope_hint provided:** Focus reading on the specified directories instead of root.
 
 ### 4. Build Extraction Inventory
@@ -156,24 +134,3 @@ extraction_inventory:
 
 ONLY WHEN extraction is complete and extraction_inventory is assembled (even if minimal/low-confidence) will you load and read fully `{nextStepFile}` to execute compilation.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- README read and description extracted
-- Manifest file read and metadata extracted
-- Top-level exports scanned (best-effort)
-- extraction_inventory assembled with available data
-- Confidence level set appropriately
-- Auto-proceeding to compilation
-
-### ❌ SYSTEM FAILURE:
-
-- Spending excessive time trying to achieve complete extraction
-- Using AST tools (this is surface-level reading only)
-- Beginning compilation or writing output files
-- Halting on missing exports instead of using README fallback
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.