What task are you trying to do?

PawWork should have a clear factory-default agent behavior that comes from PawWork itself, not from whatever legacy instruction file happens to exist on the user's machine.

As a user, I should be able to start PawWork and get the intended product behavior without first creating AGENTS.md, understanding OpenCode internals, or relying on a global Claude Code config.

What do you do today?

Today the runtime instruction path is still shaped by compatibility with existing coding-agent conventions:

• project AGENTS.md can be loaded
• project CLAUDE.md can be loaded as a compatibility fallback
• PawWork config AGENTS.md can be loaded if present
• runtime/global config AGENTS.md can be loaded if present
• global ~/.claude/CLAUDE.md can still be used as a fallback

This creates two product problems:

1. PawWork does not own enough of its factory-default behavior. If no PawWork or project instructions exist, global Claude instructions can become the effective baseline.
2. PawWork's current system prompt is too thin for the product role. It does not clearly guide default behavior for asking questions, tracking progress, using skills, or handling instruction sources.

The previous direction for this issue was to ship or generate a default global AGENTS.md. That is no longer the preferred direction. PawWork should not silently create user instruction files by default. User-owned AGENTS.md should remain an explicit customization surface.

What would a good result look like?

PawWork owns its default behavior through the built-in system prompt and a simple, explainable instruction fallback contract.

Recommended instruction source behavior:

1. Built-in PawWork system prompt is always the product baseline.
2. Project AGENTS.md is loaded when present.
3. Project CLAUDE.md remains a compatibility fallback when no project AGENTS.md applies.
4. PawWork-owned global AGENTS.md from PAWWORK_CONFIG_DIR is loaded when present.
5. Existing runtime/global config AGENTS.md may remain as compatibility behavior, but it should be clearly labeled in diagnostics.
6. Global ~/.claude/CLAUDE.md should not be used as a PawWork fallback.
7. User instructions can supplement the PawWork baseline, but cannot replace core PawWork safety and product behavior.

The system prompt should stay English and product-level. It should not include project-specific Git rules, PR conventions, commit policy, or developer-only workflow preferences.

System prompt guidance

The PawWork system prompt should describe PawWork as an open-source desktop AI agent for everyday work.

It should guide these default behaviors:

• Understand before acting. Distinguish questions, analysis, and execution requests.
• Verify checkable claims before stating them as fact.
• Use the question tool proactively when user preferences, missing context, real trade-offs, or risky choices would materially affect the next action. Recommended options should be listed first.
• Use the todo tool proactively for multi-step work, debugging, PR work, long research, file changes, and external-state changes. Keep it lightweight for one-shot answers and small read-only checks.
• Use the skill tool when an available skill clearly matches a task, especially for documents, spreadsheets, writing, research, data organization, platform operations, and repeatable workflows.
• Keep judgment, final synthesis, and user-facing decisions in the main conversation.
• Avoid promising unavailable capabilities. For example, do not claim default web search behavior until the search product work is available.

Subagent guidance should wait for #128 so the model-facing tool name and behavior are no longer confused with a generic task tool.

Dependencies and related issues

Hard dependency:

• [Feature] Rename and rewrite task as subagent #128 must land first, so [Feature] Improve PawWork system prompt and instruction fallback order #230 can refer to subagent behavior without reinforcing the confusing task naming.

Related but not blocking:

• [Feature] Define default web access and source safety strategy #132 should define PawWork's default web access and source-safety strategy. [Feature] Improve PawWork system prompt and instruction fallback order #230 should not claim search is available before [Feature] Define default web access and source safety strategy #132 lands.
• [Feature] Add onboarding guidance for user AGENTS.md #238 should handle onboarding that helps users intentionally create their own AGENTS.md. That onboarding should not be required for [Feature] Improve PawWork system prompt and instruction fallback order #230.

Future architecture direction:

• Dynamic prompt section composition, similar to Gemini CLI's tool-aware system prompt assembly, is a good later architecture improvement.
• It is not required for this issue. For [Feature] Improve PawWork system prompt and instruction fallback order #230, avoid the extra complexity and focus on the smallest stable baseline.

Which audience does this matter to most?

Both

Extra context

This issue is product-facing, but the implementation lives in the harness/runtime layer.

The relevant current files are:

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

A previous live check showed the current problem clearly:

• the inspected project had no local AGENTS.md or CLAUDE.md
• PawWork global AGENTS.md was absent
• ~/.claude/CLAUDE.md existed
• the session therefore picked up global Claude instructions

That behavior may be technically intentional as compatibility, but it is not a good PawWork factory default.

Scope

In scope:

• Rewrite the PawWork system prompt baseline.
• Remove PawWork fallback to global ~/.claude/CLAUDE.md.
• Keep project-level CLAUDE.md fallback when no project AGENTS.md applies.
• Keep PawWork/user AGENTS.md customization paths explicit and explainable.
• Add or update diagnostics so a session can show which instruction sources were considered, loaded, ignored, and why.
• Add focused tests for the fallback order and the fresh-install behavior.

Out of scope:

• Silently creating a default user AGENTS.md.
• Building onboarding for custom AGENTS.md; track that in [Feature] Add onboarding guidance for user AGENTS.md #238.
• Full Gemini-style dynamic prompt assembly.
• Shipping default web search behavior; track that in [Feature] Define default web access and source safety strategy #132.
• Adding project-specific Git, PR, or commit rules to PawWork's built-in system prompt.
• Removing project-level CLAUDE.md compatibility.

Acceptance criteria

• PawWork's built-in system prompt uses the current product positioning: open-source desktop AI agent for everyday work.
• The baseline system prompt is English.
• The prompt guides proactive but bounded use of question, todo, and skill tools.
• [Feature] Rename and rewrite task as subagent #128 is resolved before subagent guidance is added to the prompt.
• PawWork no longer falls back to global ~/.claude/CLAUDE.md as an instruction source.
• Project-level CLAUDE.md remains available as a compatibility fallback when project AGENTS.md is absent.
• Diagnostics or session debug output can explain loaded, considered, and ignored instruction sources, including why global Claude fallback was ignored.
• Focused tests cover fresh install behavior, project AGENTS.md, project CLAUDE.md fallback, PawWork global AGENTS.md, and ignored global Claude fallback.