kandev/docs/plans/github-issue-task-linking/plan.md

spec, created, status

spec	created	status
docs/specs/tasks/requirements/link-existing-task-github-issue.md	2026-07-13	completed

Implementation Plan: GitHub Issue Task Linking

Overview

Reuse the metadata-backed GitHub issue link introduced for existing tasks. Add a workspace reverse lookup, call the existing link endpoint after issue quick-launch creation, and reuse the PR task-indicator interaction for issue rows without changing issue-watch deduplication.

Backend

• Add GET /api/v1/github/task-issues?workspace_id=<id> in apps/backend/internal/github/controller.go.
• Extend apps/backend/internal/github/service_task_issue.go with a workspace lookup that normalizes manual-link and issue-watch metadata into TaskIssueLinkResponse records grouped by task ID.
• Add an indexed workspace-scoped metadata projection in apps/backend/internal/github/store.go; it reads tasks.id, tasks.title, and tasks.metadata without adding a second association table.

Frontend

• Add the workspace task-issue API and types in apps/web/lib/api/domains/github-api.ts and apps/web/lib/types/github.ts.
• Add taskIssues.byTaskId state and a useIssueKeyToTasks reverse-map hook following usePRKeyToTasks.
• Call linkTaskIssue from quick-task-launcher.tsx after an issue task is created.
• Extract the shared task-row indicator interaction from PRRowTaskIndicator, then render it from issue-list.tsx only for linked issues.
• Pass the reverse map through github-page-client.tsx. Existing responsive row wrapping remains the desktop and mobile layout.

Tests

• Backend service/store/controller tests cover manual and watched metadata shapes, malformed metadata, required workspace scope, and cross-workspace isolation.
• Frontend API, store, hook, launcher, and indicator tests cover fetch shape, grouping multiple tasks, the automatic link call, empty issue behavior, and navigation labels.

E2E Tests

• Desktop: seed linked and unlinked issues, verify single/multiple indicators, and navigate to a linked task.
• Mobile: open the issues view, verify the linked indicator remains reachable without horizontal overflow, and tap through to the task.

Implementation Waves

1. task-01-backend-reverse-lookup
2. task-02-frontend-link-and-indicator
3. task-03-e2e-and-verification

Verification

cd apps/backend && go test ./internal/github/...
cd apps && pnpm --filter @kandev/web test -- --run lib/api/domains/github-api.test.ts lib/state/slices/github/github-slice.test.ts hooks/domains/github/use-issue-key-to-tasks.test.ts components/github/my-github/quick-task-launcher.test.tsx components/github/my-github/pr-row-task-indicator.test.tsx
cd apps/web && pnpm e2e:run tests/github/issue-list-task-indicator.spec.ts
cd apps/web && pnpm e2e:run --no-build --project mobile-chrome tests/github/mobile-issue-list-task-indicator.spec.ts
make fmt
make typecheck test lint

Risks

• Metadata has two repository shapes; URL parsing is the canonical normalization path.
• A task may be archived or absent from hydrated kanban snapshots, so the API must include a task-title fallback.
• Automatic linking is a follow-up request after task creation and must not turn a successful task creation into a failed dialog submission.