bmad-module-skill-forge 0.2.0

package/src/knowledge/manual-section-integrity.md

@@ -0,0 +1,156 @@
+# Manual Section Integrity
+
+## Principle
+
+Sections marked with `[MANUAL]` delimiters contain developer-authored content that the forge never modifies, regenerates, or removes. The merge algorithm treats \[MANUAL\] blocks as inviolable during updates — they are preserved in place, and any conflict between generated content and manual content is escalated to the user.
+
+## Rationale
+
+Generated skills cover what can be extracted from source code, but developers often need to add context that no tool can infer: architectural rationale, migration guides, team conventions, known gotchas. The \[MANUAL\] marker system gives developers a safe zone for hand-written content that survives regeneration cycles.
+
+Without \[MANUAL\] preservation:
+- Developer-authored content is overwritten on every update-skill run
+- Users stop adding valuable context because it disappears
+- Skills become purely mechanical extractions with no human insight
+
+With \[MANUAL\] preservation:
+- Hand-written content persists across unlimited regeneration cycles
+- Developers invest in skill quality knowing their work is protected
+- Skills combine machine-extracted precision with human-authored context
+
+## Marker Format
+
+\[MANUAL\] sections use HTML comment delimiters:
+
+```markdown
+<!-- [MANUAL:section-name] -->
+
+Developer-authored content here. This content is never modified
+by the forge during updates or regeneration.
+
+<!-- [/MANUAL:section-name] -->
+```
+
+**Rules:**
+- `section-name` must be unique within the file
+- Opening and closing markers must match exactly
+- Multiple \[MANUAL\] blocks allowed per file
+- Nested \[MANUAL\] blocks are forbidden — trigger an ERROR if detected
+- Markers apply to any output file: `SKILL.md`, `references/*.md`, integration files
+
+## Pattern Examples
+
+### Example 1: Adding Manual Context to a Generated Skill
+
+**Context:** A developer wants to add migration notes to an API function that the forge generated.
+
+**Implementation:**
+```markdown
+## `migrateDatabase(config: MigrateConfig): Promise<void>`
+
+Runs pending database migrations in sequence.
+
+**Parameters:**
+| Name | Type | Required | Default |
+| --- | --- | --- | --- |
+| config | `MigrateConfig` | yes | — |
+
+[AST:src/migrate.ts:L15]
+
+<!-- [MANUAL:migrate-notes] -->
+
+### Migration Gotchas
+
+- Always run `backupDatabase()` before migration in production
+- Migrations are not reversible after v2.3.0 — the rollback API was removed
+- If using connection pooling, set `pool.max = 1` during migration to avoid lock conflicts
+
+<!-- [/MANUAL:migrate-notes] -->
+```
+
+**Key Points:**
+- The \[MANUAL\] block sits naturally within the generated skill structure
+- Content inside the markers is entirely developer-controlled
+- The forge regenerates everything outside the markers; the block is re-inserted in place
+
+### Example 2: Merge Algorithm During Update
+
+**Context:** The update-skill workflow needs to regenerate a skill while preserving \[MANUAL\] blocks.
+
+**Implementation:** The merge follows this sequence:
+1. **Extract** all \[MANUAL\] blocks from the existing skill, recording their section-name and parent section context
+2. **Map** each block to its parent section in the document structure
+3. **Regenerate** the skill content from fresh source extraction
+4. **Re-insert** \[MANUAL\] blocks into their original positions relative to parent sections
+5. **Flag conflicts** if any arise (see conflict types below)
+
+**Key Points:**
+- \[MANUAL\] blocks are extracted before regeneration and re-inserted after
+- Position is determined by parent section, not absolute line number
+- The merge is deterministic — same inputs always produce same output
+
+### Example 3: Conflict Resolution
+
+**Context:** Regeneration produces content that conflicts with existing \[MANUAL\] blocks.
+
+**Implementation:** Four conflict severity levels:
+
+| Severity | Condition | Resolution |
+| --- | --- | --- |
+| HIGH | Regenerated content overlaps \[MANUAL\] position | Present both versions, user chooses |
+| WARNING | Parent section deleted, \[MANUAL\] block orphaned | Flag orphaned block, user decides to keep or remove |
+| MEDIUM | \[MANUAL\] references a deleted export | Flag stale reference for user review |
+| LOW | New export generated adjacent to \[MANUAL\] block | Auto-resolve: place new content before the block |
+
+**Key Points:**
+- HIGH and WARNING conflicts always require user input — never auto-resolved
+- MEDIUM conflicts are flagged but do not block the update
+- LOW conflicts are auto-resolved with a deterministic rule (new content before block)
+
+### Example 4: Orphan Detection
+
+**Context:** An export that contained a \[MANUAL\] block has been removed from source.
+
+**Implementation:**
+```
+WARNING: Orphaned [MANUAL] block detected
+
+  Section: [MANUAL:migrate-notes]
+  Previous parent: ## `migrateDatabase(config: MigrateConfig): Promise<void>`
+  Status: Parent export removed from source
+
+  Options:
+  1. Keep block in a "Legacy Notes" section at end of skill
+  2. Remove block (content will be shown for copy before deletion)
+  3. Relocate to a different section (specify target)
+```
+
+**Key Points:**
+- Orphaned blocks are never silently deleted
+- The user always sees the content and chooses its fate
+- Option 1 preserves the content without cluttering the active skill sections
+
+## Audit Interaction
+
+The audit-skill workflow detects \[MANUAL\] section integrity issues:
+- **Malformed markers**: Missing closing tag, mismatched names
+- **Nested markers**: \[MANUAL\] inside \[MANUAL\] — always an error
+- **Stale references**: \[MANUAL\] content mentioning exports that no longer exist
+- **Orphaned blocks**: Parent section no longer in the skill
+
+These findings appear in the drift report with appropriate severity classifications.
+
+## Anti-Patterns
+
+- Modifying content inside \[MANUAL\] markers during automated updates — always preserve exactly
+- Silently removing orphaned \[MANUAL\] blocks — always escalate to user
+- Nesting \[MANUAL\] blocks — one level only, nesting is an error
+- Using \[MANUAL\] markers in provenance-map.json or metadata.json — markers are for markdown content files only
+
+## Related Fragments
+
+- [provenance-tracking.md](provenance-tracking.md) — how \[MANUAL\] sections interact with provenance (no source location, author: "manual")
+- [zero-hallucination.md](zero-hallucination.md) — \[MANUAL\] sections are the designated space for human-authored claims
+- [skill-lifecycle.md](skill-lifecycle.md) — \[MANUAL\] preservation is critical in the update and audit phases
+
+_Source: consolidated from manual-section-rules.md, merge-conflict-rules.md, and update-skill steps_

