docs: agent operating rules + mobile-Dispatch working method

[nah414]

Summary

Establishes a repo-root CLAUDE.md (auto-loaded into every Claude Code session) plus a detailed companion docs/AGENT_WORKFLOW.md, so agent operating rules are picked up automatically without re-pasting prompts each session. Optimized for Adam driving sessions remotely from a phone via mobile Dispatch.

Agent operating rules (short form; full detail in docs/AGENT_WORKFLOW.md)

1. No interactive pickers — plain-text questions only (answerable from a phone).
2. Default to autonomous execution — at a fork, take the conservative reversible option, note it, keep going.
3. Halt only for destructive/irreversible actions — push, PR open/merge, commit to main, force-push, history rewrite, deleting data, access/permission changes.
4. Always work on a feature branch; never commit to main — no push/PR without explicit approval.
5. Consolidate work; don't PR every change — one PR per work-session/batch; branches may accumulate commits and sit for days; never PR proactively.
6. Never skip git hooks or bypass signing — no --no-verify; fix the underlying issue.
7. Plan substantial work, but don't block on it — surface design choices in the final report.
8. Test before handing back — run relevant tests, report honestly.

Mobile-dispatch working method

CLAUDE.md records that this repo is primarily driven via mobile Dispatch (phone-driven Claude Code sessions while the desktop runs), which is the rationale for the no-picker / plain-text / autonomous-reversible posture.

Dated session log

CLAUDE.md includes a tight session log. 2026-06-09: README trim (#26, merged); root build-guide/planning docs reorganized into docs/ (#27, merged); auto-capture baseline wired into DriftDetector.run_cycle (branch phase-13.x.9-auto-capture-wiring, parked); these agent rules established; Step 5c cognition-classifier training + evaluation harness built (branch phase-13-step5c-cognition-training-harness, parked; lightgbm 4.6.0 kept installed for local runs).

Notes

• Branch was rebased onto current main (includes merged docs: clean up and trim main README into a concise overview #26/docs: consolidate root build-guide and planning docs into docs/ tree #27); build-guide references and the docs/README.md pointer were updated to the post-reorg docs/ tree.
• Docs-only change. Pre-commit hooks (incl. pytest smoke test) pass on every commit.

🤖 Generated with Claude Code

Summary by Sourcery

Document agent operating rules and workflow for AI assistants working in the repo, optimized for mobile Dispatch sessions, and surface them via an auto-loaded root CLAUDE.md file.

Documentation:

• Add a root-level CLAUDE.md that summarizes agent operating rules, repo context, and a dated session log for AI assistants working in the project.
• Introduce a detailed docs/AGENT_WORKFLOW.md document describing full agent workflow rules, halt conditions, branching/PR conventions, planning, testing, and reporting expectations.
• Update docs/README.md to reference the new AGENT_WORKFLOW.md as the long-form companion to CLAUDE.md.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[sourcery-ai]

Reviewer's Guide

Adds repo-wide agent operating rules optimized for mobile Dispatch workflows by introducing an auto-loaded CLAUDE.md at the repo root and a detailed AGENT_WORKFLOW.md in docs/, and wires them into the docs index.

Flow diagram for agent decision workflow and halt rules

flowchart TD
    A[Start task in Claude Code session<br/>CLAUDE_md auto-loaded] --> B[Need user input?]
    B -->|No| C[Proceed autonomously using repo rules]
    B -->|Yes| D[Ask question in plain-text reply<br/>Provide recommended default]
    D --> C

    C --> E[At a decision or fork]
    E --> F{Is choice conservative and easily reversible?}
    F -->|Yes| G[Pick conservative option<br/>Record one-line note]
    G --> H[Continue work on feature branch]

    F -->|No| I{Does action touch halt list?<br/>push / PR / main / history / data / access}
    I -->|No| H
    I -->|Yes| J[Stop and request explicit approval<br/>Show exact commands]

    H --> K[Run relevant tests]
    K --> L[Prepare final report<br/>Changes, decisions, tests, approvals needed, questions]
    L --> M[End session]

Loading

File-Level Changes

Change	Details	Files
Introduce a root CLAUDE.md with short-form agent operating rules and repo-specific context that auto-loads in Claude Code sessions.	Create CLAUDE.md with an 8-rule short-form operating guide for AI agents working in the repo. Document precedence of these rules over default agent behavior and note that live maintainer instructions still override them. Summarize repo context (architecture spec, phase-gated development, Windows/PowerShell platform) and mobile Dispatch as the primary workflow. Add a dated session log entry describing recent PRs, parked branches, and the origin of these rules.	CLAUDE.md
Add detailed AGENT_WORKFLOW.md describing the full agent workflow, halt list, branching/commit conventions, testing and reporting expectations, and platform notes.	Document the rationale and precedence for the agent workflow and its optimization for phone-driven Dispatch sessions. Expand the "no interactive pickers" rule into concrete guidance for asking questions in plain text with recommended defaults. Define autonomous execution expectations, including reversible decision-making, examples, and when to prefer asking vs. deciding. Specify a detailed halt list for destructive/irreversible actions (push, PR operations, history rewrites, data deletion, publishing, permission changes). Describe branch and commit conventions, including branch naming patterns, where to branch from, commit style, and prohibitions on skipping hooks or signing. Clarify PR cadence (one PR per work batch, never proactive PRs) and the expectation that branches can accumulate commits and sit parked. Lay out expectations for planning substantial work, surfacing design choices, running tests, and the required final report format. Add Windows/PowerShell-specific platform notes (paths, shell syntax, encoding) and rationale tying all rules back to mobile Dispatch constraints.	docs/AGENT_WORKFLOW.md
Update docs index to reference the new agent workflow documentation.	Add AGENT_WORKFLOW.md to the internal development records section of the docs index. Describe AGENT_WORKFLOW.md as the long-form companion to the root CLAUDE.md that auto-loads each session.	docs/README.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've found 1 issue, and left some high level feedback:

• Rule 3’s halt list in docs/AGENT_WORKFLOW.md includes external publishing (PyPI, registries, releases), but the short-form halt list in CLAUDE.md does not; consider adding that class of actions to CLAUDE.md to avoid the short guide giving a looser impression than the detailed one.
• There is a fair amount of duplicated wording between CLAUDE.md and docs/AGENT_WORKFLOW.md for the top-level rules; you might want to centralize the canonical descriptions in one place and keep the other strictly as a short pointer/summary to reduce drift over time.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- Rule 3’s halt list in `docs/AGENT_WORKFLOW.md` includes external publishing (PyPI, registries, releases), but the short-form halt list in `CLAUDE.md` does not; consider adding that class of actions to `CLAUDE.md` to avoid the short guide giving a looser impression than the detailed one.
- There is a fair amount of duplicated wording between `CLAUDE.md` and `docs/AGENT_WORKFLOW.md` for the top-level rules; you might want to centralize the canonical descriptions in one place and keep the other strictly as a short pointer/summary to reduce drift over time.

## Individual Comments

### Comment 1
<location path="docs/AGENT_WORKFLOW.md" line_range="5-14" />
<code_context>
+rationale, the exact halt list, branch/commit conventions, and the reporting
</code_context>
<issue_to_address>
**nitpick (typo):** Use a consistent spelling for the term "halt list" throughout the document.

You use both "halt list" and "halt-list" for the same concept. Please pick one form and use it consistently across the file for clarity.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

nitpick (typo): Use a consistent spelling for the term "halt list" throughout the document.

You use both "halt list" and "halt-list" for the same concept. Please pick one form and use it consistently across the file for clarity.