Initialize a DevFlow work session for a flow.

MUST be called before any other tools (except flow_list and flow_create). Without devflow_init, all tools are blocked.

What it does:

• Validates and loads the flow

• Locks the flow for this agent (exclusive)

• Creates an agent session for tracking

• Returns full context: flow details, feedback, tasks, allowed actions, next step

Call this at the start of every work session.

List flows as a Markdown table (ID | State | Assignee | Titel).

Conventions enforced uniformly across the plugin (skill: devflow-flow-display):

• ⭐ prefix marks flows assigned to / created by the current user

• 🔒 marks active agent sessions; idle flows have no lock-marker

• Done-flows are hidden by default (focus on open work). Pass includeDone=true to see them.

• Order matches the browser FlowsPage default (kanban_sort_order ASC for project-scope, updated_at DESC for cross-project).

Use this to find flows to work on or to brief the user on the backlog.

Get detailed information about a specific flow. Returns the full flow including:

• Summary and description

• Acceptance criteria

• Current state

• Agent status (if being worked on)

• Implementation plan (full content)

• Audit info (who created/approved)

Use this before starting work on a flow to understand requirements.

Create a new flow in a project. Use this to create new feature requests, bug reports, or tasks. The flow starts in 'idea' state by default.

DF-378 — Valid metadata triple required:

• summary: short one-line title, 3..80 characters (NOT a paragraph)

• description: detailed body, ≥ 30 characters (the goal, motivation, constraints)

• acceptanceCriteria: at least 1 testable success criterion, each ≥ 10 characters

If your text is long, put the title into summary (≤ 80 chars) and the body into description. The backend rejects payloads that violate these limits with a structured 400 flow_input_invalid.

Requires a projectId (use project_list to find it).

Update a flow's state or submit deliverables. Use this to:

• Change flow state (idea -> planning -> approval -> ready -> in_progress -> review -> done)

• Submit implementation plan for review

• Submit agent summary after implementation

agentStatus is automatically derived from your tool calls - you don't need to set it manually.

IMPORTANT: Some state transitions require mandatory fields:

• approval requires: implementationPlan

• review requires: agentSummary AND testingInstructions

Get user feedback for a flow. Use this at the start of a session to check if the user has provided feedback on:

• The implementation plan (approval phase)

• The code implementation (review phase, when rejected back to in_progress)

If feedback exists, you should address it before continuing work.

Reload only the discussion (comments) for a flow as a Markdown section.

Returns the same "## Discussion (N)"-section that flow_get appends. Useful when:

• The user said something new in the UI and you want fresh context without re-fetching the entire flow + attachments.

• You want a focused view of resolution status across comments.

Resolved comments are marked with [✓ resolved]. Body is rendered verbatim — wikilinks like [[adr-134]] stay raw (use wiki_get_page to resolve them).

List all tasks for a flow. Tasks are sub-items of a flow that track implementation progress. Returns tasks with their completion status and hierarchy.

Create a new task under a flow. Use this to break down a flow into smaller, trackable steps. Tasks can have:

• Summary (required): Brief description of what to do

• Description: Detailed implementation notes

• Acceptance criteria: List of conditions for completion

• Parent task: For creating sub-tasks

Best practice: Create tasks for each logical step before starting implementation.

Update a task's status or details. Use this to:

• Mark tasks as completed when done

• Update task description with implementation notes

• Modify acceptance criteria

• Change task status for Kanban board

Always mark tasks complete when you finish them to track progress.

Create a new agent session for a flow. An agent session tracks a unit of work performed by the AI agent. Use this at the start of a work session to log what you're doing.

Returns the created session with its ID for subsequent log and complete calls.

Log a message to an active agent session. Use this to record progress, decisions, or issues during a work session.

Supports different log levels:

• info: General progress updates (default)

• warn: Potential issues or concerns

• error: Errors encountered during work

