# AGENTS.md ## DOCUMENT_ORDER 1. AGENTS.md 2. .replworks/PRODUCT_SPEC.md 3. .replworks/TECH_STACK.md 4. .replworks/ARCHITECTURE.md 5. .replworks/TASKS.md Only these documents are authoritative. --- ## IGNORE Ignore all files under: ```text .replworks/docs/ ``` Never use files in these folders as requirements. Never implement features described only in these folders. --- ## SOURCE_OF_TRUTH Product Requirements: ```text PRODUCT_SPEC.md ``` Implementation Constraints: ```text TECH_STACK.md ``` Architecture: ```text ARCHITECTURE.md ``` Execution Plan: ```text TASKS.md ``` If a conflict exists: ```text PRODUCT_SPEC.md > TECH_STACK.md > ARCHITECTURE.md > TASKS.md > everything else ``` --- ## CONFLICT_HANDLING When documents conflict: 1. Follow the higher-priority document. 2. Report the conflict to the human. 3. Fix the lower-priority document together with the human before continuing. Never resolve a conflict silently. Never leave a conflict in place after the task is complete. --- ## DOCUMENT_RESPONSIBILITIES PRODUCT_SPEC.md defines: ```text What the product is. What the product does. ``` TECH_STACK.md defines: ```text How the product must be implemented. ``` ARCHITECTURE.md defines: ```text How the product works. ``` TASKS.md defines: ```text What should be implemented next. ``` Do not move responsibilities between documents. ARCHITECTURE.md must not contain technology, versions, or folder rules. TECH_STACK.md must not contain component responsibilities or data flows. --- ## EXTERNAL_BOUNDARY Define once. Referenced by TASK_EXECUTION and MOCK_RULES below. ```text External boundary = any behavior not controlled by this codebase. Examples: third-party DOM third-party API browser runtime behavior ``` Libraries that run inside this codebase's own process are not an external boundary. --- ## UNVERIFIED_MARK Add `[UNVERIFIED]` to the heading of the section that owns the gap. ```text Gaps in what the product is or does -> PRODUCT_SPEC.md Gaps in how the product must be implemented -> TECH_STACK.md Gaps in how the product works -> ARCHITECTURE.md ``` Clear the mark only after human confirmation. --- ## IMPLEMENTATION_RULES Implement only the selected task. Exception: HUMAN_OWNED_CHANGES. Do not implement: ```text future work roadmap items optional features assumptions inferred requirements ``` Requirements must originate from: ```text PRODUCT_SPEC.md ``` Implementation must follow: ```text TECH_STACK.md ARCHITECTURE.md ``` --- ## TASK_SELECTION Implement the task named by the human. If none is named, use the first unchecked task in TASKS.md, from top to bottom. --- ## TASK_EXECUTION For every task: 1. Read PRODUCT_SPEC.md 2. Read TECH_STACK.md 3. Read ARCHITECTURE.md 4. Read task definition 5. If the task touches a domain that is not covered by verified knowledge in PRODUCT_SPEC.md, TECH_STACK.md, or ARCHITECTURE.md: stop. Mark the relevant section UNVERIFIED (see UNVERIFIED_MARK). Do not implement against an UNVERIFIED section. Require explicit human confirmation before continuing. 6. Implement 7. Write unit tests for internal logic 8. If the task touches an EXTERNAL_BOUNDARY: write an E2E test against the live boundary. A mocked test alone does not satisfy this step. If the live boundary is unreachable, stop and report. Do not mark the task `[x]`. 9. Run all tests 10. Mark the completed task `[x]` in TASKS.md 11. Deliver and continue (see AUTO_RUN) --- ## SUBSESSION_ORCHESTRATION Goal: keep the main session context small and reduce total token usage. Subsession = a separate agent context started by the main session (Claude Code subagent / Task tool, or any equivalent). If the runtime cannot create one, run TASK_EXECUTION in the main session. The main session is the orchestrator. It decides how to delegate: one subsession per task, or several tasks per subsession when that saves tokens. Subsessions run one at a time, never in parallel. Invariants: 1. The main session owns all human communication. A subsession never asks the human. On any STOP condition it stops and reports the branch, the task ID, and the decision needed. 2. The main session confirms delivery identities once and passes them on. 3. Branch, commit, PR, and squash merge stay per task, even in a batch. 4. A subsession report is a claim. The main session verifies merge state and CI with `gh` before continuing. 5. Every rule in this file applies inside a subsession, including IGNORE, MOCK_RULES, and TASK_EXECUTION step 8 (E2E). 6. For HUMAN_OWNED_CHANGES, the subsession stops after the diff and test results. The main session obtains approval and instructs the commit. --- ## AUTO_RUN AUTO_RUN applies only to tasks from TASKS.md. Any other change the human requests in the session is committed only after human review. Repeat TASK_SELECTION and TASK_EXECUTION until no unchecked task remains. Do not stop between tasks. Do not ask for approval to start a task. Before the first git operation of a session, ask the human to confirm the delivery identities. Fill in every value and ask in this form: Commit author/committer: Co-authored-by: (only when the human took part in the change) PR creator / assignee: Merger: Is this correct? Fill missing values using available context, including `gh` commands. Show the complete values and ask: ". Is this correct?" Wait for the human's confirmation before any git operation. Per task: 1. Pull main. 2. Create branch `t-NNN-slug`. 3. Implement and test (TASK_EXECUTION). 4. Commit with the agent that wrote the code as author and committer (name and noreply email of that agent). Add a `Co-authored-by` trailer for the human account when the human specified the change or answered a question about it, in the session or on GitHub. Add no other `Co-authored-by` trailer. 5. Open a PR as the bot account. Assignee: bot account. 6. Squash merge only after every CI check on the PR has passed. Pending is not passed. If no CI is configured, there is no gate. 7. Pull main and start the next task. Never commit or merge directly to main. Commit messages and the PR title follow Conventional Commits. Merge message: use the one GitHub generates. Do not set a custom subject or body. Stop and ask the human only when: ```text an UNVERIFIED gap needs a decision documents conflict a task is invalidated, or a spec/task/stack/architecture change is needed a human-requested change is awaiting review a live EXTERNAL_BOUNDARY is unreachable a task requires a Developer decision a manual or permission step is required tests or CI cannot be fixed ``` --- ## MOCK_RULES Mock only observed behavior. ```text Allowed sources: recorded live response documented spec ``` ```text Forbidden sources: assumed behavior guessed response inferred event flow ``` If a mock's values cannot be traced to a recorded observation or a spec, do not write it. Any code touching an EXTERNAL_BOUNDARY requires at least one live observation before it may be mocked. Re-verify mocks when the external system's behavior may have changed. ## PROBE_PATHS A probe is throwaway code run to observe behavior and inform a design or technical decision. Do not ask the human where to store a probe. Use these paths: ```text Code: probes/-/ Report: .replworks/observations/-.md ``` Code and report share the same `-`. --- ## PRODUCT_SPEC_CHANGES If implementation reveals missing product requirements, or a PRODUCT_SPEC.md section is marked UNVERIFIED: ```text Stop. Do not invent requirements. ``` 1. Propose the change to the human. 2. Update PRODUCT_SPEC.md only after human confirmation. 3. Clear the UNVERIFIED mark only after human confirmation. 4. Continue implementation. --- ## TECH_STACK_CHANGES If implementation requires tech stack changes, or a TECH_STACK.md section is marked UNVERIFIED: 1. Stop. Propose the change to the human. 2. If the change conflicts with PRODUCT_SPEC.md, see CONFLICT_HANDLING. 3. Update TECH_STACK.md only after human confirmation. 4. Clear the UNVERIFIED mark only after human confirmation. 5. Update implementation. Never allow tech stack and code to diverge. --- ## ARCHITECTURE_CHANGES If implementation requires architecture changes, or an ARCHITECTURE.md section is marked UNVERIFIED: 1. Stop. Propose the change to the human. 2. If the change conflicts with PRODUCT_SPEC.md or TECH_STACK.md, see CONFLICT_HANDLING. 3. Update ARCHITECTURE.md only after human confirmation. 4. Clear the UNVERIFIED mark only after human confirmation. 5. Update implementation. Never allow architecture and code to diverge. --- ## TASK_CHANGES If implementation invalidates a task, or PRODUCT_SPEC.md changes: 1. Propose the TASKS.md change to the human. 2. Update TASKS.md only after human confirmation. Never change an existing task ID. Never regenerate TASKS.md from scratch. These rules bind the AI. The human may edit TASKS.md directly at any time. Human edits are authoritative. Exception: when the human explicitly requests task reordering that requires renumbering, the AI may approve and apply the renumbering after reviewing task dependencies, completion status, and references. Update every affected task ID reference in the same change; preserve each task's content and completion state. --- ## HUMAN_OWNED_CHANGES Content and visual design are human-owned. They are not specified in PRODUCT_SPEC.md and are not tracked in TASKS.md. ```text Content: wording, copy, translations, images, data text Visual design: styling, spacing, colors, typography, imagery, visual polish ``` Not human-owned: which screens and elements exist, their purpose, their arrangement relative to each other, their states, and their interactions. These are specified in PRODUCT_SPEC.md. When the human explicitly asks for such a change in the session: 1. Make only that change. 2. Do not change behavior, screens, elements, states, or interactions defined in PRODUCT_SPEC.md. If the change would, stop (see PRODUCT_SPEC_CHANGES). 3. Do not record the change in TASKS.md or any other document. 4. Run the verification commands defined in TECH_STACK.md. 5. Show the diff and test results. After explicit human approval, commit, open the PR, and merge by AUTO_RUN steps 4-6 (merge only after CI passes). 6. Stop. Never make such changes on your own initiative. If a task needs content or styling and none is provided, use neutral placeholders and report them when you stop. --- ## DESIGN_RULES Prefer: ```text simple explicit minimal ``` Avoid: ```text abstraction without use premature optimization speculative features ``` --- ## FILE_CREATION Do not create new top-level documents unless explicitly requested. Prefer modifying existing files. --- ## SUCCESS_CRITERIA Task is complete only when: - product requirements satisfied - architectural requirements satisfied - tech stack constraints satisfied - the task's acceptance criteria in TASKS.md satisfied - no UNVERIFIED sections remain in scope for this task - no unresolved document conflicts remain - code runs - unit tests pass - E2E tests pass for any EXTERNAL_BOUNDARY code touched - the PR is merged Then continue with the next task.