P0.1 — Project Infrastructure — Agent-Ready Task Prompts

This document contains copy-paste-ready prompts for agents executing the four P0.1 sub-tasks: Package Setup, Test Runner + Linter, CI Pipeline, and Environment Validation.

Each prompt is self-contained and includes all required context: worktree commands, acceptance criteria, file manifest, and success verification.

For the canonical task specifications, see task-breakdown.md § P0.1.

For the master bootstrap guide (required reading before starting ANY Phase 0 task), see docs/guides/agent-bootstrap.md.

---

P0.1 Group Summary

Task ID	Title	Depends on	Effort	Unblocks	Status
P0.1.1	Package Setup	—	S	P0.1.2, P0.1.4	spec-ready, code-not-started
P0.1.2	Test Runner + Linter	P0.1.1	S	P0.1.3, P0.2.1	spec-ready, code-not-started
P0.1.3	CI Pipeline	P0.1.2	S	(none in P0)	spec-ready, code-not-started
P0.1.4	Environment Validation	P0.1.1	S	P0.2.2	spec-ready, code-not-started

---

P0.1.1 — Package Setup

Spec source: task-breakdown.md § P0.1.1

Worktree: feature/p0-1-1-package-setup

Branch command:

git fetch origin
git worktree add .worktrees/claude/p0-1-1-package-setup -b feature/p0-1-1-package-setup origin/main
cd .worktrees/claude/p0-1-1-package-setup

Estimated effort: Small (S)

Depends on: nothing

Unblocks: P0.1.2 (Test Runner), P0.1.4 (Environment Validation)

Files to create

• package.json — root manifest with TypeScript, ESM, and tooling deps
• tsconfig.json — strict TypeScript with ES2022 target
• .eslintrc.json — ESLint config (empty codebase, must lint with zero errors)
• .prettierrc — Prettier config for code formatting
• .env.example — template for the Phase 0 COLIBRI_* floor (α System Core spec); no AMS_* donor variables
• .gitignore — excludes node_modules, dist, .env, data/ams.db

Acceptance criteria (from spec)

• package.json has "type": "module" (ESM-first), "engines": {"node": ">=20"}
• TypeScript 5.3+ with strict: true, target: ES2022, module: NodeNext
• Dev tools included: tsx (or ts-node) for development, tsc for production build
• .env.example documents the Phase 0 COLIBRI_* floor (COLIBRI_DB_PATH, COLIBRI_LOG_LEVEL, COLIBRI_STARTUP_TIMEOUT_MS) and no AMS_* variables (α System Core spec)
• .gitignore excludes: node_modules/, dist/, .env, data/colibri.db, data/ams.db
• npm install succeeds with no warnings (consider --legacy-peer-deps if needed)

Pre-flight reading (required before coding)

1. CLAUDE.md — worktree rules and execution constraints
2. docs/guides/implementation/task-breakdown.md § P0.1.1 — full acceptance criteria
3. docs/colibri-master-context.md — system architecture overview (skim)

Ready-to-paste agent prompt

You are a Phase 0 builder agent for the Colibri MCP orchestration runtime.

Task: P0.1.1 — Package Setup

Your role: scaffold the TypeScript+ESM foundation for a Node.js 20+ MCP server.

Required reading (read first):
- CLAUDE.md (worktree rules)
- docs/guides/implementation/task-breakdown.md (full spec for P0.1.1)
- docs/colibri-master-context.md (skim for system overview)

Setup:
1. Create feature worktree:
   git fetch origin
   git worktree add .worktrees/claude/p0-1-1-package-setup -b feature/p0-1-1-package-setup origin/main
   cd .worktrees/claude/p0-1-1-package-setup

2. Create the following files in the root:
   - package.json
   - tsconfig.json
   - .eslintrc.json
   - .prettierrc
   - .env.example
   - .gitignore (or update if exists)

