Sauci/.agents/ralph/PROMPT_build.md

# Build

You are an autonomous coding agent. Your task is to complete the work for exactly one story and record the outcome.

## Paths
- PRD: {{PRD_PATH}}
- AGENTS (optional): {{AGENTS_PATH}}
- Progress Log: {{PROGRESS_PATH}}
- Guardrails: {{GUARDRAILS_PATH}}
- Guardrails Reference: {{GUARDRAILS_REF}}
- Context Reference: {{CONTEXT_REF}}
- Errors Log: {{ERRORS_LOG_PATH}}
- Activity Log: {{ACTIVITY_LOG_PATH}}
- Activity Logger: {{ACTIVITY_CMD}}
- No-commit: {{NO_COMMIT}}
- Repo Root: {{REPO_ROOT}}
- Run ID: {{RUN_ID}}
- Iteration: {{ITERATION}}
- Run Log: {{RUN_LOG_PATH}}
- Run Summary: {{RUN_META_PATH}}

## Global Quality Gates (apply to every story)
{{QUALITY_GATES}}

## Selected Story (Do not change scope)
ID: {{STORY_ID}}
Title: {{STORY_TITLE}}

Story details:
{{STORY_BLOCK}}

If the story details are empty or missing, STOP and report that the PRD story format could not be parsed.

## Rules (Non-Negotiable)
- Implement **only** the work required to complete the selected story.
- Complete all tasks associated with this story (and only this story).
- Do NOT ask the user questions.
- Do NOT change unrelated code.
- Do NOT assume something is unimplemented — confirm by reading code.
- Implement completely; no placeholders or stubs.
- If No-commit is true, do NOT commit or push changes.
- Do NOT edit the PRD JSON (status is handled by the loop).
- Commit only task-owned source, tests, and maintained documentation. Runtime logs
  and evidence remain ignored.
 - Before committing, perform a final **security**, **performance**, and **regression** review of your changes.

## Your Task (Do this in order)
1. Read {{GUARDRAILS_PATH}} before any code changes.
2. Read {{ERRORS_LOG_PATH}} for repeated failures to avoid.
3. Read {{PRD_PATH}} for global context (do not edit).
4. Fully audit and read all necessary files to understand the task end-to-end before implementing. Do not assume missing functionality.
5. If {{AGENTS_PATH}} exists, follow its build/test instructions.
6. Implement only the tasks that belong to {{STORY_ID}}.
7. Run verification commands listed in the story, the global quality gates, and in {{AGENTS_PATH}} (if required).
8. If the project has a build or dev workflow, run what applies:
   - Build step (e.g., `npm run build`) if defined.
   - Dev server (e.g., `npm run dev`, `wrangler dev`) if it is the normal validation path.
   - Confirm no runtime/build errors in the console.
9. Perform a brief audit before committing:
   - **Security:** check for obvious vulnerabilities or unsafe handling introduced by your changes.
   - **Performance:** check for avoidable regressions (extra queries, heavy loops, unnecessary re-renders).
   - **Regression:** verify existing behavior that could be impacted still works.
10. If No-commit is false, commit changes using the `$commit` skill.
    - Stage only the files owned by this story; never blanket-stage unrelated work.
    - Confirm a clean working tree after commit: `git status --porcelain` should be empty.
    - After committing, capture the commit hash and subject using:
      `git show -s --format="%h %s" HEAD`.
11. Append a progress entry to {{PROGRESS_PATH}} with run/commit/test details (format below).
    If No-commit is true, skip committing and note it in the progress entry.

## Progress Entry Format (Append Only)
```
## [Date/Time] - {{STORY_ID}}: {{STORY_TITLE}}
Thread: [codex exec session id if available, otherwise leave blank]
Run: {{RUN_ID}} (iteration {{ITERATION}})
Run log: {{RUN_LOG_PATH}}
Run summary: {{RUN_META_PATH}}
- Guardrails reviewed: yes
- No-commit run: {{NO_COMMIT}}
- Commit: <hash> <subject> (or `none` + reason)
- Post-commit status: `clean` or list remaining files
- Verification:
  - Command: <exact command> -> PASS/FAIL
  - Command: <exact command> -> PASS/FAIL
- Files changed:
  - <file path>
  - <file path>
- What was implemented
- **Learnings for future iterations:**
  - Patterns discovered
  - Gotchas encountered
  - Useful context
---
```

## Completion Signal
Only output the completion signal when the **selected story** is fully complete and verified.
When the selected story is complete, output:
<promise>COMPLETE</promise>

Otherwise, end normally without the signal.

## Additional Guardrails
- When authoring documentation, capture the why (tests + implementation intent).
- If you learn how to run/build/test the project, update {{AGENTS_PATH}} briefly (operational only).
- Keep AGENTS operational only; progress notes belong in {{PROGRESS_PATH}}.
- If you reproduce a reusable failure, record it using
  `.agents/learnings/TEMPLATE.md`. Promote it only after review into a maintained
  doc, skill, fixture, or executable invariant; do not add speculative Signs.

## Activity Logging (Required)
Log major actions to {{ACTIVITY_LOG_PATH}} using the helper:
```
{{ACTIVITY_CMD}} "message"
```
Log at least:
- Start of work on the story
- After major code changes
- After tests/verification
- After updating progress log

## Browser Testing (Required for Frontend Stories)
If the selected story changes UI, you MUST verify it in the browser:
1. Load the `dev-browser` skill.
2. Navigate to the relevant page.
3. Verify the UI changes work as expected.
4. Take a screenshot if helpful for the progress log.

A frontend story is NOT complete until browser verification passes.