package/src/knowledge/overview.md

@@ -0,0 +1,56 @@
+# SKF Knowledge Overview
+
+## Principle
+
+Agent-level knowledge files capture cross-cutting principles and patterns that Ferris applies across multiple workflows. They are distinct from workflow `data/` files, which contain step-specific operational artifacts. Knowledge is loaded just-in-time when a workflow step directs — never preloaded into context.
+
+## Rationale
+
+The SKF module has 10 workflows containing 19 operational `data/` files embedded in step directories. These data files define schemas, templates, scoring formulas, and extraction rules tightly coupled to individual steps. But several principles — zero hallucination, confidence tiers, provenance — cut across multiple workflows and need a single authoritative source rather than fragmented repetition.
+
+Without a knowledge folder:
+- Cross-cutting principles get duplicated across workflow steps
+- Updates to foundational rules require changes in multiple locations
+- Ferris has no centralized reference for judgment calls that span workflows
+
+With knowledge files:
+- Each principle has one canonical definition
+- Workflow steps reference knowledge files instead of re-stating rules
+- Ferris loads only the knowledge relevant to the current task
+
+## Knowledge Map
+
+| File | Purpose | Key Workflows |
+| --- | --- | --- |
+| [zero-hallucination.md](zero-hallucination.md) | Every claim traces to source; uncitable content excluded | AN, BS, CS, QS, SS, US, AS, TS |
+| [confidence-tiers.md](confidence-tiers.md) | T1/T1-low/T2/T3 trust model and citation formats | AN, BS, CS, QS, SS, US, AS, TS, EX |
+| [progressive-capability.md](progressive-capability.md) | Quick/Forge/Deep tier philosophy and behavior adaptation | All 10 |
+| [agentskills-spec.md](agentskills-spec.md) | agentskills.io output format principles and compliance | CS, QS, SS, US, TS, EX |
+| [skill-lifecycle.md](skill-lifecycle.md) | End-to-end pipeline, artifact flow, workflow selection | All 10 |
+| [provenance-tracking.md](provenance-tracking.md) | Provenance-map.json, evidence reports, claim traceability | CS, QS, SS, US, AS, TS |
+| [manual-section-integrity.md](manual-section-integrity.md) | \[MANUAL\] marker preservation and merge algorithm | CS, US, AS, TS, EX |
+
+## JiT Loading Protocol
+
+1. Ferris receives a task or workflow activation
+2. Consult `skf-knowledge-index.csv` to identify relevant knowledge fragments by tags or description
+3. Load only the files needed for the current task — never bulk-load all knowledge
+4. Apply knowledge principles during workflow execution alongside step-specific `data/` files
+
+## Knowledge vs. Data
+
+| Aspect | Knowledge Files (`knowledge/`) | Data Files (`data/`) |
+| --- | --- | --- |
+| Scope | Cross-cutting, multi-workflow | Single workflow, single step |
+| Content | Principles, patterns, judgment rules | Schemas, templates, scoring formulas |
+| Loading | JiT via index lookup | JiT via step instruction |
+| Examples | Zero hallucination, confidence tiers | skill-brief-schema.md, scoring-rules.md |
+| Stability | Rarely changes | Changes with workflow evolution |
+
+## Related Fragments
+
+- [confidence-tiers.md](confidence-tiers.md) — the trust model that underpins extraction and scoring
+- [skill-lifecycle.md](skill-lifecycle.md) — the end-to-end pipeline connecting all workflows
+- [progressive-capability.md](progressive-capability.md) — tier philosophy that affects every workflow
+
+_Source: synthesized from module.yaml, README.md, and workflow README_

