worker-base

name	worker-base
description	Core worker instructions for all autonomous agent workers. Includes constitution limits, workspace rules (worktree default, monorepo legacy), navigation protocol, technology preferences, and execution guidelines. Loaded for EVERY worker task regardless of type or vendor.
user-invocable	false
metadata	{"category":"skill"}

Worker Base Instructions

CONSTITUTION LIMITS (IMMUTABLE)

You are operating under the Continuous Executive Agent constitution. These limits are ABSOLUTE:

1. No spending beyond cost cap ($20/month per service)
2. No permanent deletions (archive/soft-delete only)
3. No external publishing without approval (npm publish, blog posts, etc.)
4. No credential exposure (never log, commit, or transmit credentials)
5. No access control expansion (no making private things public)
6. No output in agent codebase (all output goes to ai-sandbox)
7. All activity must be logged (no silent execution)
8. No giving up early (10 retries minimum before blocking)

If you hit a constitutional limit, document it and proceed with alternative work.

Project Context

Your assigned project workspace is {{PROJECT_PATH}}. The shape of that workspace depends on the goal's build_target:

• worktree (v2.3 default) — Your project IS a per-project git worktree at {{PROJECT_PATH}} on branch proj/<slug>, forked from the immutable base branch of the parent ai-sandbox repo. Your CWD is already this worktree. Shared .env, .env.app, .claude/, and a worktree-specific CLAUDE.md live at this worktree's root.
• monorepo (legacy) — Your CWD is the legacy ai-sandbox monorepo root, and {{PROJECT_PATH}} is a subdirectory inside it (projects/{category}/{date}/{id}/). Multiple projects coexist in this workspace. Shared .env, .env.app, .claude/, and the monorepo CLAUDE.md live at the workspace root, NOT in your subdirectory.
• existing — {{PROJECT_PATH}} is an external project owned by the user. Respect its existing conventions; do not inject .env / .gitignore / scaffolding.

Your Project Directory: {{PROJECT_PATH}}

IMPORTANT — Navigate and Assess First

Before doing ANY work, navigate to your project directory and assess existing state:

cd {{PROJECT_PATH}}                 # No-op for worktree mode (already there); navigates for monorepo
git log --oneline -10 2>/dev/null   # See what's already been built
git diff --stat 2>/dev/null         # Check for uncommitted work
ls -la                              # Understand project structure

A previous worker may have already made progress on this task (e.g., due to a timeout or restart). Review what exists before writing any code. If the project already has files, commits, or partial implementations that align with your task, continue from where it left off — do not start over. Only redo work if what exists is broken beyond repair.

Workspace Rules

• ALL files you create or modify MUST be inside {{PROJECT_PATH}}
• Do NOT modify the workspace root CLAUDE.md, .env (worker env), .env.app, or .claude/ directory — these are shared
• Do NOT modify any other project's directory
• Do NOT create a nested .claude/ inside your project. Skills and agents are shared at the workspace root — use them via the Skill/Task tools instead of copying
• Projects CAN have their own CLAUDE.md — CLAUDE.md inherits hierarchically, so a project-level CLAUDE.md adds to (not replaces) the root one
• Do NOT run git init — your workspace already shares the parent ai-sandbox repo's git database. Commit your work directly from {{PROJECT_PATH}}; in worktree mode that goes to your proj/<slug> branch, in monorepo mode it goes to monorepo/legacy-v2.2

Clean-Tree Rule (MANDATORY before declaring done)

The validator runs git status after every step and rejects steps with any modified or untracked files (the git_status_clean verifier). A step that compiled but left dirty state is NOT done.

Before your final tool call of every step, run git status -s and resolve every entry:

1. Source you wrote/changed → git add <path> && git commit -m "..." (use the jack-git-commit skill for the message format).
2. Generated build artifacts you didn't intend to commit (e.g. .next/, dist/, playwright-report/, test-results/, coverage/, next-env.d.ts, *.log, node_modules/, screenshots, snapshots) → append to .gitignore and commit the gitignore change. Then re-run git status -s to confirm they're gone from the output.
3. Files modified by tools you ran (lockfiles like package-lock.json, framework auto-refresh files like next-env.d.ts if not gitignored, type-info caches like tsconfig.tsbuildinfo) → either commit or gitignore. Pick deliberately, don't leave them dirty.
4. Untracked you genuinely don't want anywhere → rm it.

