brainstorm-task

name	brainstorm-task
description	Plan and track implementation work using the Task DAG system. Create structured task trees linked to real code, enforce single-pipeline discipline, and generate handoff context for coders.
argument-hint	[task title or description]

Brainstorm Task

Use the Task DAG system to plan implementation work with full traceability to the code graph.

Single-Pipeline Discipline

One root task at a time. Before creating a new root task, call task_get_active_root to check if a pipeline is already running. Only create a new root task when the current pipeline is fully done or archived.

Full pipeline — strictly in order:

BRAINSTORM → VALIDATE → DESIGN (root) → REVIEW (dashboard) → [PLAN → IMPLEMENT] × N leaves → CLOSE

Each stage answers a different question:

Stage	Question	Scope	Output
Brainstorm	WHAT and WHY?	Root	DAG: tasks, notes, contracts
Validate	Are we ready?	Root	task_validate errors = 0
Design	WHAT does it consist of?	Root (1×)	Design docs: architecture, behavior, contracts, testing
Review	Does architecture look right?	Root (1×)	User feedback via dashboard annotations
Plan	WHERE in files, in what order?	1 leaf (N×)	plan.md — step-by-step checklist
Implement	CONCRETE CODE	1 leaf (N×)	Files, functions, tests
Close	Mark done, propagate up	Root	task_update(done)

Why the Design and Plan stages matter

After brainstorm, the DAG has specs and acceptance criteria but no file paths or step order. The coder receiving a leaf task still asks: "Where does this class go? What file to create? Which DI container to update?"

• Design (1 session, root-level): produces docs/feature-name/01-architecture.md, 02-behavior.md, 04-testing.md, etc. Uses task_export(root_id, include_analysis=True) as input. Human approves. Then task_update each leaf to status="ready" with finalized spec + AC.
• Plan (per leaf): reads task_export(leaf_id, include_source=True) + design docs + real file structure (find_files_by_pattern, query_graph). Produces plan.md — ordered checklist of file operations, edits, test cases. No new MCP tools needed — all data is already available.

Inputs and outputs per stage

# Design input (once per root)
task_export(root_id, include_analysis=True)   # full subtree spec
→ design docs: 01-architecture.md … 08-api-contract.md
→ human approval ✅
→ task_update each leaf: status="ready", spec=..., acceptance_criteria=...

# Plan input (per leaf, after design)
task_export(leaf_id, include_source=True)     # spec, AC, contracts, code_refs
find_files_by_pattern(["src/auth/*"])         # actual file structure
query_graph(pattern="children_of", target="src/auth/")
contract_list(task_id=leaf_id)
→ plan.md with step-by-step checklist (mkdir, create file, edit DI, write tests)

# Implement (per leaf)
Follow plan.md checklist.
task_update([{task_id, status: "done"}])
task_check_rollup(leaf_id)

Workflow phases — strictly in order:

1. Brainstorm — full task tree with notes, contracts, code links
2. Validate — task_validate must pass (0 errors) before design
3. Design — architecture + behavior docs for the root (1 session)
4. Plan — step-by-step file checklist for each leaf (N sessions)
5. Implement — code each leaf following its plan
6. Close — mark done, task_check_rollup to propagate up the tree

Phase 1: Create the Task Tree

All creation calls use list-based batch mode — always pass a list, even for one item.

task_get_active_root()          # confirm pipeline is idle

# Create root task
task_create(tasks=[{"title": "My Feature", "description": "..."}])

# Decompose in one call — all subtasks sharing the same parent
task_create(parent_id=root_id, tasks=[
    {"title": "Auth module"},
    {"title": "Token service", "description": "JWT-based"},
    {"title": "Login endpoint"},
])

# Decompose + wire dependencies atomically — edges use 0-based task indices
task_create(parent_id=root_id, tasks=[
    {"title": "OAuth interface"},    # index 0
    {"title": "Google OAuth impl"},  # index 1
    {"title": "JWT service"},        # index 2
    {"title": "Login endpoint"},     # index 3
], edges=[
    {"from": 1, "to": 0, "type": "depends_on"},   # Google OAuth needs interface
    {"from": 3, "to": 0, "type": "depends_on"},   # Login needs interface
    {"from": 3, "to": 2, "type": "depends_on"},   # Login needs JWT
])
# → tasks + edges created atomically; "edges" key in response shows created edges