package/src/knowledge/progressive-capability.md

@@ -0,0 +1,120 @@
+# Progressive Capability
+
+## Principle
+
+Every capability tier — Quick, Forge, and Deep — produces legitimate, useful skills. Tiers describe what tools are available, not a quality hierarchy. A Quick skill is complete at its tier; a Deep skill adds depth, not correctness. Framing is always positive: describe what each tier enables, never what it lacks.
+
+## Rationale
+
+Skill Forge operates in diverse environments. Some users have ast-grep, GitHub CLI, and QMD installed; others have none. The progressive capability model ensures Ferris adapts to the environment without making users feel their setup is insufficient.
+
+Without progressive capability:
+- Users without ast-grep see error messages or degraded output
+- Quick tier skills feel like failures rather than valid deliverables
+- Workflow steps contain conditional logic for missing tools scattered throughout
+
+With progressive capability:
+- Each tier has a clear identity and positive capability description
+- Workflow behavior adapts cleanly based on the detected tier
+- Users understand what their tier enables and what upgrading would add
+
+## Tier Definitions
+
+| Tier | Requirements | Capabilities | Identity |
+| --- | --- | --- | --- |
+| Quick | No tools required | Fast, template-driven, package-name resolution | Speed-first skill creation |
+| Forge | ast-grep available | AST-backed structural analysis, line-level citations | Precision-focused compilation |
+| Deep | ast-grep + gh + qmd | AST + GitHub exploration + QMD synthesis, maximum provenance | Full intelligence pipeline |
+
+## Pattern Examples
+
+### Example 1: Tool Detection and Tier Assignment
+
+**Context:** The setup-forge workflow detects available tools and assigns a tier.
+
+**Implementation:** Each tool is verified by executing its version command — presence in PATH is insufficient. The tier is the highest level where all required tools pass verification:
+
+```
+ast-grep --version  → required for Forge
+gh --version        → required for Deep
+qmd status          → required for Deep
+```
+
+If ast-grep passes but gh fails, the tier is Forge (not a "degraded Deep").
+
+**Key Points:**
+- Tools must be functional, not just installed
+- Tier assignment is deterministic — no ambiguity
+- The result is written to `forge-tier.yaml` in the sidecar and persists across sessions
+
+### Example 2: Positive Tier Framing
+
+**Context:** Reporting the detected tier to the user.
+
+**Implementation:**
+```
+Quick:  "Fast, template-driven skill creation — package-name resolution and
+         source reading. Skills ready in minutes."
+
+Forge:  "AST-backed structural analysis — line-level citations with verified
+         signatures. Precision-focused compilation."
+
+Deep:   "Full intelligence pipeline — AST verification plus GitHub exploration
+         and QMD knowledge synthesis. Maximum provenance depth."
+```
+
+**Key Points:**
+- Each description leads with what the tier does, not what it misses
+- No tier mentions another tier's capabilities as something it lacks
+- Quick is "fast" not "limited"; Forge is "precise" not "partial"
+
+### Example 3: Tier-Adaptive Extraction
+
+**Context:** The create-skill extraction step adapts its strategy based on the forge tier.
+
+**Implementation:**
+- **Quick:** Reads source files, applies pattern matching for exports and signatures, produces T1-low citations. Uses `gh_bridge` for file structure when available as a convenience, not a requirement.
+- **Forge:** Uses `ast_bridge.scan_definitions()` for structural parsing, produces T1 citations with exact AST node types. Falls back to source reading for files ast-grep cannot parse.
+- **Deep:** Identical extraction to Forge, plus QMD enrichment in a separate step. T2 annotations layer on top of the T1 base without replacing it.
+
+**Key Points:**
+- Extraction quality increases with tier, but every tier produces complete output
+- Forge and Deep share the same extraction core — Deep adds enrichment, not better parsing
+- Fallback within a tier (e.g., ast-grep fails on one file) degrades gracefully to T1-low for that file only
+
+### Example 4: Tier-Adaptive Scoring
+
+**Context:** The test-skill workflow adjusts scoring weights based on the forge tier.
+
+**Implementation:**
+- **Quick (Naive mode):** Export Coverage 50%, Signature Accuracy 30%, Type Coverage 20%. No coherence check — AST verification unavailable.
+- **Forge (Contextual mode):** Export Coverage 40%, Signature Accuracy 25%, Type Coverage 15%, Coherence 20%. Full AST-backed verification.
+- **Deep (Contextual mode):** Same weights as Forge, plus cross-repo verification and QMD coherence checks feed into the coherence score.
+
+**Key Points:**
+- Pass threshold (80%) is the same across all tiers — quality bar is tier-independent
+- Weight redistribution reflects what each tier can actually measure
+- A Quick skill scoring 85% and a Deep skill scoring 85% both pass — different measurements, same bar
+
+## Graceful Degradation
+
+When a tool becomes unavailable mid-session (e.g., ast-grep uninstalled between runs):
+1. Setup-forge re-detects and downgrades the tier
+2. Existing skills retain their original citations — they don't retroactively lose confidence
+3. New extractions use the current tier's capabilities
+4. The tier change is logged in the sidecar for audit trail
+
+## Anti-Patterns
+
+- Describing Quick tier as "basic" or "limited" — it is fast and legitimate
+- Requiring ast-grep for workflows that work fine without it (setup-forge, brief-skill)
+- Mixing tier capabilities in a single extraction (e.g., T1 citations when only source reading was used)
+- Failing a workflow because the tier is "too low" — adapt behavior instead
+
+## Related Fragments
+
+- [confidence-tiers.md](confidence-tiers.md) — how tier determines available confidence levels
+- [skill-lifecycle.md](skill-lifecycle.md) — how tier affects workflow selection and artifact flow
+- [zero-hallucination.md](zero-hallucination.md) — Quick tier has lower confidence but the same integrity standard
+
+_Source: distilled from forge-tier.yaml, tier-rules.md, and setup-forge workflow_

