cfKanban

Use this Skill for ordinary work in a cfKanban instance. Read the relevant section of English or 简体中文 for detailed inputs or recovery. Choose one language; ordinary operations do not require loading the whole guide.

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 user's daily goal

For an already joined user, lead with finding, creating, editing, changing status, completing/reopening, and commenting; do not restart onboarding. Examples: “Show my unfinished Issues in this Project”, “Create an Issue with this description”, “Move CFK-123 to in progress”, or “Add this progress Comment to CFK-123”. The expected result is the requested scoped read or verified change, not a mandatory workflow through all capabilities.

“Record CFK-123 as complete” needs actual result/validation evidence and an immutable completion record. “Finish CFK-123” can request the underlying work as well: follow the user's intent and existing authority, and never substitute a status update for implementation. For reopening, preserve previous completion records and select the requested non-done status. Read Common daily requests in the workflow reference for bilingual examples, expected results, and query choices.

Choose the execution path

For daily operations, prefer the current host's exposed, connected cfKanban MCP when its exact schema covers the requested semantics. Discover the available tools and inspect their schemas first; use the host-returned names and namespaces, not invented tool calls. The current adapter has 20 bounded tools for connection and Project discovery, self locale preferences, Issue lists/read/create/update/complete and label add/remove, Project label lists, Comments, and relations. Read the coverage guide in English or 简体中文 only when selecting a tool or checking a gap.

Use discovered cfkanban_connection_inspect to inspect non-secret candidates or verify the explicitly selected instance and live Principal. It does not choose an instance for you. Reuse unchanged verified identity/scope evidence in the current task; honor any Host binding and resolve ambiguity before reading or writing. A scoped MCP read does not first require shell help, capabilities, or directory probes.

Host workbench opening is a separate discovered capability; business MCP availability does not imply sidebar control. Use the verified public CLI or original safe scripts for uncovered semantics, including joining, profile changes other than locale, identity lifecycle, counts/candidates, self-assignment, blocking, Label creation/management/name lookup, attachments, directory association, and sensitive browser delivery. Administration and deployment remain with their respective Skills. Hosts without a usable MCP retain these paths. Select this path before dispatch; do not start a separate MCP server to bypass host or sandbox restrictions, and never replace an unsupported operation with a superficially similar tool.

When the complete verified bundle provides cfkanban, run ordinary CLI work from the user's working directory with --json --no-interactive. The CLI follows that bundle's active version, without an independent upgrade channel; use the Skills lifecycle for installation/update/removal. Let its command-level resolver use explicit IDs, Repo recommendations or a compatible private saved context; inspect returned resolved_context instead of manually rebuilding every scope tuple; fully explicit existing calls need not add this field. A unique instance needs no flag; same-instance Repo Projects may be aggregated for Issue lists, while single-Project writes require one stable target. Ambiguity returns structured candidates without a prompt. Select from the user's known intent and retry with exact IDs; ask only for a genuinely missing choice. Never save a directory/global preference unless requested: context use explicitly saves private state, while ordinary selections remain temporary. Invalid scope/defaults stop rather than broaden reads. CLI recovery uses the original journal target, not current cwd; the original safe scripts and discovered MCP still require their documented explicit inputs. Read the CLI context guide in English or 简体中文 when needed.

Keep this execution choice internal unless it explains a concrete limitation. A permission refusal, CAS conflict, timeout, or unknown write result is not a reason to switch channels and repeat the write. Retain the original tool/command, arguments, caller identity, request IDs, and Idempotency Key, including any recovery_request. Read back and apply its recovery contract through the same caller before any identical replay. Restore the original connection as needed to inspect or recover the retained operation; reconnection does not prove non-commit. Only evidence that no request was sent permits choosing a new execution path; an MCP failure alone is not that evidence.

What this Skill can do

• Inspect the local instance identity and show the authenticated Principal without exposing a Credential.
• Read or update your own display name, saved color theme, and language preference through the profile API; the discovered locale-only MCP tool covers language changes.
• Resolve an explicit or Repo-recommended Project scope, then list or search Issues and deterministic work candidates.
• Create, read, edit, prioritize, assign, block, unblock, complete, reopen, soft-delete, or restore one Issue at a time.
• Add and restore Comments, manage Project Labels, and create or remove Issue relations.
• Upload one explicitly selected local file to an Issue or download a private attachment to a new local file.
• Redeem one Project Invite, Principal Recovery Invite, or Public Join safely.
• Open one explicit Project or Issue in an available host workbench or local browser; use a five-minute, one-time Browser Launch when online mode is requested.

Use cfkanban-admin for Owner or scoped Workspace/Project administration. Use cfkanban-deploy for local Skill lifecycle, Cloudflare resources, migrations, deployment, upgrades, or out-of-band Owner recovery.

