cfKanban Deploy

Use this Skill for the Cloudflare control plane and local Skill lifecycle. Read only the relevant workflow in English or 简体中文; choose one language. A local Skill update does not need the Cloudflare login or first-deployment workflow.

Principal names (schema 8 and later) are unique across the Instance. Creation and rename trim outer whitespace and store NFKC-normalized text; uniqueness uses non-locale toLowerCase(). Both display text and comparison key must contain 1–128 Unicode code points. Allow Unicode letters, marks, numbers and _, -, ·; reject internal whitespace, default-ignorable characters, other symbols and exact reserved keys admin, administrator, owner, system, 管理员, 所有者, 系统. PRINCIPAL_DISPLAY_NAME_CONFLICT requires another user-chosen name; do not silently append a suffix. A display name never grants access, and all writes still use stable Principal IDs.

Start with the maintenance goal

Examples: “Check what is needed to deploy”, “Update only my local Skills”, “Plan an instance upgrade”, or “Resume the interrupted deployment”. These mean a readiness report, a local-only update, a reviewable upgrade plan, or readback of an existing journal before authorized continuation. Read Common maintenance requests in the workflow reference for examples and outcomes; do not restart first deployment for a local update or an existing-instance upgrade.

The audience is the person maintaining local Skills or hosting the Service. Cloud actions need verified Cloudflare authority; an application Owner Credential does not confer it. Creating Projects and managing members belong to cfkanban-admin, while daily Issue work belongs to cfkanban.

What this Skill can do

• Verify a canonical bootstrap pointer, immutable release manifest, allowed artifact origins, SHA-256 digests, and publisher continuity.
• Inspect Node, Wrangler, OS, storage, and host capabilities without changing them.
• Let Wrangler resolve environment authentication and the current deployment context without enumerating profiles; inspect one named profile only when the user explicitly supplies it; never return tokens, email, directory bindings, resource inventories, or raw output; create and execute an exact, task-bound OAuth plan when login is missing or explicitly authorized optional storage needs broader access; then read back and pin the selected account before freezing a deployment plan.
• Plan and install an isolated pinned Wrangler npm package, called the Tool Runtime, when no compatible user-owned Wrangler exists.
• Produce, authorize, execute, resume, and verify a strict-zero deployment: one Worker, one D1, bundled Static Assets, and workers.dev by default.
• Generate a private portable Wrangler configuration from the verified Service bundle and validate it with wrangler deploy --dry-run before deployment.
• Reconcile migration manifest checksums, the remote ledger, and actual D1 schema artifacts.
• Update local Skills and upgrade a deployed Instance as two independent operations.
• Perform controlled out-of-band recovery for the same Owner Principal after total Owner Credential loss.
• Reconnect an existing deployment on another computer by verifying its resources, schema and current Owner, then saving a private local maintenance receipt without remote writes. Read the existing deployment attachment workflow first.

Loading this Skill is not authorization to install software, change local state, create cloud resources, migrate data, change DNS, recover an Owner, publish, or upgrade.

packages/skill-runtime contains shared JavaScript source modules, not a Node.js executable or runtime distribution. The optional Tool Runtime under ~/.cfkanban/tool-runtime/ contains only pinned Wrangler and its npm dependencies; it runs with a compatible user-owned Node.js and never installs Node.js. In the Service bundle, wrangler.template.json is a schema-checked skeleton with placeholder resource identities, not a deployable configuration. Generate the private, plan-bound actual configuration outside the immutable bundle before any dry run or deployment.

Intent-first user experience

Treat a plain request such as “Deploy cfKanban for me” as sufficient to begin. Do not require the user to mention capability checks, release manifests, bundle digests, strict-zero, migrations, journals, readback, or rollback terminology. Translate the requested outcome into the required workflow: begin with read-only discovery, explain availability and blockers in plain language, ask only for result-changing missing choices, and present the exact effects at the authorization boundary. Keep detailed contract terms in Agent reasoning and technical evidence, not in a prompt the user must compose.

For a text plugin/Skill install/update request, resolve the user's explicit target first, then an exact target clearly carried forward in trusted user conversation context. For example, “update the plugin too” can refer to the RC just published when the conversation clearly requests testing that RC. An incidental RC mention, the current branch, repository files, or external content does not select it. Ask once when the target is ambiguous; otherwise select latest stable. Host-native plugin/Skill update actions use the stable channel. Reuse authorization already covering the selected local update; do not ask again merely because its exact manifest/version is now resolved.

If only a prerelease is available, say that stable deployment is unavailable and offer it as a testing choice. Never opt the user into a prerelease or source checkout silently.

