Imported from dnguyen316/taskmind (AGENTS.md). Install upstream with npx skills add dnguyen316/taskmind. Copyright stays with the author.

AGENTS.md - TaskMind rebuild (Codex cloud agent guide)

This file is the entry point for the autonomous agent rebuilding TaskMind from an empty repository. Codex reads AGENTS.md automatically. Read this fully before writing any code, then follow docs/build-kit/01-build-order.md milestone by milestone.

Mission

Rebuild TaskMind - an AI-centered task manager - from scratch with full feature parity to the reference implementation, using the identical stack and an AWS managed data plane (Amazon S3 for object storage, Amazon OpenSearch Service for search, RDS Postgres + ElastiCache Redis in production).

You are building a polyglot monorepo: one Vue 3 SPA + three Spring Boot services + two shared Java libraries. It is not a single backend - most work touches exactly one service. Respect service boundaries at all times.

Tech stack (do not substitute)

Monorepo layout (target)

taskmind/
  pom.xml                  # Maven parent reactor (Spring Boot 3.3.5, Java 17)
  Makefile                 # build/run/verify shortcuts
  docker-compose.yml       # thin wrapper -> infra/compose/*
  AGENTS.md  CLAUDE.md  README.md
  .github/workflows/ci.yml # runs scripts/vibe-verify.sh
  scripts/vibe-verify.sh   # CI/agent quality gate
  libs/
    events/                # taskmind-events: domain event envelope (Core -> Relay)
    ai-contracts/          # taskmind-ai-contracts: Core <-> Nova DTOs
  apps/
    backend/               # Core API (Spring Boot)                  :8080
    relay/                 # Analytics/context relay                 :8081
    ai/                    # Nova LLM orchestration                  :8082
    frontend/              # Vue 3 SPA (npm, not in reactor)         :5173
  infra/
    compose/               # docker-compose.infra.yml + .apps.yml + nginx/
    env/.env.example       # env template
  docs/                    # architecture + product docs

Maven build order (reactor): libs/events -> libs/ai-contracts -> apps/backend -> apps/relay -> apps/ai. The frontend is a separate npm project, never in Maven.

Ports

Build, run & verify commands

# Build all Java modules (libs first, then apps)
make build              # mvn clean install -DskipTests

# Run tests
make test               # mvn test (H2 in PostgreSQL mode, Flyway still runs)

# THE quality gate - run before claiming any milestone done
make vibe-verify        # = ./scripts/vibe-verify.sh : mvn test + FE typecheck
                        # per-step timeouts: 900s Java / 180s FE (exit 124 = timeout)

# Frontend (from apps/frontend)
npm install
npm run dev             # Vite :5173
npm run typecheck       # vue-tsc --noEmit (FE "lint")
npm run build           # vite build (also type-checks)

# Local infra + services
make env-example        # infra/env/.env.example -> infra/env/.env
make infra-up           # Postgres + Redis + OpenSearch + (LocalStack S3)
make run-backend        # Core :8080
make run-relay          # Relay :8081
make run-ai             # Nova :8082
make run-frontend       # Vue :5173

Targeted Java tests (from the relevant apps/<service> dir):

mvn -q -Dtest=TaskControllerTest test
mvn -q -Dtest='*Task*' test
mvn -q -Dtest=TaskControllerTest#rejectsStaleTaskUpdate test

Implementation polish loop

After each implementation pass and before final verification, do a deliberate polish loop:

1. Format backend code from the owning Spring Boot service directory with mvn -q spotless:apply -DspotlessFiles=<changed-java-files> when Java files changed. Re-run mvn -q spotless:check -DspotlessFiles=<changed-java-files> if you need a no-diff formatter guard.
2. Format frontend code from apps/frontend with npm run format -- <changed-fe-files> when Vue, TypeScript, CSS, JSON, or Markdown files changed. Re-run npm run format:check -- <changed-fe-files> for a no-diff formatter guard.
3. Code review before tests: scan your own diff with git diff --check and git diff --stat, then review the changed files by feature boundary to catch missing tests, contract drift, dead code, unsafe auth assumptions, and formatting noise quickly.
4. Session docs/changelog: for behavior changes, update the owning build-kit reference and the relevant feature changelog (docs/backend-feature-changelog.md for backend, docs/frontend-feature-changelog.md for frontend) using the session workflow. Record applicable skills and agent/delegation usage when the workflow asks for closeout notes.
5. Run the smallest targeted tests/typechecks for the touched area, then the required make vibe-verify gate before claiming work is done.

Hard rules (guardrails)

1. Never commit, push, or create branches unless the human explicitly asks. Staging (git add) and read-only inspection (git status/diff/log) are fine.
2. Schema is owned by Flyway. spring.jpa.hibernate.ddl-auto=validate. Add new migrations as V<n>__description.sql - append the next integer; never edit an applied migration. Entities carry optimistic-lock @Version columns.
3. Respect service boundaries. The frontend calls only Core. Core exposes facade endpoints to Nova/Relay. All LLM prompts/calls live in Nova. Analytics projections and read-context live in Relay. See docs/build-kit/00-overview.md.
4. DDD four layers per feature module - interfaces/rest -> application -> domain (model + repository ports) -> infrastructure/persistence/jpa. Keep each change in the layer that owns the concern. See docs/build-kit/conventions.md.
5. Keep apps/backend/openapi.yaml in sync with Core DTOs whenever you add/modify a request/response field.
6. TDD for Java: RED -> GREEN -> REFACTOR. Write the failing test first.
7. Verify before done. A milestone is complete only when make vibe-verify passes and (for UI work) a browser E2E confirms it. Do not move on with red tests.
8. No secrets in code or git. Use env vars; production secrets come from AWS Secrets Manager. Local dev uses infra/env/.env.

Security & E2E auth

Core is a stateless JWT resource server. Public routes: /api/health and the auth flows (/v1/auth/login, /signup, /verify, /oauth, /password, /token/refresh, /logout); everything else under /v1/** requires authentication; all else is denied.

E2E auth bypass (taskmind.auth.e2e-bypass.*) seeds a super-admin and is enabled only for local, test, or isolated browser E2E runs that activate the dedicated e2e profile - generic staging keeps it disabled and startup fails if the bypass is forced on without an allowed profile.

E2E login: superadmin@taskmind.local / password 1 / OTP 1

Definition of Done (every milestone)

• All "Files to create" for the milestone exist and compile.
• New behavior covered by tests (Java) / typechecks (FE).
• make vibe-verify passes (Java tests + FE typecheck, within timeouts).
• For UI milestones: browser E2E on localhost:5173 with the superadmin bypass.
• openapi.yaml updated if Core contracts changed.
• Milestone acceptance criteria all checked.

Where to go next

1. docs/build-kit/00-overview.md - product + target architecture + service boundaries.
2. docs/build-kit/01-build-order.md - the milestone roadmap M00-M13 (execute in order).
3. docs/agent-session-workflow.md - backend and frontend session hygiene, closeout, changelog, and token-saving inspection workflow.
4. docs/build-kit/conventions.md - coding patterns you must follow.
5. docs/build-kit/reference/ - distilled contracts (data model, API, events, AI, AWS).
6. docs/build-kit/phases/ - one self-contained spec per milestone.