Scoped administrators (schema 9+) have effective writer access in their managed Projects; Workspace administration includes present and future child Projects. /me.management_grants describes management separately from the compatible reader/writer data-plane projection. Direct Grants and inherited administration are independent: losing one source does not erase another, and assignment/history survive loss of writer eligibility. Use cfkanban-admin for administrator appointments or effective-member management, including an empty Workspace's {kind:"workspace",workspace_id} Web target; never substitute an Owner admin target.

Intent-first user experience

Treat a plain request such as “Join this Project: <Invite URL>” as sufficient to begin. Do not require the user to ask for Invite inspection, identity reuse, pending-Credential handling, a combined join plan, or readback. Start with the required safe inspection, explain the Project and access level in plain language, ask only for missing choices or required approval, and then complete the verified workflow. Keep protocol terminology in technical evidence, not in a prompt the user must compose.

For ordinary Issue work, resolve the requested target and carry out the authorized operation directly. A routine read, Comment, or status change does not require a separate plan or confirmation imposed by this Skill. First join and sensitive capability delivery retain their specific authorization rules below.

For “open this board/Issue,” prefer an already available host workbench and check whether its discovered schema opens the exact target or only the workbench entry. The DSH plugin exposes cfkanban_view_open with instance_id, workspace_id, project_id and optional identifier; use its actual discovered name/schema. Resolve the target through available MCP reads or existing verified context, not names alone. An explicit sidebar or conversation-panel request uses only that surface: if unavailable, explain the limitation immediately. Explicit browser and online requests retain their chosen delivery. Do not inspect host source or internal routes, invent host calls, or install a plugin to satisfy an opening request.

In Codex, discover cfkanban_workbench_open and use its current schema for a conversation view. It accepts either target:{instance_id,workspace_id,project_id,identifier?} or recommended_targets containing 1–50 unique targets with only those three UUID fields. For an explicitly requested Issue, resolve its verified instance, Workspace and Project, then include the complete CFK-N identifier in target; the opener prepares that exact detail page under current identity and permissions. Never add an Issue to recommendations, saved defaults or last-Project preferences. An inaccessible or mismatched Issue must remain a concrete error without substituting the board or another target. Inspect the current conversation's trusted absolute working directory through the same complete verified plugin bundle's read-only CLI ../../cli/cfkanban.mjs context show --directory <absolute-directory> --json --no-interactive, using verified Node from this Skill directory; reuse unchanged results. A PATH cfkanban may still use an older canonical bundle: verify that its result includes workbench_context_key, or supplement a successful older result with the same plugin bundle's read-only scope inspect-directory; never upgrade the global CLI merely to open a panel. A confirmed Git repository supplies non-secret workbench_context_key, passed as optional repository_key, also usable without a target or recommendations. An explicit verified business target takes precedence, then a complete private saved_directory choice; never adopt saved_global as a repository default. Otherwise pass all repository targets as recommended_targets, including a single target. The opener revalidates this repository's last successful Codex Project and Principal, or opens the first accessible recommendation when no usable last Project exists. Successful binding and project switching automatically remember the repository's Codex last Project without editing CLI context or scope. For a confirmed repository without recommendations, pass {repository_key} to restore its last Project or open and remember a verified single connection's accessible default. Without a trusted repository, use {}; unresolved connection ambiguity retains selection. The Agent supplies context; the panel does not discover the repository itself, and the opener rechecks identity and permissions. Do not send a directory, URL or secret, invent the key, or guess the repository from the Skill directory or MCP process cwd. Read the detailed fallback and validation rules in English or 简体中文.

The sidebar uses the separate cfkanban_workbench_global_open({}) global entrypoint, which never receives repository context. It revalidates its local last-project preference, or defaults to the first accessible Project under its verified identity, and retains project switching. The global icon and the host's manual conversation-panel entry are separate from a model tool call; the host controls where the result renders. A public ok confirms the entry call, not visible rendering or exact Project/Issue selection.

Codex display modes are only inline and fullscreen; a thread side panel is a host layout entrypoint, not a third mode. The workbench requests fullscreen initially, but must honor the host's returned mode and user exit. When available, its explicit expand control can request fullscreen again; do not reopen, repeatedly expand, or create another view merely to force a layout. Reuse the current Project and recovery state.

For target-aware tools such as DSH's opener, report a host view as open only when the tool explicitly confirms opened for the exact target; dispatch or request acceptance alone is insufficient. For Codex's openers, verify rendering and the requested business target separately, including when the global view resumes a project. An initial snapshot containing the Issue confirms prepared data, not a host-rendered page; do not report an exact view as visibly open based only on ok or snapshot data. A missing capability or an explicit unsupported result before opening permits the local browser path only for an ordinary opening request. Permission/target failures and uncertain results do not permit switching channels and trying again. Preserve the original target and follow the tool's recovery guidance. For browser delivery, resolve the trusted instance with web resolve, verify /api/v1/me, and use web open with mode:"local" and the user's actual absolute working directory; explicit unknown instances never fall back to another. Explicit mode:"online" uses Browser Launch for the full WebUI or management. Read the shared opening workflow: English / 简体中文.