Complete an active agent session. Use this when you're done with a unit of work to mark the session as finished. Optionally provide a summary of what was accomplished.

List agent sessions for a flow. Returns all sessions with their status, timing, and summary. Use this to review past work sessions on a flow.

List all documentation pages for a project, grouped by section. Returns sections with their pages (title, id, section, sortOrder). Use this to see what documentation exists before creating or updating pages.

Automatically uses the linked project if no projectId is provided.

Get a single documentation page with its full content. Returns title, section, content (markdown), tags, and metadata.

Use doc_page_list first to find the page ID.

Create a new documentation page in a project. Use this to add new knowledge, guides, or documentation. Pages are organized by sections (e.g. "Architecture", "Getting Started", "API Reference").

Automatically uses the linked project if no projectId is provided.

Update an existing documentation page. All fields are optional — only provide the fields you want to change.

Use doc_page_list first to find the page ID.

Delete a documentation page. Use doc_page_list first to find the page ID.

List all releases for a project. Returns releases with their status, target dates, and descriptions. Automatically uses the linked project if no projectId is provided.

Get detailed information about a specific release. Returns the full release including name, description, status, and dates.

Create a new release for a project. Use this to plan a new version or milestone. Automatically uses the linked project if no projectId is provided.

Update an existing release. Use this to change the release name, description, status, or target date.

Search across flows, tasks, and projects in DevFlow. Use this to find items by keyword, title, or content. Supports filtering by type (flow, task, project).

Returns matching items with their type, title, and a content snippet.

Get project-specific guidelines (markdown). Guidelines are managed by the user via the DevFlow UI and stored in the backend.

Automatically uses the linked project if no projectId is provided.

Update project-specific guidelines (markdown). Guidelines are stored in the backend and visible in the DevFlow UI.

Automatically uses the linked project if no projectId is provided.

Show DevFlow MCP connection status or manage the connection. Works without devflow_init.

Actions:

• status (default): Show version, auth, project, heartbeat

• reconnect: Refresh auth token and restart heartbeat

• link: Link to a project (requires projectId)

• unlink: Remove project link (passive mode)

• projects: List available projects

Connect this project to DevFlow. Links the current directory to a DevFlow project, enabling flow tracking and enforcement. Use when you want to start using DevFlow in this directory.

Disconnect this project from DevFlow. Removes .devflow.json and stops the heartbeat. You can re-enable anytime with devflow_connect.

Upload a file as an attachment to the current flow. Use this to attach markdown documents, text notes, HTML docs, or other text-based files. The file will be visible in the DevFlow UI and accessible to other agents.

Common use cases:

• Upload implementation plans as .md files (use kind="plan" to link it to the flow)

• Attach analysis notes or design documents (kind="design" or "notes")

• Save code review summaries (kind="summary")

• Document architectural decisions (kind="decision" — can be promoted to ADR via adr_accept)

Attach a file from disk to the current flow. Use this for images / PDFs / large files (up to 50 MB).

For agent-written text content (markdown plans, summaries, notes), prefer flow_upload which takes the content as a string.

The file is read from filePath, the mime-type is detected from the extension, and the upload is sent as multipart/form-data with auth.

Common use cases:

• Attach a screenshot, photo, or generated cover image to a flow

• Attach a PDF report or design doc the user has on disk

• Attach large CSV / YAML / JSON exports that exceed the 100 KB string-content boundary

Full-text search over all wiki assets (flows, doc_pages, reviews, releases). Uses SQLite FTS5 with prefix matching. Returns hits with title + snippet.

Use this when the user asks "what do we know about X?" or to find relevant ADRs/Patterns/Runbooks before planning.

Resolve a wiki reference to a concrete asset and return it with backlinks. The raw can be a slug (e.g. "adr-014"), a doc_page title, or a flow display_id.

List all wiki assets of a specific document_type (adr | pattern | runbook | customer_context | glossary). Returns a summary (id, title, slug, verified_state).