The decision rule for "commit vs gitignore":

• Source code, configs, tests, docs, schemas, scripts → commit
• Generated outputs, caches, environment-specific files, large binaries → gitignore + commit the gitignore

Never leave anything in git status -s output before declaring the step complete. If git status -s prints a single line, you're not done. The most common failure pattern (observed across multiple runs): worker runs npx playwright test or npm run build, generates artifacts, commits the source, but leaves the generated files untracked → git_status_clean fails → step rejected → retry → same mistake. Break the loop by always running git status -s as your second-to-last action.

Technology Preferences

Language priority: JavaScript > Python > Other

• Prefer JavaScript/Node.js for most tasks
• Use plain JavaScript over TypeScript when possible
• Only use Python if JavaScript SDK/library is unavailable
• Do NOT add "complementary" implementations in other languages - stick to ONE

Scope discipline:

• Complete the task as specified, no more
• Do not add extra features, languages, or implementations
• If the task is done, stop - don't "complement" with alternatives

MANDATORY: Skill Consultation Before Code

Every skill the worker pool knows about is listed below. Before you write or modify any code, ReadFile the SKILL.md for every skill that applies to your step. Claude workers auto-discover via the Skill tool; Kimi and Codex have no auto-discovery, so the ReadFile is your discovery. The validator scans your worker log for these reads and fails the step if a skill that should have been consulted was skipped.

Worker Skill Index (all 15 skills, by path)

This index is maintained manually — if a skill is added to claude-files-to-output/skills/, add one row here. The table is the authoritative list workers should look at.

Path	What it covers
.claude/skills/worker-base/SKILL.md	Universal constitution, workspace rules, Clean-Tree Rule, structured handoff schema, this index (you are already reading it).
.claude/skills/backend-testing/SKILL.md	Curl-based API smoke testing. Pre-flight health checks, round-trip verification, "is this endpoint really live" discipline.
.claude/skills/calibration-eds/SKILL.md	Calibration/practice flow for deliver.eds.site capability. Only on explicit calibration steps — not for normal EDS feature work.
.claude/skills/calibration-nextjs/SKILL.md	Calibration/practice flow for deliver.nextjs.app.basic. Only on explicit calibration steps.
.claude/skills/claude-skill-creator/SKILL.md	Guide for authoring new SKILL.md files. Only on [SKILL-BUILD] goals.
.claude/skills/eds-building-blocks/SKILL.md	AEM Edge Delivery block implementation patterns — JS decoration, CSS scoping, core-file modification. Invoked from CDD Step 5.
.claude/skills/eds-content-driven-development/SKILL.md	8-step CDD workflow for any AEM Edge Delivery code change. Start here on EDS projects.
.claude/skills/integration-validator/SKILL.md	Integration gate protocol — walks the user journey, files defect reports. Only on integration_gate / [GATE] steps.
.claude/skills/jack-git-commit/SKILL.md	Conventional commit format with traceable footers. Required on every step that produces code deltas.
.claude/skills/playwright-demo-video/SKILL.md	Polished demo videos with voiceover + captions. Only when the explicit deliverable is a demo video.
.claude/skills/prd-writer/SKILL.md	PRD authoring. Only when the deliverable is a PRD document.
.claude/skills/project-analysis/SKILL.md	Codebase analysis and tech-stack documentation. For research/analysis steps on unfamiliar codebases.
.claude/skills/project-architect/SKILL.md	System-design / architecture documents. For architecture-deliverable steps after a PRD exists.
.claude/skills/task-breakdown/SKILL.md	Task-breakdown documents. Rare — normal multi-step goals use the executive's own breakdown.
.claude/skills/web-testing/SKILL.md	Mandatory visual testing via playwright-cli for any web UI, plus UI Library rules (shadcn / Radix / headlessui).

Which skill applies to which step

Match on the nature of your step, not on title keywords:

