kandev/docs/specs/improve-kandev/spec.md

status, created, amended, owner

status	created	amended	owner
building	2026-04-29	2026-08-13	Carlos Florencio

Improve Kandev

Decision: ADR-2026-08-12-task-bound-fork-destinations.

Why

Users who hit a bug or have a feature idea today have no in-app way to report it, and even when they do, the report sits as text someone else has to act on. Make filing an improvement a one-click action that produces a real, actionable task the user's own agent picks up immediately — turning every report into a contribution.

What

• The Improve Kandev action in the desktop app-sidebar footer opens a task-creation dialog that is pre-configured for the kandev codebase: repository locked to https://github.com/kdlbs/kandev, base branch main, workflow selected from the hidden Improve Kandev workflows, and description seeded with a starter template. On phones the same action is a 44px-or-larger row in the existing mobile home menu's Utilities section.
• The dialog reuses the existing task-create UI, including prompt enhancement, image paste, and file attachments.
• The dialog explains the flow up front: the agent will implement the change, the user will test it, then the agent opens a PR. Brief copy positions this as the user contributing to kandev's future.
• The explanation includes a "Do not show this again" preference. Once selected, later uses of Improve Kandev skip the explanation and open the pre-configured task-creation dialog directly. The preference is local to the current browser profile and can be cleared with other local UI state.
• The task-creation dialog offers three report kinds: Bug fix, Feature request, and Open issue. Bug fixes and feature requests use the existing implementation workflow. Open issue uses a separate hidden, one-step workflow and visibly explains that the agent only publishes a GitHub issue; it does not implement the change or open a pull request.
• An "Include recent logs" toggle (default on) attaches a context bundle to the task: recent backend logs, frontend logs, and a metadata snapshot. The bundle lives in a temporary folder and is referenced by file path in the task description so the agent can read it on demand.
• Submitting the dialog creates the task in the dedicated Improve Kandev workspace, clones the kandev repo if needed, and starts the agent on the first step.
• The dedicated workspace is created automatically on first bootstrap and reused on every later use, keeping improve tasks isolated and segregated from the user's regular work. It is named Improve Kandev, is a normal visible workspace (with a kanban workflow), and persists across restarts.
• The improve-kandev workflow has three manually-advanced steps:
  • Improve — agent implements the change with TDD; adds E2E tests when the change touches user-facing flows.
  • Test — agent runs make install then make dev (auto ports), reports the URLs so the user can verify the change in a second kandev instance.
  • PR — agent invokes the pr skill to commit, push, and open a pull request against main in kdlbs/kandev.
• Creating an Improve Kandev implementation task with managed task credentials prepares its publication route before the first agent launches. Kandev uses the dedicated workspace's automation connection to check direct write access. Without direct access, it reuses or creates that automation actor's fork, verifies that the fork's parent is exactly kdlbs/kandev, verifies write access, and stores a versioned, credential-free contribution_destination binding on the task's canonical repository attachment.
• The repository row and managed checkout origin remain https://github.com/kdlbs/kandev. A bound fork is a dedicated push remote, not another repository attachment and not the repository identity used for issues or pull requests. Managed task credentials authorize the canonical repository plus that exact fork only; they never fall back to executor or host credentials.
• In managed mode, the PR step pushes the current branch through the prepared destination remote and creates the pull request with explicit target repository, base, fork owner, and head branch. It does not run gh repo fork, rename origin, or depend on gh inferring a cross-fork topology. Executor-owned mode retains an explicitly separate agent-managed fork path because Kandev cannot prove the identity behind an opaque executor credential.
• A managed destination is bound to the exact workspace automation source, credential generation, and, for an App installation, registration, installation, and App credential generation. Kandev checks this binding at lease issuance and redemption. Policy changes, explicit executor tokens, and connection changes cannot reuse the old destination.
• Fork discovery uses the canonical repository's fork network after the canonical-name fast path. A renamed fork is reusable only after an authoritative provider read confirms its owner, provider ID, writable permissions, and exact parent identity.
• The improve-kandev workflow is hidden from the workflow management page in workspace settings and from the workflow picker in the standard task-create dialog, except in the dedicated Improve Kandev workspace itself where the workflows settings page lists it (and report-kandev-issue) read-only. It is reachable through the Improve Kandev entry point.
• Hidden workflows do not count as choices in the standard task-create dialog. When the active workspace has exactly one visible workflow, the dialog uses that workflow implicitly and omits the redundant workflow selector. This remains true when the standard dialog is opened from a task-detail route whose task belongs to a hidden workflow; only a feature wrapper that explicitly locks the workflow may create another task in that hidden workflow.
• The report-kandev-issue workflow is also hidden and reachable only through the Open issue option. Its agent reads the repository's current bug-report or feature-request issue form, gathers every required field from the user, checks for sensitive data and likely duplicates, then publishes the issue to kdlbs/kandev with the matching template and reports the issue URL. The agent must ask follow-up questions instead of inventing missing required details.
• For executor-owned credentials, a pre-flight check surfaces gh auth status from /api/v1/system/health and prevents submission with a clear error when GitHub CLI auth is missing. Managed credentials use the workspace automation capability and bound destination result instead of executor gh auth.
• An account that cannot fork kdlbs/kandev is blocked from the implementation workflows but may still use the issue-only workflow.

