charleswiltgen__axiom/CURSOR-MARKETPLACE-SUBMISSION.md

Cursor Marketplace Upstream Submission Runbook

This is a maintainer checklist for a future upstream Axiom release. It does not state that Axiom has been submitted to, accepted by, or published in Cursor Marketplace.

Hard Authorization Gate

Stop unless an upstream Axiom maintainer has explicitly authorized the exact next action and account. No contributor or agent may create a fork, add or push a remote, open a pull request, create or rewrite a tag, publish a package or release, submit to Cursor Marketplace, or change a listing under this runbook without that authorization.

Publication is upstream-owned. Plugin metadata and submission must identify CharlesWiltgen/Axiom, never a contributor fork. Cursor acceptance remains subject to Cursor's review.

Release Candidate Identity

Complete every field from the immutable candidate being tested. Commands must run from a clean checkout of the upstream candidate.

Field	Required value
Upstream repository	https://github.com/CharlesWiltgen/Axiom
Base repository and branch	CharlesWiltgen/Axiom:main
Base SHA	record full 40-character SHA
Merged upstream/final smoke SHA	record full 40-character SHA
Candidate version	record generated plugin version
Release tag	record only after upstream creates an immutable tag
Responsible maintainer	record confirmed upstream owner
Smoke tester and date	record name and UTC timestamp
Sanitized evidence location	link PR artifact or maintainer-controlled record

Verify base/head before review and again before any upstream action:

git remote -v
git status --short --branch
git rev-parse HEAD
git merge-base HEAD origin/main
git log --oneline --decorate origin/main..HEAD

The pull request base must be upstream main; its head may be an authorized contributor branch. The marketplace source and immutable release tag must come from upstream after merge. The complete Cursor Desktop smoke matrix must be rerun on the actual merged upstream SHA after merge and before any tag or submission. Pre-merge smoke evidence cannot satisfy this gate, and no change-impact judgment may waive the rerun.

Exact macOS Environment

Capture command output in the sanitized evidence artifact. Do not substitute "latest" for exact versions.

sw_vers
uname -m
git rev-parse HEAD
node --version
command -v node
npm --version
npx --version
python3 --version
command -v python3

Also record the exact Cursor IDE/Desktop version, build, release channel, install source, profile/workspace used for testing, selected Axiom profile (full), approval/run mode, MCP allowlist/blocklist state, network state, and whether axiom-mcp was already cached. The supported candidate environment is macOS with Cursor IDE/Desktop, Node.js 18+, and Python 3. This runbook makes no Cursor Cloud support claim.

Automated Candidate Gates

Run against the recorded head SHA and attach complete results:

npm ci --legacy-peer-deps
npm run test:unit
npm run test:cursor
npm run build:cursor
npm run check:cursor
npm run build:mcp
node scripts/pre-deploy.ts --static
npm run docs:build
git diff --check
git status --short

After npm run build:cursor, inspect the generated delta. It must be deterministic and limited to reviewed generated consequences. npm run check:cursor must then report no drift.

Record these generated facts from axiom-cursor/reports/inventory-sha256.json rather than copying stale values:

Evidence	Required record
Generated file total	record totals.files
Generated byte total	record totals.bytes
Inventory report SHA-256	record file SHA-256
Generated README SHA-256	record README.md entry
Plugin manifest SHA-256	record .cursor-plugin/plugin.json entry
Marketplace manifest SHA-256	record repository-root file SHA-256 separately
Excluded generated mirrors	30
Authority-expansion rows	42
Released agent profile	full

Do not hardcode a checked-in candidate snapshot here. Generated byte counts and hashes change whenever canonical source or compiler output changes, so every release candidate must recompute the table above from its recorded immutable SHA and store the result in the sanitized release evidence artifact.

Do not submit if the generated report does not show 27 routers, 42 agents, 17 commands, 30 read-only/background agents, and 12 writable/foreground agents, or if any compiled/executable payload, secret, unsafe path, stale harness token, or unexpected file is present.

Final-SHA Cursor IDE/Desktop Smoke Matrix

Install the actual merged upstream SHA locally. Remove any earlier Axiom installation and Axiom Cursor Marketplace entry first so Cursor cannot reuse stale cached plugin bytes.

In Cursor:

1. Open Customize and choose Add → From Local Repo.
2. Select the Axiom repository root — the directory containing .cursor-plugin/marketplace.json — and choose Add Plugins.
3. Open Browse Marketplace. Under Axiom Cursor Marketplace, choose Add for Axiom.

The agent rows below require a Cursor plan that allows named models. Cursor Free refuses every delegation with Named models unavailable. Free plans can only use Auto., so agents register but cannot be exercised; record the account tier used for the run.

Confirm Cursor shows the plugin as installed from the local marketplace and that the source repository remains on the recorded final SHA. Keep sanitized evidence in the pull request or a linked review artifact, not in the repository. Automated inventory tests cover all definitions; manual execution samples each behavior class.

Area	Final-SHA case	Required evidence	Result/link
Customize discovery	Inspect Axiom name, version, logo, skills, agents, commands, hooks, and MCP	Exact 27 skills, 42 agents, 17 /axiom-* commands and one axiom MCP server	pending
Router positive	Ask an Apple-platform question in an Apple project	Representative Axiom router selects relevant guidance	pending
Router negative	Repeat the canary in a non-Apple repository	Axiom does not activate merely because the plugin is installed	pending
Read-only/background agent	Run one representative of the 30-agent class	Background execution; attempted mutation/state-changing shell is unavailable; inherited tools/MCP recorded	pending
Writable/foreground agent	Run one representative of the 12-agent class	Foreground execution; approvals and shared-checkout effects recorded	pending
Forced foreground	Inspect and run screenshot-validator	Writable source-background agent is released foreground	pending
No-argument command	Run one /axiom-* command without arguments	Native command appears and follows its translated workflow	pending
Argument command	Run one argument-bearing command with benign and injection-oriented text	Arguments remain task input, not shell interpolation or authorization	pending
Session hook	Start Apple-positive and non-Apple sessions	Compact context appears only where project detection allows it	pending
Subagent start hook	Delegate to one named Axiom agent on a plan that permits subagents	Skill-awareness context reaches the subagent; this is the one hook a free plan cannot demonstrate, so record the plan tier	pending
Crash read hook	Open an .ips path, then an ordinary source file	Crash path yields advisory context naming the axiom_xcsym_crash MCP tool and never a bare xcsym command; ordinary file yields nothing; neither read is gated	pending
Prompt router hook	Send an Apple-platform prompt in an Apple project, then the same prompt in a non-Apple one	Router guidance is injected only in the Apple project; the model names the matched skill	pending
Shell hook	Exercise a fixture that emits a known Axiom hint	Advisory additional_context; no permission or denial field	pending
Write hook	Exercise a Swift write fixture	Post-edit advisory context only; the edit is not blocked or undone	pending
Hook failures	Malformed, oversized, missing-file, invalid-child-JSON, nonzero, noisy-child, and timeout fixtures	Sanitized diagnostic, {} result, exit 0, no enforcement fields	pending
Plugin-root MCP	Inspect plugin with no duplicate workspace definition	Cursor auto-discovers root mcp.json	pending
MCP catalog and call	Enumerate catalog; invoke one read-only operation	Resolved npm version, inherited tools, approval decision, and output recorded	pending
MCP first launch	Start with empty relevant npm cache and network available	Resolution behavior, elapsed time, exact package version, and approval prompt/state recorded	pending
MCP cached launch	Start again with the resolved package cached	Cache path/version and launch behavior recorded without assuming offline support	pending
MCP offline	Disable network after the cache state is recorded	Actual cached/offline success or actionable failure recorded; no compatibility inference	pending
MCP blocked	Block axiom using Cursor's MCP allowlist/blocklist controls	Server cannot make calls; UI/error behavior recorded	pending
Missing Node	Test with node/npx unavailable in Cursor's environment	Actionable startup failure; plugin does not claim MCP availability	pending
Missing Python	Test with python3 unavailable in Cursor's environment	Hook failure is advisory/fail-open; plugin content remains inspectable	pending
Agent plan gate	Attempt one delegation on the account tier used for the run	Delegation either runs, or fails with the recorded Free-plan model error; agent rows above are marked not-applicable rather than passed	pending
Plugin hook gate	Confirm plugin hooks are active, not merely present	Hook fires and returns context; note that Cursor's enable_cc_plugin_import gate can clear plugin hooks silently, so an absent result is not a pass	pending

