motir-core

Open-source PM substrate for Motir — an AI-native project management tool for small startup teams. The user describes what they want to build; Motir produces a structured Epic → Story → Subtask tree; coding agents execute the Subtasks one at a time using prompts Motir generates.

Open source

motir-core is open source under the GPL-3.0 license (see LICENSE). This repo is the PM substrate: Work Items, Stories, dependency graph, multi-tenant workspaces, projects, the tree-view UI, GitHub integration, the human-todo queue, the delivery agent. The kind of thing Jira and Linear are, but open and AI-native.

The closed-source planning intelligence — the planner agent, prompt generation, async-expansion loop, shared-context retrieval — ships separately as the proprietary motir-ai service. It runs headless and is called server-to-server by motir-core. Browsers never talk to motir-ai directly, so the user experience stays unified (one app, one domain, one cookie) and the GPL boundary stays clean (a network service interface is not a derivative work).

See vision.html principle #19 and feasibility.html ADR-008 in the planning docs for the open-core architecture rationale. This split follows the same playbook as GitLab, Sentry, Plane, and Mattermost.

Rename interim: these repos are being renamed from their pre-rebrand prodect-* names to motir-core / motir-ai. GitHub redirects the old repo URLs automatically, so existing clones, remotes, and links keep working; update remotes with git remote set-url at leisure. (Vercel does NOT redirect — the *.vercel.app URLs below apply once the Vercel project rename lands.)

Stack

• Runtime: Node.js ≥22 (pnpm 11 requires it)
• Framework: Next.js 16 (App Router, React Server Components, Turbopack)
• Language: TypeScript (strict mode; noUncheckedIndexedAccess, noImplicitOverride, noFallthroughCasesInSwitch)
• Styling: Tailwind CSS v4
• Persistence: Postgres 16 (local Docker; host port 5433 to coexist with other local Postgres instances) + Prisma 7 with @prisma/adapter-pg. Connection URL lives in prisma.config.ts (Prisma 7 split it out of schema.prisma).
• Auth: NextAuth / Better-Auth (lands in Story 1.1 — not yet present)
• Testing: Vitest unit + Playwright e2e (scaffolding lands in later Subtasks)
• Lint / format: ESLint 9 (flat config) + Prettier 3. Husky pre-commit hook runs lint-staged to auto-fix staged files on every commit.

This Stack section is the authoritative reference for every later coding-agent prompt. Motir's planner (Epic 4) reads it verbatim into Subtask prompts so generated code matches the project's actual stack.

Local setup

Prerequisites: Node 22+, Docker or OrbStack, pnpm (corepack enable will handle this).

cp .env.example .env       # creates the dev DATABASE_URL
pnpm install               # installs deps + sets up husky pre-commit hook
./scripts/db-up.sh         # starts Postgres in Docker and applies migrations
pnpm dev                   # http://localhost:3000

You should see a placeholder "Motir" page on a dark theme — not the default create-next-app welcome page.

Scripts

Script	What it does
pnpm dev	Start the dev server on localhost:3000
pnpm build	Production build (must pass with 0 warnings)
pnpm start	Start the production server
pnpm lint	Run ESLint
pnpm format	Run Prettier and write fixes in place
pnpm format:check	Run Prettier in check mode (used by CI)
pnpm typecheck	Run tsc --noEmit
pnpm db:seed:large	Seed a real-scale demo project (~2,000 issues, deep tree) so the /issues List pagination + lazy/virtualized Tree are visible at scale. Idempotent; prints a sign-in. Tune via SEED_ROOTS / SEED_BIG_CHILDREN / SEED_SMALL_CHILDREN / SEED_DEEP_CHILDREN.

Project layout

app/          Next.js App Router routes
components/   React UI primitives (filled in Story 1.0.5)
lib/          Server-side logic (DB, auth, agents). `lib/db.ts` exports the
              singleton PrismaClient with the dev-mode hot-reload guard.
prisma/       Prisma schema + migrations. Real models (User, Workspace,
              WorkItem) land in Stories 1.1 / 1.2 / 1.4. Current placeholder
              `MigrationMarker` exists only to prove the migration system works.
tests/        Vitest unit + Playwright e2e (scaffolding lands in later Subtasks)
docs/         Project docs. Design system lands here in Story 1.0.5.
scripts/      Dev-loop scripts. `db-up.sh` brings up Postgres + runs migrations.
public/       Static assets
.github/
  workflows/  CI definitions (see Testing below)

Agent dispatch (BYOK)

Motir exposes a stable agent contract so you can drive your own coding agent (Claude Code / Cursor / Aider / your own script) against the project's ready set — the work items whose blockers have all landed, so they're safe to start:

• GET /api/ready?projectKey=ACME — list every ready work item.
• POST /api/ready/next with body { "projectKey": "ACME", "kinds": ["subtask"] } — get ONE item to run next, including its full description + context-file references. Pass "excludeIds": [...] across calls to walk the set.

The session cookie is the auth surface; use the same login flow your browser does.

The /ready page is the human mirror of /api/ready — anything an agent sees, a planner can see.

Testing

CI runs on every PR and push to main via .github/workflows/ci.yml. Three parallel jobs:

• Lint — pnpm lint + pnpm format:check
• TypeScript — pnpm prisma generate then pnpm typecheck
• Build — pnpm prisma migrate deploy then pnpm build, against a Postgres 16 container (started by .github/actions/postgres, which pulls the image mirror-first and retries — a services: block cannot, MOTIR-1742)

The full suite targets <3 min on a fresh clone. The pre-commit hook (Husky + lint-staged) catches lint/format issues before they reach CI; CI is the backstop, not the primary gate.

Unit + e2e test scaffolding (Vitest, Playwright) lands in later Subtasks.

Deploys

Deployed on Vercel (Hobby tier for v1). Database is managed Neon Postgres via the official Vercel-Neon integration, which auto-provisions an isolated database branch for each Vercel preview deploy.

• Production: every push to main triggers a production deploy at https://motir-core.vercel.app (Vercel's auto-assigned default; a real apex domain lands in Epic 5).
• Previews: every PR triggers an isolated preview deploy. Vercel posts the preview URL as a PR comment. The preview URL follows the pattern motir-core-git-<branch>-zhuyue11s-projects.vercel.app (per-branch stable) or motir-core-<hash>-zhuyue11s-projects.vercel.app (per-deploy). Each preview gets its own Neon DB branch so PRs can safely run destructive migrations without affecting production.
• Rollback: Vercel dashboard → Deployments → click any previous deploy → "Promote to Production". Or vercel rollback from the Vercel CLI.
• Env vars: managed in the Vercel dashboard (Settings → Environment Variables). The Neon integration sets ~10 env vars; the two we use are DATABASE_URL (pooled, for runtime queries via PgBouncer — used by lib/db.ts) and DATABASE_URL_UNPOOLED (direct connection — used by prisma migrate deploy, since PgBouncer in transaction mode breaks migrations). The other env vars (POSTGRES_URL, PGHOST, etc.) are unused by Motir and can be ignored. Never commit secrets to git. .env.example documents what's needed locally.
• Service-to-service tokens (open-core boundary): motir-ai calls motir-core over a shared bearer. MOTIR_AI_TO_CORE_SERVICE_TOKEN authenticates the inbound billing-propagation route (POST /api/internal/billing/scaled-tracker-state, Subtask 8.1.4c) — the same secret is set on motir-ai's coreClient (8.1.4d). It must match on both sides; the route fails CLOSED (rejects every request) when it is unset. Stripe secrets never enter motir-core — only this plain propagated state crosses the boundary.
• Build pipeline: Vercel runs pnpm install (which triggers postinstall: prisma generate to refresh the Prisma client against the current schema), then pnpm build (which is next build). Prisma migrations run automatically against the connected Neon branch.

Docs

• docs/cli.md — the motir CLI guide: install, authenticate, link a workspace, the work loop (next / run / auto / batch / done), terminal planning (plan), session-branch semantics, agent wiring, the sandbox, and troubleshooting.
• docs/mcp.md — the MCP server: minting a personal access token, token scopes, wiring an agent, and the full tool catalog.
• docs/approval-gates.md — approval gates: when Motir asks a person to say yes, what Approve and Request changes each do, who is asked versus who may answer, what an approval keeps, and what has not shipped yet.
• loadtest/README.md — the load-test runbook: provision or reuse the private staging copy, refresh it from production, deploy a SHA, run at 1 and N instances, check each side-effect sink, and read the report's verdict.
• docs/design-system.md — canonical reference for using the design system: tokens, primitives, patterns, voice & tone, don'ts. Read this when building any UI.
• docs/DESIGN.md — architectural spec of the design system: token taxonomy, palette/typography/spacing rules, component implementation notes.
• /tokens — live specimen route. Visit localhost:3000/tokens to see every token + primitive rendered with interactive theme + display-style toggles.
• Planning corpus (sibling to this repo, not inside it): vision.html for the 19 design principles, feasibility.html for ADRs (incl. ADR-008 on open-core), discovery.html / / for product context, + for the Epic-Story- Subtask build plan, for the running mistakes-log + lessons.

License

GPL-3.0-only. The planning intelligence ships separately under a proprietary license in moooon-B-V/motir-ai. See feasibility.html ADR-008 in the planning docs for the open-core split rationale.