Find all assets that link TO a given asset (reverse lookup). Useful to see where an ADR or Pattern is referenced.

Return the local knowledge graph around a project (nodes + edges). Optional type filter to limit which asset types appear.

Return a compact context briefing for a flow: outgoing wiki links + backlinks + tags. Use this before writing a plan to pull relevant ADRs/Patterns automatically.

Return a brief overview of the project knowledge: number of assets per type, top-tagged categories, and recent updates. Useful as a project primer.

DF-310 — Per-flow LLM-Wiki briefing. Returns the curated set of related ADRs, related patterns/runbooks/intents, parallel work in scope, and open knowledge gaps for a specific flow. This is the same data the Knowledge-Tab in the UI renders via WikiBriefingPanel.

Use this in planning + before review→done to make sure the flow's plan + implementation respect the existing wiki and to find gaps that the agent should close (preferably via 'extend', see knowledge_check_resolve).

DF-312 — Hierarchical TOC of the project's wiki, grouped by lifecycle_stage (release / plan / idea / superseded / deprecated). Each entry has id, displayId, title, lifecycleStage, documentType, tags, updatedAt.

Use this for "what does the wiki actually contain" — global counterpart to wiki_get_briefing (which is per-flow).

DF-312 — Chronological mutation feed of the wiki: ADR/doc_page creates, extends, supersedes, deprecates within a time window. Default window: 30 days. Use 'days' to widen up to 365.

Useful for "what's been happening to the wiki recently" — drives the Activity-Tab in the UI.

DF-312 — Health-report of the wiki: stale (release-stage entries older than N days that are still cited), orphan (entries with no in/out wiki-links), contradictions (deprecated/superseded ADRs that newer sources still cite).

Use periodically (or before a major refactor) to keep the wiki clean. Resolve findings via the devflow-wiki-lint skill — never delete entries, always extend / cross-link / re-classify.

DF-315 — Idea-Backlog: aggregates 5 organic idea sources from the wiki into one curated pipeline:

• Open intents (forward-deferred topics from past flows)

• Stale ADRs (>90d old, still cited — refresh candidates)

• Orphan pages (no in/out wiki-links — reconnect candidates)

• Contradictions (deprecated/superseded ADRs still cited — refactor candidates)

• Hotspot topics (resolved 2+ times across flows — strategic-review candidates)

Each item has a prefilledSummary + prefilledDescription ready to feed into flow_create. Use this to pick the next thing to work on without staring at a blank page — the wiki itself is the idea backlog.

DF-316 — Error-Driven Wiki Lookup. When you hit an unexpected error / exception / failing test, call this FIRST (via the devflow-error-investigator skill) to pull every wiki signal that's relevant: matching runbooks (FTS), ADRs whose affects_paths cover the error file, recent flows in the same area, related patterns, similar past errors from done-flows, plus a briefing-Markdown.

Iron Law of compounding wikis: never debug from scratch what the wiki has already seen. If no runbook matches AND the fix is non-trivial, write a runbook on the way out.

DF-318 — Idea-Prompt-Garage. Returns curated prompts per area (Auth, Billing, Performance, …) with wiki-evidence already loaded. The user pastes one of these prompts into a chat with you, and you respond using the devflow-area-ideation skill.

Each area has: name, icon, counts (ADRs/patterns/runbooks in scope), and a ready-to-paste prompt. Use this to find well-grounded next-step ideas for a project domain instead of brainstorming from scratch.

List all Architecture Decision Records for a project. Optional status filter (proposed | accepted | deprecated | superseded). Returns ADR-###, title, status, decided_at.

Get a single ADR by its number. Returns full content, status, supersedes chain, originated flow. Use this to pull the full rationale of a specific decision before planning changes.

Accept a decision.md flow-attachment as an official ADR. Auto-assigns the next ADR number for this project, copies frontmatter, links back to the flow. Idempotent: re-calling with the same attachmentId returns the existing ADR.