Rules:

• Only leaf tasks (no children) get code refs and contract links
• Parent tasks are grouping containers — no direct code refs
• 3 levels max for clarity; decompose further only if check_isolation score < 0.5

Phase 2: Add Notes and Design Decisions

Add multiple notes in one call — always pass a list, even for one note.

# All notes for a task in one call (typical after structured brainstorm interview)
note_add(task_id=task_id, notes=[
    {"note_type": "decision",   "content": "Use JWT", "status": "resolved",
     "resolution": "JWT tokens", "rationale": "stateless"},
    {"note_type": "question",   "content": "WebSocket or polling?"},
    {"note_type": "assumption", "content": "User model already exists"},
    {"note_type": "constraint", "content": "self-hosted only"},
    {"note_type": "risk",       "content": "Token refresh race condition"},
])

# Single note
note_add(task_id=task_id, notes=[
    {"note_type": "constraint", "content": "No external SaaS dependencies"}
])

• Notes on root/parent tasks are visible to ALL descendants via include_parent=True
• Search all notes in a subtree: note_list(task_id, include_children=True)
• Resolve open questions before handing off to coder

Async Q&A

When you have open questions or unverified assumptions that require human input, do not of waiting in the chat session. This decouples LLM work from human response time.

Note lifecycle:

open  →  answered  →  resolved / rejected / deferred
         (user in UI)   (LLM validates, updates DAG)

• open — question or assumption added, no response yet
• answered — user wrote a response in the web UI (LLM not yet involved)
• resolved — LLM validated and accepted; DAG may have been updated
• rejected — LLM or user determined the note was invalid/incorrect
• deferred — postponed, not blocking current work

LLM workflow when resuming a session

At the start of every session, call task_roadmap(). The attention.answered_notes field lists notes that need processing:

task_roadmap()
→ attention.answered_notes: [
    { id: "n3", note_type: "question",
      content: "WebSocket or polling?",
      resolution: "Let's use SSE — simpler than WS, more reliable than polling",
      task_id: "t1" },
    { id: "n7", note_type: "assumption",
      content: "User model has email field",
      resolution: "No! Users have phone only, no email",
      task_id: "t1" }
  ]

For each answered note, you MUST:

1. Read the resolution carefully
2. Assess impact on the DAG (does this change invalidate existing tasks? create new questions?)
3. Act accordingly (see table below)
4. Mark the note: note_update(note_id, status="resolved"/"rejected", rationale="...")

Decision table:

Answer type	Example	LLM action
Simple choice	"Use JWT"	note_update(resolved) + add decision note
Design clarification	"SSE not WebSocket"	note_update(resolved) + possibly rename/edit tasks
Rejected assumption	"No email field"	note_update(rejected) + task_search for affected tasks + task_archive dead paths + add new questions
Direction change	"No templates, hardcode"	note_update(resolved) + task_archive(subtree) + simplify dependencies
Scope expansion	"Also needs offline PWA"	note_update(resolved) + task_create new subtasks

task_validate() will warn if there are unprocessed answered notes. Process all answered notes before marking work ready for implementation.

note_list(task_id=root_id, status="answered", include_children=True)
# → process each, then mark resolved/rejected
note_update(note_id, status="resolved", resolution="Accepted: SSE", rationale="...")
note_update(note_id, status="rejected", resolution="User has no email", rationale="Invalidates t2, t8")

Architecture Skeleton: C4 Navigation Layer

The architecture skeleton (.code-review-graph/architecture.c4) provides a persistent, token-efficient map of the codebase. It sits between the high-level project standards and the low-level code graph:

prompts/                  ← "HOW we build" (cross-project knowledge)
architecture.c4           ← "WHAT exists" (module map, per-project)
code graph + task DAG     ← "WHERE exactly" (files, lines, per-task)

Reading the skeleton