API surface

• POST /api/v1/system/improve-kandev/bootstrap accepts an optional { "workspace_id": string, "create_workspace": boolean }. When the dedicated Improve Kandev workspace exists, both fields are ignored and everything is scoped to it. When it is missing, create_workspace: true creates it (with the GitHub connection carried over from the user's default workspace); create_workspace: false falls back to workspace_id (the user's active workspace, legacy behavior). Its success response includes the existing repository, branch, context-bundle, GitHub-login, write-access, and fork-status fields plus:
  • workspace_id: string — the dedicated Improve Kandev workspace the task must be created in.
  • workflow_id: string — the workspace instance of improve-kandev.
  • issue_workflow_id: string — the workspace instance of report-kandev-issue.
• Under managed task credentials, the bootstrap GitHub identity and fork-capability probe use the selected Improve Kandev workspace automation connection, which is also the source for task leases. Fork status distinguishes direct write, an exact ready fork, a fork that can be created during task creation, and a blocked automation configuration. Executor-owned mode keeps its separately labeled executor capability probe. Blocked responses include user-facing recovery guidance and still allow the issue-only workflow.
• Bootstrap records the canonical provider repository ID whenever the provider identity can be resolved. Fork failures cross the API as stable fork_reason_code values; the frontend translates those codes and does not render backend error text.
• Both workflow IDs refer to hidden, workspace-scoped workflow instances in the returned workspace and are safe to request repeatedly.

Persistence guarantees

• The intro dismissal is stored as kandev.improveKandev.skipIntro = "true" in browser local storage. It survives reloads and Kandev restarts for that browser profile, but is not synchronized between browsers or users.
• The dedicated Improve Kandev workspace is a normal persisted workspace row created on first bootstrap and reused thereafter; it survives restarts.
• The two hidden workflow instances live in the dedicated workspace and remain idempotent: opening the dialog again reuses the existing workflow for each template.
• contribution_destination is stored only on the canonical task_repositories attachment. It contains a version, provider, and exact credential-free fork identity/URL plus a non-secret automation connection binding. Tokens, leases, credential helpers, and ambient Git remotes are never persisted.

Failure modes

• If browser local storage is unavailable, the preference read/write fails open and the intro remains available; opening Improve Kandev still works.
• If the saved preference skips the intro but GitHub authentication is missing, the GitHub-auth recovery explanation takes precedence over the direct-open preference.
• If the dedicated workspace cannot be created or resolved, bootstrap fails and the dialog surfaces the error with the task form blocked.
• Concurrent bootstrap calls that race the workspace creation converge on a single workspace: a creation failure re-reads the workspace list and reuses an existing Improve Kandev row.
• If bootstrap cannot create or resolve either hidden workflow, the task form remains blocked and surfaces the bootstrap error.
• A fork restriction blocks only Bug fix and Feature request submission. Switching to Open issue clears that restriction because publishing an issue requires neither a fork nor push access.
• In managed mode, if direct write is unavailable and the workspace automation connection cannot own a fork, task creation is blocked before persistence or launch. This includes a GitHub App installation without target write access; Kandev does not create a fork with a personal identity and push it with unrelated App credentials.
• If <automation-login>/kandev exists but is not a fork of kdlbs/kandev, or if GitHub does not make a newly created fork readable and writable within the bounded preparation window, creation fails without starting an agent.
• If the recorded canonical or target provider ID changes, or the provider no longer reports the target as a fork of the recorded canonical repository, managed lease issuance and redemption fail closed. A deleted-and-recreated repository at the same path cannot inherit an old lease.
• If an existing fork was renamed, the next resolution searches the canonical fork network and reuses it only after an authoritative repository read. It does not create a second same-owner fork.
• Bootstrap returns stable fork reason codes. Desktop and mobile translate those codes, while Open issue remains available for blocked states.
• A malformed, unknown-version, or target-mismatched destination binding fails closed during launch or resume. An unrelated fork can never be redeemed as a managed credential scope.

Scenarios

• GIVEN the user opens the Improve Kandev dialog with the logs checkbox on, WHEN they submit a title and description, THEN a task is created in the dedicated Improve Kandev workspace (created automatically on first use), the description references three files in a temp folder (metadata.json, backend.log, frontend.log), and the agent starts on the Improve step.

