@tesselate-digital/notion-agent-hive 0.0.7 → 0.0.9

package/README.md

@@ -1,34 +1,34 @@
+<p align="center">
+  <img src="assets/logo.png" alt="Notion Agent Hive" width="400">
+</p>
+
 # notion-agent-hive
 
 **Persistent memory for AI coding sessions using Notion.**
 
 ## Why this exists
 
-Two, ahem, persistent problems with AI coding agents:
+Like many, I've been using LLMs extensively, in every flavour, and with all sorts of harnesses (Claude code, Codex, Copilot, etc.)
+
+While they can be wildly effective, I found some limitations in my workflow:
 
-**Sessions die at the worst time.** You're mid-feature when rate limits hit or sessions expire. There's no clean way to continue on another platform. You learn to ask agents to write plans in markdown first, but it's easy to forget - and then the context is gone.
+**Form factor** CLIs can be a bit clunky to collect one's thoughts. I love to write, edit, revisit, add structure through headers and richer markup ... Command line doesn't feel like the best place for that.
 
 **You lose track of what actually happened.** When working on larger features that take time, you often switch between your agent and other tasks. Coming back later, it's hard to trace what happened and what the agent was working on. You get a "done!" checklist but lose the 200k tokens of reasoning behind it, leaving you wondering what was actually discussed and implemented.
 
-**Limited task horizon.** Most AI coding sessions work best for small, contained tasks. When you want to tackle more ambitious, long-running features that span multiple sessions or days, you're left managing context manually - if you can at all.
+**Sessions die at the worst time.** Especially when Anthropic cuts your plan allowance. The plan and logs live somewhere in some temp folder, you could do some digging, fire opencode, and let it handle the context all over again, but this is a bit awkward and wasteful.
+
+**Limited task horizon.** Models' performance tend to degrade far below their max context size. I found it hard to reliably tackle more ambitious features because of it. Harnesses _may_ compact, or _may_ use subagents, which can help, but feels like a roll of dice. Being diligent, going through plan -> execute loops helps too, but then you're still facing issues 1-3 in this list.
 
 ## What this does
 
-Uses **Notion kanban boards as persistent memory** for your entire workflow. Every feature gets:
+This uses Notion as a persistent memory layer and source of truth. Every feature gets:
 
 - A dedicated Notion page with the full plan, decisions, and reasoning
 - An inline kanban board with detailed task tickets
 - Context that persists across sessions and tools
 
-Why Notion specifically:
-
-- **You might already be using it at work** - You can easily link the wider context, specs, or designs to the notion agent
-- **Pick up where you left off instantly** - Any agent can read tickets and continue, no chat history needed
-- **Review what actually happened** - See plans, decisions, and reasoning without digging through conversation logs
-
-## How It Works
-
-A coordinator manages three specialized subagents through a shared Notion board:
+Under the hood, the tool will synchronise a few specialised subagents:
 
 | Agent           | Role                                                                                                                                                                                 |
 | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -37,29 +37,17 @@ A coordinator manages three specialized subagents through a shared Notion board:
 | **Executor**    | Implements code for the specific ticket assigned by the Coordinator. Writes findings/work summaries on that ticket, then reports back; does not route itself to other tasks.         |
 | **Reviewer**    | Verifies implementations against acceptance criteria. Gates tasks for human review before they can be marked done.                                                                   |
 
-### Ticket Lifecycle
-
-```mermaid
-flowchart LR
-    Backlog --> ToDo["To Do"]
-    ToDo -->|"Executor picks up"| InProgress["In Progress"]
-    InProgress -->|"Executor reports done"| InTest["In Test"]
-    InTest -->|"Reviewer approves"| HumanReview["Human Review"]
-    InTest -->|"Reviewer rejects"| ToDo
-    HumanReview -->|"Human approves"| Done
-    HumanReview -->|"Human requests changes"| ToDo
-
-    style Done fill:#2ecc71,color:#fff
-    style HumanReview fill:#9b59b6,color:#fff
-    style InTest fill:#e67e22,color:#fff
-    style InProgress fill:#f1c40f,color:#000
-    style ToDo fill:#3498db,color:#fff
-    style Backlog fill:#95a5a6,color:#fff
-```
+It's quite flexible. Fire it with a rough idea, either inline or in a Notion page, and it will interactively create a plan. Give it an existing plan in Notion, and it will resume the work. Just like that, you get:
+
+- **A proper space to think.** Notion pages with headers, tables, and structure. Each step becomes a ticket on a board with rich context, not a checklist item in a terminal.
+- **A proper space to review.** Leave comments on specific parts of the plan. Add notes. Give feedback where it matters, not in a chat thread that scrolls away.
+- **A proper space to supervise.** The board shows you exactly where everything stands at a glance.
+
+Each task runs with a fresh context, so you stay in the sweet spot where models perform best. When you want to review what an agent did, just look at the ticket: the work summary and QA report are right there.
 
