Plan & track from Claude Code

Use Claude Code (or any MCP-aware client like Claude Desktop / Cursor) to propose plans, push work items, and update lifecycle status directly against your FastLinkIt Projects board — without leaving your editor.

This page is the in-manual summary. The full hands-on walkthrough with conversation transcripts and troubleshooting lives in docs/ProjectPlannerGuide.md in the repo.

What you can do

This is distinct from in-app AI agents (see AI agents — planning & execution). That page covers AI running server-side via the orchestrator. This page covers external AI clients calling the project from outside the FastLinkIt stack.

Two distribution channels

Both surfaces hit the same six API endpoints — pick whichever fits your tools.

Quick start

1. Generate an API key at /Account/Manage/ApiKeys with the projects scope ticked. Copy the raw key (fli_...) — shown only once.
2. Install your chosen surface — see the install steps in Plugins/claude-skill/README.md or Plugins/mcp-server/README.md in the repo.
3. Configure the env vars (FLNKIT_API_KEY required; FLNKIT_API_BASE defaults to https://flnk.it).
4. Test the connection — open a Claude Code session in any repo and ask: "What FastLinkIt projects do I have access to?"

The three moves

Plan

Ask Claude "what's next for project X?" and Claude reads CLAUDE.md + PROJECTS.md, fetches the project's methodology + columns, structures the plan to match the methodology, and surfaces a ranked list with rationale before pushing.

Default plan shape per methodology:

What the proposal looks like before you confirm:

For an Agile project, Claude indents the tree:

1. EPIC   Customer onboarding overhaul                    (no estimate)
2.   FEATURE   Sign-up flow refresh                        (likely: 16h)
3.     STORY   As a new user I want to sign up via Google  (likely: 6h)
4.   FEATURE   Welcome email sequence                      (likely: 12h)
5.     STORY   As a new user I want a 3-email welcome drip (likely: 4h)
6.     TASK    Wire welcome drip into MailingSequenceService (likely: 4h)

For a Waterfall project, items are numbered with a "depends on" column:

#  Type  Title                                  Likely  Depends on
1  TASK  Schema audit + migration plan          12h     -
2  TASK  Stand up replica DB                    8h      #1
3  TASK  Backfill replica from prod snapshot    16h     #2
4  TASK  Cutover dry-run                        6h      #3
5  TASK  Production cutover window              4h      #4

For a Kanban project, a flat priority-ranked table:

#  Type  Priority  Title                                      Likely
1  TASK  high      WIP-limit enforcement on board columns     4h
2  TASK  normal    Assignee avatars on Kanban cards           2h
3  BUG   normal    Drag handle hint on hover                  1h

Override the shape when it makes sense:

• "Don't bother with an epic, this is one cohesive change — just stories." (Agile → flat)
• "Group these into two epics rather than one." (Agile → multiple epics)
• "Don't add dependencies — these can run in parallel." (Waterfall → no chain)
• "Group these under a parent task so they show together." (Kanban → grouped)

Claude reshapes and re-prints the plan; you confirm only when the shape is right.

Always waits for your explicit "yes" before POSTing — ambiguous responses are not consent. On confirmation, items land with the hierarchy + estimates + dependencies preserved.

Pick up

Say "I'll start on FLNKA-21" and Claude opens an agent run server-side. The item moves to the project's in-progress column; anyone watching the board sees the move in real time. Claude stores the run id for the rest of the session.

Wrap up

When the work is done, summarise what changed: "Done — added the WIP-limit check, blocked drops over the limit, tests pass." Claude calls complete_task with the narrative; the item moves to Review (or Done if you say "skip review"). On failure, "Stuck — need design input on whether to block or warn" moves the item to Blocked with the reason logged. Reasons are mandatory — no silent failures.

Smoke tests at wrap-up. When the completed work needs human verification (UI changes, migrations, new endpoints, integrations), Claude lists the smoke-test steps in the wrap-up response AND offers to create them as test tasks parented to the just-completed item:

Claude: Moved FLNKA-23 to Review.

Suggested smoke tests for you to run:

1. Drag a card past the column's WIP limit — confirm the drop is blocked.
2. Reload /projects/{id}/board — confirm display state persists.

Want me to create these as test tasks parented to FLNKA-23? (y / N)

On y, Claude creates type: task items with parent_local_id set to the implementation item, tagged test, smoke-test, with the verification steps in the description. The implementation item stays in Review until the test tasks are closed. Test tasks survive across sessions, so "what's still untested?" resolves to a board query, not chat-log archaeology. Distinct from acceptance_criteria on the parent story — those are pre-emptive conditions; test tasks are follow-up verification work.

Bug

Report a bug without leaving the editor:

You: Bug: the resize handle on the work-item table loses its drag state when Blazor re-renders the thead. Edge 131 on Windows 11.

Claude: (drafts a bug item with structured repro steps + affected files inferred from the codebase, surfaces it for confirmation)

I propose:

BUG Resize handle loses drag state on Blazor thead re-render priority: normal · tags: bug, board, ux

Repro steps:

1. Open /projects/{id} list view
2. Drag a column resize handle to a new width
3. Trigger a Blazor render that replaces the thead (filter / sort / search change)
4. Try to drag the handle again

Expected: drag continues to work after the re-render Actual: handle's pointer events stop firing

Affected: Components/Pages/ProjectDetail.razor + projects-table-resize.js Environment: Edge 131 / Windows 11

Push to FLNKA? (y / N)

You: y

Claude: Created FLNKA-28. Want me to pick it up now? (y / N)

What Claude does in Bug mode:

• Asks at most one clarifying question. Trusts your description + the codebase to fill in the rest.
• Always uses a structured repro template. Numbered steps, Expected vs Actual, Affected file, Environment. Bare "this is broken" descriptions get expanded before push.
• Auto-tags bug plus the affected area (board, wiki, mailing, payments, etc.).
• Auto-parents when the bug surfaces mid-pickup. If Claude is working on FLNKA-23 and notices an unrelated bug in the same feature, the new bug parents to FLNKA-23's parent feature by default. Override with "log it standalone".
• Doesn't pick up the bug automatically. The pickup chain is always opt-in.

Override phrasing:

• "This is blocking customers — log as high" (priority bump)
• "Log it standalone" (skip auto-parent)
• "Log under the Mailing epic instead" (override parent)
• "Plan three bugs I just found: …" (batch via Plan mode)

**Attachments (screenshots / repro / log dumps)😗* Paste a screenshot in the same message as your bug description and Claude will list it in the proposal preview (📎 emoji + filename + size). On confirmation the bug is created first, then each attachment uploads via POST /api/projects/work-items/{wid}/attachments. The image shows up in the work item's preview pane Attachments section, viewable + downloadable like any other attachment. Server allowlist accepts images / PDFs / docs / archives / video; rejects executables. Max 25 MB per file.

Scan

Most sessions start with "what was I doing?" or "give me the next thing" rather than a fresh plan. Scan mode handles both:

You: What's on my plate for FastLinkIt?

Claude: (calls get_project_context with assignee=claude-code so the server returns only items assigned to the agent)

You have 4 items assigned to claude-code on FastLinkIt Agile project:

In progress (1)

• FLNKA-22 Worktree-based execution sandbox ⚠ run from previous session may still be open

Backlog (2)

• FLNKA-23 As an AI agent, I want a git worktree… priority: high
• FLNKA-26 As a project owner, I want per-run cost ceilings… priority: high

Review (1)

• FLNKA-27 Surface cost progress in AI activity panel (waiting for human review)

Want me to resume FLNKA-22, or pick up FLNKA-23 next? (or "neither")

Triggers:

• "What's on my plate?"
• "Anything assigned to me?"
• "Pick up the next one" (skips the grouped list, goes straight to the highest-priority backlog item)
• "What should I resume?"

Behaviour:

• Items grouped by status — In progress first (likely has an open run from a previous session), then Backlog, then Review.
• Never auto-resumes / auto-picks up. Claude always asks before calling start_task, even when the user says "pick up the next one" — the next-item proposal still goes through the confirmation gate.
• Session-start mention (one-line nudge): when Claude opens a new session in this repo and finds in-progress items assigned to the agent, it mentions once on the first turn — "I notice 1 item still in progress assigned to me" — so you don't lose track. Skipped silently when nothing is pending.

How it works under the hood

Both surfaces talk to the same six REST endpoints under /api/projects:

The server validates work-item types against the project's methodology — Kanban projects only accept task / bug; Agile projects accept the full hierarchy. Lifecycle transitions reuse the same column-resolution helpers as the in-app orchestrator, so a Claude Code session moving an item to In progress lands in the same column as the server-side agent layer.

What it deliberately won't do

• Push without your "yes". "Looks good" / silence are not consent.
• Pick the project for you when multiple match. Claude lists candidates and asks.
• Modify or delete existing items. Only creates new items + transitions status. Use the web UI for edits.
• Auto-merge code. Code execution is a separate scoping. Today: you write the code, the skill tracks the work.
• Bypass access controls. Same scope and ownership rules as the web UI.

Related

• Project management
• AI agents — planning & execution — the in-app agent path
• REST API — the underlying API both surfaces use