package/src/knowledge/provenance-tracking.md

@@ -0,0 +1,163 @@
+# Provenance Tracking
+
+## Principle
+
+Every claim in a generated skill has a recorded provenance chain — from the assertion in the skill back to the source location, extraction method, and confidence tier. Provenance is stored in machine-readable format (`provenance-map.json`) alongside human-readable evidence reports, making claims independently verifiable.
+
+## Rationale
+
+Skills make hundreds of individual claims: function signatures, parameter types, default values, behavioral descriptions. Without provenance, there is no way to verify whether a claim is current, to detect drift when source changes, or to trace a broken instruction back to its origin.
+
+Without provenance tracking:
+- Audit workflows cannot compare skill claims against current source
+- Update workflows cannot identify which claims need re-extraction
+- Users cannot distinguish verified claims from stale or fabricated ones
+
+With provenance tracking:
+- Every claim maps to a specific source location and extraction method
+- Audit workflows perform precise structural and semantic diffing
+- Update workflows selectively re-extract only changed claims
+
+## Provenance Artifacts
+
+| Artifact | Format | Purpose | Generated By |
+| --- | --- | --- | --- |
+| `provenance-map.json` | JSON | Machine-readable claim-to-source mapping | CS, QS, SS |
+| `evidence-report.md` | Markdown | Human-readable extraction summary | CS, QS, SS |
+| Inline citations | `[TAG:path:Lnn]` | Per-claim source reference in SKILL.md | CS, QS, SS, US |
+| `drift-report.md` | Markdown | Findings from source comparison | AS |
+
+## Pattern Examples
+
+### Example 1: Provenance Map Structure
+
+**Context:** The create-skill workflow generates a `provenance-map.json` alongside each skill.
+
+**Implementation:**
+```json
+{
+  "version": "1.0",
+  "generated_at": "2025-01-15T10:30:00Z",
+  "extraction_tier": "forge",
+  "claims": {
+    "createServer": {
+      "source_file": "src/server.ts",
+      "line": 23,
+      "confidence": "t1",
+      "extraction_method": "ast-grep",
+      "ast_node_type": "export_statement > function_declaration",
+      "signature": "createServer(options: ServerOptions): Server"
+    },
+    "parseConfig": {
+      "source_file": "src/config.ts",
+      "line": 45,
+      "confidence": "t1_low",
+      "extraction_method": "source-read",
+      "ast_node_type": null,
+      "signature": "parseConfig(input)"
+    }
+  }
+}
+```
+
+**Key Points:**
+- Each claim is keyed by export name for direct lookup
+- `ast_node_type` is null for non-AST extractions — never fabricated
+- `extraction_method` distinguishes how the claim was obtained
+- Confidence tier is recorded per-claim, not per-file
+
+### Example 2: Evidence Report
+
+**Context:** The evidence report provides a human-readable summary of the extraction.
+
+**Implementation:**
+```markdown
+# Evidence Report: express-skill
+
+## Extraction Summary
+- **Tier:** Forge
+- **Tool versions:** ast-grep 0.25.0
+- **Source files scanned:** 12
+- **Exports extracted:** 47
+- **Confidence distribution:** T1: 42, T1-low: 5, T2: 0, T3: 0
+
+## Validation Results
+- Signature accuracy: all T1 claims verified against AST
+- Coverage: 47/52 public exports documented (5 internal re-exports excluded)
+- Gaps: 3 exports with incomplete type information (marked T1-low)
+
+## Extraction Log
+| Export | File | Line | Confidence | Notes |
+| --- | --- | --- | --- | --- |
+| createServer | src/server.ts | 23 | T1 | Full signature with generics |
+| parseConfig | src/config.ts | 45 | T1-low | Type annotation missing |
+| ... | ... | ... | ... | ... |
+```
+
+**Key Points:**
+- Tool versions recorded for reproducibility
+- Coverage calculated against actual public exports, not estimated
+- Gaps explicitly listed — they feed into test-skill scoring
+
+### Example 3: Audit Drift Detection Using Provenance
+
+**Context:** The audit-skill workflow uses the provenance map to detect drift.
+
+**Implementation:** The audit process:
+1. Load the existing `provenance-map.json`
+2. Re-index current source to build a fresh reference (same extraction method)
+3. For each claim in the provenance map, compare against fresh reference:
+   - **Signature changed** → CRITICAL or HIGH severity
+   - **Export removed** → CRITICAL severity
+   - **New export undocumented** → HIGH (if > 3) or MEDIUM (if 1-3)
+   - **Implementation changed, API stable** → MEDIUM severity
+   - **Style/whitespace only** → LOW severity
+4. Produce a drift report with severity classifications
+
+**Key Points:**
+- Provenance enables precise diffing — compare specific claims, not entire files
+- Severity classification uses the rules from audit-skill/data/severity-rules.md
+- The drift report feeds into the update-skill workflow as re-extraction targets
+
+### Example 4: Provenance Preservation During Updates
+
+**Context:** The update-skill workflow merges fresh extractions with existing provenance.
+
+**Implementation:**
+1. Load existing provenance map
+2. Identify claims that need re-extraction (from audit drift report or source change detection)
+3. Re-extract only affected claims using current tier tools
+4. Merge fresh provenance entries into the existing map:
+   - Changed claims: replace with new provenance
+   - Unchanged claims: preserve existing provenance (timestamp unchanged)
+   - Removed exports: remove from provenance map
+   - New exports: add with fresh provenance
+5. Regenerate evidence report reflecting the update
+
+**Key Points:**
+- Selective re-extraction — only changed claims are re-processed
+- Provenance timestamps show when each claim was last verified
+- The merge preserves \[MANUAL\] section provenance (author: "manual", no source location)
+
+## Inline Citation Rules
+
+Citations appear directly in SKILL.md content:
+- Place citations at the end of the relevant line or block
+- Use the citation format matching the confidence tier (see [confidence-tiers.md](confidence-tiers.md))
+- Multiple citations on the same claim are ordered by confidence: T1 > T1-low > T2 > T3
+- Citations in \[MANUAL\] sections are author-provided and not managed by the forge
+
+## Anti-Patterns
+
+- Generating provenance-map.json with fabricated line numbers — line numbers must come from actual extraction
+- Copying provenance from a previous extraction without re-verifying — timestamps must reflect actual verification time
+- Omitting the evidence report — it is required for every compilation, not optional
+- Using provenance from one source file version against a different version — provenance is version-bound
+
+## Related Fragments
+
+- [confidence-tiers.md](confidence-tiers.md) — defines the citation formats used in provenance
+- [zero-hallucination.md](zero-hallucination.md) — the principle that provenance enforces
+- [manual-section-integrity.md](manual-section-integrity.md) — how \[MANUAL\] sections interact with provenance
+
+_Source: consolidated from create-skill steps 03/05/07, audit-skill steps 02/03, and skill-sections.md_

