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

package/src/shared/scripts/skf-validate-frontmatter.py

@@ -0,0 +1,318 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = ["pyyaml"]
+# ///
+"""SKF Validate Frontmatter — agentskills.io frontmatter compliance checker.
+
+Validates SKILL.md frontmatter against the agentskills.io specification.
+Aligned with the canonical reference implementation at
+agentskills/agentskills/skills-ref/src/skills_ref/validator.py.
+
+Designed for pre-check use in test-skill, create-skill, update-skill, and
+export-skill workflows. Returns structured JSON for deterministic integration.
+
+CLI:
+  python3 skf-validate-frontmatter.py <skill-md-path>
+  python3 skf-validate-frontmatter.py <skill-md-path> --skill-dir-name <name>
+
+Input:
+  Path to a SKILL.md file.
+  Optional --skill-dir-name: expected directory name for name-match check.
+  If omitted, derived from the parent directory of the SKILL.md path.
+
+Output:
+  JSON object:
+    status:     "pass" | "fail" | "warn"
+    issues:     list of { severity, field, message }
+    frontmatter: parsed frontmatter dict (if parseable)
+    summary:    { total, high, medium, low }
+
+Exit codes:
+  0  — pass (no high-severity issues)
+  1  — fail (high-severity issues found) or error
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import unicodedata
+from pathlib import Path
+
+import yaml
+
+# agentskills.io permitted frontmatter fields (matches canonical validator.py)
+ALLOWED_FIELDS = frozenset({
+    "name", "description", "license", "compatibility", "metadata", "allowed-tools",
+})
+
+MAX_SKILL_NAME_LENGTH = 64
+MAX_DESCRIPTION_LENGTH = 1024
+MAX_COMPATIBILITY_LENGTH = 500
+
+
+def parse_frontmatter(content: str) -> tuple[dict | None, list[dict]]:
+    """Extract and parse YAML frontmatter from SKILL.md content.
+
+    Returns (parsed_dict, issues). If frontmatter is structurally broken,
+    parsed_dict is None and issues contains the structural error.
+    """
+    issues: list[dict] = []
+
+    if not content.startswith("---\n") and not content.startswith("---\r\n"):
+        issues.append({
+            "severity": "high",
+            "field": "frontmatter",
+            "message": "Missing opening --- delimiter",
+        })
+        return None, issues
+
+    # Find closing --- on its own line (not a substring inside YAML values)
+    closing_idx = -1
+    search_start = content.index("\n") + 1  # skip past opening ---\n
+    for i, line in enumerate(content[search_start:].split("\n")):
+        if line.rstrip("\r") == "---":
+            closing_idx = search_start + sum(len(l) + 1 for l in content[search_start:].split("\n")[:i])
+            break
+    if closing_idx == -1:
+        issues.append({
+            "severity": "high",
+            "field": "frontmatter",
+            "message": "Missing closing --- delimiter",
+        })
+        return None, issues
+
+    # Extract text between opening and closing delimiters
+    fm_text = content[search_start:closing_idx]
+
+    # Parse with PyYAML for proper YAML handling (nested metadata, multi-line values)
+    try:
+        fm = yaml.safe_load(fm_text)
+    except yaml.YAMLError as exc:
+        issues.append({
+            "severity": "high",
+            "field": "frontmatter",
+            "message": f"Invalid YAML in frontmatter: {exc}",
+        })
+        return None, issues
+
+    if fm is None:
+        # Empty frontmatter block
+        fm = {}
+
+    if not isinstance(fm, dict):
+        issues.append({
+            "severity": "high",
+            "field": "frontmatter",
+            "message": "Frontmatter must be a YAML mapping",
+        })
+        return None, issues
+
+    # Normalize metadata sub-dict values to strings (matches canonical parser.py)
+    if "metadata" in fm and isinstance(fm["metadata"], dict):
+        fm["metadata"] = {str(k): str(v) for k, v in fm["metadata"].items()}
+
+    return fm, issues
+
+
+def _validate_name(name: str, skill_dir_name: str | None) -> list[dict]:
+    """Validate skill name format. Aligned with canonical validator.py."""
+    issues: list[dict] = []
+
+    if not name or not isinstance(name, str) or not name.strip():
+        issues.append({
+            "severity": "high",
+            "field": "name",
+            "message": "name field missing or empty",
+        })
+        return issues
+
+    name = unicodedata.normalize("NFKC", name.strip())
+
+    if len(name) > MAX_SKILL_NAME_LENGTH:
+        issues.append({
+            "severity": "high",
+            "field": "name",
+            "message": f"name exceeds {MAX_SKILL_NAME_LENGTH} chars ({len(name)} chars)",
+        })
+
+    if name != name.lower():
+        issues.append({
+            "severity": "high",
+            "field": "name",
+            "message": f"name '{name}' must be lowercase",
+        })
+
+    if name.startswith("-") or name.endswith("-"):
+        issues.append({
+            "severity": "high",
+            "field": "name",
+            "message": "name cannot start or end with a hyphen",
+        })
+
+    if "--" in name:
+        issues.append({
+            "severity": "high",
+            "field": "name",
+            "message": "name cannot contain consecutive hyphens",
+        })
+
+    if not all(c.isalnum() or c == "-" for c in name):
+        issues.append({
+            "severity": "high",
+            "field": "name",
+            "message": f"name '{name}' contains invalid characters (only letters, digits, and hyphens allowed)",
+        })
+
+    # Directory name match (with Unicode normalization)
+    if skill_dir_name:
+        dir_name = unicodedata.normalize("NFKC", skill_dir_name)
+        if dir_name != name:
+            issues.append({
+                "severity": "high",
+                "field": "name",
+                "message": f"name '{name}' does not match directory name '{skill_dir_name}'",
+            })
+
+    return issues
+
+
+def validate_frontmatter(
+    content: str,
+    skill_dir_name: str | None = None,
+) -> dict:
+    """Validate SKILL.md frontmatter against agentskills.io spec.
+
+    Returns a result dict with status, issues, frontmatter, and summary.
+    """
+    fm, issues = parse_frontmatter(content)
+
+    if fm is not None:
+        # Name validation
+        name = fm.get("name", "")
+        issues.extend(_validate_name(name, skill_dir_name))
+
+        # Description: required, non-empty, max 1024 chars
+        desc = fm.get("description", "")
+        if not desc or not isinstance(desc, str) or not desc.strip():
+            issues.append({
+                "severity": "high",
+                "field": "description",
+                "message": "description field missing or empty",
+            })
+        elif len(desc) > MAX_DESCRIPTION_LENGTH:
+            issues.append({
+                "severity": "medium",
+                "field": "description",
+                "message": f"description exceeds {MAX_DESCRIPTION_LENGTH} chars ({len(desc)} chars)",
+            })
+
+        # Compatibility: optional, max 500 chars
+        compat = fm.get("compatibility")
+        if compat is not None:
+            if not isinstance(compat, str):
+                issues.append({
+                    "severity": "medium",
+                    "field": "compatibility",
+                    "message": "compatibility must be a string",
+                })
+            elif len(compat) > MAX_COMPATIBILITY_LENGTH:
+                issues.append({
+                    "severity": "medium",
+                    "field": "compatibility",
+                    "message": f"compatibility exceeds {MAX_COMPATIBILITY_LENGTH} chars ({len(compat)} chars)",
+                })
+
+        # Unknown fields
+        for key in fm:
+            if key not in ALLOWED_FIELDS:
+                issues.append({
+                    "severity": "low",
+                    "field": key,
+                    "message": f"Unknown frontmatter field: '{key}'",
+                })
+
+    # Build summary
+    severity_counts = {"high": 0, "medium": 0, "low": 0}
+    for issue in issues:
+        severity_counts[issue["severity"]] += 1
+
+    if severity_counts["high"] > 0:
+        status = "fail"
+    elif severity_counts["medium"] > 0 or severity_counts["low"] > 0:
+        status = "warn"
+    else:
+        status = "pass"
+
+    return {
+        "status": status,
+        "issues": issues,
+        "frontmatter": fm,
+        "summary": {
+            "total": len(issues),
+            **severity_counts,
+        },
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="skf-validate-frontmatter.py",
+        description=(
+            "Validate SKILL.md frontmatter against agentskills.io specification.\n"
+            "\n"
+            "Checks: frontmatter delimiters, name format (Unicode letters + digits +\n"
+            "hyphens, no consecutive/trailing hyphens), name-directory match,\n"
+            "description presence and length, compatibility length, and unknown fields.\n"
+            "\n"
+            "Exit code 0 means pass (no high-severity issues).\n"
+            "Exit code 1 means fail (high-severity issues found)."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "skill_md",
+        metavar="SKILL.md",
+        help="path to the SKILL.md file to validate",
+    )
+    parser.add_argument(
+        "--skill-dir-name",
+        metavar="NAME",
+        default=None,
+        help="expected skill directory name (default: derived from parent directory)",
+    )
+    parser.add_argument(
+        "-o", "--output",
+        metavar="FILE",
+        help="write JSON output to FILE instead of stdout",
+    )
+
+    args = parser.parse_args()
+    skill_md_path = Path(args.skill_md)
+
+    if not skill_md_path.exists():
+        result = {
+            "status": "fail",
+            "issues": [{"severity": "high", "field": "file", "message": f"File not found: {skill_md_path}"}],
+            "frontmatter": None,
+            "summary": {"total": 1, "high": 1, "medium": 0, "low": 0},
+        }
+    else:
+        content = skill_md_path.read_text(encoding="utf-8")
+        skill_dir_name = args.skill_dir_name or skill_md_path.parent.name
+        result = validate_frontmatter(content, skill_dir_name)
+
+    output_text = json.dumps(result, indent=2)
+
+    if args.output:
+        out_path = Path(args.output)
+        out_path.write_text(output_text + "\n", encoding="utf-8")
+    else:
+        print(output_text)
+
+    return 0 if result["status"] != "fail" else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/shared/scripts/skf-validate-output.py

@@ -0,0 +1,247 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""SKF Validate Output — Validate skill package artifacts.
+
+Validates SKILL.md frontmatter, context-snippet.md format, and metadata.json
+schema against agentskills.io specification. Outputs JSON validation results.
+
+CLI: python3 skf-validate-output.py <skill-package-dir>
+     python3 skf-validate-output.py <skill-package-dir> --generated-by quick-skill
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+
+def validate_frontmatter(content, skill_name=None):
+    """Validate SKILL.md frontmatter. Returns list of issues."""
+    issues = []
+
+    # Check frontmatter delimiters
+    if not content.startswith("---\n"):
+        issues.append({"severity": "high", "field": "frontmatter", "message": "Missing opening --- delimiter"})
+        return issues
+
+    # Find closing --- on its own line (not a substring match inside YAML values)
+    end_idx = -1
+    for i, line in enumerate(content.split("\n")[1:], start=1):
+        if line.rstrip() == "---":
+            end_idx = sum(len(l) + 1 for l in content.split("\n")[:i])
+            break
+    if end_idx == -1:
+        issues.append({"severity": "high", "field": "frontmatter", "message": "Missing closing --- delimiter"})
+        return issues
+
+    fm_text = content[4:end_idx].strip()
+    fm = {}
+    for line in fm_text.split("\n"):
+        if ":" in line:
+            key, _, val = line.partition(":")
+            fm[key.strip()] = val.strip().strip("'\"")
+
+    # Required fields
+    name = fm.get("name", "")
+    if not name:
+        issues.append({"severity": "high", "field": "name", "message": "name field missing or empty"})
+    elif not re.match(r"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$", name) or len(name) > 64:
+        issues.append({"severity": "high", "field": "name", "message": f"name must be lowercase alphanumeric + hyphens, 1-64 chars, got: {name}"})
+
+    if skill_name and name and name != skill_name:
+        issues.append({"severity": "high", "field": "name", "message": f"name '{name}' does not match directory name '{skill_name}'"})
+
+    desc = fm.get("description", "")
+    if not desc:
+        issues.append({"severity": "high", "field": "description", "message": "description field missing or empty"})
+
+    # Allowed fields
+    allowed = {"name", "description", "license", "compatibility", "metadata", "allowed-tools"}
+    for key in fm:
+        if key not in allowed:
+            issues.append({"severity": "low", "field": key, "message": f"Unknown frontmatter field: {key}"})
+
+    return issues
+
+
+def validate_body_structure(content):
+    """Validate SKILL.md body has required sections. Returns list of issues."""
+    issues = []
+    body = content.split("---", 2)[-1] if content.startswith("---") else content
+
+    required_sections = ["Overview", "Key Exports", "Usage"]
+    for section in required_sections:
+        pattern = rf"^##\s+.*{re.escape(section)}"
+        if not re.search(pattern, body, re.MULTILINE | re.IGNORECASE):
+            issues.append({"severity": "medium", "field": f"section:{section}", "message": f"Missing ## {section} section"})
+
+    return issues
+
+
+def validate_context_snippet(content):
+    """Validate context-snippet.md format. Returns list of issues."""
+    issues = []
+
+    if not content or not content.strip():
+        issues.append({"severity": "high", "field": "content", "message": "Context snippet is empty"})
+        return issues
+
+    lines = content.strip().split("\n")
+
+    # First line: [name vVersion]|root: prefix
+    if lines:
+        first = lines[0]
+        if not re.match(r"\[.+ v.+\]\|root:", first):
+            issues.append({"severity": "medium", "field": "line1", "message": f"First line doesn't match expected pattern: [{first[:50]}...]"})
+
+    # Second line: |IMPORTANT:
+    if len(lines) > 1:
+        if not lines[1].startswith("|IMPORTANT:"):
+            issues.append({"severity": "medium", "field": "line2", "message": "Second line should start with |IMPORTANT:"})
+
+    # Approximate token count (rough: ~4 chars per token)
+    approx_tokens = len(content) // 4
+    if approx_tokens < 40:
+        issues.append({"severity": "low", "field": "length", "message": f"Context snippet may be too short (~{approx_tokens} tokens)"})
+    elif approx_tokens > 200:
+        issues.append({"severity": "low", "field": "length", "message": f"Context snippet may be too long (~{approx_tokens} tokens)"})
+
+    return issues
+
+
+def validate_metadata_json(data, generated_by=None):
+    """Validate metadata.json fields. Returns list of issues."""
+    issues = []
+
+    required_str = ["name", "version", "source_authority", "language", "generation_date"]
+    for field in required_str:
+        val = data.get(field)
+        if not val or not isinstance(val, str):
+            issues.append({"severity": "high", "field": field, "message": f"{field} missing or not a string"})
+
+    # source_repo should be a URL
+    repo = data.get("source_repo", "")
+    if not repo:
+        issues.append({"severity": "medium", "field": "source_repo", "message": "source_repo missing"})
+
+    # generated_by check
+    gb = data.get("generated_by", "")
+    if not gb:
+        issues.append({"severity": "medium", "field": "generated_by", "message": "generated_by missing"})
+    elif generated_by and gb != generated_by:
+        issues.append({"severity": "low", "field": "generated_by", "message": f"generated_by is '{gb}', expected '{generated_by}'"})
+
+    # confidence_tier
+    if not data.get("confidence_tier"):
+        issues.append({"severity": "medium", "field": "confidence_tier", "message": "confidence_tier missing"})
+
+    # stats
+    stats = data.get("stats", {})
+    if not isinstance(stats, dict):
+        issues.append({"severity": "high", "field": "stats", "message": "stats must be an object"})
+    else:
+        required_stats = ["exports_documented", "exports_public_api", "exports_total", "public_api_coverage", "total_coverage"]
+        for field in required_stats:
+            val = stats.get(field)
+            if val is None:
+                issues.append({"severity": "medium", "field": f"stats.{field}", "message": f"stats.{field} missing"})
+            elif not isinstance(val, (int, float)):
+                issues.append({"severity": "medium", "field": f"stats.{field}", "message": f"stats.{field} must be a number"})
+
+    return issues
+
+
+def validate_skill_package(skill_dir, generated_by=None):
+    """Validate a complete skill package directory."""
+    skill_dir = Path(skill_dir)
+    skill_name = skill_dir.name
+
+    result = {
+        "status": "ok",
+        "skill_dir": str(skill_dir),
+        "skill_name": skill_name,
+        "files_found": {},
+        "validation": {},
+        "summary": {"total_issues": 0, "by_severity": {"high": 0, "medium": 0, "low": 0}},
+    }
+
+    # Check file existence
+    files = {
+        "SKILL.md": skill_dir / "SKILL.md",
+        "context-snippet.md": skill_dir / "context-snippet.md",
+        "metadata.json": skill_dir / "metadata.json",
+    }
+
+    for name, path in files.items():
+        result["files_found"][name] = path.exists()
+
+    # Validate SKILL.md
+    skill_md_path = files["SKILL.md"]
+    if skill_md_path.exists():
+        content = skill_md_path.read_text(encoding="utf-8")
+        fm_issues = validate_frontmatter(content, skill_name)
+        body_issues = validate_body_structure(content)
+        result["validation"]["skill_md"] = {"frontmatter": fm_issues, "body": body_issues}
+        for issue in fm_issues + body_issues:
+            result["summary"]["total_issues"] += 1
+            result["summary"]["by_severity"][issue["severity"]] += 1
+    else:
+        result["validation"]["skill_md"] = {"error": "SKILL.md not found"}
+        result["summary"]["total_issues"] += 1
+        result["summary"]["by_severity"]["high"] += 1
+
+    # Validate context-snippet.md
+    snippet_path = files["context-snippet.md"]
+    if snippet_path.exists():
+        content = snippet_path.read_text(encoding="utf-8")
+        snippet_issues = validate_context_snippet(content)
+        result["validation"]["context_snippet"] = {"issues": snippet_issues}
+        for issue in snippet_issues:
+            result["summary"]["total_issues"] += 1
+            result["summary"]["by_severity"][issue["severity"]] += 1
+    else:
+        result["validation"]["context_snippet"] = {"skipped": "context-snippet.md not found"}
+
+    # Validate metadata.json
+    meta_path = files["metadata.json"]
+    if meta_path.exists():
+        try:
+            with open(meta_path, encoding="utf-8") as f:
+                meta = json.load(f)
+            meta_issues = validate_metadata_json(meta, generated_by)
+            result["validation"]["metadata"] = {"issues": meta_issues}
+            for issue in meta_issues:
+                result["summary"]["total_issues"] += 1
+                result["summary"]["by_severity"][issue["severity"]] += 1
+        except json.JSONDecodeError as e:
+            result["validation"]["metadata"] = {"error": f"JSON parse error: {e}"}
+            result["summary"]["total_issues"] += 1
+            result["summary"]["by_severity"]["high"] += 1
+    else:
+        result["validation"]["metadata"] = {"skipped": "metadata.json not found"}
+
+    # Overall pass/fail
+    result["result"] = "PASS" if result["summary"]["by_severity"]["high"] == 0 else "FAIL"
+
+    return result
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: python3 skf-validate-output.py <skill-package-dir> [--generated-by <generator>]", file=sys.stderr)
+        sys.exit(1)
+
+    pkg_dir = sys.argv[1]
+    gen_by = None
+    if "--generated-by" in sys.argv:
+        idx = sys.argv.index("--generated-by")
+        if idx + 1 < len(sys.argv):
+            gen_by = sys.argv[idx + 1]
+
+    result = validate_skill_package(pkg_dir, generated_by=gen_by)
+    print(json.dumps(result, indent=2))
+    sys.exit(0 if result["result"] == "PASS" else 1)

package/src/skf-analyze-source/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: skf-analyze-source
+description: Discover what to skill in a large repo and produce recommended skill briefs. Use when the user requests to "analyze source for skills" or "discover skill opportunities."
+---
+
+# Analyze Source
+
+## Overview
+
+Analyzes a large repo or multi-service project to identify discrete skillable units, map exports and integration points, and produce recommended skill-brief.yaml files as the primary entry point for brownfield onboarding. The analysis must be thorough enough to produce actionable briefs, but scoped enough to avoid overwhelming the user with false positives. Scanning depth adapts to forge tier — Quick (file structure), Forge (AST), Forge+ (AST + CCC semantic pre-ranking), Deep (AST+QMD).
+
+## Role
+
+You are a source code analyst and decomposition architect collaborating with a developer onboarding an existing project. You bring expertise in codebase analysis, service boundary detection, and skill scoping, while the user brings their domain knowledge. Work together as equals.
+
+## Workflow Rules
+
+These rules apply to every step in this workflow:
+
+- 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
+- Update `stepsCompleted` in output file frontmatter before loading next step
+- If any instruction references a subprocess or tool you lack, achieve the outcome in your main context thread
+- 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 | Initialize | steps-c/step-01-init.md | Yes |
+| 1b | Continue (session resume) | steps-c/step-01b-continue.md | Yes |
+| 2 | Scan Project | steps-c/step-02-scan-project.md | No (confirm) |
+| 3 | Identify Units | steps-c/step-03-identify-units.md | No (confirm) |
+| 4 | Map & Detect | steps-c/step-04-map-and-detect.md | Yes |
+| 5 | Recommend | steps-c/step-05-recommend.md | No (confirm) |
+| 6 | Generate Briefs | steps-c/step-06-generate-briefs.md | Yes |
+| 7 | Workflow Health Check | steps-c/step-07-health-check.md | Yes |
+
+## Invocation Contract
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | project_path [required], scope_hint [optional] |
+| **Gates** | step-02: Confirm Gate [C] | step-03: Confirm Gate [C] | step-05: Confirm Gate [C] |
+| **Outputs** | analysis-report.md, skill-brief.yaml files (one per recommended unit) |
+| **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`, `forge_data_folder`, `skills_output_folder`, `sidecar_path`
+
+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-init.md` to begin the workflow.