AI Workshop / Task Manager

Этот репозиторий содержит task manager на Go и сопутствующие артефакты проектирования.

Сейчас в проекте есть две основные runtime-части:

• task-manager — HTTP backend с PostgreSQL.
• task-manager-mcp — MCP server, который работает по stdio и ходит в backend по HTTP.

Схема взаимодействия:

MCP client -> task-manager-mcp -> HTTP -> task-manager -> PostgreSQL

Что где лежит

Корень проекта

• cmd/ — входные точки приложений.
• internal/ — основной код приложения по слоям.
• migrations/ — SQL-миграции для PostgreSQL.
• workflow/ — артефакты анализа, архитектуры, контрактов и реализации.
• .agents/ — локальная агентная инфраструктура: skills, gate profiles, stage policies, stack profiles.
• .codex/ — локальная конфигурация Codex.
• 08.task-manager-brief.md — исходный brief по backend-части.
• 09.task-manager-mcp-brief.md — brief по MCP-части.
• workflow-state.yaml — текущее состояние workflow-артефактов.
• Dockerfile — образ backend-сервиса.
• docker-compose.yml — локальный запуск PostgreSQL + backend.
• .env.example — пример переменных окружения.

cmd/

• cmd/task-manager/main.go — запуск HTTP backend.
• cmd/task-manager-mcp/main.go — запуск MCP server.

internal/

Код организован в стиле layered/clean architecture.

• internal/domain/task/ — доменная модель: задача, activity, статус, инварианты.
• internal/application/taskcommand/ — command use cases: создать задачу, назначить, сменить статус, добавить activity.
• internal/application/taskquery/ — query use cases: список задач, детали, stale tasks.
• internal/application/taskmcp/ — application-слой для MCP, который работает поверх backend-клиента.
• internal/ports/ — порты приложения и кодовые контракты между слоями.
• internal/adapters/httpapi/ — HTTP handler для backend API.
• internal/adapters/mcpserver/ — MCP server и регистрация tools.
• internal/adapters/taskbackend/ — HTTP-клиент, через который MCP ходит в backend.
• internal/adapters/postgres/ — реализация репозитория на PostgreSQL.
• internal/adapters/system/ — инфраструктурные адаптеры: clock, генератор id.
• internal/platform/config/ — чтение конфигурации из env.
• internal/taskmcp/ — типы и ошибки MCP-слоя.

migrations/

• 0001_init_tasks.sql — начальная схема задач.
• 0002_add_task_activities.sql — расширение схемы activity/comments.

workflow/

Это не runtime-код, а документация и артефакты по проектированию.

• workflow/task-manager/domain-model.md — доменная модель.
• workflow/task-manager/architecture.md — архитектурные границы backend-а.
• workflow/task-manager/contracts.md — текстовые REST-контракты backend-а.
• workflow/task-manager/openapi.yaml — OpenAPI-описание backend API.
• workflow/task-manager/slice-plan.md — план слайсов реализации.
• workflow/task-manager/implementation-report-SLICE-*.md — отчеты по реализованным слайсам.
• workflow/task-manager/mcp/ — отдельный пакет артефактов для MCP-фазы.

Внутри workflow/task-manager/mcp/:

• README.md — как подключать и использовать MCP server.
• architecture.md — архитектура MCP-слоя.
• contracts.md — MCP tool contracts.
• slice-plan.md — план реализации MCP-части.
• implementation-report-SLICE-01.md — отчет по реализации MCP.

Где смотреть контракты приложения

Зависит от того, какой уровень контракта нужен:

• REST-контракты backend-а: workflow/task-manager/contracts.md
• OpenAPI-спецификация backend API: workflow/task-manager/openapi.yaml
• MCP-контракты tools: workflow/task-manager/mcp/contracts.md
• Кодовые порты application-слоя:
  • internal/ports/task_command.go
  • internal/ports/task_query.go
  • internal/ports/task_mcp.go

Если нужен не только контракт, но и контекст:

• доменные правила и термины: workflow/task-manager/domain-model.md
• архитектурные границы и mapping портов: workflow/task-manager/architecture.md
• инструкция по запуску и подключению MCP: workflow/task-manager/mcp/README.md

Быстрый старт

Запуск backend через Docker Compose

docker compose up -d db app

Backend будет доступен на:

http://localhost:8081

Запуск backend вручную

export TASK_MANAGER_DATABASE_URL='postgres://taskmanager:taskmanager@localhost:5432/taskmanager?sslmode=disable'
go run ./cmd/task-manager

По умолчанию backend слушает:

http://localhost:8080

Запуск MCP server

export TASK_MANAGER_MCP_BACKEND_BASE_URL='http://localhost:8081'
go run ./cmd/task-manager-mcp

Дополнительно можно задать:

• TASK_MANAGER_HTTP_ADDR
• TASK_MANAGER_MCP_BACKEND_TIMEOUT

Полный пример env лежит в .env.example.

Полезные команды

Проверка тестов:

go test ./...

Проверка backend API:

curl http://localhost:8081/tasks