bmad-module-skill-forge 0.2.0

package/src/workflows/quick-skill/data/registry-resolution.md

@@ -0,0 +1,91 @@
+# Registry Resolution Patterns
+
+## Package-to-Repo Resolution
+
+When the user provides a package name instead of a GitHub URL, use this fallback chain to resolve the source repository.
+
+### Detection: URL vs Package Name
+
+- **GitHub URL:** Starts with `https://github.com/` or `github.com/` — extract org/repo directly
+- **Package name:** Everything else — enter resolution chain below
+
+### Resolution Fallback Chain
+
+Try each registry in order. Stop at first success.
+
+#### 1. npm Registry (JavaScript/TypeScript)
+
+```
+URL: https://registry.npmjs.org/{package_name}
+Field: repository.url
+Fallback field: homepage
+```
+
+Extract `repository.url`, strip `git+` prefix and `.git` suffix if present.
+
+#### 2. PyPI Registry (Python)
+
+```
+URL: https://pypi.org/pypi/{package_name}/json
+Field: info.project_urls.Source OR info.project_urls.Repository OR info.home_page
+```
+
+Check `project_urls` keys in order: Source, Repository, Homepage. Filter for GitHub URLs.
+
+#### 3. crates.io Registry (Rust)
+
+```
+URL: https://crates.io/api/v1/crates/{package_name}
+Field: crate.repository
+```
+
+Direct `repository` field usually points to GitHub.
+
+#### 4. Web Search Fallback
+
+If all registry lookups fail:
+
+```
+Search: "{package_name} github repository"
+```
+
+Look for GitHub URL in top results. Verify it matches the package name.
+
+#### 5. Resolution Failure
+
+If all methods fail:
+
+```
+"Could not resolve '{package_name}' to a GitHub repository.
+
+Please provide the GitHub URL directly, or check:
+- Is the package name spelled correctly?
+- Is it a private package?
+- Is the source hosted on a non-GitHub platform?"
+```
+
+**Hard halt** — cannot proceed without a resolved source.
+
+## Language Detection
+
+After resolving to a GitHub repo, detect primary language from:
+
+1. Manifest file presence:
+   - `package.json` → JavaScript/TypeScript
+   - `pyproject.toml` or `setup.py` → Python
+   - `Cargo.toml` → Rust
+   - `go.mod` → Go
+   - `pom.xml` or `build.gradle` → Java
+2. User-provided language hint (overrides detection)
+3. GitHub API language field (if accessible)
+
+## Manifest File Priority
+
+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 |

package/src/workflows/quick-skill/data/skill-template.md

@@ -0,0 +1,66 @@
+# Skill Template — Quick Skill Output
+
+## SKILL.md Section Structure
+
+The following sections should be populated in the generated SKILL.md. Best-effort — not all sections will have data for every skill.
+
+### Required Sections
+
+```markdown
+# {skill_name}
+
+## Overview
+- **Package:** {package_name}
+- **Repository:** {repo_url}
+- **Language:** {language}
+- **Source Authority:** community
+- **Generated:** {date}
+
+## Description
+{README-derived description of what the package does}
+
+## Key Exports
+{List of public exports with brief descriptions}
+
+## Usage Patterns
+{Common usage patterns extracted from README examples}
+```
+
+### Optional Sections (include when data available)
+
+```markdown
+## Configuration
+{Configuration options if found in source}
+
+## Dependencies
+{Key dependencies from manifest file}
+
+## Notes
+{Any caveats, limitations, or observations about the extraction}
+```
+
+## context-snippet.md Format (ADR-L)
+
+Two-line format targeting ~30 tokens per skill:
+
+```markdown
+{skill_name}: {top-5 exports as comma-separated list}
+  → {skills_output_folder}/{skill_name}/SKILL.md
+```
+
+## metadata.json Format
+
+```json
+{
+  "name": "{skill_name}",
+  "version": "0.1.0",
+  "source_authority": "community",
+  "source_repo": "{repo_url}",
+  "source_package": "{package_name}",
+  "language": "{language}",
+  "generated_by": "quick-skill",
+  "generated_date": "{date}",
+  "exports_count": {number},
+  "confidence": "best-effort"
+}
+```

package/src/workflows/quick-skill/steps-c/step-01-resolve-target.md