get_architecture_skeleton()                          # full file
get_architecture_skeleton(level="containers")         # L2 containers only
get_architecture_skeleton(level="components:auth")    # specific module
get_project_standards(section="patterns")             # project conventions

Use the skeleton as the FIRST orientation step in any session — before task_export or code graph queries. It gives module boundaries and relationships in ~20 lines of C4 DSL.

Writing to the skeleton (Design phase)

During design, add new architectural elements:

update_architecture_skeleton(
    feature_tag="oauth:t1",
    operations=[
        {"op": "add", "diagram": "Containers", "element": {
            "kind": "Container", "id": "oauth",
            "label": "OAuth Provider", "technology": "Python",
            "description": "Google+GitHub OAuth"}},
        {"op": "add", "diagram": "Containers", "element": {
            "kind": "Rel", "id": "oauth", "target_id": "auth",
            "label": "registers provider"}},
        {"op": "modify", "diagram": "Containers",
         "element_id": "auth",
         "changes": {"description": "12 nodes, +OAuth callback"}},
    ]
)

Rules:

• [AUTO] sections are read-only (regenerated from code graph by code-review-graph c4 --rebuild)
• [FEATURE] sections are writable by LLM via update_architecture_skeleton
• When code is implemented and graph rebuilt, FEATURE elements that now exist in AUTO are "graduated" automatically
• Dashboard renders AUTO as blue, FEATURE-only as green (new), FEATURE+AUTO overlap as yellow (modified)

Sequence diagrams

Auto-generate Mermaid sequences from existing flows or task contracts:

generate_sequence(flow_name="login")        # from existing execution flow
generate_sequence(task_id=root_id)          # from task contracts + execution order

Returns {mermaid: "sequenceDiagram\n...", gaps: [...]}. Gaps highlight missing error cases (no risk notes), missing response payloads, etc.

Interactive Dashboard

The dashboard provides visual review of the brainstorm output. Launch it after the Design phase for human review.

code-review-graph dashboard                    # auto-detect root task
code-review-graph dashboard --task t1 --port 6235

Tabs

Tab	Data source	User can
Architecture	architecture.c4 via Cytoscape.js	Drill-down L2→L3, annotate nodes
Task DAG	task_get_dag via Cytoscape.js	View dependencies, select tasks
Contracts	contract_list	View definitions, comment
Notes & Questions	note_list	Answer open questions, edit answers
Roadmap	task_roadmap	See progress, attention items
Timeline	task_execution_order	See parallel execution levels
Sequence	generate_sequence via Mermaid.js	View auto-generated sequences

Annotations (c4_element_id)

Users can pin notes to C4 diagram elements by right-clicking nodes in the Architecture tab:

# Dashboard creates:
note_add(task_id=relevant_task, notes=[{
    "note_type": "question",
    "content": "Why separate OAuthProvider?",
    "status": "answered",
    "resolution": "Suggest merging into AuthController",
    "c4_element_id": "comm_5"
}])

The c4_element_id field links the note to a specific C4 element (container, component, or contract). Values like "comm_5" (community/container), "node_123" (component), "contract_X" (contract).

Dashboard principles

• Dashboard NEVER changes: task.status, task.description, contracts, task structure
• Dashboard ONLY: answers questions (open→answered), creates annotations (new notes)
• ALL structural changes go through LLM in the next session
• LLM is the sole writer of structure; user is reviewer + answerer

Phase 3: Link Code to Tasks

Decomposition sweet spot

Rule: 1 task = 1 coherent logical change, NOT 1 task = 1 code node.

Too coarse: "Add OAuth"          → 50+ nodes → noise
Too fine:   "Add expires_at"     → 1 node → 50 tasks → management hell
Sweet spot: "JWT token service"  → 3-8 nodes → useful, manageable

Target 3–8 code nodes per leaf task:

• 1 primary file (creates / modifies)
• 2–4 related files (modifies)
• 1–3 context files (reads)

Code links only on leaf tasks. Parent/mid-level tasks are grouping containers — no direct code refs (task_validate warns if violated).

Handoff levels:

