feat: guide durable AGENTS.md updates

[Astro-Han]

Summary

Add PawWork system prompt guidance for recognizing durable user preferences, long-term tendencies, recurring background context, project conventions, and future workflow rules as candidates for AGENTS.md.

Why

PawWork should help users preserve stable guidance across sessions without turning AGENTS.md into a scratchpad. The new prompt tells the model to propose AGENTS.md updates when durable context appears, but only write persistent project guidance when the user explicitly asks or confirms.

Related Issue

No linked issue. This is a focused prompt behavior improvement discussed directly.

How To Verify

bun --cwd packages/opencode test test/session/system.test.ts

Screenshots or Recordings

Not applicable. This is a system prompt change with no visible UI changes.

Checklist

• I linked the related issue, or stated why there is no issue
• This PR has type, scope, and priority labels, or I requested maintainer labeling
• I listed the relevant verification steps, including tests when behavior changed
• I manually checked visible UI or copy changes when needed, with screenshots or recordings
• I considered macOS and Windows impact for desktop, packaging, updater, signing, paths, shell, or permissions changes
• I called out docs, release notes, dependencies, permissions, credentials, deletion behavior, or generated/local file changes when relevant
• I am targeting dev, and my PR title and commit messages use Conventional Commits in English

Summary by CodeRabbit

• Tests

  • Expanded test coverage for system prompt guidance verification.

• Chores

  • Enhanced behavioral guidelines for managing project documentation to ensure stability and prevent unintended modifications.

[coderabbitai]

Warning

Rate limit exceeded

@Astro-Han has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 7 minutes and 13 seconds before requesting another review.

To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 455a1438-e503-4ef0-a68b-e3fa660987f0

📥 Commits

Reviewing files that changed from the base of the PR and between 8daab94 and 49bab24.

📒 Files selected for processing (2)

• packages/opencode/src/session/prompt/pawwork.txt
• packages/opencode/test/session/system.test.ts

📝 Walkthrough

Walkthrough

This PR extends the PawWork system prompt with new behavioral instructions that govern agent interaction with AGENTS.md, stipulating that it should serve as durable project guidance requiring explicit user requests to write, and establishing careful editing practices. Corresponding test assertions verify these new instructions are present in the generated system prompt.

Changes

Cohort / File(s)	Summary
PawWork Prompt Instructions packages/opencode/src/session/prompt/pawwork.txt	Adds guidance directing agents to treat AGENTS.md as durable project context, restrict writes to explicit user requests, and follow careful editing practices including reading existing content, minimizing scope, avoiding duplicates, and excluding secrets or temporary details.
System Prompt Tests packages/opencode/test/session/system.test.ts	Expands test coverage with assertions verifying the system prompt includes strings about durable project context, recurring background context, locating AGENTS.md, and requiring confirmation before writing.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related issues

• [Feature] Improve PawWork system prompt and instruction fallback order #230: This PR directly addresses AGENTS.md handling guidance by adding behavioral instructions that govern how agents should treat and write to AGENTS.md, aligning with the issue's focus on built-in guidance adjustments.

Possibly related PRs

• feat(opencode): unify session behavior prompt #142: This PR builds upon the foundation where session prompts were unified to use pawwork.txt and provider/tests were adjusted; the current changes extend those AGENTS.md persistence/editing rules further and update corresponding test expectations.

Poem

🐰 A rabbit stores its treasures well,
In durable files it loves to dwell,
With careful paws it edits with care,
"Ask first!" it says, "before you dare!"
AGENTS.md shines, both clean and bright ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: guide durable AGENTS.md updates' is concise, specific, and clearly summarizes the main change: updating the system prompt to guide AGENTS.md updates for durable context.
Description check	✅ Passed	The description follows the template structure with all required sections present: Summary, Why, Related Issue, How To Verify, Screenshots/Recordings, and a completed Checklist. All key information is provided.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/agents-guidance

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request updates the system prompt in pawwork.txt to include guidelines for durable project documentation via AGENTS.md and adds corresponding tests in system.test.ts. The review suggests refining the instructions for editing AGENTS.md to ensure the agent reads existing files before proposing changes and to include operational guidance favoring specialized tools for better efficiency.