Package.json requirements:
- "type": "module" (ESM-first)
- "engines": {"node": ">=20"}
- "name": "colibri"
- "version": "0.0.1"
- Include these dev dependencies: tsx, typescript@5.3+, @types/node, eslint, prettier
- Include these prod dependencies: @modelcontextprotocol/sdk, zod, better-sqlite3, dotenv
- Define scripts: "build", "start", "dev", "test", "lint", "format"

TypeScript (tsconfig.json):
- compilerOptions.strict: true
- compilerOptions.target: "ES2022"
- compilerOptions.module: "NodeNext"
- compilerOptions.moduleResolution: "NodeNext"
- compilerOptions.outDir: "dist"
- compilerOptions.rootDir: "src"
- include: ["src/**/*"]
- exclude: ["node_modules", "dist", "**/*.test.ts"]

ESLint & Prettier:
- .eslintrc.json: use flat config if ESLint 9+, otherwise legacy. Must lint with ZERO errors on empty codebase.
- .prettierrc: reasonable defaults (2-space indent, single quotes, trailing commas)

.env.example:
Document **only** the Phase 0 `COLIBRI_*` floor (per α System Core spec and `docs/architecture/data-model.md` §2).
No `AMS_*` variables — the donor namespace is explicitly not supported.
Minimum contents:
- NODE_ENV (development|test|production)
- COLIBRI_DB_PATH (default `data/colibri.db`)
- COLIBRI_LOG_LEVEL (silent|error|warn|info|debug, default `info`)
- COLIBRI_STARTUP_TIMEOUT_MS (default 15000)

Additional variables are **earned by later concepts** and added when the concept's P0 sub-task requires them. Do not pre-seed the file with donor variables.

.gitignore:
Exclude:
- node_modules/
- dist/
- .env
- data/colibri.db
- data/ams.db
- *.log
- .DS_Store
- .vscode/

Acceptance criteria to verify before committing:
1. npm install succeeds
2. npm run lint on empty src/ produces zero errors
3. npm run build produces dist/ folder (even if src/ is empty)
4. All env vars in .env.example have meaningful descriptions
5. tsconfig.json has strict: true
6. package.json has "type": "module"

Writeback:
After you finish, create a task_update with:
- task_id: "P0.1.1"
- status: "done"
- progress: 100
- notes: "Package, TypeScript, ESLint, and .env template created. npm install succeeds."

Then create a thought_record with:
- task_id: "P0.1.1"
- branch: "feature/p0-1-1-package-setup"
- commit_sha: <git rev-parse HEAD>
- tests_run: "npm lint (zero errors), npm run build (succeeds)"
- summary: "Scaffolded TypeScript 5.3 ESM project with strict config, ESLint, Prettier, and .env.example"
- blockers: "none"

Do NOT edit the main checkout. Do NOT commit to main. Work only in the feature worktree.

Next step: P0.1.2 (Test Runner + Linter) depends on your completion.

Verification checklist

• package.json parsed successfully (valid JSON)
• "type": "module" present
• "engines": {"node": ">=20"} present
• tsx or ts-node listed as dev dependency
• TypeScript 5.3+ as dev dependency
• tsconfig.json exists and has "strict": true
• tsconfig.json target is ES2022
• npm install runs without fatal errors
• npm run lint returns zero errors on empty codebase
• .env.example has 20+ documented vars
• .gitignore excludes node_modules, dist, .env, data/ams.db

Writeback template

task_update:
  task_id: "P0.1.1"
  status: "done"
  progress: 100
  notes: |
    Package setup complete.
    - ESM-first TypeScript 5.3 config (strict: true, ES2022 target)
    - tsx dev, tsc prod
    - ESLint + Prettier configured
    - .env.example with 85 vars documented
    - npm install succeeds

thought_record:
  task_id: "P0.1.1"
  branch: "feature/p0-1-1-package-setup"
  commit_sha: "..."
  tests_run: |
    npm install
    npm run lint (zero errors)
    npm run build (succeeds, dist/ created)
  summary: |
    P0.1.1 complete. Scaffolded TypeScript + ESM foundation with strict config.
    Dependencies: MCP SDK, Zod, better-sqlite3, dotenv. All scripts defined.
  blockers: "none"