Change an ADR's status (proposed → accepted → deprecated → superseded). Use when an architectural decision is formally accepted, deprecated, or replaced.

Get the audit log (status change history) for an ADR. Returns the full timeline of status transitions with user, timestamp and optional note. Use this to understand why a decision moved from proposed → accepted or was later deprecated/superseded.

Prepare a knowledge backfill run for a project. Returns done-flows + existing ADRs + structured instructions that YOU (Claude) must follow to classify and propose knowledge drafts.

This is the MCP-first alternative to the keyword heuristic. Workflow:

1. Call this tool → receive flows, existing ADRs, and the ruleset

2. Read the flows, decide which qualify as ADR / Pattern / Runbook / Lessons-Learned

3. Skip anything already covered by existing ADRs

4. Group similar flows into ONE draft with multiple sourceFlowIds

5. For each draft: call knowledge_draft_create with the payload

Be conservative. Only propose drafts you are confident about. Better few high-quality drafts than many noisy ones.

Create a new knowledge draft. Called by YOU (Claude) after classifying flows via knowledge_backfill_request, or standalone when you identify a flow worth documenting.

Dedup is automatic — if a draft with the same (projectId, draftType, title) already exists in any status, the existing draft is returned and sourceFlowIds are merged. You can safely call this repeatedly.

Rules:

• draftType: one of adr | pattern | runbook | lessons_learned

• title: deklarativ, max 60 chars, no prefix like "ADR candidate:"

• body: 2–6 short markdown paragraphs, the consumable form of the knowledge

• rationale: one sentence why this matters

• sourceFlowIds: all flow ids that contributed to this draft (grouping)

List knowledge drafts for a project. Optional status filter (pending | accepted | rejected). Useful before proposing new drafts — check what is already queued so you don't duplicate your own suggestions.

Accept a draft. Creates the corresponding ADR or doc_page and marks the draft accepted. This is the commit step — use only when you are certain the draft is good to merge. Normally users accept via the UI; this tool exists for autonomous workflows.

Reject a draft with optional reviewer notes. Rejected drafts are remembered — dedup will not propose the same title again.