• Designer → task_export(mid_task_id) — sees all leaf subtasks, contracts, notes, plus subtask_code_refs_summary (rollup: how many unique code nodes all leaves collectively touch, which leaves have no code refs yet)
• Coder → task_export(leaf_task_id) — sees exact nodes, line ranges, acceptance criteria

Finding nodes

# Single symbol
semantic_search_nodes_tool(query="create_task", kind="Function")
→ { id: 655, qualified_name: "code_review_graph/tasks.py::create_task",
    line_start: 100, line_end: 162, params: "(...)", ... }

# Multiple symbols in one call — multi-word = FTS5 OR, single round-trip
semantic_search_nodes_tool(query="create_task add_task_edge move_task archive_task add_note")

# Filter to specific file
semantic_search_nodes_tool(query="create", file_path="tasks.py")

# All functions in a file (structural, not text-based)
query_graph_tool(pattern="children_of", target="code_review_graph/tasks.py")

Use line_end to read function bodies efficiently. MCP search returns line_start and line_end for every node. Use them to make a targeted read instead of loading the whole file:

# GOOD: read only the function you need
Read(filePath="tasks.py", offset=line_start, limit=line_end - line_start + 1)

# BAD: reading the whole file to find where a function ends bloats input context
# significantly while output context stays the same — avoid on large codebases
Read(filePath="tasks.py")

MCP does NOT replace grep for body content. semantic_search_nodes_tool only indexes declarations (name, signature, params). To search inside function bodies — use Grep or ripgrep directly.

Linking nodes

Always pass a list, even for one node. Both code_node_id (int) and qualified_name (str) can be mixed. Use values directly from semantic_search_nodes_tool — no extra lookup needed.

# Single node
task_link_code(task_id=task_id, links=[
    {"ref_type": "modifies", "code_node_id": 1791}
])

# Typical leaf task (3-8 nodes in one call)
task_link_code(task_id=task_id, links=[
    {"ref_type": "modifies", "code_node_id": 1791},
    {"ref_type": "modifies", "qualified_name": "src/auth.py::TokenModel"},
    {"ref_type": "reads",    "qualified_name": "src/config.py::JWTConfig"},
    {"ref_type": "creates",  "qualified_name": "src/auth.py::TokenResponse",
     "description": "new response schema"},
])
# Returns: {task_id, success_count, error_count, total, linked[], errors[]}
# Partial failures do NOT abort — errors collected, valid items linked.

ref_type guide:

ref_type	When to use
modifies	Changing existing function/class
creates	Adding new function/class
reads	Reading/querying only
deletes	Removing code
tests	Adding/updating tests

Phase 4: Define Contracts (Design Entities)

Contracts capture data structures, interfaces, and APIs — even before they exist in code.

# New design entity (doesn't exist yet)
contract_add(
    name="OAuthToken",
    contract_type="schema",           # schema | interface | api | event | data_format
    definition="{ access_token: str, refresh_token: str, expires_at: datetime }",
    scope_task_id=root_id,
    provider_task_id=t3_id,           # who creates this
    consumer_task_ids=[t5_id, t6_id]  # who uses it
)

# Modifying existing code (link to real code node)
contract_add(
    name="User_extended",
    contract_type="schema",
    definition="Add oauth_provider: str, oauth_id: str",
    scope_task_id=root_id,
    qualified_name="code_review_graph/graph.py::GraphStore"  # existing code
)

# Add participants after decomposition
contract_link(contract_id, task_id, role="consumer")
contract_unlink(contract_id, task_id)
# contract_link returns changed:True (new) or changed:False + reason (already linked)
# contract_unlink returns changed:True (removed) or changed:False + reason (wasn't linked)

Find all contracts in a brainstorm:

contract_list(scope_task_id=root_id)           # all including orphans
contract_list(task_id=leaf_id)                 # contracts for specific task
contract_list(name="OAuthToken")               # find by name

Phase 5: Add DAG Edges

When to use inline edges vs task_add_edge:

