Clarify Rally value prop and architecture ownership in docs

AGENTS.md

@@ -0,0 +1,21 @@
+Read `~/configs/GLOBAL-AGENTS.md` (fallback: https://raw.githubusercontent.com/justinmoon/configs/master/GLOBAL-AGENTS.md). Skip if both unavailable.
+
+# Rally Agent Notes
+
+## Product Goal
+
+Rally coordinates multi-agent coding sessions by giving each agent one actionable instruction at a time.
+
+Use Rally when protocol adherence matters more than free-form collaboration.
+
+## Architecture Ownership
+
+- Core (`src/` + `crates/rally-core`) owns session lifecycle, persistence, locking, and dispatch.
+- Workflow crates (`crates/rally-workflow-*`) own typed workflow state, transitions, and workflow-specific instructions.
+- Wrapper templates (`prompts/`) own `/rally` wrapper behavior only (argument resolution + loop bootstrap).
+
+## Practical Rules
+
+- Keep workflow-specific instruction/policy text in workflow crates.
+- Keep wrapper templates workflow-agnostic.
+- If you add/rename a run command, update wrapper-facing docs (`README.md`, `docs/skill-install-run.md`) in the same change.

README.md

@@ -1,52 +1,60 @@
 # Rally
 
-Step-by-step coordinator for multi-agent coding sessions.
+Rally is a turn-based coordinator for multi-agent coding sessions.
 
-## Skill Wrappers
+Its core job is simple: each agent polls for work and gets one clear instruction at a time.
 
-Rally now provides a wrapper-oriented command surface:
+## Why It Exists
 
-- `rally skill install --target <codex|droid|pi|claude-code|all>`
-- `rally skill run ...` (canonical wrapper entrypoint)
-- `rally skill exec ...` (alias for `run`)
-- `rally skill agent-howto ...` (prints the current detailed agent loop instructions)
-- `rally skill doctor --target ...`
-- `rally skill uninstall --target ...`
+Rally helps agents follow pre-existing workflows without improvising protocol.
 
-Install wrappers everywhere:
+- keeps each agent on a strict loop (`next` -> do work -> `done`)
+- reduces prompt ambiguity by issuing concrete next actions
+- preserves workflow state and transitions centrally
 
-```bash
-rally skill install --target all
-```
+## Extension Model
 
-Installed `/rally` wrappers are thin adapters that delegate back to Rally core:
+Today, workflow extension is **build-time**:
 
-```bash
-rally skill agent-howto "$@"
-```
+- workflows are registered in Rust via `WorkflowRegistry`
+- built-ins are wired in `src/main.rs`
+- workflow behavior/state lives in workflow crates under `crates/`
 
-## /rally Usage
+Runtime plugin workflows are planned but not shipped yet. See [todos/runtime-workflows-final.md](todos/runtime-workflows-final.md).
 
-Typical wrapper invocations:
+## Architecture Boundaries
 
-- `/rally`
-- `/rally build`
-- `/rally build reviewer`
-- `/rally <invite-code>`
+- Rally core owns session envelope, persistence, locking, and dispatch.
+- Workflow crates own workflow state schemas, transitions, and workflow-specific instruction text.
+- Wrapper prompts in `prompts/` are for `/rally` command resolution and loop bootstrap only.
 
-`rally skill run` resolves context in this order:
+If prompt text is specific to a workflow's behavior, keep it in the workflow crate, not in wrapper templates.
 
-1. explicit args (`--session`, `--as`, positional selectors)
-2. invite token input
-3. saved local workspace context
-4. interactive prompt fallback
+## Skill Wrappers
 
-## Troubleshooting
+Install wrappers:
 
-Use doctor to inspect path/status per target:
+```bash
+rally skill install --target all
+```
+
+Canonical wrapper entrypoint:
+
+```bash
+rally skill run ...
+```
+
+Alias:
 
 ```bash
-rally skill doctor --target all
+rally skill exec ...
 ```
 
-For details and target path mapping, see [docs/skill-install-run.md](docs/skill-install-run.md).
+Wrapper helpers:
+
+- `rally skill agent-howto ...`
+- `rally skill context`
+- `rally skill doctor --target ...`
+- `rally skill uninstall --target ...`
+
+For install/run details, see [docs/skill-install-run.md](docs/skill-install-run.md).