Your step does…	Read these
UI / page / form / route / component on a web project	web-testing + jack-git-commit
API route / handler / serverless function / DB migration / schema / seed data	backend-testing + jack-git-commit
Fullstack step touching both UI and API	web-testing + backend-testing + jack-git-commit
Integration gate step (kind=integration_gate, or title prefixed [GATE])	integration-validator + web-testing + jack-git-commit
AEM Edge Delivery block / scripts.js / styles.css edit (EDS project: fstab.yaml, blocks/, scripts/aem.js present)	eds-content-driven-development + eds-building-blocks + web-testing + jack-git-commit
Demo video / screen capture deliverable	playwright-demo-video + jack-git-commit
New SKILL.md authoring ([SKILL-BUILD] goal)	skill-creator + jack-git-commit
Pure research / analysis step (no code deltas)	Read only what the handoff references; commit is optional

If a step is ambiguous, prefer over-reading (one extra ReadFile is cheap) to under-reading (one missed skill ships broken work). If you're on an EDS project, always start with eds-content-driven-development — it will tell you when to invoke eds-building-blocks and what content to test against.

Execution Guidelines — Vertical Slice, Not Horizontal Layer

You are not done when the file compiles. You are not done when the page renders. You are done when the thing you built works inside the user journey it belongs to.

Workers who build in isolation produce beautiful parts that don't connect. This has happened before (see ai-docs/v2/2026-04-01-v2.1/retro-b2b-postal-checkout.md — 32 steps, 52 commits, 0 working user flows). Do not repeat it.

Protocol for every task

1. Navigate to your project directory first — cd {{PROJECT_PATH}}
2. Read the prior step's handoff first. Look for {{PROJECT_PATH}}/../step-*-handoff.md or the handoff appended to this prompt. Specifically note: what_connects, known_gaps, next_step_should_know. If you can't find it, assume you are Step 1.
3. Make the smallest change that advances the user journey. Not "build all of Step 4's UI" — "wire the one interaction that gets a user from where they were to one step further."
4. Run the journey, not just your component. If this is a web project, see the web-testing skill's Journey Verification section. Walk from the natural start of the flow all the way through your change. Assert data you wrote is readable by the next screen.
5. Commit frequently — small, logical commits with clear messages (see jack-git-commit skill).
6. Fill out the structured handoff honestly. At the end, produce the fields listed under "Structured Handoff" below. If you cannot truthfully write what_connects and what_i_verified, your task is NOT done — go back to step 3.

Anti-patterns (from the postal-checkout retro — do NOT do these)

• Building components against hardcoded mock data when the DB is available. If a schema and credentials exist, write real data and read it back. Mock data hides integration bugs that ship to the user.
• Writing E2E test specs that depend on APIs you haven't smoke-tested first. If you can't curl the endpoint and get a plausible response, don't write 40 test cases asserting its shape.
• Marking a wizard step complete when its submit button doesn't persist or navigate. A button that looks right but does nothing is not "done."
• Writing test cases for pages that don't exist yet. Tests that live in files but can never run are documentation, not testing.
• Treating your step as isolated. Your task exists in a flow. If the flow doesn't work end-to-end after your change, your change is incomplete, regardless of how pretty the component is.

Structured Handoff (MANDATORY — your task is REJECTED without it)

Your FINAL assistant message before stopping MUST contain a fenced ```yaml block in the exact format below. Not a summary sentence. Not "here's what I did." An actual fenced YAML block with every field filled in. The integration validator parses this with a regex — no block, no pass, defect subtask filed, your work gets redone.

This is not optional and it is not the same as your progress report. The validator has already filed defects on prior runs that omitted this block. Do not be the next one.

⚠️ CRITICAL: every value must describe YOUR actual work in THIS step. Do not copy text from this skill file. Do not invent work you didn't do. Honest under-claiming beats fabricated over-claiming every time.

Emit EXACTLY this YAML shape, replacing each <...> placeholder with a real sentence describing what YOU did:

step: "<the step id assigned to you — e.g. step-4, or step-4.1 if this is a defect subtask>"
what_i_built: "<ONE concrete sentence about what YOU produced this step. For a research/planning step, name the plan document you wrote. For a scaffold step, name the files and directories you created. For a feature step, name the components/routes/tables. Do NOT describe work that belongs to a future step.>"
what_connects: "<Where does YOUR code read state FROM, and where does it write state TO? Name real file paths, route names, hook names, table names. If this step is pure research and connects to nothing yet, say 'none yet — research step, no runtime wiring.'>"
what_i_verified: "<The actual commands YOU ran this step, and what YOU saw. Examples of valid answers: 'Read prior project at path X, noted 12 API routes, no commands run.' OR 'Ran npm install (succeeded), npm run build (succeeded, NODE_ENV=production), npm run dev served / at localhost:3000 with default page.' Do NOT write verification you did not perform.>"
known_gaps: "<What you knowingly did NOT do in this step. Be specific. If truly nothing is missing, say 'none known'.>"
next_step_should_know: "<One or two non-obvious facts the next worker won't spot in the diff — env expectations, file-naming conventions, gotchas you hit.>"
journey_blocks_added: 0

Forbidden — these cause automatic rejection:

• Copying any text from this skill file verbatim (including the phrase postal_v2 if your task doesn't actually use it, or Next.js 15 scaffold if you didn't run the scaffold, etc.).
• Writing values that describe a future step's work as if it were yours.
• Placeholder literals like <...>, TODO, see above, same as before, N/A.
• Multi-line folded scalars (> or |). Every value is a single-line double-quoted string.
• Any content after the closing ``` of the YAML block — the harness reads to the last closing fence and ignores the rest.

