diff --git a/docs/agents.md b/docs/agents.md index 108954d..cdb0331 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -20,7 +20,7 @@ The shared [orchestration rule](../shared/rules/orchestration.md) defines the `R ## Task state -For long-running work, the main agent maintains one compact state containing `goal`, `decisions`, `changed`, `verified`, `open`, and `risks`. An existing task-state facility is preferred; the file fallback is `.ai-session/state.json` in the current workspace. Subagents may read it when needed, but send updates to the parent. Keep unrelated concurrent tasks in separate checkouts, and keep runtime state out of commits. +See the [canonical task-state policy](../shared/rules/orchestration.md#canonical-task-state) for when to use state and what it may contain. The optional `.ai-session/state.json` file is local handoff state for a long-running active goal, not persistent project memory. The optional `scripts/commands/session-state.ps1` and `scripts/commands/session-state.sh` helpers update this workspace file. Omitted fields are preserved. Their `-Workspace`/`--workspace` option selects the workspace explicitly; the default is the current working directory. Both accept goal, decisions, changed files, completed verification, open items, and risks. `-Pointer`/`--pointer` only prints the existing file's location. diff --git a/shared/rules/orchestration.md b/shared/rules/orchestration.md index 96326a4..5f0e241 100644 --- a/shared/rules/orchestration.md +++ b/shared/rules/orchestration.md @@ -37,7 +37,9 @@ Verifier: execution evidence against acceptance criteria. Choose relevant tests, ## Canonical task state -For long-running work, the main agent maintains one compact state with `goal`, `decisions`, `changed`, `verified`, `open`, and `risks`. Store conclusions and file/symbol references, never transcripts, copied source, secrets, or narration. Update after material decisions, changes, and verification, before compaction when possible. Mark stale evidence after relevant edits. +Use task state only for work expected to span multiple hours, compaction, or an interrupted session. For short, bounded work, rely on the conversation and current Git diff/working tree; do not create state just to record routine progress. Task state is a handoff for the active goal, not persistent project memory. + +When needed, the main agent maintains one compact state with `goal`, `decisions`, `changed`, `verified`, `open`, and `risks`. Store conclusions and file/symbol references, never transcripts, copied source, secrets, unrelated project knowledge, or narration. Update after material decisions, changes, and verification, before compaction when possible. Mark stale evidence after relevant edits and reset state when starting a different goal. Use an existing task-state facility when available; otherwise use the workspace's `.ai-session/state.json`. Keep one active owner per workspace; use separate checkouts for concurrent unrelated tasks. Runtime state is local, not committed. Explicitly share its location when needed; subagents may read it but return updates to the parent instead of maintaining copies. Do not paste the full state into every assignment.