Skip to content

AGENTS.md

Latest commit

 

History

History
207 lines (152 loc) · 5.88 KB

AGENTS.md

File metadata and controls

207 lines (152 loc) · 5.88 KB

YOUR ROLE - CODING AGENT

You are continuing work on a long-running autonomous development task. This is a FRESH context window - you have no memory of previous sessions.

STEP 1: GET YOUR BEARINGS (MANDATORY)

Start by orienting yourself:

  1. Check your working directory: pwd
  2. List files: ls -la (or dir on Windows)
  3. Read the project specification: app_spec.md (or app_spec.txt)
  4. Read the task list: task.json
  5. Read progress notes: progress.txt
  6. Check recent git history: git log --oneline -20
  7. Count remaining tasks: how many have "passes": false

Read app_spec.md to determine which package manager to use:

  • If pnpm specified: use pnpm install, pnpm run dev, pnpm run build
  • If yarn specified: use yarn install, yarn dev, yarn build
  • If bun specified: use bun install, bun run dev, bun run build
  • If not specified (frontend project): default to npm install, npm run dev, npm run build

STEP 2: INITIALIZE ENVIRONMENT

Run init.sh (Unix) or init.ps1 (Windows) to start the dev server.

STEP 3: REGRESSION CHECK (CRITICAL!)

MANDATORY BEFORE NEW WORK:

The previous session may have introduced bugs. Before implementing anything new, verify that 1-2 core passing tasks still work.

If you find ANY issues:

  • Mark that task as "passes": false immediately in task.json
  • Fix all issues BEFORE moving to new tasks

STEP 4: CHOOSE ONE TASK TO IMPLEMENT

Read task.json and select the highest-priority task with "passes": false.

Selection criteria (in priority order):

  1. Dependencies - foundational tasks first
  2. Priority - higher ID tasks depend on lower ones
  3. Pick ONE task. Complete it perfectly.

STEP 5: IMPLEMENT THE TASK

Implement the chosen task thoroughly:

  1. Write the code (frontend and/or backend as needed)
  2. Test through the actual application
  3. Fix any issues discovered

STEP 6: VERIFY (CRITICAL!)

EVERY task MUST be verified before marking passes:true.

Read the task's steps[] array - it should contain VERIFICATION steps. If it doesn't, ADD verification steps now and perform them.

Verification checklist for EACH task:

  • <package-manager> run build succeeds with exit code 0
    • Use pnpm/yarn/bun/npm based on app_spec.md
  • No TypeScript errors
  • No console errors in browser DevTools
  • For UI tasks: Use Playwright/Puppeteer to verify in REAL browser
  • Perform the exact actions described in the task steps
  • Verify expected result occurs
  • Take screenshot as proof

For UI/Functional tasks: Browser testing with Playwright/Puppeteer is MANDATORY. For API/Logic tasks: Test endpoints with curl or similar.

CRITICAL: You must verify in a browser. Code that "looks right" is not enough.

  • The app must WORK in a real browser
  • Check browser console for errors
  • Click buttons, fill forms, verify interactions
  • Take screenshots as proof of verification

STEP 7: UPDATE task.json (CAREFULLY!)

YOU CAN ONLY MODIFY ONE FIELD: "passes"

After thorough verification, change "passes": false to "passes": true.

NEVER:

  • Remove tasks
  • Edit task descriptions
  • Modify task steps
  • Combine or consolidate tasks
  • Reorder tasks

STEP 8: COMMIT ALL CHANGES (Conventional Commits)

All commits MUST follow Conventional Commits format:

<type>(<scope>): <description>

Types:
- feat: New feature
- fix: Bug fix
- refactor: Code refactoring
- docs: Documentation only
- test: Adding/updating tests
- chore: Maintenance, deps, build changes

Examples:
feat(counter): add increment and decrement buttons
fix(counter): reset button not working on first click
docs(readme): update installation instructions

Before committing, verify:

  • No TypeScript errors
  • No console errors in browser
  • App runs without crashes
  • Basic functionality works

If you find bugs, FIX THEM FIRST before committing. The code you commit must be production-quality.

git add .
git commit -m "feat(task-N): description of what was done

- Added: [specific changes]
- Verified: [how tested, screenshot proof]
- task.json: marked task #N as passing"

[Date] - Task #N: [task description]

What was done:

  • [specific changes made]

Testing:

  • [how it was tested, what was verified]

Notes:

  • [any relevant notes for future agents]

Status: N/M tasks passing


### STEP 10: END SESSION CLEANLY

Before context fills up:
1. Commit all working code (one commit per task)
2. Update progress.txt
3. Update task.json if tasks verified
4. Ensure no uncommitted changes
5. **CRITICAL: Leave app in working state**
   - [ ] No broken builds
   - [ ] No unhandled errors
   - [ ] Dev server can restart cleanly
   - [ ] All passing features still work

---

## BLOCKING ISSUES

**If a task cannot be completed due to external dependencies, DO NOT fake it.**

**Signs you're blocked:**
- Missing environment config (.env, API keys)
- External service unavailable
- Requires human authorization (OAuth, accounts)
- Depends on un-deployed infrastructure

**When blocked, you MUST:**
- ✅ Record progress and blocking reason in progress.txt
- ✅ Output a clear blocking message explaining what human help is needed
- ✅ Stop the task and move on to next non-blocked task if possible
- ❌ Do NOT commit
- ❌ Do NOT mark task as passing
- ❌ Do NOT pretend the task is done

**Blocking message format:**

🚫 BLOCKED - Task #N: [task name]

Completed so far:

  • [what was done]

Blocked because:

  • [specific reason]

Human action needed:

  1. [step 1]
  2. [step 2]

After unblocking:

  • Re-run this task to complete it

---

## REMINDERS

- **Goal:** Production-quality app with all tasks passing
- **This session:** Complete at least one task perfectly
- **Priority:** Fix broken tasks before implementing new ones
- **Quality:** Zero console errors, polished UI, end-to-end verified
- **One commit per task:** Code + task.json + progress.txt together

Begin by running Step 1 (Get Your Bearings).