feed-the-machine 1.0.0

package/ftm-mind/references/event-registry.md

@@ -0,0 +1,299 @@
+# FTM Event Registry
+
+This document defines the full event vocabulary for the ftm skill system. The mind reads this during its Decide phase to determine which skills to trigger after any action completes.
+
+---
+
+## How to Read This Document
+
+Each event entry uses the following format:
+
+```markdown
+### event_name
+- **Description**: What this event means
+- **Emitted by**: [list of skills]
+- **Listened to by**: [list of skills]
+- **Fast-path**: yes/no (fast-path events bypass mind mediation and always trigger their listeners)
+- **Payload**: {key fields the event carries}
+```
+
+**Fast-path events** are always triggered immediately — the mind does not evaluate whether to route them. Use fast-path for events where the downstream response is unconditional and latency matters (documentation sync, micro-reflections).
+
+**Mediated events** pass through the mind's Decide phase. The mind evaluates context and decides whether to trigger listeners, which listener to prefer, and whether to combine multiple events before acting.
+
+---
+
+## How to Add an Event Declaration to a Skill
+
+When adding event declarations to a skill's SKILL.md, insert an `## Events` section AFTER the YAML frontmatter block and BEFORE the first major heading of existing content. Do NOT modify any other content.
+
+Use this exact format:
+
+```markdown
+## Events
+
+### Emits
+- `event_name` — when [the condition that causes this skill to emit the event]
+
+### Listens To
+- `event_name` — [what this skill does in response when this event fires]
+```
+
+Guidelines for writing clear declarations:
+- Emit conditions should describe the specific moment the event fires, not the entire skill workflow. Example: "when a git commit is made" not "during execution".
+- Listen-to descriptions should describe the triggered action, not the full response workflow. Example: "auto-investigate the failure" not "launch Phase 1 agents".
+- Use backtick-quoted event names consistently.
+- One bullet per event. If a skill emits the same event under multiple conditions, combine them into one bullet with "or" — e.g., "when the test suite passes, or when a post-fix verification succeeds".
+
+---
+
+## Full Event Vocabulary
+
+### task_received
+- **Description**: A new task has entered the system and is acknowledged by the executor
+- **Emitted by**: ftm-executor
+- **Listened to by**: ftm-mind (log task arrival, initialize tracking context), ftm-brainstorm (begin ideation work when mind routes an incoming task for exploration)
+- **Fast-path**: no
+- **Payload**: `{ task_description, plan_path, wave_number, task_number }`
+
+---
+
+### plan_generated
+- **Description**: A plan document was created and is ready for review or execution
+- **Emitted by**: ftm-executor, ftm-brainstorm
+- **Listened to by**: ftm-mind (surface plan to user, optionally trigger ftm-audit pre-flight)
+- **Fast-path**: no
+- **Payload**: `{ plan_path, plan_title, task_count, wave_count }`
+
+---
+
+### research_complete
+- **Description**: ftm-researcher finished its synthesis pipeline and structured output is ready for consumption
+- **Emitted by**: ftm-researcher
+- **Listened to by**: ftm-brainstorm (consume findings for current research sprint), ftm-mind (log research session on blackboard, optionally surface to user)
+- **Fast-path**: no
+- **Payload**: `{ query, mode, findings_count, consensus_count, contested_count, unique_count, sources_count, council_used, duration_ms }`
+
+---
+
+### plan_approved
+- **Description**: The user has approved a plan for execution
+- **Emitted by**: ftm-executor (after user confirmation)
+- **Listened to by**: ftm-executor (begin Phase 3 worktree setup and agent dispatch)
+- **Fast-path**: no
+- **Payload**: `{ plan_path, plan_title, approved_by, timestamp }`
+
+---
+
+### code_changed
+- **Description**: One or more files were modified — pre-commit state, changes not yet persisted to git history
+- **Emitted by**: ftm-executor
+- **Listened to by**: ftm-mind (record in blackboard, may trigger pre-commit checks)
+- **Fast-path**: no
+- **Payload**: `{ files_changed: [path], task_number, agent_name, worktree_path }`
+
+---
+
+### code_committed
+- **Description**: A git commit was successfully made — changes are persisted to the repository
+- **Emitted by**: ftm-executor
+- **Listened to by**: ftm-intent (update INTENT.md entries for changed functions), ftm-diagram (update DIAGRAM.mmd nodes and edges for changed modules), ftm-codex-gate (run adversarial validation at wave boundaries after commits land)
+- **Fast-path**: yes — documentation must always stay in sync with commits, no mind mediation needed
+- **Payload**: `{ commit_hash, commit_message, files_changed: [path], worktree_path, task_number }`
+
+---
+
+### map_updated
+- **Description**: The code knowledge graph has been updated — either from a full bootstrap scan or an incremental re-index of changed files
+- **Emitted by**: ftm-map
+- **Listened to by**: ftm-mind (log on blackboard, update session context with latest graph stats), ftm-intent (trigger INTENT.md regeneration from graph), ftm-diagram (trigger DIAGRAM.mmd regeneration from graph)
+- **Fast-path**: yes — downstream view generation should happen immediately without mind mediation
+- **Payload**: `{ project_path, symbols_count, edges_count, files_parsed, duration_ms, mode: "bootstrap" | "incremental" }`
+
+---
+
+### test_passed
+- **Description**: The test suite (or a targeted subset) ran and all tests passed
+- **Emitted by**: ftm-executor, ftm-debug
+- **Listened to by**: ftm-mind (update task status, potentially unblock next wave)
+- **Fast-path**: no
+- **Payload**: `{ test_runner, test_count, duration_ms, scope: "full_suite" | "task_scope", task_number }`
+
+---
+
+### test_failed
+- **Description**: The test suite ran and one or more tests failed
+- **Emitted by**: ftm-executor, ftm-debug
+- **Listened to by**: ftm-debug (auto-investigate the failure), ftm-mind (block wave advancement, update task status)
+- **Fast-path**: no
+- **Payload**: `{ test_runner, failed_tests: [{ name, file, error }], total_count, failed_count, task_number }`
+
+---
+
+### bug_fixed
+- **Description**: A specific bug was identified, a fix was applied, and the Reviewer agent approved the fix
+- **Emitted by**: ftm-debug
+- **Listened to by**: ftm-retro (record the fix as a success experience), ftm-mind (update task status, unblock dependents)
+- **Fast-path**: no
+- **Payload**: `{ bug_description, root_cause, files_changed: [path], fix_commits: [hash], reviewer_verdict }`
+
+---
+
+### audit_complete
+- **Description**: ftm-audit finished its full analysis (all three layers) for a given scope
+- **Emitted by**: ftm-audit
+- **Listened to by**: ftm-executor (interpret results: mark task complete, queue auto-fix, or hold for manual review), ftm-mind (update audit record on blackboard)
+- **Fast-path**: no
+- **Payload**: `{ scope: [path], findings_count, auto_fixed_count, manual_required_count, final_status: "PASS" | "FAIL", changelog_path }`
+
+---
+
+### issue_found
+- **Description**: A problem was discovered — by ftm-audit static analysis, by adversarial audit, or by ftm-debug investigation
+- **Emitted by**: ftm-audit, ftm-debug, ftm-codex-gate
+- **Listened to by**: ftm-mind (log the issue, decide whether to surface to user or auto-route to fix)
+- **Fast-path**: no
+- **Payload**: `{ issue_type, file_path, line_hint, description, severity: "error" | "warning", source: "knip" | "adversarial" | "debug", auto_fixable: boolean }`
+
+---
+
+### documentation_updated
+- **Description**: INTENT.md or a DIAGRAM.mmd file was updated to reflect new or changed code
+- **Emitted by**: ftm-intent, ftm-diagram
+- **Listened to by**: ftm-mind (record documentation sync on blackboard, reset the "docs behind" flag for the affected module)
+- **Fast-path**: no
+- **Payload**: `{ file_path, module_name, update_type: "intent" | "diagram", changed_entries: [string] }`
+
+---
+
+### review_complete
+- **Description**: A code review or audit review finished and produced a verdict
+- **Emitted by**: ftm-audit (after adversarial layer), ftm-debug (after Reviewer agent), ftm-council (after majority verdict or 5-round synthesis), ftm-codex-gate (after Codex analysis completes)
+- **Listened to by**: ftm-audit (validate review findings match static analysis), ftm-mind (update review status on blackboard)
+- **Fast-path**: no
+- **Payload**: `{ verdict: "APPROVED" | "APPROVED_WITH_CHANGES" | "NEEDS_REWORK", reviewer, findings: [string], task_number }`
+
+---
+
+### task_completed
+- **Description**: A task finished — including passing all verification gates (tests, audit, Codex gate)
+- **Emitted by**: ftm-executor, ftm-debug, ftm-audit, ftm-retro, ftm-brainstorm, ftm-council, ftm-codex-gate, ftm-intent, ftm-diagram, ftm-browse, ftm-pause, ftm-resume, ftm-upgrade, ftm-config, ftm-researcher
+- **Listened to by**: ftm-retro (micro-reflection trigger — record the task outcome as an experience), ftm-mind (advance wave state, check if all tasks in wave are done)
+- **Fast-path**: yes — micro-reflection runs on every task completion unconditionally; no mind mediation needed
+- **Payload**: `{ task_number, task_title, plan_path, wave_number, duration_ms, audit_result, agent_name }`
+
+---
+
+### error_encountered
+- **Description**: An unexpected error occurred during execution that was not part of a normal test failure
+- **Emitted by**: ftm-executor, ftm-debug
+- **Listened to by**: ftm-debug (diagnose the error), ftm-retro (record as a failure experience for pattern learning), ftm-mind (halt or reroute depending on severity)
+- **Fast-path**: no
+- **Payload**: `{ error_message, stack_trace, phase, task_number, skill: "ftm-executor" | "ftm-debug", recoverable: boolean }`
+
+---
+
+### session_paused
+- **Description**: The session state was serialized and saved — the user is ending the session but wants to resume later
+- **Emitted by**: ftm-pause (dedicated pause skill)
+- **Listened to by**: ftm-mind (write final blackboard snapshot, record open tasks and current wave state)
+- **Fast-path**: no
+- **Payload**: `{ session_id, plan_path, current_wave, open_tasks: [number], blackboard_snapshot_path, timestamp }`
+
+---
+
+### session_resumed
+- **Description**: A previously paused session state was restored and execution is continuing
+- **Emitted by**: ftm-resume (dedicated resume skill)
+- **Listened to by**: ftm-executor (restore wave state and re-dispatch open tasks), ftm-mind (reload blackboard snapshot)
+- **Fast-path**: no
+- **Payload**: `{ session_id, plan_path, restored_wave, open_tasks: [number], blackboard_snapshot_path, timestamp }`
+
+---
+
+### experience_recorded
+- **Description**: A new experience entry (task outcome, fix attempt, blocker) was written to the blackboard's experience log
+- **Emitted by**: ftm-retro
+- **Listened to by**: ftm-mind (evaluate whether the experience reveals a new pattern to promote)
+- **Fast-path**: no
+- **Payload**: `{ experience_type: "success" | "failure" | "fix" | "blocker", description, task_number, plan_slug, timestamp }`
+
+---
+
+### pattern_discovered
+- **Description**: A recurring pattern was identified from accumulated experiences and promoted to the patterns.json library
+- **Emitted by**: ftm-retro
+- **Listened to by**: ftm-mind (index the new pattern so it can inform future Decide-phase routing), ftm-executor (optionally: adjust agent prompts if pattern is execution-relevant)
+- **Fast-path**: no
+- **Payload**: `{ pattern_name, pattern_description, first_seen_retro, occurrence_count, suggested_action, patterns_file_path }`
+
+---
+
+### secrets_found
+- **Description**: ftm-git scan detected hardcoded credentials in staged files or the working tree — commit/push is blocked until remediation completes
+- **Emitted by**: ftm-git
+- **Listened to by**: ftm-executor (pause commit/push, await remediation), ftm-mind (record security finding on blackboard)
+- **Fast-path**: no
+- **Payload**: `{ findings: [{ file_path, line_number, secret_type, severity }], scan_scope: "staged" | "working_tree" | "history", task_number }`
+
+---
+
+### secrets_clear
+- **Description**: ftm-git scan completed with no findings — the commit or push is safe to proceed
+- **Emitted by**: ftm-git
+- **Listened to by**: ftm-executor (unblock pending commit/push operation), ftm-mind (record clean scan on blackboard)
+- **Fast-path**: no
+- **Payload**: `{ files_scanned: number, scan_scope: "staged" | "working_tree" | "history", task_number }`
+
+---
+
+### secrets_remediated
+- **Description**: ftm-git auto-fix successfully extracted secrets to .env and refactored source files — a re-scan confirmed no remaining findings
+- **Emitted by**: ftm-git
+- **Listened to by**: ftm-executor (unblock commit/push now that secrets are extracted), ftm-mind (record remediation action on blackboard)
+- **Fast-path**: no
+- **Payload**: `{ secrets_extracted: number, files_refactored: [path], env_vars_added: [string], task_number }`
+
+---
+
+## Fast-Path Summary
+
+| Event | Always triggers |
+|---|---|
+| `code_committed` | ftm-intent (INTENT.md sync), ftm-diagram (DIAGRAM.mmd sync) |
+| `task_completed` | ftm-retro (micro-reflection / experience recording) |
+| `map_updated` | ftm-intent (INTENT.md regeneration), ftm-diagram (DIAGRAM.mmd regeneration) |
+
+All other events are mediated by the mind's Decide phase.
+
+---
+
+## Event Routing Reference
+
+Use this table to quickly look up which skills are involved when an event fires:
+
+| Event | Emitters | Listeners |
+|---|---|---|
+| task_received | executor | mind, brainstorm |
+| plan_generated | executor, brainstorm | mind |
+| research_complete | researcher | brainstorm, mind |
+| plan_approved | executor | executor |
+| code_changed | executor | mind |
+| code_committed | executor | intent, diagram, codex-gate |
+| test_passed | executor, debug | mind |
+| test_failed | executor, debug | debug, mind |
+| bug_fixed | debug | retro, mind |
+| audit_complete | audit | executor, mind |
+| issue_found | audit, debug, codex-gate | mind |
+| documentation_updated | intent, diagram | mind |
+| review_complete | audit, debug, council, codex-gate | audit, mind |
+| task_completed | executor, debug, audit, retro, brainstorm, council, codex-gate, intent, diagram, browse, pause, resume, upgrade, config, researcher | retro, mind |
+| error_encountered | executor, debug | debug, retro, mind |
+| session_paused | pause | mind |
+| session_resumed | resume | executor, mind |
+| experience_recorded | retro | mind |
+| pattern_discovered | retro | mind, executor |
+| secrets_found | git | executor, mind |
+| secrets_clear | git | executor, mind |
+| secrets_remediated | git | executor, mind |
+| map_updated | map | mind, intent, diagram |

