12 — AI WORKFLOW

Depends on: 11_ROADMAP.md · Next: 13_PACKAGE_SELECTION_POLICY.md

How an AI agent acts as the entire software company. Fully autonomous — do not stop to ask for approval.

1. Roles the AI Plays

CTO · Architect · Full-Stack Engineer · AppSec/InfraSec · DevOps/SRE · DBA · UX/UI · QA Automation · SEO · Content

2. Session-Start Ritual (RUN BEFORE ANY CODING, EVERY SESSION)

# 1. Read memory fully
cat PROJECT_MEMORY.md
# 2. Verify toolchain
node --version
corepack pnpm --version
pnpm view next version && pnpm view react version && pnpm view prisma version && pnpm view zod version && pnpm view better-auth version
# 3. Health log
pnpm outdated -r  # log if newer stable exists, schedule upgrade

If newer stable of a core dep shipped mid-project → log in Dependency Health Log, schedule focused upgrade (tested, isolated PR).

3. Phase Execution Loop

Pick current phase in 11_ROADMAP.md (lowest incomplete)
  → Implement ONE module at a time:
     module.json → schema.prisma fragment → api.ts (Zod) → ui/page.tsx → docs.md → tests/
  → Run: pnpm -r build && pnpm -r typecheck && pnpm -r test
  → Run: bash scripts/grep-gates.sh && bash scripts/smoke.sh (if stack up)
  → Update PROJECT_MEMORY.md (Completed Features + Testing Results + Known Issues)
  → Repeat until all phase features meet "UI+API+DB+Tests+Docs" bar
  → Run full gates in 09_TESTING.md
  → Only then mark phase ✅ in PROJECT_MEMORY.md
  → Next phase

Never jump phases. Never commit with TODO/FIXME.

4. Documentation Discipline

Update PROJECT_MEMORY.md at end of every session and every phase gate — never bulk at end
Sections required (see PROJECT_MEMORY_TEMPLATE.md): Overview, Current Phase, Architecture (Mermaid), Technology Stack, Package Versions (pinned table + timestamp), Dependency Health Log, V1 Feature Inventory, Completed/Remaining Features, DB Structure, API Docs link, Security Decisions, Routes, Env Vars, Deployment, Testing Results (append-only), Known Issues, Future Roadmap
Success test: another agent can continue in <30 min from memory alone

5. Failure Policy

Failing command is information — diagnose root cause, fix, re-run — never || true, --force, or disabled rule without documented justified exception in PROJECT_MEMORY.md
Max 5 genuine fix attempts per blocker → then record under Known Issues with: full error output, hypothesis, next step, unblock plan → continue other work → revisit before Phase 1 (or corresponding phase) closes
Phase (or project) may not close with open security or build blockers

6. Package Decisions (Link to 13_PACKAGE_SELECTION_POLICY.md)

Before any pnpm add: score the package (see 13). Log scorecard in PROJECT_MEMORY.md. Only ≥90 installs.

7. Proof Artifacts

Every claim cites command + output pasted in TEST_REPORT.md or PROJECT_MEMORY.md:

corepack pnpm install --frozen-lockfile
pnpm -r build, pnpm -r typecheck, pnpm -r test
bash scripts/grep-gates.sh, bash scripts/smoke.sh, bash scripts/security-smoke.sh
pnpm audit --prod, pnpm licenses list

No claim without proof.

8. Delivery

When CHECKLIST.md all green and phase gates pass:

pnpm -r build
# verify zip excludes node_modules, .git, caches
bash scripts/build-zip.sh  # produces yas-enterprise-v3-production.zip (~250MB)
gitleaks detect --source yas-enterprise-v3-production.zip

Zip includes: source + Prisma migrations + seeds + .env.example + docs/ + PROJECT_MEMORY.md + TEST_REPORT.md + SECURITY.md + SBOM.spdx.json + docker/ + nginx/ + scripts/.

Next: 13_PACKAGE_SELECTION_POLICY.md — scoring.

12_AI_WORKFLOW