@@ -0,0 +1,165 @@
+---
+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'
+---
+
+# Step 1: Resolve Target
+
+## STEP GOAL:
+
+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
+
+## 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
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Accept User Input
+
+"**Quick Skill — fastest path to a skill.**
+
+Provide a **GitHub URL** or **package name** and I'll resolve it to source and compile a best-effort SKILL.md.
+
+**Target:** (GitHub URL or package name)
+
+**Optional:**
+- **Language hint:** (if the repo is multi-language)
+- **Scope hint:** (specific directories to focus on)"
+
+Wait for user input.
+
+### 2. Classify Input Type
+
+**If input starts with `https://github.com/` or `github.com/`:**
+- Extract org/repo from URL
+- Set `resolved_url` to the GitHub URL
+- Set `repo_name` to the repo name (last path segment)
+- Skip to step 4 (Detect Language)
+
+**If input is a package name:**
+- Proceed to step 3 (Registry Resolution)
+
+### 3. Registry Resolution
+
+Load {registryResolutionData} for resolution patterns.
+
+**Execute the fallback chain in order — stop at first success:**
+
+1. **npm registry:** Fetch `https://registry.npmjs.org/{package_name}` — extract `repository.url`
+2. **PyPI registry:** Fetch `https://pypi.org/pypi/{package_name}/json` — extract `info.project_urls.Source` or `info.home_page`
+3. **crates.io registry:** Fetch `https://crates.io/api/v1/crates/{package_name}` — extract `crate.repository`
+4. **Web search fallback:** Search `"{package_name} github repository"` — look for GitHub URL
+
+**If all methods fail — HARD HALT:**
+
+"**Resolution failed.** Could not resolve `{package_name}` to a GitHub repository.
+
+Please check:
+- Is the package name spelled correctly?
+- Is it a private package?
+- Is the source hosted on a non-GitHub platform?
+
+**Provide the GitHub URL directly to continue.**"
+
+Wait for corrected input. Loop back to step 2.
+
+### 4. Detect Language
+
+Determine primary language from:
+
+1. **User-provided language hint** (overrides detection)
+2. **Manifest file presence** (check via GitHub API or web browsing):
+   - `package.json` → JavaScript/TypeScript
+   - `pyproject.toml` or `setup.py` → Python
+   - `Cargo.toml` → Rust
+   - `go.mod` → Go
+
+Set `language` to detected language.
+
+### 5. Confirm Resolution
+
+"**Target resolved:**
+
+- **Repository:** {resolved_url}
+- **Name:** {repo_name}
+- **Language:** {language}
+- **Scope:** {scope_hint or 'entire repo'}
+
+**Proceeding to ecosystem check...**"
+
+### 6. Proceed to Next Step
+
+#### Menu Handling Logic:
+
+- After successful resolution confirmation, immediately load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+
+- This is an init step with auto-proceed after successful resolution
+- Proceed directly to next step after confirmation
+
+## CRITICAL STEP COMPLETION NOTE
+
+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/steps-c/step-02-ecosystem-check.md

@@ -0,0 +1,143 @@
+---
+name: 'step-02-ecosystem-check'
+description: 'Search agentskills.io ecosystem for existing official skill before compilation'
+
+nextStepFile: './step-03-quick-extract.md'
+---
+
+# Step 2: Ecosystem Check
+
+## STEP GOAL:
+
+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
+
+## 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
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Query Ecosystem
+
+Search for an existing official skill matching `{repo_name}` in the agentskills.io ecosystem.
+
+**Query methods (try in order):**
+1. Search agentskills.io registry for `{repo_name}`
+2. Web search: `"agentskills.io" "{repo_name}" skill`
+
+**Apply 5-second timeout.** If query takes longer, treat as no-match.
+
+### 2. Evaluate Result
+
+**If tool unavailable or timeout:**
+- Set `ecosystem_status: skip`
+- Proceed silently to step 3 (auto-proceed, no message to user)
+
+**If no match found:**
+- Set `ecosystem_status: no-match`
+- Auto-proceed to step 3:
+
+"**No existing official skill found for {repo_name}. Proceeding to extraction...**"
+
+**If match found:**
+- Set `ecosystem_status: match`
+- Display match details and present conditional menu:
+
+"**Existing official skill found for {repo_name}.**
+
+**Skill:** {matched_skill_name}
+**Source:** agentskills.io
+**Authority:** official
+
+An official skill already exists. You can:
+
+**[P] Proceed** — Compile a custom community skill anyway (different scope or customization)
+**[I] Install** — Install the existing official skill instead (exits this workflow)
+**[A] Abort** — Cancel compilation"
+
+### 3. Handle Match Menu (ONLY if match found)
+
+#### Menu Handling Logic:
+
+- IF P: Set `ecosystem_status: match-proceed`, then load, read entire file, then execute {nextStepFile}
+- IF I: Display install instructions for the official skill, then end workflow
+- IF A: Display "Compilation cancelled." and end workflow
+- IF Any other: help user, then redisplay the match menu
+
+#### EXECUTION RULES:
+
+- ONLY display this menu when ecosystem_status is match
+- ALWAYS halt and wait for user input when match is found
+- For no-match and skip cases, auto-proceed without menu
+
+### 4. Auto-Proceed (No Match or Skip)
+
+#### Menu Handling Logic:
+
+- After no-match or skip determination, immediately load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+
+- This is an auto-proceed path — no user interaction needed
+- Proceed directly to extraction step
+
+## CRITICAL STEP COMPLETION NOTE
+
+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/steps-c/step-03-quick-extract.md