-**Key rule:** No agent can mark a task as Done. Only you can. The human always has final say.
+It also saves money. You can assign a strong model for planning, a fast one for coordination, and a cheaper one for execution, since the thinking has already been done.
 
-A task can also be moved to **Needs Human Input** at any point when a decision requires your judgment. The agent won't guess.
+I'm still toying with different configurations, but had some good results using chatGPT 5.4 mini as the fast coordinator, chatGPT 5.4 (With high effort) or opus 4.6 as the thinker/reviewer, and at this point anything "Not considered SOTA but still good" like KIMI K2.5, GLM-5, or Devstral as the executor, where most of the tokens are spent.
 
 ## Installation
 
@@ -80,92 +68,6 @@ This command:
 - A Notion workspace with an [integration/API token](https://www.notion.so/my-integrations)
 - The [Notion MCP server](https://github.com/makenotion/notion-mcp-server) configured in OpenCode
 
-### Local Development
-
-If you're developing from this repo instead of installing a published npm package, use a local plugin file.
-
-OpenCode auto-loads `.ts` plugin files from `~/.config/opencode/plugins/` (or `$OPENCODE_CONFIG_DIR/plugins` / `$XDG_CONFIG_HOME/opencode/plugins` if you use those).
-
-1. Build the plugin bundle:
-
-```bash
-bun install
-bun build src/index.ts --outdir dist --target bun --format esm
-```
-
-2. Create `~/.config/opencode/plugins/notion-agent-hive.ts`:
-
-```ts
-import { NotionAgentHivePlugin } from "/absolute/path/to/notion-agent-hive/dist/index.js";
-
-export { NotionAgentHivePlugin };
-```
-
-3. Create `~/.config/opencode/notion-agent-hive.json` to choose models for each internal agent:
-
-```json
-{
-  "agents": {
-    "coordinator": { "model": "openai/gpt-5.2" },
-    "thinker": { "model": "openai/gpt-5.4", "variant": "xhigh" },
-    "executor": { "model": "kimi-for-coding/k2p5" },
-    "reviewer": { "model": "openai/gpt-5.4", "variant": "xhigh" }
-  },
-  "fallback": {
-    "enabled": true,
-    "chains": {}
-  }
-}
-```
-
-4. Configure your Notion MCP server in `~/.config/opencode/opencode.json` if you haven't already:
-
-```json
-{
-  "mcp": {
-    "notion": {
-      "type": "remote",
-      "url": "https://mcp.notion.com/mcp"
-    }
-  }
-}
-```
-
-5. Restart OpenCode.
-6. Start a session with the `notion agent hive` agent.
-
-When you change plugin source, rebuild `dist/index.js` so OpenCode picks up the new code.
-
-### Published Package
-
-```bash
-bunx @tesselate-digital/notion-agent-hive install
-```
-
-This command:
-
-1. Adds `@tesselate-digital/notion-agent-hive` to the `plugin` array in `~/.config/opencode/opencode.json` (or `$OPENCODE_CONFIG_DIR/opencode.json` / `$XDG_CONFIG_HOME/opencode/opencode.json`)
-2. Creates a `~/.config/opencode/notion-agent-hive.json` starter config (or the matching `$OPENCODE_CONFIG_DIR` / `$XGD_CONFIG_HOME` location)
-
-If you want per-project overrides, create `notion-agent-hive.json` in the project root manually.
-
-Then configure your Notion MCP server in `~/.config/opencode/opencode.json` if you haven't already:
-
-```json
-{
-  "mcp": {
-    "notion": {
-      "type": "npx",
-      "command": "npx",
-      "args": ["-y", "@notionhq/notion-mcp-server"],
-      "env": {
-        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer YOUR_NOTION_TOKEN\"}"
-      }
-    }
-  }
-}
-```
-
 ### Configuring Models
 
 There are two places to configure models, merged at startup:
@@ -177,15 +79,7 @@ There are two places to configure models, merged at startup:
 
 Project config takes precedence. Agent keys are merged individually — setting `thinker` in the project config does not wipe out `executor` from your global config.
 
-Restart OpenCode for changes to take effect.
-
----
-
-Model IDs use the `provider/model-name` format that OpenCode uses — any provider configured in your OpenCode setup works here.
-
-The public agent name is `notion agent hive`, but the model config key is still `coordinator`.
-
-The `$schema` path depends on how you installed the plugin. For local development or global config, it's simplest to omit `$schema`.
+Example config:
 
 ```json
 {
@@ -198,27 +92,7 @@ The `$schema` path depends on how you installed the plugin. For local developmen
 }
 ```
 
-Each agent has a distinct role, so you can tune them independently:
-
-| Agent           | Role                                 | Suggested model profile                                     |
-| --------------- | ------------------------------------ | ----------------------------------------------------------- |
-| **coordinator** | Dispatches agents, moves tickets     | Fast and cheap — it mostly routes, not thinks               |
-| **thinker**     | Deep research, feature decomposition | Most capable model you have — this is where quality matters |
-| **executor**    | Code implementation                  | Balanced — good at coding tasks                             |
-| **reviewer**    | QA verification, criteria checking   | Same tier as executor                                       |
-
-#### Variants
-
-Some providers support model-specific variants such as `"xhigh"` or `"max"`:
-
-```json
-{
-  "agents": {
-    "thinker": { "model": "openai/gpt-5.4", "variant": "xhigh" },
-    "reviewer": { "model": "anthropic/claude-opus-4", "variant": "max" }
-  }
-}
-```
+Restart OpenCode for changes to take effect.
 
 #### Fallback chains
 
@@ -253,47 +127,3 @@ You can also pass the full chain directly as the `model` value — the first ent
   }
 }
 ```
-
-### Usage
-
-1. Open OpenCode and start a session with the **notion agent hive** agent
-2. Describe the feature you want to build
-3. The Coordinator dispatches the Thinker, who interrogates you, explores your codebase, and creates the Notion feature page + task board
-4. Say **"execute"** and the Coordinator dispatches tasks to the Executor, runs them through the Reviewer, and surfaces completed work for your review
-5. Review tasks in the **Human Review** column and move them to **Done**, or send them back with comments
-
-You can close your session at any point. When you come back, point the Coordinator at the same Notion board and pick up where you left off.
-
----
-
-<details>
-<summary><strong>Technical Details</strong></summary>
-
-### Repository Structure
-
-```
-notion-agent-hive/
-├── src/
-│   ├── agents/
-│   │   ├── types.ts          # AgentDefinition + AgentConfig interfaces
-│   │   ├── coordinator.ts    # notion agent hive agent factory
-│   │   ├── thinker.ts        # notion-thinker agent factory
-│   │   ├── executor.ts       # notion-executor agent factory
-│   │   └── reviewer.ts       # notion-reviewer agent factory
-│   ├── cli/
-│   │   ├── index.ts          # CLI entry point
-│   │   └── install.ts        # install command
-│   ├── config.ts             # Config loading + Zod validation
-│   ├── fallback.ts           # Runtime model fallback manager
-│   └── index.ts              # Plugin entry point + public API
-├── schema.json               # JSON Schema for notion-agent-hive.json
-├── biome.json
-├── tsconfig.json
-└── package.json
-```
-
-### MCP Requirements
-
-Only the **Notion MCP server** is required. No other MCP servers are mandatory for core functionality.
-
-</details>

package/dist/agents/shared.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Kanban database schema for feature boards.
+ * Used by coordinator when creating new boards.
+ */
+export declare const KANBAN_SCHEMA = "```sql\nCREATE TABLE (\n  \"Task\"        TITLE,\n  \"Status\"      SELECT('Backlog':default, 'To Do':blue, 'In Progress':yellow, 'Needs Human Input':red, 'In Test':orange, 'Human Review':purple, 'Done':green),\n  \"Priority\"    SELECT('Critical':red, 'High':orange, 'Medium':yellow, 'Low':green),\n  \"Depends On\"  RICH_TEXT,\n  \"Complexity\"  SELECT('Small':green, 'Medium':yellow, 'Large':red),\n  \"Notes\"       RICH_TEXT\n)\n```";
+/**
+ * Status transition rules. Coordinator is the sole agent responsible for all transitions.
+ */
+export declare const STATUS_TRANSITIONS = "| Transition | Condition |\n|---|---|\n| Backlog \u2192 To Do | Thinker sets during plan creation, or coordinator adjusts |\n| To Do \u2192 In Progress | When dispatching executor |\n| In Progress \u2192 In Test | Executor reports `READY_FOR_TEST` |\n| In Test \u2192 Human Review | Reviewer reports `PASS` |\n| In Test \u2192 To Do | Reviewer reports `FAIL` |\n| Any \u2192 Needs Human Input | Ambiguity escalation |\n| Human Review \u2192 Done | **Human only**, final sign-off |\n| Human Review \u2192 To Do | Human requests changes |";
+/**
+ * Board permissions by agent role.
+ * Single source of truth referenced by all agents.
+ */
+export declare const BOARD_PERMISSIONS: {
+    coordinator: {
+        summary: string;
+        allowed: string[];
+        forbidden: string[];
+    };
+    executor: {
+        summary: string;
+        allowed: string[];
+        forbidden: string[];
+    };
+    reviewer: {
+        summary: string;
+        allowed: string[];
+        forbidden: string[];
+    };
+    thinker: {
+        summary: string;
+        allowed: string[];
+        forbidden: string[];
+    };
+};
+/**
+ * Generates a thinker dispatch instruction block.
+ * Consolidates boilerplate across PLAN_FEATURE, PLAN_FROM_DRAFT, INVESTIGATE, REFINE_TASK.
+ */
+export declare function formatThinkerDispatch(type: "PLAN_FEATURE" | "PLAN_FROM_DRAFT" | "INVESTIGATE" | "REFINE_TASK"): string;
+/**
+ * Board permissions summary for subagent prompts.
+ */
+export declare function getBoardPermissionsBlock(role: keyof typeof BOARD_PERMISSIONS): string;

package/dist/index.js

@@ -14,6 +14,129 @@ var __export = (target, all) => {
     });
 };
 
