Other platforms: see Platform Support below.

Path A: Build a New Bundle-Plugin

bundles-forge:blueprinting

This starts a structured interview to design your project — scope, platform targets, skill decomposition. When the design is ready, the agent automatically chains into scaffolding (project generation) and then authoring (SKILL.md writing).

Path B: Audit an Existing Project

cd your-bundle-plugin-project
bundles-forge:auditing

Runs a 10-category quality assessment with pattern-based security checks across 7 file categories.

Concepts

| Concept | What it is | |---------|------------| | Skill | Atomic capability unit (SKILL.md) — discovered by description, loaded on demand | | Plugin | Packaging/distribution unit — bundles skills, agents, hooks, and more | | Subagent | Isolated AI assistant for delegated tasks with its own context window | | Hook | Shell/HTTP/LLM/Agent action that fires automatically on lifecycle events | | MCP | Open standard connecting Claude to external tools and data sources |

Full explanations, design decisions, and architecture diagrams → Concepts Guide

Skills

The 8 skills cover the full lifecycle of a bundle-plugin project, organized into two layers:

• Orchestrators (blueprinting, optimizing, releasing) — diagnose, decide, and delegate. They chain multiple skills together to accomplish multi-step goals.
• Executors (scaffolding, authoring, auditing, testing) — single-responsibility workers. They can be invoked directly by users or dispatched by orchestrators.

flowchart LR
    Design["blueprinting"] --> Scaffold["scaffolding"]
    Design -->|"content authoring"| Write["authoring"]
    Design -->|"initial audit"| Audit["auditing"]
    Audit -->|issues| Optimize["optimizing"]
    Optimize -->|"delegate changes"| Write
    Optimize --> Audit
    Audit -->|pass| Test["testing"]
    Test -->|pass| Release["releasing"]

| Phase | Skill | What It Does | |-------|-------|-------------| | Design | blueprinting | Three-phase interview (needs exploration → architecture design → design review) → design document → orchestrates the creation pipeline: scaffolding, authoring, workflow design, and initial audit. | | Scaffold | scaffolding | Generates project structure from design, adds or removes platform support — manifests, hooks, scripts, bootstrap skill, and per-platform files. | | Write | authoring | Guides SKILL.md and agents/*.md authoring — frontmatter, descriptions, instructions, content integration, and progressive disclosure via references/. | | Audit | auditing | 10-category quality assessment including pattern-based security checks across 7 file categories. | | Test | testing | Dynamic verification — local dev-marketplace install, hook smoke tests, component discovery, and cross-platform readiness checks. | | Optimize | optimizing | Engineering improvements — description triggering, token efficiency, workflow restructuring, adding skills to fill gaps, and feedback iteration. | | Release | releasing | Orchestrates the pre-release pipeline: version drift check, audit, testing, documentation consistency, change coherence review, version bump, CHANGELOG update, and publish guidance. |

The bootstrap meta-skill using-bundles-forge provides a lightweight session prompt via hooks and full routing context on demand via the Skill tool.

Standalone use: authoring, auditing, and optimizing can be invoked independently on any existing project without going through the full lifecycle.

Guides

Each skill has a companion guide in docs/ with detailed usage, examples, and design rationale:

| Guide | Covers | |-------|--------| | Concepts Guide | Core terminology, architecture diagrams, and design decisions | | Blueprinting Guide | Three-phase interview, dialogue strategy, design document format, decomposition patterns | | Scaffolding Guide | Project anatomy, platform adapters, template system | | Authoring Guide | SKILL.md writing patterns, progressive disclosure, agent authoring | | Auditing Guide | Checklists, report templates, CI integration | | Optimizing Guide | Description tuning, token reduction, workflow restructuring | | Releasing Guide | Version management, CHANGELOG format, publishing workflow |

Agents

| Agent | Role | |-------|------| | inspector | Validates scaffolded project structure and platform adaptation | | auditor | Executes systematic quality audit with security scanning | | evaluator | Runs A/B skill evaluation for optimization and workflow chain verification for auditing (W10-W11) |

Invoking Skills

Skills are invoked automatically (the agent matches user intent to the skill's description field) or explicitly via bundles-forge:<skill-name> references — for example, bundles-forge:auditing or bundles-forge:blueprinting.

Auditing

Both auditing and optimizing accept local paths, GitHub URLs, and zip/tar.gz archives as input — the agent normalizes the target automatically.

Four audit scopes for different levels of granularity — the agent auto-detects scope from the target path:

| Scope | Invocation / Script | What It Checks | |-------|---------------------|----------------| | Full Project | bundles-forge:auditing or bundles-forge audit-plugin | 10 categories (structure, manifests, version sync, skill quality, cross-refs, workflow, hooks, testing, docs, security) | | Single Skill | bundles-forge:auditing on skills/authoring or bundles-forge audit-skill | 4 categories (structure, skill quality, cross-refs, security) | | Workflow | Explicit request or bundles-forge audit-workflow | 3 layers: static structure, semantic interface, behavioral verification (W1-W11) | | Security Only | bundles-forge:auditing (security-only mode) or bundles-forge audit-security | Pattern-based detection across 7 file categories (skill content, hook scripts, HTTP hooks, OpenCode plugins, agent prompts, bundled scripts, MCP configs) |

Quick Start (Scripts)

bundles-forge audit-plugin .                                      # full project audit
bundles-forge audit-skill skills/authoring                         # single skill audit
bundles-forge audit-workflow .                                     # workflow audit
bundles-forge audit-workflow --focus-skills new-skill .            # focused workflow audit
bundles-forge audit-security .                                      # security-only scan

Via the agent, you can also audit remote projects:

bundles-forge:auditing https://github.com/user/repo
bundles-forge:auditing https://github.com/user/repo/tree/main/skills/my-skill

Exit codes: 0 = pass, 1 = warnings, 2 = critical findings. All scripts accept --json for CI integration.

After the audit: The audit report is purely diagnostic — it identifies and scores issues but does not prescribe next steps. The user or an orchestrating skill (e.g., optimizing, releasing) decides what to fix and how.

For detailed usage, checklists, report templates, and CI integration patterns, see docs/auditing-guide.md.

Architecture

For concept explanations see Concepts Guide. For per-skill details see guides in docs/.

Skill Execution

Each skill is discovered by its description or invoked explicitly via bundles-forge:<skill-name>. The execution chains can be deep.

flowchart LR
    subgraph skills [Entry-Point Skills]
        SK_BP["blueprinting"]
        SK_SF["scaffolding"]
        SK_AU["auditing"]
        SK_OP["optimizing"]
        SK_RE["releasing"]
    end

    SK_BP -->|"design approved"| scaffolding
    SK_BP -->|"content authoring"| authoring
    SK_BP -->|"initial audit"| SK_AU
    SK_AU -->|"issues found"| SK_OP
    SK_OP -->|"delegate changes"| authoring
    SK_OP -->|"verify fixes"| SK_AU
    SK_RE -->|"pre-release check"| SK_AU
    SK_RE -->|"fix quality"| SK_OP

bundles-forge:blueprinting — Plan a new bundle-plugin

Full guide: [docs/blueprinting-guide.md](docs/blueprinting-guide.