• Inline edges= in task_create — use at decomposition time (60% of cases). Atomic: tasks + edges in one call.
• task_add_edge — use post-factum when tasks already exist ("turns out t7 depends on t4").
• task_remove_edge — use when a dependency changes ("t5 no longer needs t3 after design change").
• Viewing edges — use task_export(task_id) which returns the edges field; task_get_dag for the full subtree.

# Post-factum edge (tasks already exist) — always a list, even for one edge
task_add_edge(edges=[{"source_id": child_id, "target_id": blocker_id}],
              edge_type="depends_on")

# Pattern A — one task depends on many (all children depend on the base interface)
task_add_edge(edge_type="depends_on", edges=[
    {"source_id": google_oauth_id, "target_id": oauth_interface_id},
    {"source_id": github_oauth_id, "target_id": oauth_interface_id},
    {"source_id": login_endpoint_id, "target_id": oauth_interface_id},
])

# Pattern B — mixed edge types in one call (per-item edge_type overrides default)
task_add_edge(edge_type="depends_on", edges=[
    {"source_id": t5_id, "target_id": t2_id},
    {"source_id": t6_id, "target_id": t7_id, "edge_type": "shares_context"},
])

Edge types: depends_on | blocks | shares_context | conflicts_with | informs Cycle detection is automatic — depends_on/blocks edges cannot form cycles (checked atomically). Duplicate edges are idempotent — adding the same edge twice returns already_exists: true (no overwrite). blocks edges are cross-checked against depends_on to prevent mutual-wait deadlocks.

Phase 6: Run Analysis

task_find_conflicts(root_task_id)            # tasks sharing same code nodes (direct, depth=0)
task_find_conflicts(root_task_id, depth=1)   # + indirect: tasks connected via code graph edges
task_contradiction_report(root_task_id)      # compile full report for LLM semantic analysis
task_check_isolation(task_id)         # isolation_score < 0.5 → too coupled, split
task_blast_radius(task_id, depth=2)   # code impact radius (affected_nodes_count + uncovered_nodes)
task_execution_order(root_task_id)    # parallelism-aware order (levels)
task_suggest_contracts(root_task_id)  # hidden code dependencies without contracts
task_find_for_impact(file_paths)      # open tasks in blast radius of changed files

Interpret check_isolation:

• score > 0.7 → well isolated, safe to implement independently
• score 0.4–0.7 → moderate coupling, coordinate with related tasks
• score < 0.4 → highly coupled, consider splitting or adding contracts
• status: "not_applicable" → task has no code refs yet (link code first)

Summary includes both external_dependencies (callees this task calls) and external_dependents (callers of this task).

task_blast_radius response:

• affected_nodes_count — scalar count of BFS-reachable nodes (always present)
• uncovered_nodes — actionable list: nodes in blast radius not covered by any task
• include_affected_nodes=True — opt-in to get full affected_nodes list (can be large)
• status: "not_applicable" → task has no code refs linked yet

Rule of 3 Ps: Problems / Gaps / Contradictions

Brainstorming should resolve three categories of risk before implementation:

P1 — Problems      → task_validate + task_blast_radius + task_check_isolation
P2 — Gaps          → task_blast_radius.uncovered_nodes + task_find_for_impact
P3 — Contradictions → task_find_conflicts(depth=1) + task_contradiction_report

P1: Problems

Algorithmic checks that catch structural issues:

• task_validate() — gate-check: 9 algorithmic checks (missing code refs, open questions, unsatisfied deps)
• task_blast_radius(task_id) — code graph impact; uncovered_nodes = code this task touches but no subtask explains
• task_check_isolation(task_id) — score < 0.5 → task too coupled, consider splitting

P2: Gaps

Cross-layer coverage queries:

• task_blast_radius(task_id).uncovered_nodes — nodes in blast radius not covered by any task
• task_find_for_impact(file_paths) — open tasks in blast radius of changed files
• task_suggest_contracts(root_task_id) — hidden code dependencies needing interface contracts

P3: Contradictions

Three-level detection:

Level 1 — Direct code overlap (algorithmic):

task_find_conflicts(root_task_id, depth=0)

→ tasks that modify the same code nodes: both_modify, read_write, shared_ref

Level 2 — Indirect code coupling (algorithmic):