package/src/knowledge/skf-knowledge-index.csv

@@ -0,0 +1,9 @@
+id,name,description,tags,tier,fragment_file
+overview,Knowledge Overview,"Entry point — knowledge map, JiT loading protocol, relationship to workflow data/ files","knowledge,navigation,jit-loading",core,knowledge/overview.md
+zero-hallucination,Zero Hallucination Principle,"Foundational principle — uncitable content is excluded not guessed, every claim traces to source","integrity,provenance,extraction",core,knowledge/zero-hallucination.md
+confidence-tiers,Confidence Tiers,"Trust model — T1/T1-low/T2/T3 labels, citation formats, tier interaction rules","confidence,citations,evidence,tiers",core,knowledge/confidence-tiers.md
+progressive-capability,Progressive Capability,"Quick/Forge/Deep philosophy — every tier is legitimate, positive framing, graceful degradation","tiers,quick,forge,deep,capability",core,knowledge/progressive-capability.md
+agentskills-spec,agentskills.io Specification,"Format principles — frontmatter, progressive disclosure, directory structure, compliance rules","agentskills,format,compliance,output",core,knowledge/agentskills-spec.md
+skill-lifecycle,Skill Lifecycle,"End-to-end pipeline — workflow connections, artifact flow, decision rules for workflow selection","lifecycle,pipeline,workflows,artifacts",core,knowledge/skill-lifecycle.md
+provenance-tracking,Provenance Tracking,"Provenance mechanism — provenance-map.json, evidence reports, claim traceability","provenance,evidence,traceability,citations",core,knowledge/provenance-tracking.md
+manual-section-integrity,Manual Section Integrity,"[MANUAL] preservation — marker format, merge algorithm, orphan detection","manual,preservation,merge,markers",core,knowledge/manual-section-integrity.md

