bmad-module-skill-forge 0.2.0

package/package.json

@@ -0,0 +1,109 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "bmad-module-skill-forge",
+  "version": "0.2.0",
+  "description": "BMAD module — AST-verified, provenance-backed agent skills compiler with progressive capability tiers (Quick/Forge/Deep)",
+  "keywords": [
+    "bmad",
+    "agent-skills",
+    "agentskills",
+    "skill-forge",
+    "ast-grep",
+    "provenance",
+    "code-analysis"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/armelhbobdad/bmad-module-skill-forge.git"
+  },
+  "license": "MIT",
+  "author": "armelhbobdad",
+  "main": "tools/cli/skf-cli.js",
+  "bin": {
+    "bmad-module-skill-forge": "tools/skf-npx-wrapper.js",
+    "skill-forge": "tools/skf-npx-wrapper.js"
+  },
+  "scripts": {
+    "docs:build": "node tools/build-docs.js",
+    "docs:dev": "npm run --prefix website docs:dev",
+    "docs:fix-links": "node tools/fix-doc-links.js --write",
+    "docs:preview": "npm run --prefix website preview",
+    "docs:validate-links": "node tools/validate-doc-links.js",
+    "format:check": "prettier --check \"**/*.{js,cjs,mjs,json,yaml}\"",
+    "format:fix": "prettier --write \"**/*.{js,cjs,mjs,json,yaml}\"",
+    "lint": "eslint . --ext .js,.cjs,.mjs,.yaml --max-warnings=0",
+    "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
+    "lint:md": "markdownlint-cli2 \"**/*.md\"",
+    "prepare": "husky || exit 0",
+    "release": "npm run release:patch",
+    "release:major": "npm version major && git push --follow-tags",
+    "release:minor": "npm version minor && git push --follow-tags",
+    "release:patch": "npm version patch && git push --follow-tags",
+    "release:prerelease": "npm version prerelease && git push --follow-tags",
+    "test": "npm run test:schemas && npm run test:install && npm run test:cli && npm run test:knowledge && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
+    "test:cli": "node test/test-cli-integration.js",
+    "test:install": "node test/test-installation-components.js",
+    "test:knowledge": "node test/test-knowledge-base.js",
+    "test:schemas": "node test/test-agent-schema.js",
+    "validate:schemas": "node test/validate-agent-schema.js"
+  },
+  "lint-staged": {
+    "*.{js,cjs,mjs}": [
+      "npm run lint:fix",
+      "npm run format:fix"
+    ],
+    "*.yaml": [
+      "eslint --fix",
+      "npm run format:fix"
+    ],
+    "*.json": [
+      "npm run format:fix"
+    ],
+    "*.md": [
+      "markdownlint-cli2"
+    ]
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.1.0",
+    "chalk": "^4.1.2",
+    "commander": "^14.0.0",
+    "figlet": "^1.8.0",
+    "fs-extra": "^11.3.0",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@astrojs/sitemap": "^3.6.0",
+    "@astrojs/starlight": "^0.37.0",
+    "@eslint/js": "^9.33.0",
+    "archiver": "^7.0.1",
+    "astro": "^5.16.0",
+    "c8": "^10.1.3",
+    "csv-parse": "^6.1.0",
+    "eslint": "^9.33.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-n": "^17.21.3",
+    "eslint-plugin-unicorn": "^60.0.0",
+    "eslint-plugin-yml": "^1.18.0",
+    "glob": "^11.0.3",
+    "husky": "^9.1.7",
+    "ignore": "^7.0.5",
+    "jest": "^30.0.4",
+    "lint-staged": "^16.1.1",
+    "markdownlint-cli2": "^0.19.1",
+    "prettier": "^3.7.4",
+    "prettier-plugin-packagejson": "^2.5.19",
+    "semver": "^7.6.3",
+    "sharp": "^0.33.5",
+    "wrap-ansi": "^7.0.0",
+    "xml2js": "^0.6.2",
+    "yaml": "^2.7.0",
+    "yaml-eslint-parser": "^1.2.3",
+    "yaml-lint": "^1.7.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/agents/forger.agent.yaml

@@ -0,0 +1,93 @@
+agent:
+  webskip: true
+  metadata:
+    id: "_bmad/skf/agents/forger.md"
+    name: Ferris
+    title: Skill Architect & Integrity Guardian
+    icon: "⚒️"
+    module: skf
+    hasSidecar: true
+    sidecar-folder: forger-sidecar
+    sidecar-path: "{project-root}/_bmad/_memory/forger-sidecar/"
+
+  persona:
+    role: |
+      Skill compilation specialist who transforms code repositories, documentation, and developer discourse into verified agent skills.
+      Manages the full lifecycle: source analysis, skill briefing, AST-backed compilation,
+      integrity testing, and ecosystem-ready export across progressive capability tiers
+      (Quick/Forge/Deep).
+
+    identity: |
+      The forge master — a precision-focused craftsman who works through four modes:
+      Architect (exploratory, assembling), Surgeon (precise, preserving), Audit
+      (judgmental, scoring), and Delivery (packaging, ecosystem-ready). Modes are
+      workflow-bound, not conversation-bound. Takes quiet pride in verified work and
+      treats every claim as something that must be proven.
+
+    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.
+
+    principles:
+      - "Channel expert source code analysis wisdom: draw upon deep knowledge of AST patterns, function signatures, type systems, and what separates verified skill definitions from hallucinated ones"
+      - "Zero hallucination tolerance — every instruction traces to code; if it can't be cited, it doesn't exist"
+      - "Structural truth over semantic guessing — AST first, always; never infer what can be parsed"
+      - "Provenance is non-negotiable — every claim has a source, line number, and confidence tier"
+      - "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 across workflows — consult knowledge/ when a step directs, not from memory"
+
+  critical_actions:
+    - "Load COMPLETE file {project-root}/_bmad/_memory/forger-sidecar/preferences.yaml"
+    - "Load COMPLETE file {project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml"
+    - "ONLY read/write files in {project-root}/_bmad/_memory/forger-sidecar/"
+    - "Consult {project-root}/_bmad/skf/knowledge/skf-knowledge-index.csv to select knowledge fragments under knowledge/ and load only the files needed for the current task"
+    - "Load the referenced fragment(s) from {project-root}/_bmad/skf/knowledge/ before giving recommendations"
+
+  menu:
+    - trigger: SF or fuzzy match on setup-forge
+      workflow: "{project-root}/_bmad/skf/workflows/skillforge/setup-forge/workflow.md"
+      description: "[SF] Setup Forge — initialize environment, detect tools, set tier"
+
+    - trigger: AN or fuzzy match on analyze-source
+      workflow: "{project-root}/_bmad/skf/workflows/skillforge/analyze-source/workflow.md"
+      description: "[AN] Analyze Source — discover what to skill, recommend stack skill"
+
+    - trigger: BS or fuzzy match on brief-skill
+      workflow: "{project-root}/_bmad/skf/workflows/skillforge/brief-skill/workflow.md"
+      description: "[BS] Brief Skill — design a skill scope through guided discovery"
+
+    - trigger: CS or fuzzy match on create-skill
+      workflow: "{project-root}/_bmad/skf/workflows/skillforge/create-skill/workflow.md"
+      description: "[CS] Create Skill — compile a skill from brief"
+
+    - trigger: QS or fuzzy match on quick-skill
+      workflow: "{project-root}/_bmad/skf/workflows/skillforge/quick-skill/workflow.md"
+      description: "[QS] Quick Skill — fast skill, no brief needed"
+
+    - trigger: SS or fuzzy match on create-stack-skill
+      workflow: "{project-root}/_bmad/skf/workflows/skillforge/create-stack-skill/workflow.md"
+      description: "[SS] Stack Skill — consolidated project stack skill"
+
+    - trigger: US or fuzzy match on update-skill
+      workflow: "{project-root}/_bmad/skf/workflows/skillforge/update-skill/workflow.md"
+      description: "[US] Update Skill — regenerate after changes, preserves [MANUAL]"
+
+    - trigger: AS or fuzzy match on audit-skill
+      workflow: "{project-root}/_bmad/skf/workflows/skillforge/audit-skill/workflow.md"
+      description: "[AS] Audit Skill — check for drift"
+
+    - trigger: TS or fuzzy match on test-skill
+      workflow: "{project-root}/_bmad/skf/workflows/skillforge/test-skill/workflow.md"
+      description: "[TS] Test Skill — verify completeness"
+
+    - trigger: EX or fuzzy match on export-skill
+      workflow: "{project-root}/_bmad/skf/workflows/skillforge/export-skill/workflow.md"
+      description: "[EX] Export Skill — package for distribution"
+
+    - trigger: WS or fuzzy match on workflow-status
+      action: "Show current lifecycle position, active skill briefs, and forge tier status"
+      description: "[WS] Workflow Status — show current lifecycle position"

package/src/forger/README.md

@@ -0,0 +1,17 @@
+# forger-sidecar
+
+This folder stores persistent memory for the **Ferris** agent (Skill Architect & Integrity Guardian).
+
+## Purpose
+
+Cross-session state for the SKF module's skill compilation lifecycle.
+
+## Files
+
+- `preferences.yaml` — User preferences: language defaults, output format settings
+- `forge-tier.yaml` — Tool availability (ast-grep, gh, QMD) and derived capability tier
+
+## Runtime Access
+
+After BMAD installation, this folder will be accessible at:
+`{project-root}/_bmad/_memory/forger-sidecar/`

package/src/forger/forge-tier.yaml

@@ -0,0 +1,13 @@
+# Ferris Sidecar: Forge Tier State
+# Written by setup-forge workflow on first run
+
+# Tool availability (detected during [SF] Setup Forge)
+tools:
+  ast_grep: ~
+  gh_cli: ~
+  qmd: ~
+
+# Capability tier (derived from tool availability)
+# Quick = no tools | Forge = ast-grep | Deep = ast-grep + gh + qmd
+tier: ~
+tier_detected_at: ~

package/src/forger/preferences.yaml

@@ -0,0 +1,10 @@
+# Ferris Sidecar: User Preferences
+# Written by setup-forge workflow on first run
+
+# Language defaults
+output_language: ~
+skill_format_version: ~
+
+# Output preferences
+citation_style: ~
+confidence_display: ~

package/src/knowledge/agentskills-spec.md

@@ -0,0 +1,158 @@
+# agentskills.io Specification
+
+## Principle
+
+Skills produced by Skill Forge comply with the agentskills.io specification — a format designed for agent consumption through progressive disclosure. The format prioritizes discoverability at low token cost, deterministic procedural instructions, and just-in-time resource loading.
+
+## Rationale
+
+Agent skills are not documentation for humans. They are instructions consumed by AI agents that treat every statement as actionable truth. The agentskills.io format was designed around this constraint: minimal metadata for discovery, structured instructions for activation, and on-demand resources for execution.
+
+Without format compliance:
+- Skills are not portable across agent platforms
+- Discovery requires loading full skill content, wasting context tokens
+- Agents cannot distinguish skills from general documentation
+
+With format compliance:
+- Skills are discoverable from ~100 tokens of frontmatter metadata
+- Full activation loads < 500 lines of structured instructions
+- Resources load on demand, keeping context lean during execution
+
+## Format Structure
+
+### Required: SKILL.md
+
+The minimum viable skill is a single `SKILL.md` file containing:
+
+**Frontmatter** (YAML between `---` markers):
+```yaml
+---
+name: library-name
+description: >
+  What the skill does and when to use it. Include specific keywords
+  for agent discovery. Mention what NOT to use it for.
+---
+```
+
+**Frontmatter constraints:**
+- `name`: 1-64 characters, lowercase alphanumeric + hyphens, must match parent directory name
+- `description`: 1-1024 characters, trigger-optimized for agent matching
+
+**Body:** Free-form markdown — no structural restrictions, but Skill Forge follows a consistent section order (see skill-sections.md in create-skill/data/).
+
+### Optional: Supporting Directories
+
+```
+skill-name/
+├── SKILL.md              # Instructions and API reference
+├── scripts/              # Executable automation
+├── references/           # Detailed reference material
+└── assets/               # Templates, schemas, configs
+```
+
+All subdirectories are exactly one level deep. Files are loaded on demand when SKILL.md directs — never automatically.
+
+## Progressive Disclosure Model
+
+The format implements a three-phase loading model:
+
+| Phase | What Loads | Token Cost | When |
+| --- | --- | --- | --- |
+| Discovery | `name` + `description` from frontmatter | ~50-100 tokens | Agent startup, all skills |
+| Activation | Full `SKILL.md` body | < 5000 tokens | Task matches skill description |
+| Execution | Files from `scripts/`, `references/`, `assets/` | Variable | SKILL.md directs agent to load |
+
+## Pattern Examples
+
+### Example 1: Trigger-Optimized Description
+
+**Context:** Writing a skill description that agents can match to user tasks.
+
+**Implementation:**
+```yaml
+description: >
+  Extract and transform data from PostgreSQL databases using pg client.
+  Use for database queries, schema inspection, connection management,
+  and migration execution. NOT for: MongoDB, Redis, or other non-SQL stores.
+  NOT for: ORM-level abstractions (use typeorm-skill or prisma-skill instead).
+```
+
+**Key Points:**
+- Leads with what the skill does (positive triggers)
+- Includes negative triggers to prevent false matches
+- References alternative skills for excluded use cases
+- Specific keywords: "PostgreSQL", "pg client", "schema inspection"
+
+### Example 2: Just-in-Time Resource Loading
+
+**Context:** A skill needs to reference a complex schema during execution.
+
+**Implementation:**
+```markdown
+## Configuration
+
+The library accepts a configuration object matching the schema in
+`references/config-schema.md`. Load that file now to validate
+the user's configuration against the expected structure.
+```
+
+**Key Points:**
+- The directive is explicit: "Load that file now"
+- Agents do not pre-load reference files — they follow the instruction when they reach it
+- Relative paths use forward slashes, one level deep only
+
+### Example 3: Procedural Instructions for Agents
+
+**Context:** Writing skill instructions that agents execute deterministically.
+
+**Implementation:**
+```markdown
+## Setup
+
+1. Check if `pg` is installed: run `npm list pg` in the project directory.
+2. If not installed, run `npm install pg`.
+3. Locate the database configuration:
+   - Check `src/config/database.ts` first
+   - If not found, check environment variables: `DATABASE_URL`, `PG_HOST`
+   - If neither exists, ask the user for connection details
+4. Validate the connection by running the health check in `scripts/health-check.sql`.
+```
+
+**Key Points:**
+- Step-by-step numbering with decision trees
+- Third-person imperative voice ("Check if..." not "You should check...")
+- Concrete file paths and commands, not vague guidance
+- Fallback paths explicitly mapped
+
+### Example 4: Skill Forge Compliance Checks
+
+**Context:** The validate step in create-skill checks agentskills.io compliance.
+
+**Implementation:** Validation covers:
+1. Frontmatter present with required `name` and `description` fields
+2. `name` matches parent directory name and formatting rules
+3. `description` length within 1-1024 characters
+4. SKILL.md body under 500 lines (warning, not failure)
+5. All relative paths resolve to existing files
+6. No deeply nested subdirectories (max one level)
+
+**Key Points:**
+- Compliance is checked during create-skill, not as a post-hoc audit
+- Line count is a guideline — exceeding 500 lines produces a warning
+- Path validation prevents broken references in the published skill
+
+## Anti-Patterns
+
+- Writing skills as documentation (README-style) instead of procedural agent instructions
+- Deeply nested directory structures — one level maximum from skill root
+- Vague descriptions ("helps with databases") — descriptions must be specific and trigger-optimized
+- Including redundant content that duplicates what the agent already knows (standard language features, basic CLI commands)
+- Bundling large library code inside skills — skills reference existing tools, not replace them
+
+## Related Fragments
+
+- [skill-lifecycle.md](skill-lifecycle.md) — where agentskills.io compliance fits in the pipeline
+- [confidence-tiers.md](confidence-tiers.md) — how citations appear within the formatted output
+- [zero-hallucination.md](zero-hallucination.md) — the integrity principle that shapes skill content
+
+_Source: synthesized from agentskills.io specification, what-are-skills.mdx, integrate-skills.mdx, and Best Practices for Creating Agent Skills_

package/src/knowledge/confidence-tiers.md

@@ -0,0 +1,153 @@
+# Confidence Tiers
+
+## Principle
+
+Every extracted claim carries a confidence tier label — T1, T1-low, T2, or T3 — that tells consuming agents how much to trust the information. The tier determines citation format, affects scoring weights, and governs how claims interact during updates and audits.
+
+## Rationale
+
+Not all extracted information has equal reliability. An AST-parsed function signature is structurally verified; a type inferred from pattern matching might be wrong; a QMD-enriched usage note adds context but not structural proof; an external doc reference is only as current as its source.
+
+Without confidence tiers:
+- All claims appear equally trustworthy regardless of extraction method
+- Agents cannot distinguish verified signatures from inferred patterns
+- Audit and update workflows have no basis for prioritizing drift findings
+
+With confidence tiers:
+- Each claim transparently declares its evidence strength
+- Scoring weights adjust based on the distribution of tiers
+- Update workflows know which claims to re-verify first
+
+## Tier Definitions
+
+| Tier | Label | Source | Extraction Method | Available At |
+| --- | --- | --- | --- | --- |
+| T1 | AST-verified | Source code | ast-grep structural parsing | Forge, Deep |
+| T1-low | Source-read | Source code | Pattern matching, file reading | Quick, Forge, Deep |
+| T2 | QMD-enriched | Knowledge base | QMD semantic search + synthesis | Deep |
+| T3 | External reference | Docs, URLs | External documentation lookup | All tiers |
+
+## Citation Formats
+
+Each tier has a defined citation format used consistently across all skill output:
+
+```
+T1:     [AST:filepath:Lnn]          — AST-verified, line-level precision
+T1-low: [SRC:filepath:Lnn]          — source-read, line-level but unverified structure
+T2:     [QMD:collection:document]   — QMD knowledge enrichment
+T3:     [EXT:url-or-reference]      — external documentation reference
+```
+
+## Pattern Examples
+
+### Example 1: T1 — AST-Verified Export
+
+**Context:** ast-grep parses a TypeScript file and extracts a function export with full signature.
+
+**Implementation:**
+```markdown
+## `createServer(options: ServerOptions): Server`
+
+Creates and configures an HTTP server instance.
+
+**Parameters:**
+| Name | Type | Required | Default |
+| --- | --- | --- | --- |
+| options | `ServerOptions` | yes | — |
+
+[AST:src/server.ts:L23]
+```
+
+**Key Points:**
+- Signature extracted by AST — structurally guaranteed to match source
+- Line number is exact, not approximate
+- Only available when ast-grep is present (Forge/Deep tier)
+
+### Example 2: T1-low — Source-Read Extraction
+
+**Context:** Quick tier extraction reads source files without AST parsing.
+
+**Implementation:**
+```markdown
+## `createServer(options)`
+
+Creates and configures an HTTP server instance.
+
+**Parameters:**
+| Name | Type | Required | Default |
+| --- | --- | --- | --- |
+| options | `object` | yes | — |
+
+[SRC:src/server.ts:L23] — type inferred from usage, not structurally verified
+```
+
+**Key Points:**
+- Same function, but parameter type is `object` not `ServerOptions` — pattern matching missed the type alias
+- Citation explicitly notes the inference limitation
+- Still useful — location is correct, signature is close
+
+### Example 3: T2 — QMD Enrichment
+
+**Context:** Deep tier enriches an extracted API with usage patterns from QMD knowledge base.
+
+**Implementation:**
+```markdown
+### Usage Context
+
+`createServer` is typically used with `loadMiddleware()` in application bootstrap.
+Common pattern: create server first, then attach middleware chain before calling `.listen()`.
+
+[QMD:project-docs:architecture-overview]
+```
+
+**Key Points:**
+- Enrichment adds context, not structural claims
+- QMD citations reference collection and document, not line numbers
+- T2 content appears in enrichment sections, not in API signatures
+
+### Example 4: Tier Interaction During Updates
+
+**Context:** An update-skill workflow detects that a T1-low claim now contradicts fresh T1 extraction.
+
+**Implementation:** The merge algorithm applies tier precedence:
+1. T1 always overrides T1-low for the same export
+2. T2 enrichments are preserved unless the underlying T1/T1-low claim changed
+3. T3 references are flagged for manual review if the API they describe changed
+
+**Key Points:**
+- Higher confidence tiers take precedence in merge conflicts
+- T2 enrichments are additive — they don't conflict with structural claims
+- T3 references may go stale and are flagged, not auto-removed
+
+## Confidence Distribution in Metadata
+
+Every generated skill includes a confidence distribution in `metadata.json`:
+
+```json
+{
+  "confidence_distribution": {
+    "t1": 42,
+    "t1_low": 5,
+    "t2": 12,
+    "t3": 3
+  },
+  "extraction_tier": "deep"
+}
+```
+
+This distribution feeds into test-skill scoring — skills with higher T1 ratios score better on signature accuracy.
+
+## Anti-Patterns
+
+- Omitting the confidence tier from a citation — every citation must declare its level
+- Using T1 format (`[AST:...]`) when ast-grep was not actually used for that extraction
+- Treating T1-low and T1 as equivalent during scoring — they have different weight impacts
+- Adding T2 enrichment without a QMD citation — enrichment without provenance is hallucination
+
+## Related Fragments
+
+- [zero-hallucination.md](zero-hallucination.md) — the principle that motivates tiered confidence
+- [provenance-tracking.md](provenance-tracking.md) — how citations are recorded in provenance-map.json
+- [progressive-capability.md](progressive-capability.md) — how forge tier determines available confidence levels
+
+_Source: consolidated from extraction-patterns.md, create-skill steps 03/05, and scoring-rules.md_