Git plugin projections contain guidance and source, but not prebuilt local assets. Local browser opening requires the complete verified Skill bundle of the same release installed through cfkanban-deploy; the runtime verifies its private active receipt and full tree before loading it. A missing, modified, or different-version canonical bundle is refused. Do not build in the plugin cache, copy individual assets, or silently install another version.

When browser delivery is selected, honor the requested browser. When trusted host context identifies Codex App and an IAB navigation tool is available, prefer local mode in IAB with delivery:"host_browser"; do not infer the host from environment variables. On an unverified delivery path, run web preflight and verify the requested browser and visible success page. Keep the probe tab handle/ID and navigate that same tab to the one-time relay URL; create a tab only when no reusable probe tab remains. Reuse successful preflight evidence while the task and delivery environment stay unchanged. Other hosts with verified browser tab control can use the same host_browser flow; a plain system_browser opener cannot guarantee tab reuse. An opener executable or navigation tool alone does not prove reachability. Consume the exact one-time relay event immediately in the chosen browser, without repeating or persisting its URL; keep the local process alive while the workbench is open. Verify the displayed Principal and Project after navigation. A browser failure alone does not require a new identity. Copy Issue IDs/URLs or raw description/comment Markdown; the UI does not send to Agent sessions or build a duplicate handoff summary.

Online Web Session lifetime

Browser Launch remains a five-minute, single-use capability. On supporting Services, Agent-launch and Passkey Sessions start with eight hours and may renew on real foreground mouse, keyboard, or touch activity: eight hours after renewal, at most one actual extension per Session every 30 minutes, capped at seven days from its original creation. Identity, source, and scope stay unchanged. Background work, refresh, and focus checks do not renew. Only the Web's Cookie-only, same-origin/CSRF endpoint can renew; never use a Skill Bearer request for this. Missing Session renewal metadata means the old fixed eight-hour behavior, regardless of local Skill version.

Expiry or source revocation requires fresh sign-in. Keep the original page open for any offered text draft, let the user explicitly restore or copy and review it, and never replay a write. Drafts stay in page memory, exclude credentials/capabilities/attachments, and are lost on refresh/close or explicit sign-out. Read the details in English or 简体中文.

Optional working-directory association

When directory recommendations or association are relevant, use the read-only scope inspect-directory once per user working directory in the current task, with the user's absolute working directory, not the Skill directory. An MCP request with an explicit verified Project or Issue can proceed without this probe. The inspector detects Git repositories, including subdirectories and worktrees, and returns the appropriate scope_directory, existing scope, and association_recommended; the outer Agent need not run separate Git probes. Reuse that result for subsequent operations; use scope_directory for scope read/scope merge, and pass scope.targets (or [] when scope is null) as repoTargets to scope resolve. After saving, read back the scope without repeating Git detection. A missing/unavailable Git probe is not evidence of a non-Git directory; do not guess a root or recommend setup from unknown or unavailable.

SHOULD: When using cfKanban from a detected Git repository with association_recommended=true, briefly offer once to save a Project association at its worktree root, including after Invite/Public Join or an operation with an explicit Project. Mention that this creates .cfkanban-scope.json. Continue the requested operation; the suggestion is optional and never a setup gate. Do not repeat it when configured or declined. Outside a Git repository, do not proactively offer or save an association; handle a request to inspect or save one when the user asks. Lists/searches without explicit or recommended targets still need an explanation of the authorized aggregate scope and may offer a one-off Project selection without suggesting a file in non-Git directories.

Example: “I can create .cfkanban-scope.json at this repository root to remember DemoProject for future work.” / “可以在这个仓库根目录创建 .cfkanban-scope.json，记住 DemoProject 的项目关联，方便以后协作。” User acceptance of this suggestion or an explicit association request authorizes scope merge; joining or naming a Project for one request alone does not. Preserve existing targets and resolve ambiguous names against authorized Projects rather than guessing from Git remotes. Read Working-directory association in the workflow reference when inspecting or saving an association.

Command entry point

For operations using the script path, run commands from this Skill directory:

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

Read help once when using scripts from the installed release, and again after an update or when a command's inputs are unclear. It returns commands, effects, input fields, and output classifications. MCP operations use their discovered schemas instead. Other commands receive one structured JSON object on stdin. Never put a Credential in that JSON: authenticated commands read the current secret from private state, while invite redeem and public-join redeem inject a pending secret internally when required. Generic api request refuses endpoints that create a one-time Invite or Browser Launch; their dedicated commands own the delivery boundary.

Task-to-command map

This is the script/REST reference for uncovered operations and hosts without MCP. For covered daily operations, use the discovered MCP tool with the same domain semantics and readback requirements.