docs: modularize agent startup docs [AI-assisted]

[artemgetmann]

Summary

• Problem: AGENTS.md and CONSUMER.md had turned into large startup docs, and Claude CLI was warning that the loaded CLAUDE.md was impacting performance.
• Why it matters: startup prompt bloat slows agent startup, hides the actual always-on rules, and mixes fork-specific workflow with upstream-only guidance.
• What changed: slimmed the startup docs into routing contracts, fixed default PR target guidance, and moved bulky operational detail into targeted docs under docs/agent-guides/.
• What did NOT change (scope boundary): no product logic, runtime behavior, tests, CI config, or upstream project code paths.
• AI-assisted: Yes
• Testing level: lightly tested

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #
• Related #

User-visible / Behavior Changes

• Claude startup in this repo no longer shows the large CLAUDE.md warning.
• Top-level agent instructions now default to this fork first and point upstream only when explicitly requested.
• Consumer-product branch guidance now points new work at codex/consumer-openclaw-project instead of treating consumer as the active default.

Security Impact (required)

• New permissions/capabilities? (Yes/No): No
• Secrets/tokens handling changed? (Yes/No): No
• New/changed network calls? (Yes/No): No
• Command/tool execution surface changed? (Yes/No): No
• Data access scope changed? (Yes/No): No
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS
• Runtime/container: local Claude CLI in tmux
• Model/provider: Claude Code v2.1.81
• Integration/channel (if any): none
• Relevant config (redacted): repo-local CLAUDE.md -> AGENTS.md symlink

Steps

1. Open this repo in a tmux pane and launch claude.
2. Observe startup output.
3. Compare startup docs and branch guidance before vs after the refactor.

Expected

• No large CLAUDE.md startup warning.
• Top-level instructions stay lean and route to focused docs.
• Consumer and fork PR guidance is unambiguous.

Actual

• Verified: startup output no longer shows the large CLAUDE.md warning.
• Verified: AGENTS.md and CONSUMER.md are lean entrypoints with pointers.

Evidence

• Trace/log snippets
• Failing test/log before + passing after
• Screenshot/recording
• Perf numbers (if relevant)

Snippet from post-change startup in tmux:

Claude Code v2.1.81
...
❯

No Large CLAUDE.md will impact performance warning appeared.

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: launched claude in a new tmux pane inside this repo and confirmed the large-file warning is gone.
• Edge cases checked: confirmed CLAUDE.md still resolves through the AGENTS.md symlink and that branch-target guidance now distinguishes fork main, consumer integration, and upstream-only-on-request.
• What you did not verify: pnpm build, pnpm check, pnpm test, or any runtime/product behavior outside the startup docs.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes/No): Yes
• Config/env changes? (Yes/No): No
• Migration needed? (Yes/No): No
• If yes, exact upgrade steps:

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: revert commit 4ef6d20f01
• Files/config to restore: AGENTS.md, CONSUMER.md, and docs/agent-guides/*
• Known bad symptoms reviewers should watch for: missing startup guidance, broken doc pointers, or stale branch-target instructions.

Risks and Mitigations

• Risk: a required rule may have been moved too far out of the startup path.
  • Mitigation: kept always-on constraints in AGENTS.md and grouped the moved detail into task-based docs instead of scattering it.
• Risk: branch-target guidance could still be interpreted incorrectly for consumer work.
  • Mitigation: top-level docs now state fork main vs codex/consumer-openclaw-project vs upstream explicitly.