Templates

For Lecture 03's bounded validation refactor, use the repository instructions, task brief, handover, and runnable fixture. Those templates include verified fixture commands and distinguish guidance from enforcement.

Copy any of these files directly into your repository. They form the minimal harness pack — the three files every agentic project needs to function reliably.

AGENTS.md

The static context file. Commit it to your repository root. Every agent session reads it first.

# AGENTS.md

## About this repo
[One paragraph: what this codebase does, its main tech stack, and its purpose]

## Build & test
- Install: `npm install`
- Test: `npm test`
- Lint: `npm run lint`
- Build: `npm run build`
- Type check: `npm run typecheck`

## Scope rules
- NEVER modify files outside the directories listed in feature_list.json scope fields
- NEVER edit: package-lock.json, .env, any file in infra/ or .github/
- ALWAYS stay within the scope defined for the active task

## Architecture rules
- All external API calls go through src/api/client.ts
- All data validation uses zod schemas in src/schemas/
- No direct database queries outside src/db/
- All new modules must have a corresponding test file

## Session protocol
1. Read feature_list.json — identify the highest-priority pending task
2. Update the task status to "in_progress" in feature_list.json
3. Implement the task within the defined scope
4. Run the full verification pipeline (test + lint + build)
5. If verification passes: mark task "complete" in feature_list.json
6. If verification fails: mark task "failed", write failure details to progress.md
7. Update progress.md with session summary
8. Never mark a task complete if any test or lint check is failing

## Human checkpoints
Stop and write a review request to reviews/YYYY-MM-DD-review.md if:
- You need to modify a file outside your scope to complete the task
- Tests fail more than 3 times in a row
- The task description conflicts with these rules
- You are about to modify a shared interface or schema

feature_list.json

The task registry. The agent reads this to find its next task and writes back status updates.

{
  "version": "1.0",
  "project": "your-project-name",
  "updated": "2026-04-17",
  "features": [
    {
      "id": "feat-001",
      "title": "Short, imperative task title",
      "status": "pending",
      "priority": "high",
      "scope": [
        "src/module-name/",
        "tests/module-name/"
      ],
      "acceptance": [
        "Specific, verifiable criterion 1",
        "Specific, verifiable criterion 2",
        "npm test passes with no failures",
        "npm run lint passes with no errors"
      ],
      "notes": "",
      "sessions": []
    }
  ]
}

Status values: pending → in_progress → complete | failed | blocked

progress.md

The session state file. Updated at the end of every agent session.

# Agent Progress

## Current session
- **Date**: YYYY-MM-DD
- **Status**: [not started | in progress | complete | blocked]
- **Active task**: [feat-id or "none"]
- **Verification**: [not run | passed | failed]

## Last session summary
[Agent writes 2–3 sentences describing what was done, what passed, and what comes next]

## Completed tasks
- feat-001: Title — completed YYYY-MM-DD

## Pending tasks
- feat-002: Title — pending
- feat-003: Title — pending

## Blocked tasks
(none)

## Notes for next session
[Agent writes any context the next session needs that isn't in feature_list.json]

session-log.json

Optional but recommended. Written by the agent at the end of every session for observability.

{
  "session_id": "YYYY-MM-DD-NNN",
  "date": "YYYY-MM-DD",
  "task_id": "feat-001",
  "status": "complete",
  "files_read": [
    "AGENTS.md",
    "feature_list.json",
    "src/auth/routes.ts"
  ],
  "files_modified": [
    "src/auth/login.ts",
    "src/auth/logout.ts",
    "tests/auth/login.test.ts"
  ],
  "verification": {
    "tests": "passed",
    "lint": "passed",
    "build": "passed"
  },
  "next_task": "feat-002",
  "notes": ""
}

review-request.md

Written to reviews/YYYY-MM-DD-review.md when a human checkpoint is triggered.

# Review Request — YYYY-MM-DD

## Task
[feat-id]: Task title

## What I did
- [Action 1]
- [Action 2]

## Why I stopped
[Specific reason — scope conflict / test failure / ambiguity]

## What I need from you
[Specific question or decision required]

## Relevant files
- [file-path]: [why it's relevant]

## Proposed next step if approved
[What the agent will do after receiving a response]