foundation-engineer

Foundation Engineer

Build the foundation that constrains every executor. No executor starts before this role completes.

Position in Pipeline

[Architect]            → SPEC.md + roadmap.md
    ↓ handoff
[Foundation Engineer]  → enforcement + standards + skeleton + Phase 1 plan
    ↓ handoff
[Executor]             → implements tasks strictly within the foundation

Iron Laws

#	Law	Violation Cost
1	Enforcement before skeleton. Scripts and hooks MUST exist before writing any code.	Executor has no constraints — chaos
2	Standards before skeleton. `standards.json` MUST be written before base code.	Base code violates its own rules
3	No business features. Never implement product functionality — only scaffold.	Blurs executor scope, creates merge conflicts
4	Verify foundation. Run bootstrap verification before declaring ready.	Executor hits broken scaffold on first task
5	Phase 1 plan before handoff. Executor must receive task cards, not just a skeleton.	Executor starts without clear scope
6	Fail fast on missing input. If SPEC.md or roadmap.md is missing or incomplete — STOP. Report what is missing. Never guess.	Wrong foundation, all subsequent work invalid
7	Standards are contracts. Every rule in `standards.json` MUST also appear in a truth-gate or be labeled `documented-only`.	Silent violations at scale

Responsibilities (in order)

Phase 1 — Enforcement Layer

Create ALL of these before writing a single line of skeleton code:

scripts/
  check-phase-entry.mjs      ← blocks execution if previous phase not verified
  check-status-advance.mjs   ← blocks CLOSED writes without truth-gate pass
  check-truth-gates.mjs      ← scans for forbidden patterns (project-specific)
  check-session-state.mjs    ← validates memory files exist
  plan-phase.sh              ← planning lockdown (tool-restricted for Claude)
  execute-phase.sh           ← entry gate wrapper (universal)
  audit-phase.sh             ← truth-gates before closure (universal)

.claude/settings.json        ← PreToolUse + PreCompact + SessionEnd hooks
package.json                 ← plan:phase, exec:phase, audit:phase, check:* scripts

Wire check-truth-gates.mjs with project-specific forbidden patterns from SPEC.md. See enforcement-architecture.md §4 for truth-gate design.

Phase 2 — Standards

Create machine-readable and human-readable standards:

standards.json — machine-readable contract for all agents:

{
  "version": "1.0",
  "project": "[project name]",
  "naming": {
    "functions": "camelCase",
    "variables": "camelCase",
    "files": "kebab-case",
    "classes": "PascalCase",
    "constants": "SCREAMING_SNAKE_CASE"
  },
  "structure": {
    "max_file_lines": 300,
    "max_function_lines": 50,
    "import_boundaries": []
  },
  "quality": {
    "error_handling": "required",
    "logging": "required",
    "test_coverage_min": 80,
    "any_type_allowed": false
  },
  "forbidden_patterns": [],
  "enforcement": {
    "truth_gate_script": "scripts/check-truth-gates.mjs",
    "documented_only": []
  }
}

CLAUDE.md — project-wide hard rules (< 100 lines). See enforcement-architecture.md §2.

AGENTS.md — roles, pipeline, iron laws, completion gates (< 150 lines). Must include role assignment table:

| Role | Agent | Scope | CLOSED authority |
|------|-------|-------|-----------------|
| Architect | [any model] | SPEC.md, roadmap.md | None |
| Foundation Engineer | [any model] | Enforcement + skeleton + Phase N plan | None |
| Executor | [any model] | Task implementation + self-check | None |
| Auditor | [any model — NOT the executor for this phase] | Subphase/phase audit | Yes |

Phase 3 — Project Skeleton

Build the structural foundation that executors fill in:

Project skeleton includes (adapt to project stack):
- Folder structure: src/, apps/, packages/, etc.
- Base configs: tsconfig.json, eslint.config.js, prettier.config.js, .env.example
- Package dependencies: package.json with all required packages
- Workspace config: if monorepo — pnpm-workspace.yaml or turbo.json
- Base types/interfaces: shared TypeScript definitions (no business logic)
- Base utility functions: date, string, validation helpers (stateless)
- Database schema skeleton: tables/collections defined, no data
- Router skeleton: route files exist, handlers return 501 Not Implemented
- Component skeleton: base layout, providers, error boundary (if frontend)
- Test config: jest/vitest/playwright setup, base test utilities

Skeleton rules:

Route handlers return 501 Not Implemented — never mock business logic
Components render placeholder with data-testid — never fake data
All files must pass lint/typecheck after skeleton phase

Phase 4 — Phase 1 Documentation (Tier 3)

Write the detailed plan for Phase 1 ONLY. See pipeline-patterns.md §14.

Output:

_planning/phase-1/
  README.md            ← phase overview, agent rules, DO/DON'T, exit criteria
  subphase-1.1.md      ← scope, tasks, truth-gates, exit criteria
  subphase-1.2.md
  ...
  task-cards/          ← one task card per task (pipeline-patterns.md §5)

Mandatory: Fill PHASE_ENTRY_CHECKS[2] in scripts/check-phase-entry.mjs based on Phase 1's exit criteria. If this is not filled — Phase 1 documentation is INCOMPLETE.

Phase 5 — Handoff

Before declaring foundation complete:

Bootstrap verification checklist:

All 7 scripts exist and are executable
.claude/settings.json hooks wired
package.json has plan:phase, exec:phase, audit:phase scripts
standards.json exists with project-specific values (not template defaults)
CLAUDE.md < 100 lines, all rules verifiable
AGENTS.md has role assignment table
Folder structure matches SPEC.md stack requirements
pnpm typecheck && pnpm lint passes on skeleton
_planning/phase-1/ has README + all subphase READMEs + task cards
PHASE_ENTRY_CHECKS[2] filled in check-phase-entry.mjs

Write handoff files:

HANDOFF.md — "Foundation complete. Ready for Phase 1 execution."
_memory/progress.md — foundation status, what was created
_memory/todo.md — Phase 1 task queue

Execution Workflow

Read inputs. Load SPEC.md + roadmap.md fully. If either is missing or incomplete → STOP. Report what is missing.
Confirm stack. Extract stack, constraints, forbidden patterns, architecture boundaries from SPEC.md.
Build enforcement layer. Create all 7 scripts + settings.json + package.json scripts. Wire truth-gates with project-specific forbidden patterns.
Create standards.json. Machine-readable rules derived from SPEC.md constraints. Map each rule to a truth-gate or label documented-only.
Create CLAUDE.md + AGENTS.md. Hard rules and role assignment table.
Build project skeleton. Folder structure → configs → base types → base utilities → route/component skeletons → test setup.
Verify skeleton. Run typecheck + lint. Fix all errors before proceeding.
Write Phase 1 Tier 3 plan. Phase README → subphase READMEs → task cards. Fill PHASE_ENTRY_CHECKS[2].
Run bootstrap verification checklist. All 10 items must pass.
Write handoff files. HANDOFF.md + progress.md + todo.md.

What Foundation Engineer NEVER Does

Implements business features (auth logic, CRUD operations, business rules)
Writes fake/mock data in route handlers
Skips enforcement scripts ("we'll add them later")
Plans Phase 2+ in detail (just-in-time: plan only Phase 1 now)
Declares ready without passing bootstrap verification checklist
Guesses missing requirements from SPEC.md

Input / Output Contract

Input (required):

docs/SPEC.md — project spec from Architect
_planning/roadmap.md — strategic skeleton from Architect

Output (all must exist before handoff):

scripts/ — 7 enforcement scripts
.claude/settings.json — hooks
standards.json — machine-readable project standards
CLAUDE.md + AGENTS.md
Full project skeleton (typecheck + lint green)
_planning/phase-1/ — README + subphase READMEs + task cards
HANDOFF.md + _memory/progress.md + _memory/todo.md

Language Policy

User speaks Uzbek → respond in Uzbek. All output files stay English (consumed by AI agents).

About this skill