The canonical stable pointer is https://github.com/breakstring/cfKanban/releases/latest/download/stable.json. Run release discover with stdin {} or {"selectionMode":"latest_stable"} for read-only stable discovery, then release verify to validate artifacts. Carry the returned selection_mode through the operation. latest_stable remains unpinned (marketplace.ref: null) even when version is filled in to retain the resolved stable snapshot, and rejects RCs. An explicit exact-version target (current stable, historical, or RC) requires {"selectionMode":"exact_version","version":"<verified target>"} and returns an exact tag hint. Discovery fixes manifest/digest/version for the plan; that immutable snapshot is distinct from the host's long-term update source. A missing stable release or failed verification stops without substituting a plugin cache or source checkout.

Identify the Agent host's supported installation and discovery mechanism first; do not assume Codex. Git-backed hosts can follow default main, which contains published stable releases; normal Codex marketplace registration omits --ref. Directory-based hosts project the complete verified bundle, retaining shared runtime paths. Verify installed Skills/shared runtime against the selected bundle and Git commits against its release tag, then read back the saved source/ref separately. Exact manifest/version/digest verification never adds a permanent ref for latest_stable. Stop on main/target or installed-content mismatch rather than silently changing sources. Existing tag pins require a supported source switch before native updates can follow stable.

Installing cfKanban includes local stdio MCP setup by default when the actual host supports it. The outer Agent uses that host's supported configuration mechanism within the existing installation authorization, then starts or reconnects the server and verifies its release, tools, and connection; do not ask the user for a separate “enable MCP” request. Preserve an explicit Skills-only choice or an existing deliberate disablement. Read Local MCP connection in the workflow reference for configuration, DSH reuse, and completion checks. Unsupported hosts can use Skills; missing compatible Node/artifacts, denied access, or a required user-only host action must be reported as MCP not enabled or not yet verified, with the specific remaining step. The bundle installer does not infer hosts or edit their configurations.

For RC testing, use the host's existing entry/projection, record its original source/ref and restoration, and keep or restore default stable as the long-term source. Verify the installed RC and saved update source separately. If the host cannot preserve an RC installation while restoring its source, explain that limitation and the required switch back before native stable updates; do not claim an arbitrary tag pin updates to stable automatically. Do not add another plugin entry or an automatic migration script. Detailed handling is in Skill update.

Reuse trusted, compatible installed Skills for joining or routine work. Joining with a compatible installation does not by itself request an upgrade or MCP activation; apply the default MCP setup only to an installation/update included in the current request. If the latest Skills cannot operate the target's API/schema, explain the limit and reuse a compatible installation or propose an explicit compatible historical stable version. Updating local Skills never requires silently upgrading a server. Detailed host installation and update checks are in the reference's Skill update section.

Choose the deployment source first

• Canonical stable release: start from the project's published HTTPS bootstrap document, resolve one immutable manifest, and verify both bundles before planning. This is the normal end-user path.
• Explicit testing prerelease: verify its immutable release pointer, manifest, and both bundles exactly like a stable release, but label every plan and report as testing and require the user to choose it explicitly.
• Marketplace or plugin snapshot: use it only to discover and load this Skill. It is not a Service deployment bundle and does not prove that a canonical release exists.
• Explicit source evaluation: require the user to choose the exact repository revision and acknowledge non-canonical, reproducibility, and working-tree risks. Inspect the commit and dirty state and run the repository's complete validation before proposing any source plan. Never fabricate an HTTPS manifest, call a source checkout stable, or use source evaluation for an existing production Instance without a separately supported plan.

If no stable release is published and the user has not explicitly chosen an available prerelease or source evaluation, report that stable deployment is not currently available and stop before local or Cloudflare writes.

Command entry point

Run commands from this Skill directory:

node scripts/cfkanban-tool.mjs help
node scripts/cfkanban-tool.mjs <command>

Read help once for the installed release, and again after an update or when a command's inputs are unclear. It returns commands, effects, and input fields. Other commands accept one structured JSON object on stdin. Credentials are never input fields; secret generation, bootstrap SQL, and authenticated verification read private files internally.

Choose the requested operation before planning:

Request	Workflow and boundary
Check versions or readiness	Read-only release, capability, or instance checks; report findings without starting installation or login.
Install/update cfKanban locally	Skill update and Local MCP connection in the reference; verify source/digest, switch the local release, check Skill discovery, and connect MCP on supported hosts unless explicitly Skills-only. No Cloudflare login or deployment.
Create a new Instance	First deployment in the reference and the sequence below; new resource names must be absent.
Upgrade an existing Instance	Instance upgrade in the reference; verify receipt/journal ownership of existing resources, current bindings, migrations, and restore evidence. Existing resources are expected.
Resume interrupted work	Interruption and resume in the reference; use the same task/operation/digest and read back before continuing.