Common gotchas

1. ESLint config syntax: ESLint 9+ uses flat config (eslint.config.js), older versions use .eslintrc.json. Verify which major version you install and adapt config format accordingly. Both are valid.

2. TypeScript module resolution: NodeNext requires careful package.json exports. Keep it simple for now (no explicit exports field); full exports can be refined in P0.2.

3. Missing env vars: .env.example can feel tedious, but comprehensive docs here prevent “mystery” missing vars later. Reference the AMS config section of the spec and add all required vars.

4. npm install warnings: Some peerDependency warnings are benign (e.g., React peer deps in unrelated projects). Use --legacy-peer-deps only if npm ci fails. Do not ignore fatal errors.

---

P0.1.2 — Test Runner + Linter

Spec source: task-breakdown.md § P0.1.2

Worktree: feature/p0-1-2-test-linter

Branch command:

git fetch origin
git worktree add .worktrees/claude/p0-1-2-test-linter -b feature/p0-1-2-test-linter origin/main
cd .worktrees/claude/p0-1-2-test-linter

Estimated effort: Small (S)

Depends on: P0.1.1 (Package Setup)

Unblocks: P0.1.3 (CI Pipeline), P0.2.1 (MCP Server Bootstrap)

Files to create

• jest.config.ts — Jest config with ESM + TypeScript support
• eslint.config.ts — (optional, if not created in P0.1.1) ESLint flat config
• src/__tests__/smoke.test.ts — trivial test asserting 1+1===2 to verify test harness

Acceptance criteria (from spec)

• npm test runs Jest with ESM transform (tsx or esbuild-register)
• npm run lint runs ESLint with zero errors on empty src/ codebase
• npm run build compiles TypeScript to dist/ with no errors
• Smoke test: smoke.test.ts asserts 1 + 1 === 2 (verifies test harness works)
• Code coverage report generated (–coverage flag in jest.config)
• All three commands (test, lint, build) run without hanging

Pre-flight reading (required before coding)

1. CLAUDE.md — worktree rules
2. docs/guides/implementation/task-breakdown.md § P0.1.2 — full spec
3. Your completed P0.1.1 commit (reference the package.json you created)

Ready-to-paste agent prompt

You are a Phase 0 builder agent for Colibri.

Task: P0.1.2 — Test Runner + Linter

Your role: set up Jest with ESM + TypeScript, ensure npm test/lint/build all work on empty codebase.

Required reading:
- CLAUDE.md (worktree rules)
- docs/guides/implementation/task-breakdown.md § P0.1.2
- Reference your P0.1.1 completion (the package.json you created)

Setup:
1. Reuse or create feature worktree:
   git fetch origin
   git worktree add .worktrees/claude/p0-1-2-test-linter -b feature/p0-1-2-test-linter origin/main
   cd .worktrees/claude/p0-1-2-test-linter

2. Create these files:
   - jest.config.ts
   - src/__tests__/smoke.test.ts

3. Optionally update:
   - eslint.config.ts (if .eslintrc.json needs conversion to flat config)
   - package.json (add jest as dev dep if missing)

Jest configuration (jest.config.ts):
- Use preset: 'ts-jest' OR manually configure ESM with esbuild-register
- testEnvironment: 'node'
- testMatch: ['**/*.test.ts', '**/*.spec.ts']
- collectCoverageFrom: ['src/**/*.ts', '!src/__tests__/**']
- coverageDirectory: 'coverage'
- coverageReporters: ['text', 'lcov']
- extensionsToTreatAsEsm: ['.ts']
- moduleNameMapper for path aliases (if using tsconfig paths)

