中文

A toolkit for building bundle-plugins — AI coding plugins organized around collaborative skill workflows — across Claude Code, Cursor, Codex, OpenCode, Gemini CLI, and OpenClaw.

A single skill (SKILL.md) does one thing — an AI agent discovers it by its description field and loads it on demand. A bundle-plugin takes this further: multiple skills reference each other and form a workflow, where one skill's output feeds the next.

graph LR
    A["Skill A"] -->|output feeds| B["Skill B"]
    B -->|output feeds| C["Skill C"]
    C -->|validates| A

bundles-forge itself is a bundle-plugin — blueprinting produces a design, scaffolding generates a project from it, auditing validates the result, and optimizing iterates on issues found.

If your plugin has 3+ skills that form a workflow, you're building a bundle-plugin. This toolkit gives you scaffolding, quality gates, and multi-platform publishing for that pattern.

1. Add the marketplace:

   /plugin marketplace add OdradekAI/bundles-forge

2. Install the plugin:

   /plugin install bundles-forge@bundles-forge-dev

Or clone locally for development:

git clone https://github.com/OdradekAI/bundles-forge.git
cd bundles-forge

# Add your local marketplace
/plugin marketplace add ./

# Install the plugin
/plugin install bundles-forge@bundles-forge-dev

Other platforms: see Platform Support below.

/bundles-blueprint

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).

cd your-bundle-plugin-project
/bundles-audit

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

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

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"]

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.

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

Skills without a slash command are invoked automatically (the agent matches user intent to the skill's description field) or explicitly when another skill chains to them via bundles-forge:<skill-name> references.

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:

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-audit https://github.com/user/repo
/bundles-audit 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.

flowchart LR
    subgraph commands [Slash Commands]
        CMD_BP["/bundles-blueprint"]
        CMD_SF["/bundles-scaffold"]
        CMD_AU["/bundles-audit"]
        CMD_OP["/bundles-optimize"]
        CMD_RE["/bundles-release"]
        CMD_SC["/bundles-scan"]
    end

    CMD_BP --> blueprinting
    CMD_SF --> scaffolding
    CMD_AU --> auditing
    CMD_OP --> optimizing
    CMD_RE --> releasing
    CMD_SC -->|"security only"| auditing

    blueprinting -->|"design approved"| scaffolding
    blueprinting -->|"content authoring"| authoring
    blueprinting -->|"initial audit"| auditing
    auditing -->|"issues found"| optimizing
    optimizing -->|"delegate changes"| authoring
    optimizing -->|"verify fixes"| auditing
    releasing -->|"pre-release check"| auditing
    releasing -->|"fix quality"| optimizing

User runs /bundles-blueprint
  → blueprinting: context exploration (scan existing files/skills)
  → blueprinting: Phase 1 — needs exploration (problem, users, capabilities, flow)
  → blueprinting: Phase 2 — architecture design (complexity, platforms, skill decomposition, workflow)
  → blueprinting: Phase 3 — generate design document + self-review
  → User approves design document (HARD-GATE)
  → Scaffold: invoke scaffolding — generate project structure, manifests, hooks, scripts
    → inspector agent validates scaffold (if subagents available)
  → Author Content: invoke authoring — guide SKILL.md and agents/*.md content (with design context)
  → Wire Workflow: blueprinting wires cross-references, integration sections
  → Run Audit: invoke auditing — initial quality check

User runs /bundles-scaffold
  → scaffolding: detect context (new project vs existing project)
  → New project: ask mode preference (intelligent/custom), generate structure
  → Existing project:
    → Add/remove platform: generate adapter files, update .version-bump.json, hooks, README
    → Add/remove optional components (MCP servers, CLI executables, LSP, userConfig, output-styles)
    → inspector agent validates changes (if subagents available)

User runs /bundles-audit
  → auditing: detect scope (full project vs single skill vs workflow)
  → Full project: 10 categories (structure, manifests, version sync,
    quality, cross-refs, workflow, hooks, testing, docs, security)
    → auditor agent runs checklist (if subagents available)
    → Scripts: bundles-forge audit-plugin, audit-workflow, audit-security, audit-skill
  → Single skill: 4 categories (structure, quality, cross-refs, security)
  → Workflow: 3 layers (static structure, semantic interface, behavioral)
  → Score + report with Critical / Warning / Info findings
  → Report delivered to calling context (user or orchestrating skill) for action

User runs /bundles-optimize
  → optimizing: detect scope (project vs single skill)
  → Project scope: 6 optimization targets
    (descriptions, tokens, workflow chains,
     security, restructuring, optional components)
  → Skill scope: targeted optimization + feedback iteration
  → Description A/B test:
    → 2x evaluator agents in parallel (if subagents available)
    → Compare reports → pick winner
  → Verify fixes via auditing

User runs /bundles-release
  → releasing: verify prerequisites (clean working tree, branch check)
  → Pre-flight checks
    → bundles-forge bump-version --check (version drift)
    → auditing (full quality + security)
    → bundles-forge audit-docs (documentation consistency)
  → Address critical findings (block release until resolved)
  → Documentation sync (change coherence review + doc updates)
  → bundles-forge bump-version <new-version> (update all manifests)
  → Update CHANGELOG.md and README.md
  → Final verification (--check + --audit + bundles-forge audit-docs)
  → Commit, tag, push, gh release create

Search for bundles-forge in the Cursor plugin marketplace, or use /add-plugin bundles-forge.

See .codex/INSTALL.md

See .opencode/INSTALL.md

gemini extensions install https://github.com/OdradekAI/bundles-forge.git

From ClawHub:

openclaw bundles install clawhub:bundles-forge

From a local clone:

openclaw plugins install ./bundles-forge

Verify with openclaw plugins inspect bundles-forge — should show Format: bundle.

Skills, audit reports, and script output accumulate in the conversation context over a long session. If you notice the agent slowing down or losing track of earlier context:

• Start a fresh session for each major lifecycle phase (blueprinting, authoring, auditing)
• Use slash commands (/bundles-audit, /bundles-optimize) to re-anchor the agent on the current task
• Prefer script output over inline checks — bundles-forge audit-plugin . produces a compact summary instead of the agent reasoning through each check

• Python 3.9+ — required for auditing scripts and version management tools
• python in PATH — hook scripts invoke python directly. On systems where only python3 is available, create an alias or symlink:
  • macOS/Linux: sudo ln -s $(which python3) /usr/local/bin/python
  • Windows: Python installer includes python by default; verify with python --version

Contributions welcome. Please follow the existing code style and ensure all platform manifests stay in sync using bundles-forge bump-version --check and bundles-forge checklists --check.

Apache-2.0