task_find_conflicts(root_task_id, depth=1)

→ tasks whose nodes are connected via code graph edges (calls/imports). Returned as conflict_type: "indirect" with coupling_nodes.

Level 3 — Semantic contradictions (LLM-driven):

task_contradiction_report(root_task_id)

Returns a compact report:

{
  code_conflicts:      [...],   # depth=1 conflicts — algorithmic
  all_decisions:       [...],   # every decision note in the subtree
  all_constraints:     [...],   # every constraint note
  all_contracts:       [...],   # all interface contracts
  leaf_tasks_summary:  [...]    # compact: title + first 200 chars + ref_types
}

Pass this to the LLM as a single prompt: "Find semantic contradictions between these decisions, constraints, and contracts." The LLM looks for things like "All APIs synchronous" + "Realtime WebSocket notifications" — architectural conflicts across different branches of the task tree.

Record found contradictions as:

task_add_edge(edge_type="conflicts_with", edges=[{"source_id": t5_id, "target_id": t8_id}])
note_add(task_id=root_id, notes=[{"note_type": "risk", "content": "Sync-only API conflicts with WebSocket requirement"}])

Phase 7: Validate Before Implementation

task_validate()   # auto-detects active root, runs 9 checks

Required: 0 errors before handing off to coder. Warnings are advisory.

Common errors to fix:

• Missing acceptance_criteria on leaf tasks → add via task_update(updates=[{task_id, acceptance_criteria: "..."}])
• Open questions → resolve via note_update(note_id, status="resolved", resolution="...")
• Proposed contracts between ready tasks → contract_update(id, status="agreed")

  Backward transition (e.g. implemented→proposed) returns a "warning" field in response

• Leaf tasks with no code refs → task_link_code(...) or justify in notes

Phase 8: Generate Handoff Context

task_export()                              # full context for active root
task_export(task_id, include_analysis=True) # + isolation, conflicts, pipeline_state
task_roadmap()                             # progress snapshot + attention block

Every task_export response includes a mermaid_diagram field — a graph TD Mermaid diagram of the full subtree with subgraphs for parent tasks and depends_on edges between leaves.

Mermaid diagram for the Designer

The mermaid_diagram from task_export(root_id) gives the designer the complete task skeleton at a glance — all mid-level groups and their leaf tasks, with dependency arrows showing what must be done before what. Use it to:

• Understand scope instantly — one look shows all nested levels without scrolling through task lists
• Spot deep nesting — if a subtree has 3+ levels of nesting and many leaves, that branch is a candidate for a dedicated sub-agent design session rather than a single monolithic design pass
• Distribute design work across sub-agents — when the tree is large, split by top-level mid-task:

# Full tree too large for one design session? Use mermaid to identify natural splits:
task_export(root_id)
→ mermaid_diagram shows:
    subgraph cluster_t2 [JWT Token Service]      ← 8 leaves
    subgraph cluster_t3 [Google OAuth Flow]      ← 6 leaves
    subgraph cluster_t4 [Login Endpoint]         ← 4 leaves

# Hand each cluster to a separate designer sub-agent:
task_export(t2_id, include_analysis=True)   # → designer agent A (JWT)
task_export(t3_id, include_analysis=True)   # → designer agent B (Google OAuth)
task_export(t4_id, include_analysis=True)   # → designer agent C (Login)

Rule of thumb: if a single mid-level subtree has more than 8 leaves, spawn a dedicated design sub-agent for it. The mermaid_diagram makes this split decision visual and obvious.

CLI equivalent (generates markdown file for humans + LLM):

code-review-graph task-report

Phase 9: Implementation Tracking

task_update(updates=[{"task_id": task_id, "status": "in_progress"}])
task_update(updates=[{"task_id": task_id, "status": "done"}])
task_check_rollup(task_id)    # check if parent can be closed

After all leaves are done:

task_validate()    # confirm 0 errors still
task_archive(task_ids=[root_task_id], reason="Completed successfully")