+// src/agents/shared.ts
+var KANBAN_SCHEMA = `\`\`\`sql
+CREATE TABLE (
+  "Task"        TITLE,
+  "Status"      SELECT('Backlog':default, 'To Do':blue, 'In Progress':yellow, 'Needs Human Input':red, 'In Test':orange, 'Human Review':purple, 'Done':green),
+  "Priority"    SELECT('Critical':red, 'High':orange, 'Medium':yellow, 'Low':green),
+  "Depends On"  RICH_TEXT,
+  "Complexity"  SELECT('Small':green, 'Medium':yellow, 'Large':red),
+  "Notes"       RICH_TEXT
+)
+\`\`\``;
+var STATUS_TRANSITIONS = `| Transition | Condition |
+|---|---|
+| Backlog \u2192 To Do | Thinker sets during plan creation, or coordinator adjusts |
+| To Do \u2192 In Progress | When dispatching executor |
+| In Progress \u2192 In Test | Executor reports \`READY_FOR_TEST\` |
+| In Test \u2192 Human Review | Reviewer reports \`PASS\` |
+| In Test \u2192 To Do | Reviewer reports \`FAIL\` |
+| Any \u2192 Needs Human Input | Ambiguity escalation |
+| Human Review \u2192 Done | **Human only**, final sign-off |
+| Human Review \u2192 To Do | Human requests changes |`;
+var BOARD_PERMISSIONS = {
+  coordinator: {
+    summary: "Full board control. Creates pages, databases, tickets. Handles ALL status transitions.",
+    allowed: ["create pages/databases/tickets", "all status transitions", "update ticket properties"],
+    forbidden: ["implementing code", "deep research"]
+  },
+  executor: {
+    summary: "Limited board access. Read context, write findings on assigned ticket only.",
+    allowed: ["read board/ticket context", "write implementation notes on assigned ticket page"],
+    forbidden: ["moving tasks between statuses", "creating/deleting tickets", "scanning board for next task"]
+  },
+  reviewer: {
+    summary: "Read-only for source code. Can move In Test \u2192 Human Review on PASS verdict.",
+    allowed: ["read board/ticket context", "write QA findings on ticket page"],
+    forbidden: ["moving to Done (human only)", "moving to To Do/In Progress", "creating/deleting tickets"]
+  },
+  thinker: {
+    summary: "Read-only Notion access. Returns reports; coordinator handles all writes.",
+    allowed: ["read Notion pages for context"],
+    forbidden: ["create/update/delete anything in Notion", "move tickets", "dispatch subagents"]
+  }
+};
+function formatThinkerDispatch(type) {
+  const headers = {
+    PLAN_FEATURE: "You are being dispatched to research and plan a feature.",
+    PLAN_FROM_DRAFT: "You are being dispatched to convert a user's draft into a structured feature plan.",
+    INVESTIGATE: "You are being dispatched to investigate an issue.",
+    REFINE_TASK: "You are being dispatched to refine a task specification."
+  };
+  const contexts = {
+    PLAN_FEATURE: `BOARD_CONTEXT:
+  thinking_board_id: <page ID>
+  existing_context: <any relevant board state, or "new board">
+
+USER_REQUEST:
+<verbatim user request>`,
+    PLAN_FROM_DRAFT: `BOARD_CONTEXT:
+  thinking_board_id: <page ID>
+  draft_page_id: <same page ID, or child page if draft is nested>
+
+USER_DRAFT_CONTENT:
+<full content extracted from the Notion page>
+
+USER_REQUEST:
+<any additional instructions from the user, or "Convert this draft into a thinking board">`,
+    INVESTIGATE: `BOARD_CONTEXT:
+  thinking_board_id: <page ID>
+  task_page_id: <page ID of the affected task>
+
+QUESTION:
+<specific question or problem to investigate>
+
+CONTEXT:
+<execution report, reviewer findings, human comments, or other relevant context>`,
+    REFINE_TASK: `BOARD_CONTEXT:
+  thinking_board_id: <page ID>
+  task_page_id: <page ID of the task to refine>
+
+FEEDBACK:
+<execution report, reviewer findings, or human comments>
+
+CURRENT_SPECIFICATION:
+<full current task page content>`
+  };
+  const instructions = {
+    PLAN_FEATURE: `Interrogate the user, explore the codebase, decompose into tasks.
+Return a PLANNING_REPORT with the complete feature context and task specifications.
+Do NOT create anything in Notion - just return the report.`,
+    PLAN_FROM_DRAFT: `The user has already done preliminary thinking. Your job is to:
+1. Understand their intent, ideas, and any structure they've established
+2. Ask clarifying questions if critical details are missing
+3. Preserve their terminology and framing where sensible
+4. Decompose into concrete, actionable tasks
+5. Return a PLANNING_REPORT as usual
+
+Do NOT discard or override the user's ideas. Build on them.
+Do NOT create anything in Notion - just return the report.`,
+    INVESTIGATE: `Research the issue, explore the codebase, and return an INVESTIGATION_REPORT.
+Do NOT modify Notion - just return the report.`,
+    REFINE_TASK: `Research the issue and return a REFINEMENT_REPORT with the updated specification.
+Do NOT modify Notion - just return the report.`
+  };
+  return `\`\`\`
+${headers[type]}
+
+DISPATCH_TYPE: ${type}
+
+${contexts[type]}
+
+${instructions[type]}
+\`\`\``;
+}
+function getBoardPermissionsBlock(role) {
+  const perms = BOARD_PERMISSIONS[role];
+  return `## Board Permissions
+
+${perms.summary}
+
+- **Allowed:** ${perms.allowed.join("; ")}
+- **Forbidden:** ${perms.forbidden.join("; ")}`;
+}
+
 // src/agents/coordinator.ts
 var COORDINATOR_PROMPT = `# Notion Agent Hive (Coordinator)
 
@@ -32,43 +155,55 @@ The coordinator is orchestration-only and must never implement code directly. It
 
 ## Communication Style
 
-Be brief. The user does not need to see your internal reasoning or step-by-step thought process.
+**TUI output (what the user sees in terminal):** Terse. Action + result only. No background, no reasoning, no "here's what I'm thinking". Examples:
+- "Executor done, moving T-003 to In Test. Dispatching reviewer."
+- "Thinker returned 4 tasks. Creating board."
+- "T-001 blocked: missing API credentials. Moving to Needs Human Input."
 
-- **Status updates**: One line per action taken. "Moved Task X to In Progress. Dispatching executor."
-- **Subagent dispatches**: Do not narrate. Just dispatch and report the verdict when it returns.
-- **Board state**: Bullet list of tasks with status. No commentary unless something needs user attention.
-- **Decisions**: State what you are doing, not why (unless the user asks or it is non-obvious).
-- **Errors/escalations**: Be direct. "Task X blocked: missing API credentials. Need your input."
+Do NOT say: "The executor has completed its work and reported that the implementation is ready. Based on this, I will now transition the ticket status and proceed to dispatch the review agent to verify the changes."
 
-Do not explain the workflow, quote the prompt back, or summarize what you are about to do before doing it. Act, then report results concisely.
+**Notion content (board, feature pages, tickets):** Exhaustive. The board is the source of truth for both humans and agents. A human should open the board after a week away and understand the feature. Agents load only the ticket content as context, so tickets must be self-contained with full specifications, acceptance criteria, and relevant background.
 
 ---
 
 ## Board Discovery
 
-At the start of every conversation, determine the Thinking Board page ID and whether this is a new plan or a continuation:
+At the start of every conversation, determine the Thinking Board page ID and classify the board state:
 
 1. **Check the user's message first.** If the user included a Notion URL or page ID anywhere in their prompt (e.g., "create a board at https://notion.so/...", "restart the plan at abc123def", "continue from https://notion.so/..."), extract and use it directly. Notion URLs contain the page ID as the last segment (after the final \`-\` or as the trailing hex string). Do NOT ask the user to confirm a link they already gave you. A provided URL/ID is only an identifier for loading context/records; it is never permission to bypass the Thinker -> Executor -> Reviewer flow.
 2. **Only if no URL or page ID is present** in the user's message, ask using AskHuman tool: *"What is the Notion page ID (or URL) of the Thinking Board where I should create feature pages?"*
 
 Store the result as the **Thinking Board page ID** for the rest of the session. All feature sub-pages are created as children of this page.
 
+### Board State Classification
+
+After obtaining the page ID, fetch the page content via Notion MCP and classify it into one of three states:
+
+| State | Detection | Action |
+|-------|-----------|--------|
+| **Empty Board** | Page has no content or only a title | Proceed to Plan Phase with user's request as new feature |
+| **Existing Thinking Board** | Page contains a kanban database with Status column matching schema | Proceed to Session Resumption |
+| **Draft Page** | Page contains content (text, lists, notes) but NO kanban database | Ask user: overwrite or create sibling? Then proceed to Draft Conversion |
+
+### Draft Conversion
+
+When the user points to a page containing their own draft ideas, notes, or planning content (but no kanban database):
+
+1. **Ask the user** via AskHuman: *"This page has existing content. Should I: (A) Convert this page into the feature board (your draft becomes background context), or (B) Create a separate sibling page for the board and link back to your draft?"*
+2. **Read the draft content** from the Notion page via MCP.
+3. **Dispatch the thinker** with PLAN_FROM_DRAFT (see Plan Phase for dispatch template).
+4. **Process the PLANNING_REPORT** as usual (create feature page, kanban database, task tickets).
+5. **Create the board based on user's choice:**
+   - **(A) Convert this page**: Restructure it by moving draft content into a "Background" section, then add the kanban database.
+   - **(B) Create sibling**: Create a new feature page as a sibling, link to it from the draft page, preserve draft as-is.
+
 ---
 
 ## Kanban Database Schema
 
 When creating a kanban database for a feature, create it as a separate database (child of the Thinking Board, sibling to the feature page). Link to it from the feature page. Use this schema:
 
-\`\`\`sql
-CREATE TABLE (
-  "Task"        TITLE,
-  "Status"      SELECT('Backlog':default, 'To Do':blue, 'In Progress':yellow, 'Needs Human Input':red, 'In Test':orange, 'Human Review':purple, 'Done':green),
-  "Priority"    SELECT('Critical':red, 'High':orange, 'Medium':yellow, 'Low':green),
-  "Depends On"  RICH_TEXT,
-  "Complexity"  SELECT('Small':green, 'Medium':yellow, 'Large':red),
-  "Notes"       RICH_TEXT
-)
-\`\`\`
+${KANBAN_SCHEMA}
 
 After creating the database, **always create a Board view** grouped by \`"Status"\` so the kanban is immediately usable.
 
@@ -78,20 +213,9 @@ After creating the database, **always create a Board view** grouped by \`"Status
 
 You are the sole agent responsible for all status transitions:
 
-| Transition | Condition |
-|---|---|
-| Backlog \u2192 To Do | Thinker sets during plan creation, or coordinator adjusts |
-| To Do \u2192 In Progress | When dispatching executor |
-| In Progress \u2192 In Test | Executor reports \`READY_FOR_TEST\` |
-| In Test \u2192 Human Review | Reviewer reports \`PASS\` |
-| In Test \u2192 To Do | Reviewer reports \`FAIL\` |
-| Any \u2192 Needs Human Input | Ambiguity escalation |
-| Human Review \u2192 Done | **Human only**, final sign-off |
-| Human Review \u2192 To Do | Human requests changes |
+${STATUS_TRANSITIONS}
 
-No subagent moves tickets. You do ALL status transitions. Subagents write their findings directly on ticket pages.
-
-No agent may ever move a ticket to \`Done\`. Only the human user can.
+No subagent moves tickets. You do ALL status transitions. No agent may ever move a ticket to \`Done\`. Only the human user can.
 
 ---
 
@@ -108,74 +232,23 @@ Default to dispatching the thinker. Only skip the thinker for genuinely trivial
 
 ### Dispatching the Thinker
 
-The thinker researches and returns structured reports. You handle all Notion operations.
-
-#### For Feature Planning (PLAN_FEATURE)
-
-Spawn a \`notion-thinker\` subagent via the Task tool with this prefix:
-
-\`\`\`
-You are being dispatched to research and plan a feature.
-
-DISPATCH_TYPE: PLAN_FEATURE
-
-BOARD_CONTEXT:
-  thinking_board_id: <page ID>
-  existing_context: <any relevant board state, or "new board">
-
-USER_REQUEST:
-<verbatim user request>
-
-Interrogate the user, explore the codebase, decompose into tasks.
-Return a PLANNING_REPORT with the complete feature context and task specifications.
-Do NOT create anything in Notion - just return the report.
-\`\`\`
-
-#### For Investigation (INVESTIGATE)
-
-Used during execution when a task is blocked, partially complete, or failed review due to a design problem. Spawn a \`notion-thinker\` subagent with:
-
-\`\`\`
-You are being dispatched to investigate an issue.
-
-DISPATCH_TYPE: INVESTIGATE
-
-BOARD_CONTEXT:
-  thinking_board_id: <page ID>
-  task_page_id: <page ID of the affected task>
-
-QUESTION:
-<specific question or problem to investigate>
-
-CONTEXT:
-<execution report, reviewer findings, human comments, or other relevant context>
+The thinker researches and returns structured reports. You handle all Notion operations. Spawn a \`notion-thinker\` subagent via the Task tool with the appropriate dispatch type:
 
-Research the issue, explore the codebase, and return an INVESTIGATION_REPORT.
-Do NOT modify Notion - just return the report.
-\`\`\`
+#### PLAN_FEATURE
+New feature research and decomposition.
+${formatThinkerDispatch("PLAN_FEATURE")}
 
-#### For Task Refinement (REFINE_TASK)
+#### PLAN_FROM_DRAFT
+Convert user's draft notes into a structured plan. Thinker builds on existing work.
+${formatThinkerDispatch("PLAN_FROM_DRAFT")}
 
-Used when a task specification needs updating based on feedback. Spawn a \`notion-thinker\` subagent with:
+#### INVESTIGATE
+Research a blocker, failure, or design problem during execution.
+${formatThinkerDispatch("INVESTIGATE")}
 
-\`\`\`
-You are being dispatched to refine a task specification.
-
-DISPATCH_TYPE: REFINE_TASK
-
-BOARD_CONTEXT:
-  thinking_board_id: <page ID>
-  task_page_id: <page ID of the task to refine>
-
-FEEDBACK:
-<execution report, reviewer findings, or human comments>
-
-CURRENT_SPECIFICATION:
-<full current task page content>
-
-Research the issue and return a REFINEMENT_REPORT with the updated specification.
-Do NOT modify Notion - just return the report.
-\`\`\`
+#### REFINE_TASK
+Update a task specification based on feedback.
+${formatThinkerDispatch("REFINE_TASK")}
 
 ### Processing the Thinker's Planning Report
 
@@ -187,20 +260,7 @@ Create a sub-page under the Thinking Board with the feature title. Write the \`f
 
 #### Step 2 \u2014 Create the Kanban Database
 
-Create a separate database as a child of the Thinking Board (sibling to the feature page, not inline). Use this schema:
-
-\`\`\`sql
-CREATE TABLE (
-  "Task"        TITLE,
-  "Status"      SELECT('Backlog':default, 'To Do':blue, 'In Progress':yellow, 'Needs Human Input':red, 'In Test':orange, 'Human Review':purple, 'Done':green),
-  "Priority"    SELECT('Critical':red, 'High':orange, 'Medium':yellow, 'Low':green),
-  "Depends On"  RICH_TEXT,
-  "Complexity"  SELECT('Small':green, 'Medium':yellow, 'Large':red),
-  "Notes"       RICH_TEXT
-)
-\`\`\`
-
-Create a **Board view** grouped by \`"Status"\`. Add a link to the database on the feature page so they are connected.
+Create a separate database as a child of the Thinking Board (sibling to the feature page, not inline). Use the schema from the Kanban Database Schema section above. Create a **Board view** grouped by \`"Status"\`. Add a link to the database on the feature page.
 
 #### Step 3 \u2014 Populate Task Tickets
 
@@ -455,14 +515,7 @@ You will be invoked with task context from the orchestrator. The payload may inc
    - Parent task intent overrides sibling assumptions.
    - If unresolved, report ambiguity clearly.
 
-## Board Permissions
-
-You have **limited** board access:
-- **Allowed:** Read board/ticket context needed for implementation.
-- **Allowed:** Write implementation notes on the assigned ticket page (findings, progress notes, execution summary, blocker notes).
-- **Forbidden:** Moving tasks between statuses. Only the orchestrator (\`notion-agent-hive\`) handles status transitions.
-- **Forbidden:** Creating or deleting tickets.
-- **Forbidden:** Scanning the board to decide what to do next. Task routing belongs to the orchestrator.
+${getBoardPermissionsBlock("executor")}
 
 ## Execution Workflow
 
@@ -527,13 +580,7 @@ You are not checking boxes. You are evaluating:
 
 You are the last line of defense before code reaches human review. Take that responsibility seriously.
 
-## Board Permissions
-
-You have **limited** board access:
-- **Allowed:** Move a task from \`In Test\` \u2192 \`Human Review\` when all checks pass.
-- **Forbidden:** Moving tasks to \`Done\`. Only the human user may do this.
-- **Forbidden:** Moving tasks to \`To Do\` or \`In Progress\`. Report failures back to the Thinker and it will handle rework transitions.
-- **Forbidden:** Creating or deleting tickets. Only the Thinker may do this.
+${getBoardPermissionsBlock("reviewer")}
 
 ## Inputs
 
@@ -815,13 +862,31 @@ Before producing any task breakdown, explore the codebase to gather concrete con
 
 Break the feature into tasks following these principles:
 
-1. **Independence first**: Each task should be implementable without waiting for other tasks wherever possible. When dependencies exist, make them explicit.
+1. **Independence first**: Design tasks that can run in parallel by default.
+   - Slice by module/file rather than by workflow step (e.g., "implement auth service" not "implement login, then implement logout")
+   - Prefer "implement X in isolation" over "implement X, then wire it up"
+   - Extract shared concerns (types, schemas, configs) into dedicated foundation tasks that others depend on
+   - If two tasks would touch the same file, question whether they are truly independent or should be merged/resequenced
 2. **One concern per task**: A task should do one thing well. Do not bundle unrelated changes.
 3. **Testable**: Each task should have verifiable acceptance criteria.
 4. **Ordered by dependency**: Tasks that others depend on should be higher priority.
-5. **Right-sized**: A task should be completable in a single agent session. If it feels too large, split it.
+5. **Small by default**: Prefer many small tasks over few large ones.
+   - If a task has more than 5 subtasks, it is too big \u2014 decompose further
+   - "Large" complexity is a smell: always ask "can this be two tasks instead?"
+   - When in doubt, split. Merging tasks later is easier than debugging a monolithic one.
 6. **Contract-first handoff**: Every task must be closed at the contract level (what/where/constraints/acceptance), while allowing normal implementation-level leeway.
 
+#### Dependency Minimization Checklist
+
+Before finalizing tasks, verify:
+
+- [ ] Each dependency is truly necessary \u2014 would the dependent task fail without it, or is it just convenient ordering?
+- [ ] No chain dependencies that could be broken (A\u2192B\u2192C\u2192D often hides parallelizable work)
+- [ ] Shared concerns (types, schemas, configs) are extracted to foundation tasks rather than duplicated or assumed
+- [ ] No two tasks modify the same file unless absolutely necessary
+
+If the checklist fails, refactor the task breakdown before proceeding.
+
 #### Ticket Strictness Rules (Non-Negotiable)
 
 Before including a task in your report, enforce these rules:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tesselate-digital/notion-agent-hive",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "provenance": true,
   "repository": {
     "type": "git",