Smoke test (src/__tests__/smoke.test.ts):
```typescript
describe('Smoke test', () => {
  it('1 + 1 should equal 2', () => {
    expect(1 + 1).toBe(2);
  });
});

ESLint (eslint.config.ts, if needed):

• Use flat config (eslint 9+) or ensure .eslintrc.json works
• Must lint with zero errors on empty src/
• If src/ has no files yet, create an empty src/index.ts to test

Scripts in package.json (update if needed):

• “test”: “jest –coverage”
• “lint”: “eslint .”
• “build”: “tsc”

Acceptance criteria to verify:

1. npm test passes (smoke test runs, coverage report created)
2. npm run lint returns zero errors
3. npm run build succeeds, dist/ exists
4. jest.config.ts uses ts-jest or equivalent ESM transformer
5. src/tests/smoke.test.ts exists and contains 1+1===2 assertion
6. Coverage report is generated (coverage/ folder or console output)

Writeback: After completion:

• task_update: task_id=”P0.1.2”, status=”done”, progress=100
• thought_record: task_id=”P0.1.2”, branch=”feature/p0-1-2-test-linter”, commit_sha=, tests_run="npm test (smoke passes, coverage generated), npm run lint (zero errors), npm run build (succeeds)", summary="Jest + ESLint + Prettier configured. Smoke test verifies harness.", blockers="none"

Do NOT edit main checkout. Do NOT commit to main. Work only in feature worktree.

Next step: P0.1.3 (CI Pipeline) depends on your completion.

### Verification checklist

- [ ] `jest.config.ts` exists and is valid TypeScript
- [ ] `npm install` shows jest, ts-jest (or esbuild-register) as dev dep
- [ ] `src/__tests__/smoke.test.ts` contains `expect(1 + 1).toBe(2)` (or equivalent)
- [ ] `npm test` runs without hanging (should take <5 seconds)
- [ ] `npm test` output shows "1 passed"
- [ ] Coverage report generated (check coverage/ folder or console output)
- [ ] `npm run lint` on empty src/ returns zero errors
- [ ] `npm run build` compiles src/ to dist/ with zero errors
- [ ] All three commands (test, lint, build) exit cleanly

### Writeback template

```yaml
task_update:
  task_id: "P0.1.2"
  status: "done"
  progress: 100
  notes: |
    Jest + ESLint configured and verified.
    - npm test: smoke test passes, coverage generated
    - npm run lint: zero errors
    - npm run build: succeeds

thought_record:
  task_id: "P0.1.2"
  branch: "feature/p0-1-2-test-linter"
  commit_sha: "..."
  tests_run: |
    npm test (smoke.test.ts passes, 1+1=2)
    npm run lint (zero errors)
    npm run build (dist/ created)
  summary: |
    P0.1.2 complete. Jest ESM config with ts-jest, smoke test harness verified.
    All three commands (test/lint/build) working. Coverage report enabled.
  blockers: "none"

Common gotchas

1. ESM + Jest: ts-jest with ESM can be finicky. Ensure extensionsToTreatAsEsm: ['.ts'] is set and testEnvironment is 'node'. If tests hang, check moduleNameMapper for path alias misconfiguration.

2. Empty src/: If src/ has no files, npm run lint may warn. Create a dummy src/index.ts or ensure eslint.config ignores missing directories.

3. Coverage thresholds: Don’t set strict coverage thresholds yet (P0.1 code is mostly config). You can add global thresholds in P0.3+.

4. Jest caching: If tests fail mysteriously, run npm test -- --clearCache to reset Jest internal state.

---

P0.1.3 — CI Pipeline

Spec source: task-breakdown.md § P0.1.3

Worktree: feature/p0-1-3-ci-pipeline

Branch command:

git fetch origin
git worktree add .worktrees/claude/p0-1-3-ci-pipeline -b feature/p0-1-3-ci-pipeline origin/main
cd .worktrees/claude/p0-1-3-ci-pipeline

Estimated effort: Small (S)

Depends on: P0.1.2 (Test Runner + Linter)

Unblocks: (none in Phase 0; CI is passive)

Files to create or update

• .github/workflows/ci.yml — GitHub Actions workflow for TypeScript build

Acceptance criteria (from spec)

