bmad-module-skill-forge 0.5.0 → 0.7.0

package/src/knowledge/skill-lifecycle.md

@@ -2,7 +2,7 @@
 
 ## Principle
 
-The 10 SKF workflows form an end-to-end pipeline from source discovery through verified export. Each workflow produces artifacts consumed by downstream workflows. Understanding the lifecycle enables Ferris to recommend the right workflow for a user's situation and to maintain artifact continuity across the pipeline.
+The 12 SKF workflows form an end-to-end pipeline from source discovery through verified export, with a pre-code architecture verification path. Each workflow produces artifacts consumed by downstream workflows. Understanding the lifecycle enables Ferris to recommend the right workflow for a user's situation and to maintain artifact continuity across the pipeline.
 
 ## Rationale
 
@@ -26,6 +26,7 @@ With lifecycle awareness:
 | Discovery | AN (Analyze Source) | Scan project, identify skillable units | Analysis report, skill briefs |
 | Design | BS (Brief Skill) | Interactive scope definition for one skill | `skill-brief.yaml` |
 | Compilation | CS, QS, SS (Create/Quick/Stack) | Extract source and compile skill | `SKILL.md`, metadata, provenance, `scripts/`, `assets/` (when source contains them) |
+| Architecture Verification | VS, RA (Verify Stack, Refine Architecture) | Pre-code feasibility check and architecture refinement | Feasibility report, refined architecture doc |
 | Maintenance | US, AS (Update/Audit) | Detect drift and refresh skills | Updated `SKILL.md`, drift report |
 | Verification | TS (Test Skill) | Quality gate — completeness scoring | Test report, pass/fail decision |
 | Distribution | EX (Export Skill) | Package and inject into agent context | agentskills.io bundle, snippets |
@@ -66,6 +67,20 @@ SF → QS → EX
 2. **QS** resolves a package name or URL to source and compiles directly — no brief needed
 3. **EX** packages for distribution (optional TS between QS and EX for quality assurance)
 
+### Pre-Code Stack Verification
+
+```
+SF → CS×N (per library) → VS → RA → SS (compose) → TS → EX
+```
+
+1. **SF** ensures environment is configured
+2. **CS** compiles individual skills for each library in the stack
+3. **VS** cross-references skills against architecture and PRD — produces a feasibility report with verdicts
+4. **RA** refines the architecture document using skill API evidence and VS findings
+5. **SS** (compose-mode) synthesizes the stack skill from individual skills + refined architecture
+6. **TS** verifies the composed stack skill
+7. **EX** packages for distribution
+
 ### Maintenance
 
 ```
@@ -92,6 +107,7 @@ AS → US → TS → EX
 | User has a package name, wants fast results | QS |
 | User wants to skill their entire project | AN → CS (batch) |
 | User has an existing skill that may be outdated | AS → US |
+| User wants to verify tech stack before building | CS×N → VS → RA → SS (compose) |
 
 **Key Points:**
 - SF is always prerequisite (but only needs to run once per project)
@@ -113,12 +129,19 @@ CS → SKILL.md + metadata.json + provenance-map.json + scripts/ + assets/ (when
 TS → test-report.md (pass/fail gate)
        ↓ (passing skill consumed by EX)
 EX → agentskills.io bundle + context snippets
+
+VS → feasibility-report-{project_name}.md (verdict + integration verdicts)
+       ↓ (report consumed by RA)
+RA → refined-architecture-{project_name}.md (gaps filled, issues flagged, improvements suggested)
+       ↓ (refined doc consumed by SS compose-mode)
+SS (compose) → SKILL.md (stack skill synthesized from individual skills + architecture)
 ```
 
 **Key Points:**
 - `forge-tier.yaml` is the universal dependency — all workflows read it
 - Skill briefs are the handoff between discovery/design and compilation
 - TS acts as a gate — failing skills do not proceed to EX
+- VS/RA form a pre-code verification loop — rerun after architecture changes
 
 ### Example 3: Stack Skill vs. Individual Skills
 
@@ -139,6 +162,7 @@ EX → agentskills.io bundle + context snippets
 - **Analyze Source** and **Brief Skill** are alternative entry points to compilation
 - **Test Skill** is optional but recommended — the quality gate before export
 - **Audit Skill** and **Update Skill** form the maintenance loop
+- **Verify Stack** and **Refine Architecture** form the pre-code verification path
 - **Export Skill** is the terminal workflow — it produces the distributable artifact
 
 ## Related Fragments
@@ -147,4 +171,4 @@ EX → agentskills.io bundle + context snippets
 - [agentskills-spec.md](agentskills-spec.md) — the output format that export-skill packages
 - [provenance-tracking.md](provenance-tracking.md) — how provenance flows through the pipeline
 
-_Source: synthesized from all 10 workflow.md files and module-help.csv_
+_Source: synthesized from all 12 workflow.md files (including VS, RA) and module-help.csv_

package/src/knowledge/split-body-strategy.md

@@ -2,7 +2,7 @@
 
 ## Principle
 