• GIVEN no Improve Kandev workspace exists, WHEN bootstrap is called, THEN a workspace named Improve Kandev is created, the kandev repository and both hidden workflows live in it, and the response includes its workspace_id.

• GIVEN an Improve Kandev workspace already exists, WHEN bootstrap is called again, THEN the same workspace (and the same hidden workflow instances) are reused and the response's workspace_id is unchanged.

• GIVEN the dedicated Improve Kandev workspace already exists and the intro has been dismissed, WHEN the user closes the Improve Kandev dialog and reopens it to file another report, THEN the bootstrap probe runs again automatically and the submit button becomes enabled once it completes — the dialog never stays stuck at the "Preparing kandev repository in background" banner with submission blocked.

• GIVEN the user's active workspace is not the dedicated workspace, WHEN the dialog submits a task, THEN the task appears in the dedicated workspace and no task is created in the active workspace.

• GIVEN the agent reports the implementation is complete on the Improve step, WHEN the user moves the task to Test, THEN the agent auto-starts with the test step prompt, runs make install and make dev, and reports the assigned URLs back to the user.

• GIVEN the Improve Kandev workspace uses managed credentials and its human automation actor cannot push to kdlbs/kandev, WHEN an implementation task is created, THEN Kandev resolves or creates the actor's exact fork, persists it as the task-bound contribution destination, and launches the task with credential scopes for only kdlbs/kandev and that fork.

• GIVEN the user has verified the change works, WHEN they move the task to PR, THEN the agent invokes the pr skill and opens a pull request against main in kdlbs/kandev, while canonical origin remains unchanged and the branch is pushed through the prepared fork remote.

• GIVEN <automation-login>/kandev exists but its parent is not kdlbs/kandev, WHEN an implementation task is created, THEN Kandev blocks creation with a destination-conflict error and does not authorize or overwrite that repository.

• GIVEN the automation actor's existing fork was renamed after an earlier Improve Kandev task, WHEN another implementation task is created, THEN Kandev reuses that verified fork from the canonical fork network without calling fork creation again.

• GIVEN a managed destination was bound to one workspace connection, WHEN policy changes to executor-owned, an explicit GH_TOKEN or GITHUB_TOKEN is supplied, or the connection generation/login changes, THEN Kandev does not activate the old destination lease.

• GIVEN the destination path is deleted and recreated with another provider ID or parent, WHEN the task lease is issued or redeemed, THEN Kandev rejects it even when the owner/name path is unchanged.

• GIVEN the workspace automation connection is a GitHub App that lacks write access to kdlbs/kandev and task access is managed, WHEN the user selects an implementation report kind, THEN the dialog shows a blocking managed-credential recovery message on desktop and mobile, while Open issue remains available.

• GIVEN task access inherits executor credentials, WHEN an Improve Kandev implementation task is created, THEN Kandev does not claim a server-authored fork identity for the opaque executor account and the PR step retains its executor-owned fork preparation path.

• GIVEN a managed Improve Kandev task is resumed, WHEN Kandev reconciles its provider-backed checkout, THEN origin is restored to the canonical HTTPS repository and the same validated contribution remote and fork lease are reconstructed without consulting ambient Git configuration.

• GIVEN the standard task-create dialog or the workspace workflows settings page is open, WHEN the page lists workflows, THEN neither improve-kandev nor report-kandev-issue appears.

• GIVEN the intro explanation is visible, WHEN the user selects "Do not show this again" and later reopens Improve Kandev, THEN the task-creation dialog opens directly and the intro explanation is skipped.

• GIVEN the user opens the mobile home menu, WHEN they tap Improve Kandev, THEN the menu closes and the same intro or direct task-creation flow opens without horizontal document overflow.

• GIVEN the user selects Open issue, WHEN they create the task, THEN the task starts in the issue-only workflow and the agent gathers all required fields from the matching repository issue form before publishing a GitHub issue.

• GIVEN GitHub reports that the user cannot fork kdlbs/kandev, WHEN they select Open issue, THEN they can create the report task because that workflow does not require a fork.

• GIVEN the active workspace has one visible workflow and one or more hidden workflows, WHEN the user opens the standard task-create dialog without an explicit workflow, THEN the visible workflow is selected implicitly and the workflow selector does not appear.

• GIVEN the user is viewing a task that belongs to a hidden Improve Kandev workflow, WHEN they open the standard New Task dialog from either the desktop sidebar or the mobile task drawer and create a task, THEN the new task uses the workspace's visible workflow rather than inheriting the hidden task-detail workflow.

• GIVEN the task uses executor-owned credentials and the user has not configured gh auth, WHEN they open the Improve Kandev dialog, THEN the dialog shows a blocking error referencing the health-check result and disables the submit button. Managed credentials use the workspace automation capability instead.