package/ftm-mind/references/mcp-inventory.md

@@ -0,0 +1,296 @@
+# MCP Capability Inventory
+**Purpose**: Orient-phase reference. Scan input → match domain keywords → select MCP → check approval gate.
+
+---
+
+## 1. Server Catalog
+
+### Development
+
+#### `git`
+| Field | Detail |
+|-------|--------|
+| **Tools** | `git_status`, `git_diff`, `git_diff_staged`, `git_diff_unstaged`, `git_log`, `git_show`, `git_add`, `git_commit`, `git_checkout`, `git_create_branch`, `git_branch`, `git_reset` |
+| **When to use** | Checking repo state, reviewing changes, branching, committing, exploring history |
+| **When NOT to use** | Detached HEAD state (orphaned commits risk); force-push to main |
+| **Approval required** | Auto: `status`, `diff`, `log`, `show`, `branch` (read). Needs approval: `commit`, `push`, `reset`, `checkout` (destructive or state-changing) |
+
+#### `playwright`
+| Field | Detail |
+|-------|--------|
+| **Tools** | `browser_navigate`, `browser_click`, `browser_fill_form`, `browser_type`, `browser_snapshot`, `browser_take_screenshot`, `browser_select_option`, `browser_press_key`, `browser_wait_for`, `browser_evaluate`, `browser_console_messages`, `browser_network_requests`, `browser_tabs`, `browser_close`, `browser_drag`, `browser_hover`, `browser_file_upload`, `browser_handle_dialog`, `browser_resize`, `browser_run_code`, `browser_install` |
+| **When to use** | E2E testing, visual verification, UI interaction testing, scraping pages that require JS |
+| **When NOT to use** | Headless server environments; when a REST API exists for the same data; anti-bot risk |
+| **Approval required** | Auto: `snapshot`, `screenshot`, `console_messages` (read). Needs approval: form submissions, file uploads, any write-through-browser action |
+
+#### `sequential-thinking`
+| Field | Detail |
+|-------|--------|
+| **Tools** | `sequentialthinking` |
+| **When to use** | Multi-step reasoning, architecture decisions, complex debugging chains, trade-off analysis |
+| **When NOT to use** | Simple single-step lookups — adds latency and token cost without benefit |
+| **Approval required** | Auto: analysis only, no side effects |
+
+#### `chrome-devtools`
+| Field | Detail |
+|-------|--------|
+| **Tools** | Chrome DevTools Protocol bridge tools |
+| **When to use** | Low-level browser debugging, network inspection, performance profiling of a running Chrome instance |
+| **When NOT to use** | General web browsing; prefer `playwright` for test automation |
+| **Approval required** | Auto: inspection. Needs approval: any action that modifies browser state or page |
+
+---
+
+### Communication
+
+#### `slack`
+| Field | Detail |
+|-------|--------|
+| **Tools** | `slack_list_channels`, `slack_get_channel_history`, `slack_get_thread_replies`, `slack_post_message`, `slack_reply_to_thread`, `slack_get_users`, `slack_get_user_profile`, `slack_add_reaction` |
+| **When to use** | Notifying team, posting updates, searching conversation history, replying to threads |
+| **When NOT to use** | Sending sensitive credentials or PII; bulk messaging that looks like spam |
+| **Approval required** | Auto: `list_channels`, `get_channel_history`, `get_thread_replies`, `get_users`, `get_user_profile` (read). Needs approval: `post_message`, `reply_to_thread`, `add_reaction` (write to Slack) |
+
+#### `gmail`
+| Field | Detail |
+|-------|--------|
+| **Tools** | `search_emails`, `read_email`, `draft_email`, `send_email`, `delete_email`, `modify_email`, `batch_modify_emails`, `batch_delete_emails`, `create_label`, `update_label`, `delete_label`, `list_email_labels`, `create_filter`, `create_filter_from_template`, `get_filter`, `list_filters`, `delete_filter`, `get_or_create_label`, `download_attachment` |
+| **When to use** | Email triage, searching inbox, drafting replies, managing labels/filters |
+| **When NOT to use** | Bulk delete without confirmation; sending on behalf of user without explicit approval |
+| **Approval required** | Auto: `search_emails`, `read_email`, `list_email_labels`, `get_filter`, `list_filters` (read). Needs approval: `send_email`, `delete_email`, `batch_delete_emails`, `batch_modify_emails`, `create_filter` (write/destructive) |
+
+---
+
+### Project Management
+
+#### `mcp-atlassian-personal` (personal Jira + Confluence account)
+| Field | Detail |
+|-------|--------|
+| **Tools** | Jira: `jira_search`, `jira_get_issue`, `jira_create_issue`, `jira_update_issue`, `jira_delete_issue`, `jira_transition_issue`, `jira_add_comment`, `jira_edit_comment`, `jira_get_transitions`, `jira_get_all_projects`, `jira_get_project_issues`, `jira_get_board_issues`, `jira_get_sprint_issues`, `jira_get_sprints_from_board`, `jira_get_agile_boards`, `jira_create_sprint`, `jira_update_sprint`, `jira_add_issues_to_sprint`, `jira_batch_create_issues`, `jira_create_issue_link`, `jira_remove_issue_link`, `jira_get_link_types`, `jira_add_worklog`, `jira_get_worklog`, `jira_add_watcher`, `jira_remove_watcher`, `jira_get_issue_watchers`, `jira_get_user_profile`, `jira_download_attachments`, `jira_get_issue_images`, `jira_link_to_epic`, `jira_get_project_components`, `jira_get_project_versions`, `jira_batch_create_versions`, `jira_create_version`, `jira_get_issue_sla`, `jira_get_issue_dates`, `jira_get_issue_development_info`, `jira_get_issues_development_info`, `jira_batch_get_changelogs`, `jira_get_queue_issues`, `jira_get_service_desk_for_project`, `jira_get_service_desk_queues`, `jira_create_remote_issue_link`, `jira_search_fields`, `jira_get_field_options`, `jira_get_issue_proforma_forms`, `jira_get_proforma_form_details`, `jira_update_proforma_form_answers` | Confluence: `confluence_search`, `confluence_get_page`, `confluence_create_page`, `confluence_update_page`, `confluence_delete_page`, `confluence_add_comment`, `confluence_reply_to_comment`, `confluence_get_comments`, `confluence_add_label`, `confluence_get_labels`, `confluence_get_page_children`, `confluence_get_page_history`, `confluence_get_page_diff`, `confluence_get_page_views`, `confluence_move_page`, `confluence_upload_attachment`, `confluence_upload_attachments`, `confluence_get_attachments`, `confluence_delete_attachment`, `confluence_download_attachment`, `confluence_download_content_attachments`, `confluence_get_page_images`, `confluence_search_user` |
+| **When to use** | Tracking personal tickets, updating your own issues, commenting, logging work, searching your Jira backlog, reading/writing Confluence docs |
+| **When NOT to use** | IT admin operations (use `mcp-atlassian` instead); service desk ticket management (use `freshservice-mcp`) |
+| **Approval required** | Auto: all `get_*`, `search*`, `list_*`, `download_*` (read). Needs approval: `create_issue`, `update_issue`, `delete_issue`, `transition_issue`, `add_comment`, `create_page`, `update_page`, `delete_page`, `add_worklog` |
+
+#### `mcp-atlassian` (IT admin Jira + Confluence account)
+| Field | Detail |
+|-------|--------|
+| **Tools** | Same tool set as `mcp-atlassian-personal` |
+| **When to use** | IT admin operations, organization-wide Jira/Confluence actions requiring admin credentials |
+| **When NOT to use** | Personal work — use `mcp-atlassian-personal` to avoid admin footprint on personal tickets |
+| **Approval required** | Same gate as personal; extra caution given admin scope — all writes need approval |
+
+---
+
+### Service Desk
+
+#### `freshservice-mcp`
+| Field | Detail |
+|-------|--------|
+| **Tools** | Tickets: `get_tickets`, `get_ticket_by_id`, `create_ticket`, `update_ticket`, `delete_ticket`, `get_ticket_fields`, `filter_tickets`, `list_all_ticket_conversation`, `create_ticket_note`, `send_ticket_reply`, `get_requested_items` | Agents/Requesters: `get_all_agents`, `get_agent`, `create_agent`, `update_agent`, `filter_agents`, `get_all_requesters`, `get_requester_id`, `create_requester`, `update_requester`, `filter_requesters`, `list_all_requester_fields`, `get_all_requester_groups`, `get_requester_groups_by_id`, `create_requester_group`, `update_requester_group`, `list_requester_group_members`, `add_requester_to_group` | Groups/Products: `get_all_agent_groups`, `getAgentGroupById`, `create_group`, `update_group`, `get_all_products`, `get_products_by_id`, `create_product`, `update_product` | Solutions/Canned: `get_all_solution_category`, `get_solution_category`, `create_solution_category`, `update_solution_category`, `get_list_of_solution_folder`, `get_solution_folder`, `create_solution_folder`, `update_solution_folder`, `get_list_of_solution_article`, `get_solution_article`, `create_solution_article`, `update_solution_article`, `publish_solution_article`, `list_all_canned_response_folder`, `list_canned_response_folder`, `get_all_canned_response`, `get_canned_response` | Service: `create_service_request`, `list_service_items` | Workspace: `get_workspace`, `list_all_workspaces` |
+| **When to use** | IT service desk tickets, hardware requests, onboarding/offboarding, software access requests, agent/group management |
+| **When NOT to use** | Engineering project tracking (use Jira); general team comms (use Slack) |
+| **Approval required** | Auto: all `get_*`, `filter_*`, `list_*` (read). Needs approval: `create_ticket`, `update_ticket`, `delete_ticket`, `send_ticket_reply`, `create_ticket_note`, `create_service_request`, `create_agent`, `update_agent` |
+
+---
+
+### Documentation & Knowledge
+
+#### `context7`
+| Field | Detail |
+|-------|--------|
+| **Tools** | `resolve-library-id`, `get-library-docs` |
+| **When to use** | Library/framework API docs, "how do I use X library", version-specific documentation lookup |
+| **When NOT to use** | Internal company docs (use Confluence/Glean); saved personal reading (use Readwise if configured) |
+| **Approval required** | Auto: all read-only |
+
+#### `glean_default`
+| Field | Detail |
+|-------|--------|
+| **Tools** | `chat`, `search`, `read_document` |
+| **When to use** | Searching internal Klaviyo knowledge base, finding internal docs, policies, runbooks, past decisions |
+| **When NOT to use** | External library docs (use context7); real-time web search (use WebSearch tool) |
+| **Approval required** | Auto: all read-only |
+
+#### `apple-doc-mcp`
+| Field | Detail |
+|-------|--------|
+| **Tools** | `list_technologies`, `get_documentation`, `search_symbols`, `list_container_technologies`, `get_container_documentation`, `search_container_symbols`, `list_containerization_technologies`, `get_containerization_documentation`, `search_containerization_symbols`, `check_updates` |
+| **When to use** | Apple platform development (Swift, SwiftUI, UIKit, AppKit), containerization docs for Apple frameworks |
+| **When NOT to use** | Non-Apple development contexts; general web docs |
+| **Approval required** | Auto: all read-only |
+
+---
+
+### People & CRM
+
+#### `lusha`
+| Field | Detail |
+|-------|--------|
+| **Tools** | `contactSearch`, `contactEnrich`, `personBulkLookup`, `companySearch`, `companyEnrich`, `companyBulkLookup`, `contactFilters`, `companyFilters` |
+| **When to use** | Finding contact info for a person or company, enriching a lead with email/phone, company intelligence lookups |
+| **When NOT to use** | Internal employee lookups (use Slack/Glean); existing contacts already in CRM |
+| **Approval required** | Auto: all search/enrich (read from Lusha). Needs approval if results are being written somewhere |
+
+---
+
+### Calendar
+
+#### `google-calendar`
+| Field | Detail |
+|-------|--------|
+| **Tools** | `list-calendars`, `list-events`, `get-event`, `search-events`, `create-event`, `create-events`, `update-event`, `delete-event`, `respond-to-event`, `get-freebusy`, `get-current-time`, `list-colors`, `manage-accounts` |
+| **When to use** | Checking schedule, finding free time, creating/updating meetings, responding to invites, scheduling across participants |
+| **When NOT to use** | Non-calendar scheduling (use Jira for sprint planning) |
+| **Approval required** | Auto: `list-calendars`, `list-events`, `get-event`, `search-events`, `get-freebusy`, `get-current-time`, `list-colors` (read). Needs approval: `create-event`, `update-event`, `delete-event`, `respond-to-event` |
+
+---
+
+## 2. Contextual Trigger Map
+
+| User says / context contains... | Reach for... | Tool category |
+|----------------------------------|--------------|---------------|
+| "commit", "push", "branch", "PR", "git log", "diff", "staged" | `git` | Version control |
+| "Jira", "ticket", "sprint", "story", "epic", "backlog", "SCRUM" | `mcp-atlassian-personal` | Project mgmt |
+| "IT ticket", "service request", "Freshservice", "hardware request", "onboarding", "access request" | `freshservice-mcp` | Service desk |
+| "Confluence", "wiki", "internal doc", "runbook", "write a page" | `mcp-atlassian-personal` | Documentation |
+| "Slack", "post to channel", "notify the team", "DM", "thread" | `slack` | Communication |
+| "email", "Gmail", "inbox", "draft", "reply to", "send to" | `gmail` | Communication |
+| "calendar", "meeting", "schedule", "free time", "invite", "block time" | `google-calendar` | Calendar |
+| "how do I use [library]", "API docs", "documentation for X framework" | `context7` | Ext. docs |
+| "find in internal docs", "Glean", "search Klaviyo", "company policy" | `glean_default` | Internal knowledge |
+| "screenshot", "test the UI", "click button", "E2E", "browser test" | `playwright` | Testing |
+| "find someone's email", "contact info", "company profile", "person lookup" | `lusha` | CRM/people |
+| "Swift docs", "SwiftUI", "UIKit", "Apple framework", "AppKit" | `apple-doc-mcp` | Apple dev |
+| "think through this", "complex analysis", "multi-step reasoning", "trade-offs" | `sequential-thinking` | Reasoning |
+| "debug browser", "network request", "Chrome DevTools", "performance profile" | `chrome-devtools` | Dev tools |
+| "who is oncall", "search internal", "Klaviyo runbook" | `glean_default` | Internal ops |
+| "IT admin", "org-wide Jira change", "admin Confluence" | `mcp-atlassian` | Admin ops |
+| "highlight", "saved article", "Readwise", "reading list" | *(Readwise — not configured in current settings)* | — |
+
+---
+
+## 3. Multi-MCP Workflows
+
+### W1: Jira Ticket → Research → Implement → PR → Notify Team
+```
+1. mcp-atlassian-personal.jira_get_issue          → read ticket details
+2. context7.get-library-docs                       → research relevant APIs
+3. git.git_status + git.git_create_branch          → prep branch
+4. [implement code changes]
+5. git.git_add + git.git_commit                    → commit work
+6. slack.slack_post_message                        → notify team of PR
+```
+
+### W2: Calendar Check → Draft Message → Email Follow-up
+```
+1. google-calendar.get-freebusy                    → find mutual availability
+2. google-calendar.search-events                   → context on existing meetings
+3. slack.slack_post_message OR slack.slack_reply_to_thread  → async coordination
+4. gmail.draft_email                               → formal follow-up (needs approval to send)
+5. google-calendar.create-event                    → book the slot (needs approval)
+```
+
+### W3: IT Service Request → Jira Tracking → Slack Update
+```
+1. freshservice-mcp.get_ticket_by_id               → read service request
+2. mcp-atlassian-personal.jira_create_issue        → create linked engineering task (needs approval)
+3. freshservice-mcp.update_ticket                  → update FS ticket with Jira link (needs approval)
+4. slack.slack_post_message                        → notify requester's team (needs approval)
+```
+
+### W4: Bug Report → Code Investigation → Fix → Test → Close
+```
+1. mcp-atlassian-personal.jira_get_issue           → read bug details
+2. git.git_log + git.git_diff                      → inspect recent changes
+3. glean_default.search                            → search internal runbooks for context
+4. [implement fix]
+5. playwright.browser_navigate + browser_snapshot  → visual smoke test
+6. git.git_add + git.git_commit                    → commit fix
+7. mcp-atlassian-personal.jira_transition_issue    → close/resolve ticket (needs approval)
+```
+
+### W5: New Hire Onboarding Request → Access Provisioning → Confirm
+```
+1. freshservice-mcp.get_ticket_by_id               → read onboarding request
+2. mcp-atlassian-personal.jira_create_issue        → create IT tasks (needs approval)
+3. lusha.contactEnrich                             → enrich new hire contact info if needed
+4. freshservice-mcp.create_requester               → add to Freshservice (needs approval)
+5. slack.slack_post_message                        → notify IT and manager (needs approval)
+6. gmail.draft_email                               → welcome email (needs approval to send)
+```
+
+### W6: Architecture Research → Documentation → Team Sync
+```
+1. context7.get-library-docs                       → library/framework research
+2. glean_default.search                            → find existing internal decisions
+3. sequential-thinking.sequentialthinking          → synthesize trade-offs
+4. mcp-atlassian-personal.confluence_create_page   → write decision doc (needs approval)
+5. slack.slack_post_message                        → share with team (needs approval)
+6. google-calendar.create-event                    → schedule review meeting (needs approval)
+```
+
+---
+
+## 4. Approval Gate Annotations
+
+### Auto-execute (safe — read/query/list only)
+| Operation type | Examples |
+|----------------|---------|
+| Read git state | `git_status`, `git_diff`, `git_log`, `git_show`, `git_branch` |
+| Search/list Jira | `jira_search`, `jira_get_issue`, `jira_get_all_projects`, `jira_get_sprint_issues` |
+| Read Confluence | `confluence_get_page`, `confluence_search`, `confluence_get_comments` |
+| Read Freshservice | `get_tickets`, `get_ticket_by_id`, `filter_tickets`, `get_all_agents` |
+| Read calendar | `list-events`, `get-event`, `search-events`, `get-freebusy`, `get-current-time` |
+| Read Slack | `list_channels`, `get_channel_history`, `get_thread_replies`, `get_users` |
+| Read Gmail | `search_emails`, `read_email`, `list_email_labels` |
+| Lookup contacts | `lusha.contactSearch`, `lusha.companySearch`, `lusha.contactEnrich` |
+| Read docs | `context7.get-library-docs`, `glean_default.search`, `apple-doc-mcp.*` |
+| Browser inspect | `playwright.browser_snapshot`, `browser_screenshot`, `browser_console_messages` |
+| Analysis | `sequential-thinking.sequentialthinking` |
+
+### Needs approval (write / mutate / send / delete)
+| Operation type | Examples |
+|----------------|---------|
+| Git write | `git_commit`, `git_checkout`, `git_reset`, `git_create_branch` |
+| Jira write | `jira_create_issue`, `jira_update_issue`, `jira_delete_issue`, `jira_transition_issue`, `jira_add_comment`, `jira_add_worklog` |
+| Confluence write | `confluence_create_page`, `confluence_update_page`, `confluence_delete_page`, `confluence_add_comment` |
+| Freshservice write | `create_ticket`, `update_ticket`, `delete_ticket`, `send_ticket_reply`, `create_ticket_note`, `create_service_request`, `create_agent`, `update_agent` |
+| Calendar write | `create-event`, `update-event`, `delete-event`, `respond-to-event` |
+| Slack write | `slack_post_message`, `slack_reply_to_thread`, `slack_add_reaction` |
+| Gmail write | `send_email`, `draft_email`, `delete_email`, `batch_delete_emails`, `create_filter` |
+| Browser actions | Form submissions, file uploads, page mutations via Playwright |
+
+> **Hook enforcement**: `settings.json` registers a `PreToolUse` guard script on `mcp__mcp-atlassian-personal`, `mcp__mcp-atlassian`, `mcp__freshservice-mcp`, `mcp__slack`, and `mcp__gmail`. The guard will intercept write operations — treat any tool in those namespaces as needing user confirmation before proceeding.
+
+---
+
+## 5. Mind Integration Notes (Orient Phase)
+
+### Scan → Match → Gate → Chain
+
+```
+INPUT SCAN (keywords, intent, entities)
+  │
+  ├── Domain keyword detected?
+  │     └── Yes → look up Contextual Trigger Map (Section 2)
+  │
+  ├── Single domain or multi-domain?
+  │     ├── Single → pick direct MCP tool
+  │     └── Multi  → pick workflow from Section 3 or compose ad-hoc chain
+  │
+  ├── Approval gate check (Section 4)
+  │     ├── Read-only? → auto-proceed
+  │     └── Write/send/delete? → surface to user for confirmation
+  │
+  └── Execute → synthesize result → continue OODA loop
+```
+
+### Orient heuristics
+
+1. **Prefer read before write**: Always gather current state (`get_issue`, `git_status`, `list-events`) before proposing mutations.
+2. **Parallel reads are safe**: `jira_get_issue` + `glean_default.search` + `git_log` can run concurrently — no side effects.
+3. **Chain writes sequentially**: Write operations must be user-confirmed and ordered — never batch-execute multiple destructive actions.
+4. **Use personal over admin**: Default to `mcp-atlassian-personal` unless the task explicitly requires IT admin scope.
+5. **Match specificity**: IT/hardware/access → Freshservice. Engineering work → Jira. Internal knowledge → Glean. External library → context7. Personal saved reading → Readwise (not currently configured).
+6. **Stop after answer**: If a single read resolves the question, stop. Do not escalate to `sequential-thinking` for simple factual lookups.
+7. **Guard hook awareness**: Slack, Gmail, Atlassian, and Freshservice write operations are intercepted by the external-action-guard hook — do not attempt to batch them silently.