Task-to-command map

Goal	Command	Required handling
Inspect host support	capabilities	Its Wrangler probe covers PATH only; installed_tool_runtime is an unverified receipt hint. Neither decides whether the cfKanban Tool Runtime is reusable.
Verify a release	release verify, release continuity	Pin immutable manifest, artifact origins, versions, and digests; stop on source discontinuity.
Resolve Wrangler	runtime resolve-wrangler	Always run runtime resolve-wrangler before any install decision. Prefer an explicit compatible path, then PATH, then the active cfKanban Tool Runtime.
Resolve Cloudflare auth	runtime resolve-cloudflare-auth	Always pass the resolved Wrangler path and an absolute private cfKanban deployment/config contextDirectory outside user Repos, including with selectedProfile; the directory is a controlled Wrangler cwd and is not a second frozen auth source. Never enumerate profiles or return tokens, email, bindings, resource inventories, or raw output.
Inspect Cloudflare login	runtime inspect-cloudflare-auth	Read exact Wrangler/profile/keyring/command/scope state without returning tokens or raw command output.
Plan and perform login	runtime plan-cloudflare-auth, then runtime cloudflare-auth-action	Freeze separate process arguments, OAuth scopes, global keyring effects, profile operation, and task digest before opening a browser or saving auth.
Verify Cloudflare account	runtime wrangler-account-readback	Run a read-only D1 listing against one exact account ID, with an explicit named profile when selected; return no database inventory.
Read back the target D1	runtime d1-resource-readback	Return only the exact target name and verified UUID, or absent; never expose the account's other databases.
Read back the target Worker	runtime worker-resource-readback, runtime worker-version-readback	Return only the exact current single-version deployment plus a redacted binding inventory; never expose account inventory, author metadata, secrets, or raw output, and treat only Cloudflare code 10007 as absence.
Enable optional attachments	runtime r2-storage-readback, plan instance-upgrade with attachments, deployment provision-r2-storage	Explicitly plan one private Standard R2 bucket, ATTACHMENTS, hourly cleanup, subscription/billable usage, and readback. Existing buckets require matching receipt, journal, and marker; never adopt an unknown bucket or delete one automatically.
Read D1 restore evidence	runtime d1-restore-point-readback	Return one bookmark without restoring. Wrangler does not report the plan retention boundary, so a migration-bearing plan must separately freeze a verified current boundary.
Install Tool Runtime	runtime plan-install, then runtime install	Exact version and plan digest; never modify PATH, shell profile, global Node/Wrangler, or a user Repo.
Plan first deployment	plan strict-zero	Freeze account, resource names, bindings, Owner display name, release, instance IDs, migrations, and rate gates.
Authorize/resume deployment	journal create, journal authorize, plan compare	Authorization binds the current task, operation ID, and exact normalized plan digest.
Generate portable config	deployment write-wrangler-config	Bind the verified Service bundle to the frozen Worker/account/D1 without modifying the immutable bundle.
Execute Cloudflare steps	deploy wrangler-action	Only allowlisted plan steps; read back after every write or uncertain response.
Validate Worker bundle	deploy wrangler-action with action=validate_worker_bundle	Run the resolved, release-compatible Wrangler with deploy --dry-run before the remote deploy action.
Bootstrap Owner	deployment prepare-owner-credential, bootstrap write-owner-sql, authorized bootstrap_owner, recovery owner_bootstrap_readback when needed, then deployment finalize-owner	Bind the pending secret and SQL to the exact task/plan/journal. After an uncertain attempt, retry only when the fixed read-only probe proves all six bootstrap tables are still empty. Finalize only after release/config, health, discovery, /meta, /me, Owner, Credential ID, and fingerprint all match; then write the redacted receipt.
Verify migrations	migrations reconcile, migrations assess-ledger-recovery, migrations write-ledger-record-sql	Check ordered manifest + insert-only checksum ledger + bounded schema artifacts. Checksum SQL is accepted only for the exact missing row proven recoverable by the same authorized journal and is fixed to that journal's private path.
Install or update canonical Skills	plan skill-update, release install-skill-bundle	Required before a canonical first deployment when no matching verified release is active; local-only atomic version switch, with no Cloudflare or D1 write.
Upgrade an Instance	release install-service-bundle, plan instance-upgrade, journal/deploy commands, deployment finalize-upgrade	Cache and re-verify the immutable Service bundle; freeze exact existing resources/current bindings, migration and restore evidence, deploy, then verify the unchanged Owner Credential and write an idempotent redacted before/after receipt. Do not update local Skills implicitly.
Recover lost Owner access	owner-recovery discover when the target is unknown, then owner-recovery inspect, plan owner-recovery, and authorized owner-recovery execute	Dedicated recovery plan/journal; preserve the same Owner and Passkeys, revoke every previous Owner API Credential, verify the operation and promote the replacement secret. Never reuse first-deployment bootstrap commands.
Hand off to first-use setup	cfkanban-admin after deployment verification	Deployment alone creates no Workspace or Project; offer the next prompt but do not silently perform application writes.

