Flownix Review

Run a code review and persist it in Flownix via MCP. Every run either creates a new review or appends an iteration to an existing one for the same branch.

Trigger

• /review — review current diff, scope = whole branch
• /review <slug> — review changes related to node ACME-TASK-5 (or any slug)
• "create review", "run code review", "add review iteration"

Tools are written as bare names (get_node, rag_query). The mcp__<server>__ prefix comes from whatever key the user registered the server under, and differs per person — a hardcoded prefix breaks for everyone who named it differently.

Step 0 — Load project config context

cat .flownix 2>/dev/null || cat .ai-flow

Parse YAML → extract project.id and project.key.
If missing → invoke flownix-init first, then continue.

Step 1 — Detect git context

Run in parallel:

git branch --show-current                     # → branch name
git rev-parse --short HEAD                    # → commit_hash
git log origin/main...HEAD --oneline          # → commits being reviewed
git diff origin/main...HEAD --stat            # → changed files overview

Reviewer name → use git config user.name or fallback to "AI Agent".

Step 2 — Resolve node (if slug provided)

If a slug was passed as argument (e.g. /review ACME-TASK-5):

node = get_node_by_slug({
  slug: "<slug>",
  project_id: "<project_id>"
})

Use the node to:

• Understand what was being built (read node.content)
• Get prior commit_hash from node.commit_hash (may already be set)
• Scope the diff review to files relevant to that task

Read node comments with [progress] and [done] prefixes to understand the state of work.

Pull project knowledge the diff must respect

rag_query({ project_id: "<project_id>", query: "<subsystem the diff touches> architecture decision", kind_filter: "doc" })
rag_context({ project_id: "<project_id>", query: "<what the branch changes> — conventions and prior decisions" })

Semantic search finds the recorded decisions and conventions no diff shows: a change that contradicts one is a review finding, not a nitpick. Confirm each hit with get_node before citing it in the review, and cite the slug. If rag tools are unavailable, review from the diff and node content alone — say so in the review. See flownix-rag-search.

Step 3 — Check for existing review on this branch

reviews = list_reviews({ project_id: "<project_id>" })

Look for a review where branch === <current_branch>.

• Found → remember review_id, will add an iteration (Step 6)
• Not found → will create a new review (Step 5)

Step 4 — Run the code review

Analyze the diff (git diff origin/main...HEAD) with full attention to:

If node slug provided: focus on code that implements the node's task/feature as described in node.content.

If no slug: review the full branch diff.

Run review analysis now. Format result as structured Markdown:

## Ревью итерация N

### 🎯 Область ревью
[What is being reviewed — branch + node title if slug provided]

### 🔴 Критические проблемы
[Numbered list of blockers. "—" if none]

### 🟡 Замечания
[Numbered list of non-blocking issues, style violations, naming]

### ✅ Что хорошо
[What's implemented well]

### 💡 Рекомендации
[Concrete actionable improvements with code snippets if helpful]

### ⚖️ Вердикт
**APPROVE** | **REQUEST CHANGES** | **NEEDS DISCUSSION**

[1-2 sentence summary]

Step 5 — Create new review (if no existing)

result = create_review({
  project_id: "<project_id>",
  reviewer: "<reviewer_name>",
  branch: "<branch>",
  commit_hash: "<commit_hash>",      // optional but preferred
  content: "<formatted review markdown>"
})
// result.review_id → save for next steps

Step 6 — Add iteration (if review already exists)

result = add_review_iteration({
  review_id: "<existing_review_id>",
  commit_hash: "<commit_hash>",      // optional
  content: "<formatted review markdown>"
})
// result.iteration_number → for confirmation message

Step 7 — Link review to node (if slug was provided)

Run both calls in parallel:

7a — Persist bidirectional link (review ↔ node, navigable in UI):

// Load current node_links first so we append, not replace
existing = get_review({ review_id: "<review_id>" })
current_ids = existing.node_links.map(l => l.node_id)  // may be empty

set_review_nodes({
  review_id: "<review_id>",
  node_ids: [...current_ids, "<node_id>"]   // node_id from get_node_by_slug
})

After this call:

• The review panel shows the node as a clickable chip → navigates to ?tab=planning&node=<id>
• The node detail panel shows the review as a backlink → navigates to ?tab=reviews&review=<id>

7b — Add [review] comment to the node (for audit trail):

add_comment({
  slug: "<slug>",
  project_id: "<project_id>",
  body: "[review] Ревью итерация <N>. Вердикт: <APPROVE|REQUEST CHANGES|NEEDS DISCUSSION>. Review ID: <review_id>"
})

Step 7c — Bind the review to system components — mandatory

A review is linked to the parts of the system its diff touched, the same way nodes and docs are. Derive them from the changed paths, not from the node's existing links.

list_components({ project_id })        // match repo_path against the diff's paths
set_review_components({ review_id: "<review_id>", components: ["AF-COMP-3", "AF-COMP-7"] })

• Several components are normal — a branch touching the API and the web app is bound to both. set_review_components replaces the set, so pass the full list.
• No component matches a path the diff changed? Create it — create_component({ project_id, title, repo_path, component_kind, parent }) — then bind. Never leave a review unbound because the inventory is behind the repository.
• The project has no components at all → run map-components.

Step 8 — Report to user

Tell the user:

✅ Ревью сохранено в Flownix
   Review ID:  <review_id>
   Итерация:   <N>
   Ветка:      <branch>
   Коммит:     <commit_hash>
   Нода:       <slug> (если была передана)
   UI:         /projects/<project_id>?tab=reviews&review=<review_id>

MCP Tool Reference

Decision table

Example invocations

/review                     → full branch review, auto-detect project
/review ACME-TASK-5         → review scoped to task, linked back to node
/review ACME-FEATURE-2      → review scoped to feature