AGENTS.md

Structural map for AI agents and new contributors. Read this file first to orient yourself, then drill into the referenced documents.

Maintained by /aif. Update when the project structure changes significantly. The Documentation section is maintained by /aif-docs.

Project Overview

MAIster is the self-hosted execution and governance layer for reproducible AI-powered SDLC processes over private code. Current validation wedge: processes from core packages running across internal/private projects through the Web control plane, ACP supervisor, graph-only Flow engine, multi-workspace execution, HITL, evidence, review, and promotion. External ACP adapters remain the agent runtimes.

Full description: .ai-factory/DESCRIPTION.md.

Tech Stack

• Framework: Next.js 16.2 (App Router)
• Language: TypeScript 5.6 (strict)
• UI library: HeroUI v3 (@heroui/react 3.2.6)
• Styling: Tailwind CSS 4 + tailwind-variants
• Database: Postgres 16 via Drizzle ORM
• Supervisor daemon (supervisor/): Fastify 5 + pino + zod; ACP via @agentclientprotocol/sdk@2.0.2 spawning claude-agent-acp@0.95.0, codex-acp@2.2.2, and readiness-gated gemini --acp, opencode acp, and mimo acp adapter binaries
• Tests: vitest (unit + integration), Playwright (E2E)
• Package manager: pnpm (monorepo workspace: web + supervisor)
• Node: 24

Project Structure

mAIster/
├── .ai-factory/                # AI Factory project context
│   ├── config.yaml             # AI Factory configuration (language, paths, git)
│   ├── DESCRIPTION.md          # Project specification
│   ├── ARCHITECTURE.md         # Architecture pattern, folder structure, deps
│   ├── ROADMAP.md              # Roadmap and completed work
│   ├── plans/                  # Full-mode /aif-plan output, branch-keyed
│   └── rules/                  # Project conventions for AI agents
│       ├── base.md             # Project-wide rules
│       ├── frontend.md         # Web-tier rules (HeroUI, RSC, lint)
│       ├── backend.md          # Server-tier rules (subprocess, SSE, errors)
│       └── database.md         # Drizzle / Postgres rules
├── .github/                    # Public issue forms and pull-request template
│   ├── ISSUE_TEMPLATE/
│   └── PULL_REQUEST_TEMPLATE.md
├── .agents/                    # Codex agent bundles (do not hand-edit)
├── .claude/                    # Claude skills + agents (managed via /aif)
├── .codex/                     # Codex skills + config.toml
├── .mcp.json                   # MCP servers: github, filesystem, postgres,
│                               #              chromeDevtools, playwright
├── .ai-factory.json            # AI Factory installed-skills registry
├── .pre-commit-config.yaml     # Pre-commit hooks: lint/typecheck/prettier (web + supervisor)
├── pnpm-workspace.yaml         # Monorepo: web + supervisor + site + site-docs
├── pnpm-lock.yaml              # Frozen lockfile (root)
├── Dockerfile                  # Single image; web/supervisor selected via command:
├── compose.yml                 # Postgres only; web + supervisor run on the host
├── compose.production.yml      # Prod hardening: read_only, cap_drop, tmpfs
├── docs/                       # Product & engineering documentation
│   ├── VISION.md
│   ├── PRODUCT_VIEW.md
│   ├── supervisor.md           # HTTP+SSE API, lifecycle, event/object plane
│   ├── configuration.md
│   ├── database-schema.md
│   ├── error-taxonomy.md
│   ├── getting-started.md
│   ├── architecture.md
│   ├── decisions.md
│   ├── api/
│   ├── db/
│   └── system-analytics/
├── site/                       # Public EN/RU product landing (Next.js)
│   ├── app/                    # Localized routes + GitHub repository proxy
│   ├── components/             # Landing UI; reuses the web login SpineGraph
│   ├── lib/                    # Localized copy, locale and GitHub contracts
│   └── public/                 # Landing-only generated/static artwork
├── site-docs/                  # Public EN/RU user docs (Mintlify + Markdown)
│   ├── concepts/               # Public product concepts
│   ├── guides/                 # Public task-oriented guides
│   ├── operations/             # Public operator guides
│   ├── reference/              # Public manifest and runtime reference
│   ├── ru/                     # Russian public-doc parity tree
│   └── docs.json               # Navigation, theme, AI-context integrations
├── supervisor/                 # ── ACP SUPERVISOR DAEMON ──
│   ├── src/
│   │   ├── main.ts             # Fastify boot + graceful shutdown
│   │   ├── http-api.ts         # 6 routes (POST/DELETE/GET /sessions, SSE, checkpoint/input stubs)
│   │   ├── spawn.ts            # child_process dispatch (claude-agent-acp | codex-acp)
│   │   ├── heartbeat.ts        # exit/error → session.exited/crashed + orphan watcher
│   │   ├── cost.ts             # cache/input/output usage normalization
│   │   ├── registry.ts         # In-memory SessionRecord map + per-session event ring buffer
│   │   ├── types.ts            # Zod schemas + SessionEvent union + SupervisorError
│   │   └── __tests__/          # 30 unit + 9 integration tests
│   ├── test/fixtures/
│   │   └── fake-acp.mjs        # Stand-in for the real ACP binary in tests
│   ├── package.json            # @maister/supervisor; tsx runtime
│   ├── tsconfig.json
│   ├── vitest.workspace.ts     # unit | integration split
│   └── eslint.config.mjs
├── web/                        # ── NEXT.JS WEB TIER ──
│   ├── app/                    # App Router (layout, pages, api/, server actions)
│   ├── components/             # HeroUI-based React components
│   ├── config/                 # Site config (navItems), fonts
│   ├── lib/                    # Server-only modules (errors, atomic, config, db, supervisor-client)
│   ├── i18n/                   # EN + RU translations (required from day one)
│   ├── styles/                 # globals.css (Tailwind 4 + HeroUI styles)
│   ├── types/                  # Shared TS types
│   ├── public/                 # Static assets
│   ├── CLAUDE.md               # Web slice conventions — READ THIS
│   ├── package.json            # Dependencies, scripts (dev/build/start/lint)
│   ├── tsconfig.json           # strict, @/* path alias
│   ├── next.config.mjs
│   ├── eslint.config.mjs       # ESLint 9 flat config
│   └── postcss.config.mjs      # @tailwindcss/postcss
├── CLAUDE.md                   # Root project instructions for AI agents
├── AGENTS.md                   # This file
├── README.md                   # Landing page: quick start, docs index
├── CONTRIBUTING.md             # Development and contribution workflow
├── SECURITY.md                 # Private vulnerability-reporting policy
├── CODE_OF_CONDUCT.md          # Contributor Covenant 2.1
├── .env.example                # Server env vars (web + supervisor)
├── .dockerignore
├── LICENSE                     # MIT
└── .gitignore