-Selective split is the recommended strategy when `split-body` is needed. Extract only the largest Tier 2 section(s) to stay under the `body.max_lines` limit — keep all actionable Tier 1 content inline. Full split-body reduces agent accuracy because on-demand retrieval underperforms inline passive context.
+Selective split is the recommended strategy when `split-body` is needed. Extract only the largest Tier 2 section(s) to stay under the 500-line body guideline — keep all actionable Tier 1 content inline. Full split-body reduces agent accuracy because on-demand retrieval underperforms inline passive context.
 
 ## Rationale
 
@@ -28,9 +28,15 @@ A split-body skill is identified by:
 
 When processing a split-body skill, any workflow step that reads SKILL.md content must also traverse `references/*.md` to get the complete picture.
 
+## Anti-Patterns
+
+- Running `skill-check split-body --write` without first attempting selective split
+- Moving Tier 1 sections (Quick Start, Key API Summary) to references/ — these must stay inline
+- Splitting before checking whether context snippet anchors will break
+
 ## Recommended Approach
 
-When `body.max_lines` is exceeded:
+When the 500-line body guideline is exceeded:
 1. Identify which Tier 2 section(s) are largest (usually `## Full API Reference`)
 2. Extract only those specific sections to `references/`
 3. Keep all Tier 1 sections and smaller Tier 2 sections inline
@@ -39,3 +45,11 @@ When `body.max_lines` is exceeded:
 ## Scripts and Assets Interaction
 
 Split-body affects only SKILL.md content movement to `references/`. The `scripts/` and `assets/` directories are unaffected — they remain as top-level siblings of SKILL.md regardless of split-body decisions. They do not count toward the body line limit.
+
+## Related Fragments
+
+- [agentskills-spec.md](agentskills-spec.md) — 500-line guideline for SKILL.md body size and the `references/` directory structure
+- [skill-lifecycle.md](skill-lifecycle.md) — where split-body decisions fit in the compilation pipeline
+- `test-skill/data/scoring-rules.md` — tessl/split-body interaction and the pre-split baseline recommendation during test reporting
+
+_Source: derived from agentskills.io split-body guidance and Vercel agent accuracy research (inline vs on-demand retrieval)_

package/src/knowledge/zero-hallucination.md

@@ -62,14 +62,17 @@ With zero hallucination enforcement:
 
 **Implementation:** Extraction relies on source reading and pattern matching. All citations use `[SRC:file:Lnn]` format (T1-low confidence). The skill clearly states its extraction tier so consuming agents understand the confidence level.
 