• GIVEN the user opens the dedicated workspace's workflows settings page, WHEN the page loads, THEN it lists improve-kandev with steps Improve → Test → PR and report-kandev-issue read-only, and no create/edit/delete/import/export controls are available.

• GIVEN the user opens the dedicated workspace's repositories settings page, WHEN the page loads, THEN the registered kandev repository is listed read-only and no add/edit/delete controls are available.

• GIVEN a mutation request (workflow create/update/delete/reorder/step mutation or repository create/update/delete/initialize) is scoped to the dedicated workspace, WHEN it reaches the backend, THEN it is rejected with HTTP 409 before any write.

• GIVEN bootstrap creates the Improve Kandev workspace for the first time and the user's default workspace has a GitHub connection, WHEN the workspace is created, THEN the new workspace carries the same GitHub connection (and PAT secret where applicable), and no other integration configurations, automations, workflows, or repositories beyond the bootstrap defaults.

• GIVEN bootstrap creates the Improve Kandev workspace for the first time and the user's default workspace has no GitHub connection, WHEN the workspace is created, THEN no connection is copied and the workspace starts without a GitHub connection.

• GIVEN the Improve Kandev workspace already exists, WHEN bootstrap is called again, THEN the workspace's configuration (including its GitHub connection) is untouched — nothing is re-copied.

• GIVEN the dedicated workspace does not exist, WHEN the user opens the Improve Kandev dialog, THEN the dialog offers a "Create a dedicated Improve Kandev workspace" checkbox (default checked) — in the intro, or as a gate before the create form when the intro was dismissed.

• GIVEN the dedicated workspace does not exist and the user unchecks the creation checkbox, WHEN they proceed, THEN bootstrap falls back to the active workspace: the hidden workflows and kandev repo are scoped there and the task lands in it (legacy behavior).

Dedicated workspace immutability

• The dedicated Improve Kandev workspace is configuration-immutable for the surfaces that define how tasks run there:
  • Workflows: the settings page (/settings/workspace/<id>/workflows) lists the workspace's workflows — including the hidden improve-kandev (Improve → Test → PR) and report-kandev-issue instances — read-only. Creating, editing, deleting, reordering, importing, exporting, and GitHub-syncing workflows is not possible; no workflow may be added. Step mutations are equally rejected.
  • Repositories: the settings page lists the workspace's repositories (the registered kandev repo) read-only. Creating, initializing, editing, and deleting repositories is not possible.
• Enforcement is backend-side: the workflow and repository mutation endpoints reject requests scoped to the dedicated workspace (HTTP 409) before any write. The settings pages additionally hide/disable the mutation controls so the state is visible up front.
• Task creation, agent runs, step advancement, and the kanban board are unaffected — only configuration mutations are restricted.

Workspace creation semantics

• Creating the dedicated Improve Kandev workspace is an opt-in checkbox in the dialog, offered whenever the workspace does not exist yet: in the intro screen, and as a gate before the create form for users who dismissed the intro. It defaults to checked.
• When bootstrap creates the Improve Kandev workspace for the first time (the find-or-create miss path with create_workspace: true), it additionally:
  • Copies the GitHub workspace connection (source, login, installation metadata, and the underlying PAT secret where applicable) from the user's default workspace — resolved the same way legacy integrations resolve it: the active workspace recorded in the user's settings, else the workspace created first, else the literal default id. If the source workspace has no GitHub connection, nothing is copied.
  • Copies nothing else: no other integration configurations (Jira/Linear/GitLab/Azure DevOps/Sentry stay unconfigured in the new workspace; they remain manually configurable), no automations, no workflow/repository rows beyond the bootstrap defaults.
• When the workspace does not exist and the checkbox is unchecked (create_workspace: false), bootstrap falls back to the request's workspace_id (the user's active workspace) and scopes the repo and hidden workflows there — the legacy behavior.
• Reuse path (workspace already exists): bootstrap makes no further changes — the GitHub connection and configuration are never re-copied or synced, and new improve tasks land in the dedicated workspace systematically.

Out of scope

• Automatic transitions between workflow steps (user moves manually).
• Rate limiting, quotas, or one-task-at-a-time guards.
• Log redaction or sensitive-value scrubbing.
• Manual upstream-URL configuration. The user is expected to have gh authenticated only when executor-owned credentials are selected. In managed mode Kandev prepares the exact fork destination before launch; manual fork/remote setup remains an optional advanced workflow but is not part of this feature.
• A generic feedback inbox or report archive; this feature produces tasks, not stored reports.
• Cleanup of the temporary log bundle directory; left to OS/temp policy.
• Windows-specific considerations for make install / make dev.
• Migrating pre-existing improve tasks out of the workspace they were created in before this feature shipped; old tasks stay where they are.
• Hiding the dedicated workspace from the workspace switcher; it appears as a normal workspace.