The MCP command is exactly npx -y axiom-mcp. The -y flag suppresses npm's install confirmation; it does not pre-approve the MCP server or bypass Cursor's allowlist/blocklist. Record the exact npm-resolved package version and compare it with the intended release. A version mismatch, unexpected tool, or changed consent surface blocks submission pending maintainer review.

Capability and Authority Review

Review axiom-cursor/reports/capability-disposition.json on the final SHA.

• Confirm all 42 authority-expansion rows are present. Cursor agents inherit host tool and MCP access that can exceed their canonical per-agent tool lists.
• Confirm the release has exactly 30 read-only/background and 12 writable/foreground agents.
• Confirm all writable agents, including screenshot-validator, are foreground.
• Confirm prompts and hooks are described as guidance or advisory context, never as security boundaries.
• Confirm omitted global hook behavior and all six per-agent hook dispositions are represented in the report. UserPromptSubmit is ported to beforeSubmitPrompt, not omitted; confirm the report says so.
• Confirm supported hooks fail open and do not emit decision, permission, or failClosed fields.

Any authority-class failure blocks publication. Do not silently downgrade the shipping profile or broaden a tool surface; return through a reviewed source/compiler change and rerun the complete final-SHA matrix.

Bounded Upstream Issues

Before submission, link narrow upstream issues in this table. A blank or non-upstream link blocks submission. Creating the issues is itself an external action and requires maintainer authorization.

Required issue	Scope boundary	Upstream issue URL
Marketplace submission and review	Listing metadata, review feedback, acceptance, and publication only	required
Cross-harness MCP integrity and consent	Version/dependency pinning, artifact integrity, tool exposure, and consent across existing harnesses; no unrelated MCP redesign	required
Cursor Cloud investigation	Research only; no support claim until separately designed and verified	required
Failed or deferred agent capability	One issue per capability that fails the full-profile authority gate; no blanket compatibility claim	required if applicable

Use the upstream Axiom issue tracker. Each issue must name an owner, acceptance criteria, and affected release without expanding this submission's authority.

Upstream Tag and Submission

Only after the branch is merged, the complete matrix above has passed on the actual merged upstream SHA, required issues are linked, and an upstream maintainer explicitly authorizes release:

1. Check out and record the actual merged upstream commit.
2. Regenerate all governed distributions from that commit and rerun the full release gates.
3. Rerun the complete Cursor Desktop smoke matrix on that same merged upstream SHA and bind the evidence to it.
4. Confirm all governed version surfaces agree.
5. Have the upstream maintainer create an immutable release tag pointing to the verified merged upstream SHA. Never move or rewrite that tag.
6. Record tag, SHA, generated totals/hashes, smoke artifact, resolved MCP version, responsible maintainer, and support owner in the handoff.
7. Have the upstream maintainer submit the upstream public repository through Cursor's Marketplace publishing process.
8. Preserve Cursor review correspondence and final listing metadata in a maintainer-controlled record.

Marketplace rejection blocks publication, not the underlying Axiom release. Address requested changes through a reviewed patch and a new verified release; do not silently change the tagged source.

Rollback

Before publication

• Stop submission or withdraw the candidate through the maintainer-owned process.
• Remove or disable only the unaccepted Cursor marketplace entry or release wiring under review.
• Keep the immutable release history intact; use a reviewed follow-up commit for corrections.
• Record the reason, affected SHA/version, owner, and next gate in the bounded marketplace issue.

After publication

• Notify the upstream support/security owner immediately with sanitized evidence.
• If impact warrants, have the authorized maintainer request delisting or disable the listing through Cursor's supported process.
• Publish a reviewed upstream patch release; never rewrite the affected tag.
• Regenerate, rerun all automated gates and the complete Cursor Desktop smoke matrix on the patched merged upstream SHA, create a new immutable tag, and resubmit only with explicit maintainer authorization.
• Record user guidance for disabling the plugin or MCP server while the fix is pending.

Final Decision Record

The responsible upstream maintainer must record one outcome: blocked, authorized for submission, submitted and awaiting review, published, or rolled back. Record the decision, exact timestamp, actor, upstream SHA/tag, evidence links, issue links, and rollback owner. Until that record exists, this runbook conveys no publication or acceptance status.