Harvest knowledge from a single done-flow. Call this right after flow_update transitions a flow to done (the server's nextStep will remind you). Returns the flow + existing ADRs + related drafts + instructions. Decide: does this flow warrant a new draft? If yes, call knowledge_draft_create. If the theme is already covered, skip.

Run a knowledge check on a flow: spot drift against existing ADRs and identify missing knowledge (topics without an asset). Returns flow text + ADR snapshots + instructions. YOU return the analysis — no draft creation in this tool. Use before submitting a flow to review.

Check whether an ADR has drifted from the actual codebase.

Returns the ADR content + its affects_paths (glob patterns). YOU THEN:

1. Use your own Glob/Read/Grep tools to inspect the files under those paths in the user's workspace

2. Compare the ADR's claims/decisions to what the code actually does

3. Return a structured drift report: { drifts: [{ claim, evidence, severity }] } or {} if no drift.

If affectsPaths is empty, tell the user: "ADR-N has no affects_paths configured — ask them to add glob patterns via the UI".

Get a compact context bundle for planning a flow. Returns related ADRs, parallel open flows, similar done flows, forward-intents, architecture-module excerpts and drift warnings — all in one call, priority- scored, budgeted under ~5500 tokens.

Call this AT THE START of planning instead of scattering wiki_search/adr_list/ flow_list calls. Use the markdown output directly as context; use the JSON sections if you want to cross-reference specific items.

Bootstrap the knowledge base of a project by auditing its code. Returns a structured prompt: default subsystem list (auth/data/api/frontend/realtime/billing/admin/mobile/docs/devops/testing), dedup-list of existing ADRs/drafts/pages, and explicit instructions for Claude to read the local repo with Glob/Grep/Read and then create architecture_module pages + knowledge drafts.

Call this once per new project. Idempotent — re-running will skip existing entries via the dedup-list.

Snapshot of open work across the project. Returns four buckets:

• inFlightFlows: flows currently in planning / in_progress / review

• openIntents: forward-intent doc-pages with status != 'resolved' (from flow_seal / DF-254)

• proposedAdrs: ADRs with status='proposed' (not yet accepted)

• pendingDrafts: knowledge_drafts with status='pending'

Use this BEFORE starting planning so you don't propose something already in flight or already captured as an intent. Optional tag / path filters narrow the result to your area. Pass excludeFlowId= to exclude the flow you are currently planning for.

Close a forward-intent page. Sets frontmatter.status='resolved' and links the resolving flow.

Forward-intents are doc_pages with document_type='intent' — written by flow_seal (DF-254) when a done-flow declared follow-up work via forward_intents frontmatter. When your current flow actually delivers that follow-up, call this tool so the loop is closed and the intent disappears from pending_work / planning_context.

flowId = the flow that is resolving the intent (typically your current flow). pageId = the intent doc-page id (find via pending_work → openIntents).

Suggest project tags for a piece of content using TF-IDF against the existing project tag pool. Never invents new tags — only existing ones are suggested, to avoid tag-wildwuchs.

Use when you are writing a new doc-page / ADR / flow summary and want to tag it consistently with the rest of the project. Returns suggestions ranked by confidence with matchedTokens for debuggability.

Pass existingTags so already-applied tags are excluded from suggestions.

Resolve a single knowledge-check warning manually. In most cases you do NOT need this tool anymore — the pre-tool-use hook on flow_update auto-calls POST /api/projects/:id/knowledge/auto-resolve which applies the Iron Law in bulk (extend > create > intent_defer; never dismiss). Use this manual tool only for surgical overrides.

Iron Law of the LLM-Wiki: extend > create > intent_defer > NEVER dismiss. The backend now ENFORCES this — calling resolutionType='dismiss' when an extend-target exists returns 400 'iron_law_dismiss_blocked' with the recommended slug.

Resolution types:

• 'extend' — PREFERRED. Append a dated update section to an existing ADR/pattern/runbook. Pass entityType + entityId + body + rationale. Backend appends '## Update YYYY-MM-DD — extended by '.

• 'adr' — link to a NEW/existing ADR (entityType='adr', entityId=).

• 'pattern' — existing pattern doc covers it (entityType='doc_page', entityId=).

• 'runbook' — existing runbook covers it.

• 'intent_defer' — defer to a later flow. Seeds an intent doc-page; horizon: 'next-quarter'|'later'.

• 'dismiss' — LAST RESORT. Backend rejects this whenever an extend-target exists; reserved for genuinely off-topic mentions.

flowId = the flow the warning is attached to. topic = the warning's topic string (e.g. 'billing').

Emit a discipline-token for a flow + skill (DF-289 backend, DF-292 gate-check).

A discipline-token is an HMAC-signed proof that a discipline-skill ran successfully. The signed token is returned ONLY once — the backend stores only the hash. Keep the signed token in session memory.

Use this at the END of a discipline-skill run (devflow-tdd, devflow-verification-gate, devflow-adr-compliance, devflow-collision-acknowledged, ...) once all iron-laws of the skill are satisfied.

Pass the token later to flow_update when transitioning under agent_with_discipline policy: flow_update({ flowId, currentState: 'done', selfApproved: true, disciplineTokens: [token] })

The backend verifies all required tokens before allowing the transition. Without an opt-in project (project_configs.allow_agent_self_approval=1) and matching pipeline_steps.required_skills, the gate-check rejects.

List active (non-expired) discipline-tokens for a flow. Does NOT return raw tokens — only metadata (id, skillName, createdAt, expiresAt, evidence). Use this to check what a flow already has before deciding whether to emit a fresh one.