Two Node processes: web/ (Next.js — UI + Route Handlers + server actions

• Drizzle DB access + SSE bridge) and supervisor/ (Fastify daemon — owns ACP sessions and spawns agent processes). They communicate over HTTP+SSE through web/lib/supervisor-client.ts; the supervisor runs as a separate process on the supported single host. Stage B removes the web runtime-data mount; Stage C owns remote repository/workspace placement.

Key Entry Points

Documentation

AI Context Files

When this file disagrees with CLAUDE.md or docs/, those win — update this file.

Agent Rules

• Decompose shell commands — run each command separately, not chained, so failures surface clearly and approvals stay scoped.
  • Wrong (combined): git checkout main && git pull
  • Right (decomposed): first git checkout main, then git pull origin main
• Read CLAUDE.md and web/CLAUDE.md first before touching any code. Both files encode product spine, current implementation boundaries, and project conventions.
• Surgical changes only — every changed line must trace directly to the user's request. Do not refactor adjacent code while you're there.
• Throw MaisterError with code for known domain failures. Never use plain Error for domain errors. UI branches on code, never on string matching.
• Atomic writes to .maister/ — always tmp + rename via atomicWriteJson. The Flow may read mid-write otherwise.
• No chokidar / fs.watch / polling. State transitions are driven by ACP notifications (live path) plus artifact presence (recovery path); process exit codes feed the heartbeat-promoted crash event.
• Agent processes live in supervisor/, not web/. The web tier reaches the supervisor through web/lib/supervisor-client.ts only. ACP sessions are held live across permission HITL; designed checkpoint resume uses the same acp_session_id handle.
• Scope labels are descriptive, not blockers — use docs labels (Implemented, Designed, Phase 2) to explain trade-offs. Do not block useful work solely because an old planning note called it out of scope.