Selective archiving — when changing approach mid-brainstorm (archive only what's no longer needed):

task_archive(reason="Switching to in-app only", task_ids=["t2", "t3", "t6"])

Preview before destructive operations — dry_run=True returns what WOULD be affected without executing:

task_delete(task_id, cascade=True, dry_run=True)   # → {would_delete: [{id, title}], count: N}
task_archive(task_ids=[...], reason="...", dry_run=True)  # → {would_archive: [{id, title}], count: N}

Restructuring — move a group of tasks to a new parent in one call:

task_move(new_parent_id=auth_group_id, task_ids=["t2", "t3", "t4"])

Cross-Layer Queries

# "Which tasks touch AuthService?" (open tasks only by default)
task_find_by_code_node(code_node_id)                  # open_only=True by default
task_find_by_code_node(code_node_id, open_only=False) # include done/archived

# "What open tasks are in blast radius of my changes?"
task_find_for_impact(file_paths=["src/auth.py", "src/user.py"])

# "Which task pairs need contracts?"
task_suggest_contracts(root_task_id)

# "Is this task safe to implement alone?"
task_check_isolation(task_id)

# "What code will this task touch transitively?"
task_blast_radius(task_id, depth=2)

# "In what order should I implement leaves?"
task_execution_order(root_task_id)   # returns parallel levels

Tips

• Sweet spot: 3–8 code nodes per leaf task — not 1, not 50
• Batch API: all 6 bulk ops use list-based batch — always pass a list, even for one item
  • task_create(tasks=[...], parent_id=...) — decompose
  • task_add_edge(edges=[...], edge_type=...) — add dependencies
  • task_link_code(task_id=.., links=[...]) — link code nodes
  • task_move(task_ids=[...], new_parent_id=...) — restructure tree
  • task_archive(task_ids=[...], reason=...) — selective archiving
  • note_add(task_id=.., notes=[...]) — add brainstorm notes
• Handoff: designer gets task_export(mid_task_id), coder gets task_export(leaf_task_id, include_analysis=True)
• mermaid_diagram: every task_export returns this field — use it to instantly see the full subtree skeleton (subgraphs = parent tasks, arrows = depends_on edges). For deep trees (3+ levels, many leaves), use it to identify subtree boundaries and distribute design/plan work across sub-agents — one sub-agent per top-level cluster
• priority_score in execution levels: task_execution_order now returns each task enriched with priority_score (0..1) and ranking_signals (isolation_score, dependents_count, provider_count). Tasks within each level are sorted by score descending — the most foundational (many dependents) and most isolated (safe to implement alone) tasks come first. Start with the highest-score tasks in each level
• Always link leaf tasks to code before task_validate — unlisted code refs are a warning
• Use note_list(include_children=True) to search decisions across the whole brainstorm
• task_suggest_code_links(task_id) — scored by keyword match count, already-linked nodes excluded, limit=20 default
• task_search(root_task_id, query="auth") finds tasks by title/description text
• task_get_dag(root_task_id) returns the full tree with all edges; use compact=True for {id, title, status, depth, parent_id} nodes (faster for large trees)
• task_delete(task_id) response includes deleted_tasks: [{id, title}] — confirm what was deleted
• Pipeline error on task_create includes blocking_task_id for direct navigation to the blocking root
• answered notes: after user answers via UI, task_roadmap() shows them in attention.answered_notes; process each with note_update before task_validate passes cleanly
• Contract status auto-upgrades when provider task status changes (draft→proposed→acknowledged→implemented)
• Rule of 3 Ps: after decomposition, verify P1 (task_validate + blast_radius), P2 (uncovered_nodes), P3 (task_find_conflicts depth=1 + task_contradiction_report)
• Semantic contradictions: task_contradiction_report gives LLM everything to find conflicts in decisions/constraints — one call, compact output
• Architecture skeleton: get_architecture_skeleton() before any design session — 20 lines of C4 beats scrolling through code_refs
• Dashboard for review: after Design phase, code-review-graph dashboard for human review; annotations become notes for LLM processing
• Sequence generation: generate_sequence(task_id=root_id) auto-generates happy-path sequence from contracts; add risk notes for error cases
• c4_element_id in notes: pin annotations to specific architecture elements; group by element in dashboard