-```yaml
-# metadata.json (excerpt)
-confidence_distribution:
-  t1: 0
-  t1_low: 47
-  t2: 0
-  t3: 3
-extraction_tier: quick
+```json
+// metadata.json (excerpt)
+{
+  "confidence_tier": "Quick",
+  "confidence_distribution": {
+    "t1": 0,
+    "t1_low": 47,
+    "t2": 0,
+    "t3": 3
+  }
+}
 ```
 
 **Key Points:**

package/src/module-help.csv

@@ -1,12 +1,15 @@
 module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs,
-skf,anytime,Setup Forge,SF,,_bmad/skf/workflows/skillforge/setup-forge/workflow.md,skf_setup_forge,false,ferris,Create Mode,"Initialize forge environment — detect tools and set capability tier (Quick/Forge/Deep)",,forge-config.yaml,
+skf,anytime,Setup Forge,SF,,_bmad/skf/workflows/skillforge/setup-forge/workflow.md,skf_setup_forge,false,ferris,Create Mode,"Initialize forge environment — detect tools and set capability tier (Quick/Forge/Forge+/Deep)",,forge-tier.yaml,
 skf,anytime,Analyze Source,AN,,_bmad/skf/workflows/skillforge/analyze-source/workflow.md,skf_analyze_source,false,ferris,Create Mode,"Discover what to skill in a large repo — produces recommended skill briefs",forge_data_folder,skill-brief.yaml,
 skf,anytime,Brief Skill,BS,,_bmad/skf/workflows/skillforge/brief-skill/workflow.md,skf_brief_skill,false,ferris,Create Mode,"Design a skill scope through guided discovery",forge_data_folder,skill-brief.yaml,
 skf,anytime,Create Skill,CS,,_bmad/skf/workflows/skillforge/create-skill/workflow.md,skf_create_skill,false,ferris,Create Mode,"Compile a skill from a brief — supports --batch for multiple briefs",skills_output_folder,SKILL.md,
 skf,anytime,Quick Skill,QS,,_bmad/skf/workflows/skillforge/quick-skill/workflow.md,skf_quick_skill,false,ferris,Create Mode,"Fast skill from a package name or GitHub URL — no brief needed",skills_output_folder,SKILL.md,
-skf,anytime,Stack Skill,SS,,_bmad/skf/workflows/skillforge/create-stack-skill/workflow.md,skf_create_stack_skill,false,ferris,Create Mode,"Consolidated project stack skill with integration patterns",skills_output_folder,SKILL.md,
-skf,anytime,Update Skill,US,,_bmad/skf/workflows/skillforge/update-skill/workflow.md,skf_update_skill,false,ferris,Create Mode,"Smart regeneration preserving [MANUAL] sections after source changes",skills_output_folder,SKILL.md,
-skf,anytime,Audit Skill,AS,,_bmad/skf/workflows/skillforge/audit-skill/workflow.md,skf_audit_skill,false,ferris,Create Mode,"Drift detection between skill and current source code",,"drift report",
-skf,anytime,Test Skill,TS,,_bmad/skf/workflows/skillforge/test-skill/workflow.md,skf_test_skill,false,ferris,Create Mode,"Cognitive completeness verification — quality gate before export",,"completeness score",
-skf,anytime,Export Skill,EX,,_bmad/skf/workflows/skillforge/export-skill/workflow.md,skf_export_skill,false,ferris,Create Mode,"Package for distribution and inject context into CLAUDE.md/AGENTS.md",skills_output_folder,"agentskills.io package",
+skf,anytime,Stack Skill,SS,,_bmad/skf/workflows/skillforge/create-stack-skill/workflow.md,skf_create_stack_skill,false,ferris,Create Mode,"Consolidated project stack skill with integration patterns — code-mode (analyzes manifests) or compose-mode (synthesizes from existing skills + architecture doc)",skills_output_folder,SKILL.md,
+skf,anytime,Update Skill,US,,_bmad/skf/workflows/skillforge/update-skill/workflow.md,skf_update_skill,false,ferris,Surgeon Mode,"Smart regeneration preserving [MANUAL] sections after source changes",skills_output_folder,SKILL.md,
+skf,anytime,Audit Skill,AS,,_bmad/skf/workflows/skillforge/audit-skill/workflow.md,skf_audit_skill,false,ferris,Audit Mode,"Drift detection between skill and current source code",,"drift report",
+skf,anytime,Test Skill,TS,,_bmad/skf/workflows/skillforge/test-skill/workflow.md,skf_test_skill,false,ferris,Audit Mode,"Cognitive completeness verification — quality gate before export",,"completeness score",
+skf,anytime,Export Skill,EX,,_bmad/skf/workflows/skillforge/export-skill/workflow.md,skf_export_skill,false,ferris,Delivery Mode,"Package for distribution and inject context into CLAUDE.md/AGENTS.md/.cursorrules",skills_output_folder,"agentskills.io package",
+skf,anytime,Verify Stack,VS,,_bmad/skf/workflows/skillforge/verify-stack/workflow.md,skf_verify_stack,false,ferris,Audit Mode,"Pre-code stack feasibility verification against architecture and PRD documents",forge_data_folder,"feasibility-report-{project_name}.md",
+skf,anytime,Refine Architecture,RA,,_bmad/skf/workflows/skillforge/refine-architecture/workflow.md,skf_refine_architecture,false,ferris,Architect Mode,"Improve architecture doc using verified skill data and VS feasibility findings",output_folder,"refined-architecture-{project_name}.md",
+skf,anytime,Workflow Status,WS,,,skf_workflow_status,false,ferris,Reference,"Show current lifecycle position, active skill briefs, and forge tier status",,lifecycle status,
 skf,anytime,Knowledge Index,KI,,_bmad/skf/knowledge/skf-knowledge-index.csv,skf_knowledge_index,false,ferris,Reference,"Cross-cutting principles and patterns — JiT loaded by workflows via index lookup",,"knowledge fragments",

package/src/module.yaml

@@ -2,7 +2,7 @@ code: skf
 name: "SKF: Skill Forge — Evidence-Based Agent Skills Compiler"
 header: "Turn code and docs into instructions AI agents can actually follow"
 subheader: "Every instruction traces to source. Zero hallucination tolerance."
-description: "Skill Forge transforms code repositories, documentation, and developer discourse into agentskills.io-compliant, version-pinned, provenance-backed agent skills. Uses ast-grep for structural truth, QMD for knowledge intelligence, and a progressive capability model (Quick/Forge/Deep). Standalone module — no other modules required. Recommended alongside BMM for full development workflow integration."
+description: "Skill Forge transforms code repositories, documentation, and developer discourse into agentskills.io-compliant, version-pinned, provenance-backed agent skills. Uses ast-grep for structural truth, cocoindex-code for semantic discovery, QMD for knowledge intelligence, and a progressive capability model (Quick/Forge/Forge+/Deep). Standalone module — no other modules required. Recommended alongside BMM for full development workflow integration."
 default_selected: false
 
 skills_output_folder:
@@ -20,3 +20,6 @@ forge_data_folder:
 ## communication_language
 ## document_output_language
 ## output_folder
+
+# Variables from Agent Sidecar Config:
+## sidecar_path  (from forger.agent.yaml metadata.sidecar-path)

package/src/workflows/README.md

@@ -1,6 +1,6 @@
 # SKF Workflows
 
-Ten workflows covering the full skill compilation lifecycle — from source discovery through verified export.
+Twelve workflows covering the full skill lifecycle — from source discovery through verified export, with pre-code architecture verification.
 
 All workflows are triggered via Ferris (`@Ferris <code>`) and execute as step-by-step sequences with just-in-time step loading.
 
@@ -8,15 +8,17 @@ All workflows are triggered via Ferris (`@Ferris <code>`) and execute as step-by
 
 | Code | Workflow | Steps | Mode | Purpose |
 | --- | --- | --- | --- | --- |
-| SF | [setup-forge](setup-forge/workflow.md) | 4 | Architect | Initialize environment, detect tools, set capability tier |
+| SF | [setup-forge](setup-forge/workflow.md) | 5 | Architect | Initialize environment, detect tools, set capability tier |
 | AN | [analyze-source](analyze-source/workflow.md) | 7 | Architect | Discover skillable units in a repo, produce recommended briefs |
 | BS | [brief-skill](brief-skill/workflow.md) | 5 | Architect | Design a skill scope through guided discovery |
-| CS | [create-skill](create-skill/workflow.md) | 8 | Surgeon | Compile a skill from brief with provenance (supports --batch) |
-| QS | [quick-skill](quick-skill/workflow.md) | 6 | Surgeon | Fast skill from package name or GitHub URL — no brief needed |
-| SS | [create-stack-skill](create-stack-skill/workflow.md) | 9 | Surgeon | Consolidated project stack skill with integration patterns |
+| CS | [create-skill](create-skill/workflow.md) | 8 | Architect | Compile a skill from brief with provenance (supports --batch) |
+| QS | [quick-skill](quick-skill/workflow.md) | 6 | Architect | Fast skill from package name or GitHub URL — no brief needed |
+| SS | [create-stack-skill](create-stack-skill/workflow.md) | 9 | Architect | Consolidated project stack skill with integration patterns (code-mode + compose-mode) |
+| VS | [verify-stack](verify-stack/workflow.md) | 6 | Audit | Validate tech stack feasibility against architecture and PRD |
+| RA | [refine-architecture](refine-architecture/workflow.md) | 6 | Architect | Improve architecture doc using verified skill data |
 | US | [update-skill](update-skill/workflow.md) | 7 | Surgeon | Regenerate after source changes, preserving \[MANUAL\] sections |
 | AS | [audit-skill](audit-skill/workflow.md) | 6 | Audit | Drift detection between skill and current source code |
-| TS | [test-skill](test-skill/workflow.md) | 6 | Audit | Cognitive completeness verification — quality gate before export |
+| TS | [test-skill](test-skill/workflow.md) | 7 | Audit | Cognitive completeness verification — quality gate before export |
 | EX | [export-skill](export-skill/workflow.md) | 6 | Delivery | Package for distribution, inject into CLAUDE.md/AGENTS.md |
 
 ## Typical Flows
@@ -39,6 +41,12 @@ SF → BS → CS → TS → EX
 SF → QS → EX
 ```
 