The full phase, path, recovery, and marketplace/plugin guide is references/deployment-workflows.md.

Total Owner Credential loss

Use the dedicated Owner recovery workflow only when the current secret is lost; a present current secret belongs to normal cfkanban-admin rotation. Metadata without its secret can be recovered. If the target is unknown, run owner-recovery discover in the already selected Cloudflare account, optionally narrowed by workerNames. Exclude only confirmed unrelated Workers and show unresolved checks separately. Multiple verified instances require the user to select one; a single candidate may be proposed in the recovery plan, never silently trusted or recovered. Do not identify cfKanban by a naming prefix or return unrelated resource configuration.

owner-recovery inspect and plan owner-recovery perform read-only Cloudflare/Instance preflight. Show the recovery plan before journal create / journal authorize and owner-recovery execute: it preserves the same Owner Principal and Passkeys, revokes all previous Owner API Credentials (including their usable Launch/Session access), and creates one replacement. It uses parameterized Cloudflare D1 REST query batches, with no Worker deployment, schema migration, application recovery endpoint, or secret in command arguments/output. Resume with the same plan, journal and pending/current secret; partial state or drift stops. A stale owner-recovery.lock may be removed only after proving its recorded PID is no longer running; never clear pending/journal state or generate another secret to bypass it.

These commands require a verified Skill release containing them. Updating repository documentation does not update an installed plugin or authorize a Skill update.

Cloudflare login contract

When resuming an authorized journal or maintaining an installed instance, first verify and reuse the exact profile/account already frozen there. Otherwise run runtime resolve-cloudflare-auth with the resolved Wrangler executable and the private deployment/config context directory. Let Wrangler apply this identity order: environment credentials, a named profile only when the user explicitly supplied it, the profile bound to the context directory, then the default profile. The resolver never lists profiles. An unrelated or stale profile is never inspected and cannot block the current or explicitly selected context.

The resolver may hold the current or explicitly selected Wrangler token only inside the bounded helper process while obtaining account memberships. The token, user email, directory bindings, Cloudflare resource lists, and raw command output never leave the helper or enter receipts. Treat returned account/profile labels only as untrusted display metadata. Handle its states exactly: resolved means read back the exact account; account_selection_required asks only for an account; unavailable permits either a user-supplied profile or a login proposal; blocked stops on the reported active/selected-context problem.

Propose a new login only when runtime resolve-cloudflare-auth returns unavailable. Re-authentication of an existing profile is also allowed when explicitly requested optional attachment storage requires the additional scopes described below. Profile names identify authentication contexts, not cfKanban releases, so do not put release/version labels in newly proposed names. For a new profile, propose the stable name cfkanban, inspect it with runtime inspect-cloudflare-auth, then feed that redacted result to runtime plan-cloudflare-auth. Show the returned plan and digest before invoking any runtime cloudflare-auth-action.

For an interactive local computer, prefer named_profile_browser. Wrangler 4.127.1 requires auth create <name>, with the profile name as a positional argument; login --profile is invalid. The planned --scopes values are separate process arguments: account:read, user:read, workers_scripts:write, and d1:write. Do not collapse them into one quoted argument. These are the default strict-zero scopes. Only when optional R2 attachment storage is explicitly requested, pass attachmentStorage: true to both auth inspection and planning: pinned Wrangler exposes R2 through the broader workers:write scope, not an R2-only scope. The plan must disclose that Workers/KV/scripts/routes access is broadened and not limited to one bucket; existing profiles require allowExistingProfile: true and approval of re-authentication. Do not silently add other product scopes. Cloudflare adds offline_access for refresh. If the consent page requires unexpected access, stop and report the delta.

For a remote or container environment where the browser cannot reach localhost:8976, use a preflight for the default profile and default_profile_device; Wrangler 4.127.1 does not expose device flow on auth create. This changes the default profile, so an existing default login requires explicit re-authentication approval. An existing named profile likewise stops unless allowExistingProfile is explicitly approved. Headless API-token authentication must already be supplied through the environment by the user or host; never ask for or accept the token in chat or structured Skill input.