package/src/knowledge/skill-lifecycle.md

@@ -0,0 +1,150 @@
+# Skill Lifecycle
+
+## 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.
+
+## Rationale
+
+Skills are not created in a single step — they move through discovery, design, compilation, verification, and distribution phases. Each phase has dedicated workflows with specific inputs and outputs. The lifecycle model prevents users from skipping critical steps and ensures artifacts flow cleanly between workflows.
+
+Without lifecycle awareness:
+- Users jump to create-skill without proper analysis or briefing
+- Generated skills lack provenance because upstream artifacts were skipped
+- Export packages reference stale or untested skills
+
+With lifecycle awareness:
+- Ferris recommends the appropriate entry point based on the user's context
+- Artifact dependencies are explicit — each workflow declares its inputs
+- The full pipeline produces verified, export-ready skills with complete provenance
+
+## Pipeline Phases
+
+| Phase | Workflows | Purpose | Artifacts Produced |
+| --- | --- | --- | --- |
+| Setup | SF (Setup Forge) | Detect environment and set capability tier | `forge-tier.yaml` |
+| 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 |
+| 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 |
+
+## Typical Flows
+
+### First-Time Setup (Brownfield Project)
+
+```
+SF → AN → CS (--batch) → TS → EX
+```
+
+1. **SF** detects tools, writes forge tier
+2. **AN** scans the project, identifies skillable units, generates skill briefs
+3. **CS** compiles skills from briefs (batch mode processes all briefs)
+4. **TS** runs completeness verification on each skill
+5. **EX** packages passing skills for distribution
+
+### Single Skill (Full Quality)
+
+```
+SF → BS → CS → TS → EX
+```
+
+1. **SF** ensures environment is configured
+2. **BS** guides the user through scope definition, produces a validated brief
+3. **CS** compiles the skill with full provenance
+4. **TS** verifies completeness
+5. **EX** packages for distribution
+
+### Single Skill (Fast)
+
+```
+SF → QS → EX
+```
+
+1. **SF** ensures environment is configured
+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)
+
+### Maintenance
+
+```
+AS → US → TS → EX
+```
+
+1. **AS** detects drift between skill and current source
+2. **US** re-extracts changed exports and merges, preserving \[MANUAL\] sections
+3. **TS** re-verifies the updated skill
+4. **EX** re-exports the updated package
+
+## Pattern Examples
+
+### Example 1: Workflow Selection Decision
+
+**Context:** A user asks Ferris to create a skill for a specific library.
+
+**Implementation:** Ferris evaluates the situation:
+
+| Condition | Recommended Flow |
+| --- | --- |
+| User knows exactly what to skill, has a brief | CS directly |
+| User knows the library but needs scope guidance | BS → CS |
+| 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 |
+
+**Key Points:**
+- SF is always prerequisite (but only needs to run once per project)
+- Quick skill (QS) skips briefing — appropriate for well-known packages
+- Analyze source (AN) is the brownfield entry point for large projects
+
+### Example 2: Artifact Flow Between Workflows
+
+**Context:** Tracking how artifacts flow through the pipeline.
+
+**Implementation:**
+```
+SF → forge-tier.yaml
+       ↓ (read by all subsequent workflows)
+AN → analysis-report.md + skill-brief.yaml[]
+       ↓ (briefs consumed by CS)
+CS → SKILL.md + metadata.json + provenance-map.json + evidence-report.md
+       ↓ (skill consumed by TS)
+TS → test-report.md (pass/fail gate)
+       ↓ (passing skill consumed by EX)
+EX → agentskills.io bundle + context snippets
+```
+
+**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
+
+### Example 3: Stack Skill vs. Individual Skills
+
+**Context:** A user wants to document how multiple libraries work together in their project.
+
+**Implementation:** Two approaches serve different needs:
+- **Individual skills** (via CS or QS): One skill per library, each with its own provenance and lifecycle. Best for reusable skills that apply across projects.
+- **Stack skill** (via SS): A single consolidated skill documenting how libraries connect. Detects co-import patterns and integration surfaces. Best for project-specific context.
+
+**Key Points:**
+- Stack skills and individual skills are complementary, not competing
+- SS detects integration patterns (e.g., "express + passport always used together for auth routes")
+- Individual skills track per-library provenance; stack skills track inter-library relationships
+
+## Integration Points
+
+- **Setup Forge** must run before any other workflow — it establishes the tier
+- **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
+- **Export Skill** is the terminal workflow — it produces the distributable artifact
+
+## Related Fragments
+
+- [progressive-capability.md](progressive-capability.md) — how the forge tier affects each pipeline phase
+- [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_