+**Pre-code stack verification:**
+
+```
+SF → CS×N (per library) → VS → RA → SS (compose) → TS → EX
+```
+
 **Maintenance:**
 
 ```
@@ -75,10 +83,8 @@ Each workflow follows a consistent structure:
 │   └── ...
 ├── data/                    # Reference data — schemas, rules, patterns
 │   └── *.md
-├── templates/               # Output skeletons (only analyze-source, test-skill)
-│   └── *-template.md
-├── workflow-plan-*.md       # Design plan (build artifact)
-└── validation-report.md     # BMAD validation results (build artifact)
+└── templates/               # Output skeletons (only analyze-source, test-skill)
+    └── *-template.md
 ```
 
 ### Step Loading
@@ -89,9 +95,9 @@ Steps execute sequentially via just-in-time loading. Only the current step is in
 
 ### setup-forge (SF)
 
-**4 steps** | **Data:** tier-rules.md
+**5 steps** | **Data:** tier-rules.md
 
-Detects available tools (ast-grep, gh, QMD), determines the capability tier (Quick/Forge/Deep), writes `forge-tier.yaml` to the sidecar, and optionally indexes the project. Run this first — all other workflows adapt behavior to the detected tier.
+Detects available tools (ast-grep, gh, QMD), determines the capability tier (Quick/Forge/Forge+/Deep), writes `forge-tier.yaml` to the sidecar, and optionally indexes the project. Run this first — all other workflows adapt behavior to the detected tier.
 
 ### analyze-source (AN)
 
@@ -101,13 +107,13 @@ Brownfield onboarding entry point. Scans project structure, identifies skillable
 
 ### brief-skill (BS)
 
-**5 steps** | **Data:** skill-brief-schema.md
+**5 steps** | **Data:** skill-brief-schema.md, scope-templates.md
 
 Interactive guided discovery. Gathers user intent (target repo, language, what to skill), analyzes the target to understand boundaries, walks through scope definition with the user, confirms the brief, then writes a validated `skill-brief.yaml`.
 
 ### create-skill (CS)
 
-**8 steps** | **Data:** extraction-patterns.md, skill-sections.md
+**8 primary steps (11 step files including sub-steps)** | **Data:** extraction-patterns.md, extraction-patterns-tracing.md, skill-sections.md, tier-degradation-rules.md, compile-assembly-rules.md, source-resolution-protocols.md
 
 The core compilation engine. Loads a brief, checks ecosystem context, extracts source with AST-backed provenance (T1 confidence when ast-grep available), enriches with usage patterns, compiles into agentskills.io-compliant sections, validates structural integrity, generates the `SKILL.md` artifact, and produces an evidence report. Supports `--batch` for processing multiple briefs.
 
