Fix #62: Always consider agents.md and readme files

src/clayde/prompts/address_review.j2

@@ -16,13 +16,15 @@ REPOSITORY ON DISK: {{ repo_path }}
 
 Steps:
 1. Check out the branch: git checkout {{ branch_name }} && git pull origin {{ branch_name }}
-2. Read and understand each review comment
-3. Make the requested changes
-4. Run tests if a test command is discoverable (check CLAUDE.md, README, Makefile, package.json, pyproject.toml, justfile):
+2. Read the README (README.md, README.rst, README.txt, or README) and agents.md at the root and in any relevant subdirectories.
+3. Read and understand each review comment.
+4. Make the requested changes.
+5. If any changes affect documented usage, configuration, architecture, or behavior, update the README and agents.md accordingly.
+6. Run tests if a test command is discoverable (check CLAUDE.md, README, Makefile, package.json, pyproject.toml, justfile):
    - If no test runner is discoverable, skip this step.
    - If a test suite exists: ensure all tests pass after your changes (pre-existing failures are exempt). Do NOT commit if your changes introduced new test failures.
-5. Commit with a clear message referencing the review, e.g.: "Address review: <summary>"
-6. Push: git push origin {{ branch_name }}
+7. Commit with a clear message referencing the review, e.g.: "Address review: <summary>"
+8. Push: git push origin {{ branch_name }}
 
 After making all changes, provide a short summary of what you changed in response
 to each review comment.

src/clayde/prompts/implement.j2

@@ -16,14 +16,16 @@ REPOSITORY ON DISK: {{ repo_path }}
 Steps:
 1. Before creating a branch, check whether branch `{{ branch_name }}` already exists. If so, resume from the existing state rather than starting fresh.
 2. Create or switch to branch: git checkout -b {{ branch_name }} (or git checkout {{ branch_name }} if it exists)
-3. Implement the plan carefully, following existing code style and paying attention to agents.md files if they exist
-4. Write or update tests if applicable
-5. Run tests if a test command is discoverable (check CLAUDE.md, README, Makefile, package.json, pyproject.toml, justfile):
+3. Read the README (README.md, README.rst, README.txt, or README) and agents.md at the root and in any relevant subdirectories before writing any code.
+4. Implement the plan carefully, following existing code style.
+5. After implementing, update the README and agents.md as needed to reflect any changes to usage, configuration, architecture, or behavior.
+6. Write or update tests if applicable
+7. Run tests if a test command is discoverable (check CLAUDE.md, README, Makefile, package.json, pyproject.toml, justfile):
    - If no test runner is discoverable, skip this step.
    - If a test suite exists: first note any pre-existing failures (run tests on the base branch before your changes if needed), then ensure all tests pass after your changes (pre-existing failures are exempt). If there are pre-existing failures, you MUST mention them in your PR summary. Do NOT commit if your changes introduced new test failures.
-6. Review your own changes for correctness, edge cases, and style and run "just cleanup" if it exists before committing
-7. Commit with a clear message, e.g.: "Fix #{{ number }}: <summary>"
-8. Push: git push origin {{ branch_name }}
+8. Review your own changes for correctness, edge cases, and style and run "just cleanup" if it exists before committing
+9. Commit with a clear message, e.g.: "Fix #{{ number }}: <summary>"
+10. Push: git push origin {{ branch_name }}
 
 Do NOT create a pull request — it will be created automatically after you finish.
 

src/clayde/prompts/preliminary_plan.j2

@@ -12,9 +12,12 @@ EXISTING COMMENTS:
 
 REPOSITORY ON DISK: {{ repo_path }}
 
-Explore the repository briefly to understand the codebase relevant to this issue.
-Pay special attention to agents.md files throughout.
-Then produce a SHORT preliminary plan that includes:
+Before doing anything else, read the following files if they exist in the repository:
+- README (any of: README.md, README.rst, README.txt, README)
+- agents.md (at the root and any subdirectories relevant to this issue)
+
+Then explore the repository briefly to understand the codebase relevant to this issue.
+Produce a SHORT preliminary plan that includes:
 - A brief overview of your approach (a few paragraphs, NOT an exhaustive plan)
 - Any clarifying questions you have
 

src/clayde/prompts/thorough_plan.j2

@@ -15,9 +15,12 @@ DISCUSSION AFTER PRELIMINARY PLAN:
 
 REPOSITORY ON DISK: {{ repo_path }}
 
-Explore the repository to understand the codebase relevant to this issue.
-Pay special attention to agents.md files throughout.
-Then produce a plan that describes WHAT needs to change, not HOW to change it.
+Before doing anything else, read the following files if they exist in the repository:
+- README (any of: README.md, README.rst, README.txt, README)
+- agents.md (at the root and any subdirectories relevant to this issue)
+
+Then explore the repository to understand the codebase relevant to this issue.
+Produce a plan that describes WHAT needs to change, not HOW to change it.
 The plan will be reviewed by a human, so prioritize clarity and readability.
 Use clear structure, short paragraphs, and plain language.
 

src/clayde/prompts/update_plan.j2

@@ -15,6 +15,9 @@ NEW COMMENTS SINCE LAST UPDATE:
 
 REPOSITORY ON DISK: {{ repo_path }}
 
+If you need to re-explore the repository to answer questions or evaluate feedback,
+remember to also read the README and agents.md files.
+
 {% if phase == "preliminary" -%}
 IMPORTANT: This is a PRELIMINARY plan — a short overview with questions and a
 scope estimate. Do NOT escalate it into a thorough implementation plan. Keep the