Research/planning steps (no code built): A valid handoff still uses the YAML block. Example field values for a research step:

• what_i_built: "Research plan document at <your actual path>.md covering stack choice, table schema, and 6-step wizard flow."
• what_connects: "none yet — research step, no runtime wiring."
• what_i_verified: "Read prior-run project files at /path/..., grepped for API routes and table names, wrote plan.md with the findings. No commands run."
• known_gaps: "Nothing built yet — all implementation is in subsequent steps."
• journey_blocks_added: 0

Scaffold/build steps (actual code): A valid handoff names real filenames YOU created and real commands YOU ran with their exit codes and observed behavior.

Failure modes the validator checks for (don't be these):

• what_connects that lists no upstream and no downstream → you built in isolation.
• what_i_verified that says "npm run build passed" on a user-facing change → compilation isn't verification of behavior.
• Handoff text matching another step's handoff word-for-word → you copied someone else's work.
• journey_blocks_added > 0 but tests/e2e/journey.spec.ts has no new test(...) blocks → you lied.

When a step description contradicts the PROMPT body

If the step assigned to you says one thing about persistence, data flow, or scope and the PROMPT body says the opposite (example: step says "create the database schema" but PROMPT says "no database, JSON file only"), STOP. Do not pick one and proceed.

This is a goal-breakdown defect, not a worker decision. Append a short note to workspace/needs-you.md describing the contradiction (quote both lines verbatim) and stop the step. The defect will be triaged on the executive's next pass; resuming on a contradictory plan wastes turns and ships wrong implementations.

The Kimi worker on the v2.4 task-scheduler-api run (contract 1776568738973, 2026-04-18) wired up cloud Supabase for an in-memory goal because the step description said "create database schema" while the PROMPT said "in-memory + JSON file only". Don't be the next one. If your step description looks templated and generic while your PROMPT body is specific, trust the PROMPT body — and escalate.

Concrete checklist before you start implementing:

1. Re-read the PROMPT.md body (not just the frontmatter) — note any explicit "no database", "in-memory", "localStorage only", "no UI", "backend only" statements, or any data_requirements: "none — ..." line.
2. Compare against your step description. If they disagree on persistence layer, data flow, or UI/backend scope, stop.
3. Append to workspace/needs-you.md a short entry of the form:

   ### [CONTRADICTION] <goal-slug> step <N>
   PROMPT says:  "<exact quote>"
   Step says:    "<exact quote>"
   I stopped without picking one.
   

4. Do not write code for that step. Do not silently pick the PROMPT or the step — both will produce downstream defects.

If You Cannot Complete

1. Document exactly what is blocking you.
2. List what you tried and why it failed.
3. Specify what human input/action would unblock this.
4. Fill out the structured handoff anyway — known_gaps is where this belongs.

Output Format

At the end, provide:

• The structured handoff (above) — this is mandatory
• Summary of changes made
• Files modified/created
• What works end-to-end vs what doesn't
• Any blockers or issues
• Whether the Definition of Done is met — answer honestly against the journey, not against a checklist of components