@@ -119,13 +125,25 @@ Fastest path to a skill. Accepts a GitHub URL or package name, resolves to sourc
 
 ### create-stack-skill (SS)
 
-**9 steps** | **Data:** integration-patterns.md, manifest-patterns.md, stack-skill-template.md
+**9 steps** | **Data:** integration-patterns.md, manifest-patterns.md, stack-skill-template.md, compose-mode-rules.md
+
+Two modes: **Code-mode** analyzes dependency manifests and co-import patterns from actual source code. **Compose-mode** synthesizes a stack skill from pre-generated individual skills + architecture document (no codebase required). Both produce the same output format — consolidated stack skill with integration patterns.
+
+### verify-stack (VS)
+
+**6 steps** | **Data:** integration-verification-rules.md, coverage-patterns.md, feasibility-report-template.md
+
+Pre-code verification engine. Cross-references generated skills against architecture and PRD documents. Three passes: coverage verification (does a skill exist for each tech?), integration verification (do the APIs actually connect?), and requirements verification (does the stack cover the PRD?). Produces a feasibility report with evidence-backed verdicts and prescriptive recommendations. Re-runnable — swap libraries, regenerate skills, re-verify.
+
+### refine-architecture (RA)
+
+**6 steps** | **Data:** refinement-rules.md
 
-Analyzes dependency manifests (package.json, requirements.txt, Cargo.toml, etc.) to detect libraries, ranks by import frequency, discovers co-import integration patterns between libraries, compiles a consolidated stack skill documenting how libraries connect, validates, and generates output.
+Architecture improvement engine. Takes the original architecture document and refines it using verified skill data and VS feasibility findings. Fills gaps, flags issues, suggests improvements — all backed by specific API evidence from the generated skills. Produces a refined architecture document.
 
 ### update-skill (US)
 
-**7 steps** | **Data:** manual-section-rules.md, merge-conflict-rules.md
+**7 steps** | **Data:** manual-section-rules.md, merge-conflict-rules.md, remote-source-resolution.md (tier-degradation-rules shared from create-skill)
 
 Surgical update engine. Loads the existing skill, detects what changed in source since last compilation, re-extracts only affected exports with fresh provenance, merges new extractions while preserving all `[MANUAL]` developer-authored content, validates the merged result, writes the updated skill, and produces a change report.
 
@@ -137,7 +155,7 @@ Drift detection engine. Loads the skill under audit, re-indexes current source t
 
 ### test-skill (TS)
 
-**6 steps** | **Data:** output-section-formats.md, scoring-rules.md | **Templates:** test-report-template.md
+**7 steps** | **Data:** output-section-formats.md, scoring-rules.md, source-access-protocol.md | **Templates:** test-report-template.md
 
 Quality gate before export. Loads the skill, detects test mode (naive for Quick tier, contextual for Forge/Deep), runs coverage checks against source, runs coherence checks for internal consistency, scores using weighted rubric, and produces a completeness report with pass/fail gate decision.
 

package/src/workflows/analyze-source/data/skill-brief-schema.md

@@ -4,7 +4,7 @@
 
 Defines the output contract for skill-brief.yaml files generated by analyze-source. Each generated brief must conform to this schema to be consumable by brief-skill and create-skill downstream workflows.
 
-## Required Fields (9)
+## Required Fields
 
 | Field | Type | Constraint | Description |
 |-------|------|------------|-------------|
@@ -14,7 +14,7 @@ Defines the output contract for skill-brief.yaml files generated by analyze-sour
 | language | string | Recognized language | Primary programming language |
 | scope | object | See Scope Object below | Boundary definition |
 | description | string | 1-3 sentences | What the skill covers |
-| forge_tier | string | `quick` / `forge` / `deep` | Inherited from forge-tier.yaml |
+| forge_tier | string | `Quick` / `Forge` / `Forge+` / `Deep` | Inherited from forge-tier.yaml (Title Case) |
 | created | string | ISO date `YYYY-MM-DD` | Generation date |
 | created_by | string | user_name from config | Who generated the brief |
 
@@ -26,6 +26,13 @@ Defines the output contract for skill-brief.yaml files generated by analyze-sour
 | doc_urls | array | `{url, label}` objects | Documentation URLs for T3 content. Required when `source_type: "docs-only"` |
 | `scripts_intent` | string | `detect` / `none` / free-text | Describes whether scripts should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip scripts), or a free-text description of expected scripts (e.g., "CLI validation tools in bin/"). |
 | `assets_intent` | string | `detect` / `none` / free-text | Describes whether assets should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip assets), or a free-text description of expected assets (e.g., "JSON schemas in schemas/"). |
+| `source_authority` | string | `official` / `community` / `internal` | Default `community`. Set to `official` only when the skill creator is the library maintainer. Forced to `community` when `source_type: "docs-only"`. |
+
+When `source_type: "docs-only"`:
+- `source_repo` becomes optional (set to doc site URL for reference)
+- `doc_urls` must have at least one entry
+- `source_authority` is forced to `community` (T3 external documentation cannot be `official`)
+- All extracted content gets `[EXT:{url}]` citations
 
 ## Version Detection
 