package/ftm-mind/references/protocols/COMPLEXITY-SIZING.md

@@ -0,0 +1,72 @@
+# Complexity Sizing
+
+Size the task from observed evidence, not vibes.
+
+## Micro
+
+`just do it`
+
+Signals:
+- one coherent local action
+- trivial blast radius
+- rollback is obvious
+- no meaningful uncertainty
+- no dedicated verification step needed
+
+Typical examples: rename a variable, fix a typo, answer a factual question after one read, add an import, tweak a comment.
+
+## Small
+
+`do + test`
+
+Signals:
+- 1-3 files
+- one concern
+- clear done state
+- at least one verification step is warranted
+- still reversible without planning overhead
+
+Typical examples: implement a simple helper, patch a bug in one area, add or update a focused test, update docs plus one code path.
+
+## Medium
+
+`lightweight plan`
+
+Signals:
+- multiple changes with ordering
+- moderate uncertainty
+- multi-file or multi-step
+- a bug or feature spans layers but not a full program of work
+- benefits from an explicit short plan before execution
+
+Typical examples: fix a flaky test with several hypotheses, add UI + API + tests for one feature, refactor a module with dependent updates.
+
+## Large
+
+`brainstorm + plan + executor`
+
+Signals:
+- cross-domain work
+- major uncertainty or architectural choice
+- a plan document already exists
+- many files or multiple independent workstreams
+- would benefit from orchestration, parallel execution, or audit passes
+
+Typical examples: build a feature from scratch, implement a long plan doc, re-architect a subsystem.
+
+## Boundary: where micro ends and small begins
+
+Micro ends the moment any of these become true:
+- more than one meaningful edit is required
+- a test or build check is needed to trust the change
+- the correct change is not self-evident
+- the blast radius is larger than the immediate line or local block
+
+## ADaPT Rule
+
+Try the simpler tier first.
+- If it looks small, start small.
+- If it looks medium, see whether a small direct pass resolves it.
+- If it looks large, ask whether a medium plan-plus-execute path is enough before invoking full orchestration.
+
+Escalate only when: the simple approach fails, the user explicitly asks for the larger workflow, or the complexity is obvious from the start.