Slack MCP Agent — AI Development Guide

Project Overview

HR task automation via Slack. Users mention the bot, it generates an execution plan through a 4-layer pipeline (L1-L4), gets human approval at each stage, then executes via Anthropic Managed Agents with Custom Tools for freee API.

Goal: Internal demo MVP by end of April 2026.

Architecture (3 processes)

Process	Tech	Role
Backend	Python (Slack Bolt, Socket Mode)	Pipeline L1-L4, Custom Tool Executor, Slack UI
MCP Server	Python (FastMCP)	Tool exposure to Managed Agents (mock data for dev)
Web	Next.js (App Router, shadcn/ui)	Admin panel (pipeline list, settings, audit log)

Backend and Web share a single SQLite DB file (data/agent.db). Backend writes, Web mostly reads.

4-Layer Pipeline

• L1: User message -> Task JSON (title, description, priority, taskType)
• L2: Task -> Prompt text (execution strategy, natural language)
• L3: Prompt -> Process JSON (steps array with tool, toolInput)
• L4: Process -> Managed Agent Execution (polling loop)

Each layer has human approval gates between L2->L3 and L3->L4.

Development Commands

make dev            # Start Backend + MCP + ngrok (all-in-one)
make dev-backend    # Backend only (hot reload)
make dev-mcp        # MCP Server only (hot reload)
make test           # All tests with coverage
make check          # lint + typecheck + test
make db-reset       # Delete DB
make db-seed        # Insert sample data
make docs-serve     # Preview the spec site locally (http://127.0.0.1:8000)
make docs-build     # Build the spec site into ./site/

Set MOCK_MODE=true in .env to mock L4 execution (default for dev).

Rules

Must Follow

• Run make test before considering work complete. All tests must pass.
• Run make check before creating a PR.
• Every new function/module must have tests. Use TDD when possible.
• Follow existing patterns in the codebase. Read neighboring files before writing new code.
• Keep SQL in standard syntax (no SQLite-specific extensions) for future PostgreSQL migration.
• No ORM. Use raw SQL via aiosqlite (backend) and better-sqlite3 (web).
• Use ULID for all primary keys (import ulid; str(ulid.new())).
• All Python files start with from __future__ import annotations.

Must NOT Do

• Do not use emoji in UI labels, buttons, navigation, headings, or descriptions (DESIGN.md D-6).
• Do not use rich_text blocks in Slack Block Kit (slack-ui-spec.md P-5).
• Do not commit .env, data/, or any credentials.
• Do not add dependencies without checking existing pyproject.toml first.
• Do not modify system prompt files (backend/src/prompts/*.md) without understanding the output contract.

Key Design Documents

Document	What it defines
docs/architecture.md	System architecture, component diagram, auth, persistence
docs/data-model.md	ER diagram, table definitions, state transitions
docs/custom-tools.md	Tool catalog, Shared Schema, freee adapter
docs/prompt-design.md	L1-L4 prompt strategy, output contracts
docs/slack-ui-spec.md	Block Kit JSON for all 4 card types and states
docs/admin-ui-spec.md	Web admin panel screens and wireframes
docs/error-handling.md	Failure patterns, retry, rejection, cancellation
docs/project-structure.md	Directory layout, naming conventions
docs/tech-decisions.md	ADR: why Python, SQLite, Slack Bolt, etc.
DESIGN.md	Web admin panel design tokens and component guidelines

Always read the relevant design doc before implementing a feature.

Spec Site (MkDocs)

All files under docs/**/*.md plus the root README.md / AGENTS.md / DESIGN.md are published as a browsable spec site via MkDocs + Material theme.

• Config: mkdocs.yml (root). If you add a new file under docs/, also add it to nav: so it appears in the sidebar.
• Local preview: make docs-serve then open http://127.0.0.1:8000
• Deploy: .github/workflows/docs.yml builds the site and deploys to Cloudflare Pages on every push to main. Access to the deployed site is restricted via Cloudflare Access.
• Source of truth: Markdown files in this repository. Do not edit the deployed HTML directly.

When making non-trivial feature changes, keep the relevant doc(s) in docs/ in sync in the same PR. See .cursor/skills/sync-docs/SKILL.md for the sync checklist.

Naming Conventions

• Python: snake_case functions/vars, PascalCase classes, UPPER_SNAKE constants
• TypeScript: camelCase functions/vars, PascalCase components/types, kebab-case filenames
• DB: snake_case tables (plural) and columns
• Git branches: feature/, fix/, chore/ prefixes

See docs/project-structure.md Section 9 for full details.

Git Workflow

• Branch from main for each feature/fix
• PR title format: feat: ... / fix: ... / chore: ...
• Keep PRs focused on a single concern

Worktree Parallel Development

When running multiple agents in parallel via git worktree:

1. Create: git worktree add ../slack-mcp-agent-<branch> -b <branch>
2. Copy env: cp .env ../slack-mcp-agent-<branch>/.env
3. Port isolation: Override ports in the worktree .env to avoid conflicts:
4. BACKEND_PORT (default 8000) — use 8010, 8020, etc.
5. MCP_HR_FREEE_PORT (default 8001) — use 8011, 8021, etc.
6. WEB_PORT (default 3100) — use 3110, 3120, etc. (also update BASE_URL)
7. DB isolation: Each worktree gets its own data/agent.db automatically (path is relative).
8. Install deps: Run make setup in the worktree before starting.
9. Cleanup: git worktree remove ../slack-mcp-agent-<branch>