@@ -36,8 +43,12 @@ During brief generation, attempt to auto-detect the source version before defaul
 - **Rust:** `Cargo.toml` `[package] version` (static) → if `version = { workspace = true }`, resolve from workspace root `Cargo.toml` → `git describe --tags --abbrev=0`
 - **Go:** version tag from `go.mod` or `git describe --tags --abbrev=0`
 
+If the source is a remote GitHub repo, use `gh api repos/{owner}/{repo}/contents/{file}` to read the version file. If the source is local, read the file directly.
+
 If detection succeeds, use the detected version. If it fails or returns a non-semver value, fall back to `"1.0.0"`.
 
+The create-skill workflow (step-03-extract) also performs version reconciliation at extraction time — if the source version has changed since the brief was created, the extraction step warns and uses the source version.
+
 ## Scope Object
 
 ```yaml
@@ -57,6 +68,7 @@ scope:
 | full-library | Entire codebase of a unit |
 | specific-modules | Selected components or packages |
 | public-api | Only exported interfaces |
+| docs-only | When source_type is docs-only — no source code available, all content from doc_urls |
 
 ## YAML Template
 
@@ -74,7 +86,7 @@ scope:
     - '{exclude_pattern}'
   notes: '{scope_rationale}'
 description: '{1-3 sentence description}'
-forge_tier: '{forge_tier}'
+forge_tier: '{Quick|Forge|Forge+|Deep}'
 created: '{current_date}'
 created_by: '{user_name}'
 ```
@@ -84,10 +96,11 @@ created_by: '{user_name}'
 1. **Name uniqueness**: No duplicate names within forge_data_folder
 2. **Source accessibility**: source_repo path must exist or be reachable
 3. **Language recognized**: Must be a known programming language
-4. **Scope type valid**: Must match one of the three defined types
-5. **Include patterns**: At least one include glob pattern required
+4. **Scope type valid**: Must match one of the four defined types (full-library, specific-modules, public-api, docs-only)
+5. **Include patterns**: At least one include glob pattern required (exception: `docs-only` scope, where include patterns are optional since no source code is available)
 6. **Forge tier match**: Must match value in forge-tier.yaml
 7. **Docs-only mode**: When `source_type: "docs-only"`, `doc_urls` required (>= 1), `source_repo` optional
+8. Each `doc_urls` entry must have a valid `url` field
 
 ## Output Location
 

package/src/workflows/analyze-source/data/unit-detection-heuristics.md

@@ -111,4 +111,5 @@ Flag units as stack skill candidates when:
 |------------|-------------------|
 | Quick | File structure analysis: directory trees, manifest files, entry points, naming conventions |
 | Forge | AST analysis: export surfaces, import graphs, dependency trees, type hierarchies |
+| Forge+ | AST + CCC: semantic file pre-ranking before structural analysis, CCC signals for relevance scoring |
 | Deep | AST + QMD: temporal evolution, refactoring patterns, semantic relationships, architectural drift |

package/src/workflows/analyze-source/steps-c/step-01-init.md

@@ -4,7 +4,7 @@ description: 'Initialize analysis workflow — load config, detect continuation,
 
 nextStepFile: './step-02-scan-project.md'
 continueFile: './step-01b-continue.md'
-outputFile: '{output_folder}/analyze-source-report-{project_name}.md'
+outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
 templateFile: '../templates/analysis-report-template.md'
 ---
 
@@ -73,10 +73,10 @@ Look for {outputFile}.
 
 **Check forge-tier.yaml:**
 - Look for `{sidecar_path}/forge-tier.yaml`
-- **IF missing:** HARD HALT — "**Cannot proceed.** forge-tier.yaml not found at `{sidecar_path}/forge-tier.yaml`. Please run the setup-forge workflow first to configure your forge tier (Quick/Forge/Deep)."
+- **IF missing:** HARD HALT — "**Cannot proceed.** forge-tier.yaml not found at `{sidecar_path}/forge-tier.yaml`. Please run the setup-forge workflow first to configure your forge tier (Quick/Forge/Forge+/Deep)."
 - **IF found:** Read and note the forge tier value
 
-**Apply tier override:** Read `{sidecar_path}/preferences.yaml`. If `tier_override` is set and is a valid tier value (Quick, Forge, or Deep), use it instead of the detected tier.
+**Apply tier override:** Read `{sidecar_path}/preferences.yaml`. If `tier_override` is set and is a valid tier value (Quick, Forge, Forge+, or Deep), use it instead of the detected tier.
 
 "**Forge tier detected:** {tier} — analysis depth will be calibrated accordingly."
 
@@ -118,7 +118,7 @@ Wait for user input. Document any hints provided.
 
 ### 5. Check for Existing Skills
 
-Scan `{forge_data_folder}/` for existing `skill-brief.yaml` files.
+Scan `{forge_data_folder}/*/skill-brief.yaml` (one level deep — each skill has its own subdirectory) for existing skill briefs.
 
 **IF existing skills found:**
 "**Existing skills detected:**

package/src/workflows/analyze-source/steps-c/step-01b-continue.md

@@ -2,7 +2,7 @@
 name: 'step-01b-continue'
 description: 'Handle workflow continuation from previous session'
 