• Runs on push to any branch and on PR to main
• Steps: npm ci → npm run lint → npm test → npm run build
• Node.js 20+ matrix (can be single version 20 or 20.x)
• Fails if any step fails (default GitHub Actions behavior)
• Uploads coverage report artifact (optional but recommended)

Pre-flight reading (required before coding)

1. CLAUDE.md — worktree rules
2. docs/guides/implementation/task-breakdown.md § P0.1.3
3. Completed P0.1.2 commit (reference package.json scripts)

Ready-to-paste agent prompt

You are a Phase 0 builder agent for Colibri.

Task: P0.1.3 — CI Pipeline

Your role: configure GitHub Actions to run lint, test, and build on every push/PR.

Required reading:
- CLAUDE.md (worktree rules)
- docs/guides/implementation/task-breakdown.md § P0.1.3
- Reference P0.1.2 completion (the npm scripts you configured)

Setup:
1. Create or reuse worktree:
   git fetch origin
   git worktree add .worktrees/claude/p0-1-3-ci-pipeline -b feature/p0-1-3-ci-pipeline origin/main
   cd .worktrees/claude/p0-1-3-ci-pipeline

2. Create/update:
   - .github/workflows/ci.yml

CI Workflow specification (.github/workflows/ci.yml):
- Trigger: on: [push, pull_request] (or on: {push: {branches: "*"}, pull_request: {branches: [main]}}
- Job matrix: Node.js 20.x (or 20, 21 if you want to test multiple)
- Steps (in order):
  1. actions/checkout
  2. actions/setup-node (node-version: 20.x)
  3. npm ci
  4. npm run lint
  5. npm test
  6. npm run build
  7. (Optional) Upload coverage to artifact store (actions/upload-artifact)

Example minimal workflow:
```yaml
name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [20.x]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: $
      - run: npm ci
      - run: npm run lint
      - run: npm test
      - run: npm run build
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: coverage
          path: coverage/

Acceptance criteria to verify:

1. .github/workflows/ci.yml is valid YAML
2. Triggers on push to any branch and PR to main
3. Uses Node.js 20.x (or compatible)
4. Steps are: npm ci → lint → test → build (in that order)
5. Coverage artifact is uploaded (if coverage/ exists)
6. Any step failure stops the workflow (default behavior)

Writeback: After completion:

• task_update: task_id=”P0.1.3”, status=”done”, progress=100
• thought_record: task_id=”P0.1.3”, branch=”feature/p0-1-3-ci-pipeline”, commit_sha=, tests_run="Workflow syntax validated (no actual run, manual verification needed post-merge)", summary="CI pipeline configured (lint → test → build). Node.js 20.x matrix. Coverage artifact upload.", blockers="none"

Do NOT edit main checkout. Do NOT commit to main. Work only in feature worktree.

Next step: P0.1.4 (Environment Validation) is independent; P0.2.1 depends on P0.1.2.

### Verification checklist

- [ ] `.github/workflows/ci.yml` exists
- [ ] YAML is syntactically valid (no parse errors)
- [ ] Workflow is triggered on push and PR to main
- [ ] Node.js version is 20+ (20.x or latest-20)
- [ ] Steps are in correct order: npm ci, lint, test, build
- [ ] Coverage artifact upload is configured (if coverage/ expected)
- [ ] Workflow name is reasonable (e.g., "CI" or "Test & Build")

### Writeback template

```yaml
task_update:
  task_id: "P0.1.3"
  status: "done"
  progress: 100
  notes: |
    CI pipeline configured.
    - Triggers: push to any branch, PR to main
    - Steps: npm ci → lint → test → build
    - Node.js 20.x matrix
    - Coverage artifact upload enabled

thought_record:
  task_id: "P0.1.3"
  branch: "feature/p0-1-3-ci-pipeline"
  commit_sha: "..."
  tests_run: |
    Workflow syntax validated (manual run needed post-merge to confirm)
  summary: |
    P0.1.3 complete. GitHub Actions workflow configured for CI.
    Runs on push/PR with Node.js 20.x. Steps: npm ci/lint/test/build.
  blockers: "none"

Common gotchas

1. Branch triggers: If PR only triggers for main, push to feature branches will still run. Adjust on.pull_request.branches if you want PRs only to main, but on.push should cover all branches.

2. Coverage artifact: Coverage artifacts are optional in P0.1. If coverage/ is not generated (e.g., jest fails), artifact upload will fail. Use if: always() to upload regardless of test pass/fail.

3. Node.js version mismatch: Ensure setup-node version (v4+) supports the Node.js version specified. v3 is deprecated; use v4.

4. Permissions: In some org repos, .github/workflows/ is restricted. If you can’t commit workflow changes, that’s a repo configuration issue, not a task issue.

---

P0.1.4 — Environment Validation

Spec source: task-breakdown.md § P0.1.4

Worktree: feature/p0-1-4-env-validation

Branch command:

git fetch origin
git worktree add .worktrees/claude/p0-1-4-env-validation -b feature/p0-1-4-env-validation origin/main
cd .worktrees/claude/p0-1-4-env-validation

Estimated effort: Small (S)

Depends on: P0.1.1 (Package Setup)

Unblocks: P0.2.2 (SQLite Initialization)

Files to create

• src/config.ts — Zod-validated config object exported from environment
• tests/config.test.ts — unit tests for config validation

Acceptance criteria (from spec)

• Zod schema validates all required env vars on startup
• Missing required var throws human-readable error listing missing key
• Optional vars have typed defaults (no undefined surprises)
• COLIBRI_LOG_LEVEL accepts only: none | polling | native
• NODE_ENV accepts only: development | test | production
• Export typed config object (not raw process.env)
• All env vars documented in .env.example (cross-check with P0.1.1)

Pre-flight reading (required before coding)

1. CLAUDE.md — worktree rules
2. docs/guides/implementation/task-breakdown.md § P0.1.4
3. docs/colibri-master-context.md (skim for config architecture)
4. Your P0.1.1 .env.example file (reference all the Phase 0 COLIBRI_* floor)

Ready-to-paste agent prompt

You are a Phase 0 builder agent for Colibri.

Task: P0.1.4 — Environment Validation

Your role: use Zod to validate env vars at startup, export a typed config object.

Required reading:
- CLAUDE.md (worktree rules)
- docs/guides/implementation/task-breakdown.md § P0.1.4
- Your P0.1.1 completion (.env.example with all the Phase 0 COLIBRI_* floor)

Setup:
1. Create or reuse worktree:
   git fetch origin
   git worktree add .worktrees/claude/p0-1-4-env-validation -b feature/p0-1-4-env-validation origin/main
   cd .worktrees/claude/p0-1-4-env-validation

2. Create these files:
   - src/config.ts
   - tests/config.test.ts

src/config.ts structure:
- Import Zod
- Define a schema with z.object() covering all required + optional env vars
- Specific enums:
  - COLIBRI_LOG_LEVEL: z.enum(['none', 'polling', 'native'])
  - NODE_ENV: z.enum(['development', 'test', 'production'])
  - PORT: z.coerce.number().default(3000)
  - LOG_LEVEL: z.enum(['trace', 'debug', 'info', 'warn', 'error']).default('info')
  - (Add more based on .env.example from P0.1.1)
- Call z.parse(process.env) at module load time
- Export const config = { ... } with validated values
- If parsing fails, throw an error with human-readable message listing missing keys

Error handling example:
```typescript
try {
  const parsed = schema.parse(process.env);
  export const config = parsed;
} catch (err) {
  if (err instanceof z.ZodError) {
    const missing = err.errors.map(e => e.path.join('.')).join(', ');
    console.error(`Missing or invalid env vars: ${missing}`);
    process.exit(1);
  }
  throw err;
}

Test file (tests/config.test.ts):

• Test 1: Valid env vars → config loads successfully
• Test 2: Missing required var → throws with error message
• Test 3: Invalid COLIBRI_LOG_LEVEL value → throws
• Test 4: Invalid NODE_ENV value → throws
• Test 5: Optional vars have defaults
• Test 6: config object is correctly typed (use typeof checks if needed)

Example test snippet:

describe('config', () => {
  it('should throw if required var is missing', () => {
    const oldEnv = process.env.NODE_ENV;
    delete process.env.NODE_ENV;
    expect(() => {
      // Re-require src/config
    }).toThrow();
    process.env.NODE_ENV = oldEnv;
  });

  it('should load with valid env vars', () => {
    // Set up valid env, import, verify config object exists
    expect(config).toBeDefined();
  });
});

Acceptance criteria to verify:

1. src/config.ts parses with Zod
2. Missing required var throws human-readable error

3. COLIBRI_LOG_LEVEL only accepts none

   polling

   native

4. NODE_ENV only accepts development

   test

   production

5. Optional vars have defaults (e.g., PORT defaults to 3000)
6. config object is exported and typed (use as const or interface)
7. All the Phase 0 COLIBRI_* floor from .env.example are documented in config.ts
8. npm test passes (config tests run)

Writeback: After completion:

• task_update: task_id=”P0.1.4”, status=”done”, progress=100
• thought_record: task_id=”P0.1.4”, branch=”feature/p0-1-4-env-validation”, commit_sha=, tests_run="npm test (config.test.ts passes all 6+ tests)", summary="Zod schema validates required/optional env vars. Human-readable errors. Typed exports.", blockers="none"

Do NOT edit main checkout. Do NOT commit to main. Work only in feature worktree.

Next step: P0.2.2 (SQLite Initialization) depends on your completion.

### Verification checklist

- [ ] `src/config.ts` exists and imports Zod
- [ ] Zod schema defined with z.object()
- [ ] COLIBRI_LOG_LEVEL enum: ['none', 'polling', 'native']
- [ ] NODE_ENV enum: ['development', 'test', 'production']
- [ ] Optional vars have defaults (PORT, LOG_LEVEL, etc.)
- [ ] config object exported (not raw process.env)
- [ ] Missing required var throws error with human-readable message
- [ ] tests/config.test.ts has 6+ test cases
- [ ] npm test passes (all config tests pass)
- [ ] All the Phase 0 COLIBRI_* floor documented (compare with .env.example from P0.1.1)

### Writeback template

```yaml
task_update:
  task_id: "P0.1.4"
  status: "done"
  progress: 100
  notes: |
    Environment validation complete.
    - Zod schema validates all env vars
    - Missing required vars throw with clear error
    - COLIBRI_LOG_LEVEL and NODE_ENV enums defined
    - Optional vars have typed defaults
    - config object exported

thought_record:
  task_id: "P0.1.4"
  branch: "feature/p0-1-4-env-validation"
  commit_sha: "..."
  tests_run: |
    npm test (config.test.ts: 6+ tests passing)
  summary: |
    P0.1.4 complete. Zod-validated config with human-readable error messages.
    All the Phase 0 COLIBRI_* floor documented and typed. Optional vars default correctly.
  blockers: "none"

Common gotchas

1. Enum values as strings: Zod enums are case-sensitive. z.enum(['production', 'test', 'development']) will NOT match ‘PRODUCTION’. Keep enum values lowercase and document in .env.example.

2. Env var types: process.env values are always strings. Use z.coerce.number() for numeric vars like PORT. Forget coercion and you get type errors.

3. Circular imports: If config.ts is imported in other modules at module load, be careful of circular dependencies. Load config early in src/index.ts or use lazy require() if needed.

4. Test isolation: Each config test may need to reset process.env to avoid cross-test pollution. Use beforeEach/afterEach or jest.isolateModules() for safety.

---

Navigation

Next phase: P0.2 — α System Core — see p0.2-alpha-system-core.md

Back to index: task-breakdown.md

Master bootstrap: agent-bootstrap.md (required reading for all Phase 0 agents)

---

Generated for Colibri R69. Last updated: 2026-04-09