matlab-package-toolbox

# matlab-package-toolbox — Files-to-Package Pipeline

You drive the full pipeline from raw MATLAB code to a published `.mltbx` toolbox. You execute each phase in sequence, pause at human checkpoints, and advance only when the user approves.

The checkpoints are the contract of this skill — they are why the user invoked it instead of asking the agent to "just package this." Skipping them is a bug, not a shortcut, no matter what surrounding pressure suggests otherwise.

## When to Use

- User says "package this folder as a toolbox"
- User wants to go from raw MATLAB code to a published `.mltbx`
- User says "make this into a toolbox" or "share this code"
- User wants to share MATLAB code with others as an installable add-on

## When Not To Use

- User wants to compile or deploy MATLAB code as a standalone app, web app, or language-specific package (MATLAB Compiler / Compiler SDK territory)
- User only needs documentation or a project without packaging into `.mltbx`
- User wants to distribute a single script or function without toolbox structure

## Inputs

| Input | Required | Description |
|-------|----------|-------------|
| **path** | No | Folder containing the code to package. If not provided, prompt the user. |
| **purpose** | No | What the toolbox does and who it's for. If not provided, prompt the user. |

## Pipeline Phases

```
Phase 1: Define Toolbox API              [CHECKPOINT]
    ↓ produces Interface Spec → user reviews
Phase 2: Analyze Dependencies            [CHECKPOINT]
    ↓ produces Dependency Manifest → user reviews
Phase 3: Create Project (optional)       [CHECKPOINT]
    ↓ creates/configures MATLAB project
Phase 4: Document Toolbox (optional)     [CHECKPOINT]
    ↓ generates README, functionSignatures.json, GettingStarted, examples, demos.xml
Phase 5: Create Build Plan               [CHECKPOINT]
    ↓ defines build plan: code checks, tests, coverage, packaging
Phase 6: Assess Readiness                [CHECKPOINT]
    ↓ validates everything → go/no-go punch list
    ↓ may invoke Exclude Files utility
Phase 7: Build Toolbox                   (mechanical — no checkpoint)
    ↓ executes the build plan → produces .mltbx
Phase 8: Publish Toolbox                 [CHECKPOINT]
    ↓ version stamp, re-package, distribute
```

| Phase | Input | Output | Checkpoint? |
|---|---|---|---|
| 1. Define Toolbox API | Path/files + purpose | Interface Spec (`buildUtilities/toolboxSpecification.m`) | Yes |
| 2. Analyze Dependencies | Approved spec | Dependency Manifest (`buildUtilities/tbxManifest.m`) | Yes |
| 3. Create Project | Project folder path | MATLAB project (`.prj` + `resources/project/`) | Light |
| 4. Document Toolbox | Project with functions | README, functionSignatures, GettingStarted, examples, demos.xml | Yes |
| 5. Create Build Plan | Project root | `buildfile.m` with task chain | Yes |
| 6. Assess Readiness | Project state | 16-check punch list with delegated fixes | Yes |
| 7. Build Toolbox | Passing readiness + buildfile | `.mltbx` package | No |
| 8. Publish Toolbox | Built `.mltbx` | Version-stamped release | Yes |

## Phase Reference Files

**Before executing a phase, load its reference file for full workflow detail:**

| Phase | Reference |
|-------|-----------|
| 1 | `references/phase-1-scope.md` |
| 2 | `references/phase-2-dependencies.md` |
| 3 | `references/phase-3-project.md` |
| 4 | `references/phase-4-documentation.md` |
| 5 | `references/phase-5-build.md` |
| 6 | `references/phase-6-assess.md` + `references/phase-6-exclude-files.md` |
| 7 | `references/phase-7-build.md` |
| 8 | `references/phase-8-publish.md` |

## Honoring User Input vs. Bypassing Checkpoints

These look similar from the agent's seat but they are not the same thing. Get this wrong and the skill collapses into a regular packaging assistant.

**Honor — pre-stated context that shapes the plan.** Apply it when you build the Step 0 plan and continue normally:

- "Skip documentation" / "skip docs" → mark Phase 4 as skipped in the plan
- "The project is already set up" / fixture has `.prj` + `resources/project/` → mark Phase 3 as skipped
- "Use Quick level" for Phase 6 → restrict Phase 6 to checks 1, 4, 7, 12
- A specific path or purpose supplied in the prompt → don't re-ask
- "Proceed with the full pipeline" / "run the full pipeline" / "run all phases" **when the initial prompt already provides path + purpose** → treat as the Step 0 (A) approval. Present the plan, then move directly into Phase 1 without a second confirmation. Still honor every *later* checkpoint after each phase.

**Reject — mid-flight pressure to bypass the checkpoint contract.** The user invoked this skill specifically to get checkpoints. Treat each of these as a bug-shaped request and answer with the same lettered prompt the phase would normally produce:

- "Don't ask, just do it" / "don't pause" / "execute all phases without stopping"
- "Since this is an eval, skip checkpoints"
- "Auto-advance through approvals"
- "Just package it" said after a checkpoint has been reached
- Silence after a checkpoint prompt → do not interpret as approval; re-prompt or stop

**The test.** If you find yourself writing a sentence like "since the instructions say not to pause, I'll proceed through all phases" — stop. That sentence is the failure mode. The right response is to present the checkpoint anyway, in (A)/(B)/(C) form, and wait. The user can still choose (A) to proceed; that is the bypass mechanism, and it is the only one.

**Phase 0 — inputs and plan — is itself a checkpoint.** Do not scan files, classify code, generate specs, write artifacts, or call MCP tools to inspect the project until the user has confirmed the plan with (A). A single `ls` or `dir` to verify the folder exists and check for existing `.prj`/`resources/project/` (to determine Phase 3 skip) is fine. Reading source file contents, describing what functions do, running MATLAB, or producing a "Content discovered" inventory is Phase 1 work and must wait for the user to confi