-outputFile: '{output_folder}/analyze-source-report-{project_name}.md'
+outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
 nextStepOptions:
   step-02: './step-02-scan-project.md'
   step-03: './step-03-identify-units.md'

package/src/workflows/analyze-source/steps-c/step-02-scan-project.md

@@ -3,7 +3,7 @@ name: 'step-02-scan-project'
 description: 'Map project structure, detect service boundaries, and identify package manifests'
 
 nextStepFile: './step-03-identify-units.md'
-outputFile: '{output_folder}/analyze-source-report-{project_name}.md'
+outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
 heuristicsFile: '../data/unit-detection-heuristics.md'
 ---
 

package/src/workflows/analyze-source/steps-c/step-03-identify-units.md

@@ -3,7 +3,7 @@ name: 'step-03-identify-units'
 description: 'Classify discrete skillable units from scan results using detection heuristics and assign scope types'
 
 nextStepFile: './step-04-map-and-detect.md'
-outputFile: '{output_folder}/analyze-source-report-{project_name}.md'
+outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
 heuristicsFile: '../data/unit-detection-heuristics.md'
 ---
 

package/src/workflows/analyze-source/steps-c/step-04-map-and-detect.md

@@ -3,7 +3,7 @@ name: 'step-04-map-and-detect'
 description: 'Map exports per unit and detect cross-unit integration points, flag stack skill candidates'
 
 nextStepFile: './step-05-recommend.md'
-outputFile: '{output_folder}/analyze-source-report-{project_name}.md'
+outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
 heuristicsFile: '../data/unit-detection-heuristics.md'
 ---
 