@@ -0,0 +1,177 @@
+---
+name: 'step-03-quick-extract'
+description: 'Read source repository and extract public API surface via surface-level source reading'
+
+nextStepFile: './step-04-compile.md'
+---
+
+# Step 3: Quick Extract
+
+## STEP GOAL:
+
+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:
+
+- 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
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Read README
+
+Read `README.md` from the repository root via web browsing.
+
+Extract:
+- **Description:** What the package does (first paragraph or tagline)
+- **Features:** Key features or capabilities listed
+- **Usage patterns:** Code examples showing common usage
+- **Installation:** Package manager install command (confirms package name)
+
+If README is unavailable, note and continue.
+
+### 2. Read Manifest File
+
+Based on detected language, read the primary manifest file:
+
+- **JavaScript/TypeScript:** `package.json` — extract name, version, description, main, exports, dependencies
+- **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
+
+Extract:
+- **Package metadata:** name, version, description
+- **Entry points:** main, exports, module fields
+- **Key dependencies:** direct dependencies list
+
+### 3. Scan Top-Level Exports
+
+Based on language and entry points from manifest, read the primary export files:
+
+**JavaScript/TypeScript:**
+- Read `index.js`, `index.ts`, `src/index.ts`, or `main` field from package.json
+- Extract: `export` statements, `module.exports` assignments
+- Pattern: lines matching `export (const|function|class|default|type|interface)`
+
+**Python:**
+- Read `__init__.py` or `src/{package}/__init__.py`
+- Extract: `__all__` list, top-level function/class definitions
+- Pattern: lines matching `def |class |__all__`
+
+**Rust:**
+- Read `src/lib.rs`
+- Extract: `pub fn`, `pub struct`, `pub enum`, `pub trait` declarations
+- Pattern: lines matching `pub (fn|struct|enum|trait|mod)`
+
+**Go:**
+- Read exported functions from top-level `.go` files
+- Extract: capitalized function names (Go export convention)
+- Pattern: lines matching `func [A-Z]`
+
+**If scope_hint provided:** Focus reading on the specified directories instead of root.
+
+### 4. Build Extraction Inventory
+
+Assemble the extraction inventory from collected data:
+
+```
+extraction_inventory:
+  description: {from README or manifest}
+  package_name: {from manifest}
+  version: {from manifest}
+  language: {detected}
+  exports: [{name, type, brief_description}]
+  usage_patterns: [{pattern from README examples}]
+  dependencies: [{key deps from manifest}]
+  confidence: {high/medium/low based on data quality}
+```
+
+**If no exports found:**
+- Set confidence to `low`
+- Use README description and features as fallback content
+- Note: "No exports detected — SKILL.md will be based on README content only"
+
+### 5. Report Extraction Summary
+
+"**Extraction complete:**
+
+- **Package:** {package_name} v{version}
+- **Language:** {language}
+- **Exports found:** {count}
+- **Confidence:** {confidence}
+- **Source files read:** {count}
+
+**Proceeding to compilation...**"
+
+### 6. Auto-Proceed to Compilation
+
+#### Menu Handling Logic:
+
+- After extraction summary, immediately load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+
+- This is an auto-proceed step — extraction results flow directly to compilation
+- Proceed directly to next step after summary
+
+## CRITICAL STEP COMPLETION NOTE
+
+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.