@@ -81,6 +81,10 @@ DO NOT BE LAZY — For EACH qualifying unit, launch a subprocess (or analyze in
 2. Counts and categorizes exports based on forge tier:
    - **Quick tier:** Count files by type, identify index/barrel files, list directory structure
    - **Forge tier:** Parse export statements, identify public API surface, count exported functions/classes/types
+   - **Forge+ tier:** All Forge analysis plus:
+     - If `tools.ccc` is true: run `ccc_bridge.search("{unit_name} exports public API", top_k=15)` to discover semantically relevant files beyond directory scan
+     - Merge CCC-discovered files with scoped file list — files from CCC that are within the unit's directory are added to the analysis queue
+     - Record CCC signals in per-unit findings: top 3 CCC-ranked file names (or "—" if no ccc results)
    - **Deep tier:** All Forge analysis plus:
      - ast-grep structural export extraction: `ast-grep -p 'export $$$' --lang typescript` or equivalent per language to build a verified export inventory
      - ast-grep type/interface mapping: `ast-grep -p 'interface $NAME' --lang typescript` or `ast-grep -p 'class $NAME($$$)' --lang python`
@@ -96,9 +100,9 @@ DO NOT BE LAZY — For EACH qualifying unit, launch a subprocess (or analyze in
 
 **Per-unit export summary:**
 
-| Unit | Files | Exports | Export Pattern | API Surface | Scripts/Assets |
-|------|-------|---------|----------------|-------------|----------------|
-| {name} | {count} | {count} | {pattern} | {small/medium/large} | {N scripts, M assets or --} |
+| Unit | Files | Exports | Export Pattern | API Surface | Scripts/Assets | CCC Signals |
+|------|-------|---------|----------------|-------------|----------------|-------------|
+| {name} | {count} | {count} | {pattern} | {small/medium/large} | {N scripts, M assets or --} | {CCC signals or --} |
 
 ### 3. Map Import Graph
 

package/src/workflows/analyze-source/steps-c/step-05-recommend.md

@@ -3,7 +3,7 @@ name: 'step-05-recommend'
 description: 'Present unit recommendations with rationale for user confirmation or rejection'
 
 nextStepFile: './step-06-generate-briefs.md'
-outputFile: '{output_folder}/analyze-source-report-{project_name}.md'
+outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
 schemaFile: '../data/skill-brief-schema.md'
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
 partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'

package/src/workflows/analyze-source/steps-c/step-06-generate-briefs.md

@@ -2,7 +2,7 @@
 name: 'step-06-generate-briefs'
 description: 'Generate skill-brief.yaml per confirmed unit, write analysis summary, recommend next workflow'
 
-outputFile: '{output_folder}/analyze-source-report-{project_name}.md'
+outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
 schemaFile: '../data/skill-brief-schema.md'
 ---
 
@@ -218,7 +218,7 @@ nextWorkflow: '{primary recommendation}'
 ### ✅ SUCCESS:
 
 - Every confirmed unit has a skill-brief.yaml generated and validated
-- All 9 required schema fields present and valid in each brief
+- All required schema fields present and all 8 validation rules passed in each brief
 - Files written to correct paths in forge_data_folder
 - User confirmed before files were written
 - Next workflow recommended per unit

package/src/workflows/analyze-source/workflow.md

@@ -2,7 +2,7 @@
 name: analyze-source
 description: Decomposition engine — discover what to skill, recommend stack skill
 web_bundle: true
-installed_path: '{project-root}/_bmad/skf/workflows/analyze-source'
+installed_path: '{project-root}/_bmad/skf/workflows/skillforge/analyze-source'
 ---
 
 # Analyze Source
@@ -24,7 +24,7 @@ installed_path: '{project-root}/_bmad/skf/workflows/analyze-source'
 - **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
 - **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array
 - **Append-Only Building**: Build the analysis report by appending content as directed to the output file
-- **Tier-Aware Analysis**: Scanning depth adapts to forge tier — Quick (file structure), Forge (AST), Deep (AST+QMD)
+- **Tier-Aware Analysis**: Scanning depth adapts to forge tier — Quick (file structure), Forge (AST), Forge+ (AST + CCC semantic pre-ranking), Deep (AST+QMD)
 
 ### Step Processing Rules
 

package/src/workflows/audit-skill/data/drift-report-template.md

@@ -13,15 +13,15 @@ nextWorkflow: ''
 previousWorkflow: 'create-skill'
 ---
 
-# Drift Report: {{skill_name}}
+# Drift Report: {skill_name}
 
 ## Audit Summary
 
-**Skill:** {{skill_name}}
-**Source:** {{source_path}}
-**Tier:** {{forge_tier}}
-**Date:** {{date}}
-**Overall Drift Score:** {{drift_score}}
+**Skill:** {skill_name}
+**Source:** {source_path}
+**Tier:** {forge_tier}
+**Date:** {date}
+**Overall Drift Score:** {drift_score}
 
 | Category | Count |
 |----------|-------|

package/src/workflows/audit-skill/data/severity-rules.md

@@ -48,5 +48,5 @@
 |-------|--------|-------------|
 | T1 | AST extraction (ast-grep) | High — structural truth |
 | T1-low | Text pattern matching (no AST) | Moderate — pattern-based |
-| T2 | QMD temporal context | High — evidence-backed |
+| T2 | QMD semantic context | High — evidence-backed temporal context |
 | T3 | External documentation reference | Variable — secondary source |

package/src/workflows/audit-skill/steps-c/step-01-init.md

@@ -82,10 +82,10 @@ Load `{sidecar_path}/forge-tier.yaml` to detect available tools.
 - HALT workflow
 
 **If found:**
-- Extract tier level: Quick / Forge / Deep
+- Extract tier level: Quick / Forge / Forge+ / Deep
 - Extract available tools: gh_bridge, ast_bridge, qmd_bridge
 
-**Apply tier override:** Read `{sidecar_path}/preferences.yaml`. If `tier_override` is set and is a valid tier value (Quick, Forge, or Deep), use it instead of the detected tier.
+**Apply tier override:** Read `{sidecar_path}/preferences.yaml`. If `tier_override` is set and is a valid tier value (Quick, Forge, Forge+, or Deep), use it instead of the detected tier.
 
 ### 3. Load Skill Artifacts
 
@@ -152,6 +152,7 @@ Create `{outputFile}` from `{templateFile}`:
 **Analysis plan based on tier:**
 - {Quick: text-diff comparison (T1-low confidence)}
 - {Forge: AST structural comparison (T1 confidence)}
+- {Forge+: AST structural comparison + CCC-assisted rename detection (T1 confidence)}
 - {Deep: AST structural + QMD semantic comparison (T1 + T2 confidence)}
 
 **Ready to begin drift analysis?**"

package/src/workflows/audit-skill/steps-c/step-02-re-index.md

@@ -68,6 +68,11 @@ Based on forge tier detected in Step 01:
 - Extract: export name, type (function/class/type/const), full signature, file path, line number
 - Confidence label: T1
 
+**Forge+ tier (ast-grep + ccc available):**
+- Identical extraction to Forge tier: use ast_bridge for AST extraction per source file
+- Confidence label: T1
+- CCC rename detection available (see section 4b)
+
 **Deep tier (ast-grep + QMD available):**
 - Forge extraction (above) PLUS
 - Query qmd_bridge for temporal context: when exports were added, modification history, usage frequency
@@ -134,9 +139,26 @@ Append temporal metadata to each export in the snapshot.
 Log: "No QMD extraction collection found for {skill_name}. Temporal enrichment skipped. Re-run [CS] Create Skill to generate the collection."
 Continue without T2 enrichment — this is not an error.
 
-**IF forge tier is Quick or Forge:**
+**IF forge tier is Quick, Forge, or Forge+:**
 Skip this section. Temporal context requires Deep tier.
 
+### 4b. CCC Rename Detection (Forge+ and Deep with ccc)
+
+**IF `tools.ccc` is true in forge-tier.yaml:**
+
+For each export in the skill baseline that was NOT found at its recorded file path during re-extraction (potential "deleted" export):
+
+1. Run `ccc_bridge.search("{export_name}", source_root, top_k=5)` to find candidate current locations
+2. If CCC returns files containing the export name:
+   - Run ast-grep verification on each candidate file
+   - If verified at a new location: reclassify from "deleted" to "moved" with the new file:line reference
+   - This reduces false-positive structural drift findings where exports were relocated, not removed
+3. If CCC returns no results or verification fails: keep the "deleted" classification
+
+CCC failures: skip rename detection silently, proceed with standard structural diff.
+
+**IF `tools.ccc` is false:** Skip this section silently.
+
 ### 5. Validate Extraction Completeness
 
 "**Extraction complete.**