Skip to content

PostgreSQL backup tool with Point-In-Time-Recovery and restore verification

REFACTOR (agents): Let agents refactor touched code instead of listing suggestions, answer a blocked full review with one short line and summarize results without review rounds, and add the pack command, foreground checks, repository-only memory and the git-commits skill for Claude Code

Rostislav Dugin790d6cb85326
diff --git a/.agent-hooks/review_gate.py b/.agent-hooks/review_gate.py
index 41408f9b..5c51213d 100755
--- a/.agent-hooks/review_gate.py
+++ b/.agent-hooks/review_gate.py
@@ -94,6 +94,13 @@ OPENSPEC_PLANNING_COMMANDS = (
"$openspec-update-change",
)
PLANNING_COMMANDS = (*OPENSPEC_PLANNING_COMMANDS, "/plan")
+# The repeat review reads the reply after a block, so the reply names the rejected findings,
+# and the summary for the user waits until the review accepts the result.
+FULL_REVIEW_REPLY_INSTRUCTION = (
+ "Then finish the turn again with one short line about your fixes that names every rejected finding "
+ "with the reason. Do not write the summary for the user yet: the hook asks for it once the review accepts the result. "
+ "The repeat review checks the previous findings and the new edits."
+)
HUMANIZER_CONTEXT = (
"Mandatory first step: load the communication skill (.agents/skills/humanizer/SKILL.md) "
"before any other action and apply it to all prose you write. "
@@ -634,8 +641,15 @@ def gate_stop(session, gate, client):
)
return
- feedback = f"{AUTOMATIC_REVIEW_PREFIX} {gate}\n{reason}\nFix the result and finish the turn again; the review will repeat."
- emit({"decision": "block", "reason": feedback})
+ if subject == "plan":
+ instruction = "Revise the plan and show it again; the review will repeat."
+ else:
+ instruction = (
+ f"Fix the {subject}, then finish the turn again with a new reply written for the user: "
+ "a summary of the final state, without retelling this review, its findings or your fixes. "
+ "The review will repeat."
+ )
+ emit({"decision": "block", "reason": f"{AUTOMATIC_REVIEW_PREFIX} {gate}\n{reason}\n{instruction}"})
def get_task_marks(change_dir):
@@ -915,7 +929,7 @@ def gate_full_review(session, client, full_review):
session,
full_review,
f"{check_failure}\n\nNo reviewer ran.",
- "Fix the failure and finish the turn again; the full review will repeat.",
+ "Fix the failure. " + FULL_REVIEW_REPLY_INSTRUCTION,
)
return
@@ -1030,13 +1044,13 @@ IMPLEMENTATION_REVIEW = FullReview(
get_checks=lambda root, targets: get_module_checks(root),
block_instruction="Resolve every finding yourself, without asking the user. Fix a bug in the code. "
"On a spec mismatch, pick the right side and fix the other one, including the change's delta spec. "
- "Reject a false finding and explain why in your final response. Minor findings are optional. "
- "If a reviewer could not run, find the cause of the failure. "
- "Then finish the turn again: the repeat review checks the previous findings and the new edits.",
+ "Reject a false finding. Minor findings are optional. "
+ "If a reviewer could not run, find the cause of the failure. " + FULL_REVIEW_REPLY_INSTRUCTION,
optional_findings_title="Optional findings",
- summary_instruction="Do not change files any more. Write the user a summary of the whole implementation, not only the last round: "
- "what was done for the change's tasks; what the full review found in each round and how you resolved it, "
- "which findings you rejected and why, which minor ones you left; which checks passed; the next step.",
+ summary_instruction="Do not change files any more. Write the user a summary of the implementation as if there had been no review: "
+ "what was done for the change's tasks, which decisions were made, which checks passed, "
+ "which minor findings you left, and the next step. "
+ "Leave out review rounds, findings and the fixes made for them.",
)
PROPOSAL_REVIEW = FullReview(
gate="proposal",
@@ -1054,14 +1068,13 @@ PROPOSAL_REVIEW = FullReview(
Check(".", ("openspec", "validate", target.change_dir.name, "--strict")) for target in targets
],
block_instruction="Resolve every gap, mismatch, tasks and simplify finding yourself, without asking the user: "
- "fix the change's artifacts, and reject a false finding with the reason in your final response. "
+ "fix the change's artifacts, and reject a false finding. "
"Do not apply scope findings: cutting the feature needs the user's consent, and the user sees them in the summary. "
- "Minor findings are optional. If a reviewer could not run, find the cause of the failure. "
- "Then finish the turn again: the repeat review checks the previous findings and the new edits.",
+ "Minor findings are optional. If a reviewer could not run, find the cause of the failure. " + FULL_REVIEW_REPLY_INSTRUCTION,
optional_findings_title="Findings that do not block the turn",
- summary_instruction="Do not change files any more. Write the user a summary of the whole proposal, not only the last round: "
- "what is proposed; what the full review found in each round and how you resolved it, "
- "which findings you rejected and why, which minor ones you left. "
+ summary_instruction="Do not change files any more. Write the user a summary of the proposal as if there had been no review: "
+ "what is proposed and which decisions were made. "
+ "Leave out review rounds, findings and the fixes made for them. "
"List every scope finding separately: what the user loses and what they save, the decision is theirs. "
"End with the next step.",
)
diff --git a/.agent-hooks/review_gate_test.py b/.agent-hooks/review_gate_test.py
index 1a41106b..6ae7db97 100644
--- a/.agent-hooks/review_gate_test.py
+++ b/.agent-hooks/review_gate_test.py
@@ -196,6 +196,19 @@ def finding(category, summary, file="src/widgets.py:10"):
return {"category": category, "file": file, "summary": summary}
+class ShortReplyAssertions:
+ def assert_asks_for_short_reply(self, reason):
+ self.assertIn("one short line about your fixes that names every rejected finding with the reason", reason)
+ self.assertIn("Do not write the summary for the user yet", reason)
+
+
+class SummaryAssertions:
+ def assert_asks_for_summary_without_review(self, reason):
+ self.assertIn("as if there had been no review", reason)
+ self.assertIn("Leave out review rounds, findings and the fixes made for them.", reason)
+ self.assertNotIn("each round", reason)
+
+
class SessionStartTest(unittest.TestCase):
def test_tells_agent_to_load_communication_skill(self):
repository = HookRepository(self)
@@ -269,6 +282,20 @@ class DiffGateTest(unittest.TestCase):
self.assertEqual(response["decision"], "block")
self.assertIn("No test for an empty list.", response["reason"])
+ self.assertIn("a summary of the final state, without retelling this review", response["reason"])
+ self.assertNotIn("Fix the result", response["reason"])
+
+ def test_asks_to_revise_plan_when_necessity_blocks_codex_plan_in_final_message(self):
+ repository = HookRepository(self)
+ repository.set_reviewer_result({"ok": False, "reason": "The plan keeps a compatibility alias."})
+ repository.submit_prompt("/plan the widgets", client="codex")
+
+ response = repository.stop("necessity", client="codex", message="# Plan\n\nAdd widgets.\n")
+
+ self.assertEqual(response["decision"], "block")
+ self.assertIn("The plan keeps a compatibility alias.", response["reason"])
+ self.assertIn("Revise the plan and show it again", response["reason"])
+ self.assertNotIn("summary", response["reason"])
def test_diff_reviewer_prompt_checks_agent_instructions(self):
repository = HookRepository(self)
@@ -530,7 +557,7 @@ class ImplementationGateStartTest(unittest.TestCase):
self.assertEqual(json.loads(process.stdout), {})
-class ImplementationGateChecksTest(unittest.TestCase):
+class ImplementationGateChecksTest(ShortReplyAssertions, unittest.TestCase):
def test_runs_only_backend_linter_when_change_touches_backend(self):
repository = HookRepository(self)
repository.submit_prompt("Continue")
@@ -602,6 +629,7 @@ class ImplementationGateChecksTest(unittest.TestCase):
self.assertEqual(response["decision"], "block")
self.assertIn("`golangci-lint run ./cmd/... ./internal/...` in `backend`", response["reason"])
self.assertIn("service.go:12:2: ineffectual assignment to err", response["reason"])
+ self.assert_asks_for_short_reply(response["reason"])
self.assertEqual(repository.reviewer_calls(), [])
def test_never_runs_formatters_or_just(self):
@@ -644,7 +672,7 @@ class ImplementationGateChecksTest(unittest.TestCase):
self.assertEqual(repository.reviewer_calls(), [])
-class ImplementationGateReviewTest(unittest.TestCase):
+class ImplementationGateReviewTest(ShortReplyAssertions, unittest.TestCase):
def test_runs_reviewer_per_spec_and_one_for_docs_on_claude_with_medium_effort(self):
repository = HookRepository(self)
repository.write_change(spec_names=("widgets", "gadgets"), tasks="- [x] 1.1 Build\n")
@@ -704,6 +732,7 @@ class ImplementationGateReviewTest(unittest.TestCase):
self.assertEqual(response["decision"], "block")
self.assertIn("[bug] src/widgets.py:10: Race between the check and the write.", response["reason"])
self.assertIn("without asking the user", response["reason"])
+ self.assert_asks_for_short_reply(response["reason"])
def test_marks_minor_findings_optional_when_turn_is_blocked(self):
repository = HookRepository(self)
@@ -755,7 +784,7 @@ class ImplementationGateReviewTest(unittest.TestCase):
self.assertIn("rate limit exceeded", response["reason"])
-class ImplementationGateRepeatTest(unittest.TestCase):
+class ImplementationGateRepeatTest(SummaryAssertions, unittest.TestCase):
def block_with_bug(self, repository):
repository.set_reviewer_result({"findings": [finding("bug", "Race between the check and the write.")]})
repository.submit_prompt("Continue")
@@ -792,7 +821,7 @@ class ImplementationGateRepeatTest(unittest.TestCase):
self.assertEqual(len(repository.reviewer_calls()), 2)
- def test_asks_for_summary_of_whole_implementation_once_after_repeat_accepts_change(self):
+ def test_asks_for_summary_without_review_once_after_repeat_accepts_change(self):
repository = HookRepository(self)
self.block_with_bug(repository)
repository.set_reviewer_result({"findings": [finding("minor", "Long function.")]})
@@ -804,7 +833,8 @@ class ImplementationGateRepeatTest(unittest.TestCase):
self.assertEqual(response["decision"], "block")
self.assertIn("accepted the change", response["reason"])
- self.assertIn("summary of the whole implementation", response["reason"])
+ self.assertIn("summary of the implementation", response["reason"])
+ self.assert_asks_for_summary_without_review(response["reason"])
self.assertIn("Long function.", response["reason"])
self.assertEqual(summary_response, {})
self.assertEqual(repository.calls(), [])
@@ -980,7 +1010,7 @@ class ProposalGateValidationTest(unittest.TestCase):
self.assertEqual(repository.reviewer_calls(), [])
-class ProposalGateReviewTest(unittest.TestCase):
+class ProposalGateReviewTest(ShortReplyAssertions, SummaryAssertions, unittest.TestCase):
def test_runs_reviewer_per_spec_and_for_proposal_and_tasks_on_claude_with_medium_effort(self):
repository = HookRepository(self)
repository.submit_prompt("Write a spec")
@@ -1040,6 +1070,7 @@ class ProposalGateReviewTest(unittest.TestCase):
self.assertEqual(response["decision"], "block")
self.assertIn("[simplify] design.md:12: A field in an existing table replaces the new table.", response["reason"])
self.assertIn("without asking the user", response["reason"])
+ self.assert_asks_for_short_reply(response["reason"])
def test_asks_for_summary_with_scope_finding_without_requiring_fix(self):
repository = HookRepository(self)
@@ -1054,7 +1085,8 @@ class ProposalGateReviewTest(unittest.TestCase):
self.assertEqual(response["decision"], "block")
self.assertIn("Full proposal review accepted the proposal.", response["reason"])
self.assertIn("[scope] (the user decides) proposal.md:5: The settings screen can be dropped.", response["reason"])
- self.assertIn("summary of the whole proposal", response["reason"])
+ self.assertIn("summary of the proposal", response["reason"])
+ self.assert_asks_for_summary_without_review(response["reason"])
self.assertIn("what the user loses and what they save", response["reason"])
self.assertEqual(summary_response, {})
self.assertEqual(repository.calls(), [])
@@ -1086,7 +1118,7 @@ class ProposalGateReviewTest(unittest.TestCase):
self.assertIn("does not match the schema", response["reason"])
-class ProposalGateRepeatTest(unittest.TestCase):
+class ProposalGateRepeatTest(ShortReplyAssertions, SummaryAssertions, unittest.TestCase):
def block_with_gap(self, repository):
repository.set_reviewer_result({"findings": [finding("gap", "The answer for an empty list is missing.", file="specs/gadgets/spec.md:8")]})
repository.submit_prompt("Write a spec")
@@ -1094,6 +1126,19 @@ class ProposalGateRepeatTest(unittest.TestCase):
repository.stop("proposal")
repository.clear_calls()
+ def test_blocks_turn_with_gap_and_asks_for_short_reply_without_summary(self):
+ repository = HookRepository(self)
+ repository.set_reviewer_result({"findings": [finding("gap", "The answer for an empty list is missing.", file="specs/gadgets/spec.md:8")]})
+ repository.submit_prompt("Write a spec")
+ repository.write_proposal()
+
+ response = repository.stop("proposal")
+
+ self.assertEqual(response["decision"], "block")
+ self.assertIn("[gap] specs/gadgets/spec.md:8: The answer for an empty list is missing.", response["reason"])
+ self.assertIn("without asking the user", response["reason"])
+ self.assert_asks_for_short_reply(response["reason"])
+
def test_repeat_runs_one_reviewer_with_previous_findings_and_files_changed_after_review(self):
repository = HookRepository(self)
self.block_with_gap(repository)
@@ -1108,7 +1153,7 @@ class ProposalGateRepeatTest(unittest.TestCase):
self.assertIn(f"- openspec/changes/{PROPOSAL_NAME}/specs/gadgets/spec.md", changed_paths)
self.assertNotIn("design.md", changed_paths)
- def test_asks_for_summary_of_whole_proposal_once_after_repeat_accepts_it(self):
+ def test_asks_for_summary_without_review_once_after_repeat_accepts_proposal(self):
repository = HookRepository(self)
self.block_with_gap(repository)
repository.set_reviewer_result({"findings": []})
@@ -1120,10 +1165,24 @@ class ProposalGateRepeatTest(unittest.TestCase):
self.assertEqual(response["decision"], "block")
self.assertIn("accepted the proposal", response["reason"])
- self.assertIn("summary of the whole proposal", response["reason"])
+ self.assertIn("summary of the proposal", response["reason"])
+ self.assert_asks_for_summary_without_review(response["reason"])
self.assertEqual(summary_response, {})
self.assertEqual(repository.calls(), [])
+ def test_lists_scope_option_in_summary_without_review_when_repeat_accepts_proposal(self):
+ repository = HookRepository(self)
+ self.block_with_gap(repository)
+ repository.set_reviewer_result({"findings": [finding("scope", "The settings screen can be dropped.", file="proposal.md:5")]})
+ repository.write(f"openspec/changes/{PROPOSAL_NAME}/specs/gadgets/spec.md", "# gadgets\n\nEmpty list.\n")
+
+ response = repository.stop("proposal")
+
+ self.assertEqual(response["decision"], "block")
+ self.assertIn("[scope] (the user decides) proposal.md:5: The settings screen can be dropped.", response["reason"])
+ self.assertIn("List every scope finding separately: what the user loses and what they save", response["reason"])
+ self.assert_asks_for_summary_without_review(response["reason"])
+
def test_stops_agent_with_remaining_findings_after_third_block(self):
repository = HookRepository(self)
self.block_with_gap(repository)
diff --git a/.claude/skills/git-commits/SKILL.md b/.claude/skills/git-commits/SKILL.md
new file mode 120000
index 00000000..c6297788
--- /dev/null
+++ b/.claude/skills/git-commits/SKILL.md
@@ -0,0 +1 @@
+../../../.agents/skills/git-commits/SKILL.md
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index 564fe699..a617607c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -19,6 +19,7 @@ node_modules/
!.claude/settings.json
!.claude/skills/
.claude/skills/*
+!.claude/skills/git-commits/
!.claude/skills/humanizer/
backend/cleanup_test_db.exe
plans/
diff --git a/AGENTS.md b/AGENTS.md
index 77acec29..6fc6424f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -43,6 +43,10 @@ Work happens on a Fedora host; any other host distro is on its own. Tool version
| `goose -dir backend/migrations up` (or `down`), with `.env` exported | Apply or roll back migrations on the dev database; goose reads `GOOSE_DRIVER` and `GOOSE_DBSTRING` from the environment |
| `swag init -d . -g cmd/main.go -o swagger`, run in `backend/` | Regenerate the API docs |
+### Running commands
+
+Run tests, linters and builds as ordinary foreground commands, so the user sees which command runs and that the agent is working. A backend, frontend or other long-lived process the agent started to check its work is stopped before the task ends. Long-lived processes the user wants running are started by the user.
+
### Several agents, one set of containers
Several agents may work on this repo at once, in different worktrees, sharing one Docker daemon, one set of test containers and one pool of test metadata databases. Don't let that stop you from running tests — simultaneous runs are rare and usually harmless. Two habits keep them that way:
@@ -84,10 +88,6 @@ The dictionaries are the only target-language text anywhere under `frontend/`, `
5. **Deliver quality** — correct, testable, maintainable code with minimal tests/validation. Prefer controller tests over unit tests.
6. **Fix root causes, not symptoms** — ask "why did this happen?" and address the underlying issue.
-### After each run: suggest refactorings
-
-Reread the diff with fresh eyes and **list** (don't silently apply) refactor suggestions: unclear names, duplication, dead code, deep nesting, misplaced responsibilities, leaky abstractions. Keep suggestions concrete (file + lines), behavior-preserving, and scoped to the current change. If the diff is already clean, say so in one line.
-
### Review hooks
Every change answers to this document **and** the module doc for each area it touches. The module docs add stack-specific rules on top of this one; they never replace it, so a change under `backend/` answers to both.
@@ -99,6 +99,8 @@ What the agent does with findings:
- A blocking finding is resolved by the agent itself, without asking the user, and then the agent finishes the turn again. It fixes the code, the documentation or the change's artifacts; when the implementation is right, it fixes the delta spec. A false finding is rejected with the reason in the response.
- A `minor` finding is optional.
- A `scope` finding proposes cutting the feature. The agent does not apply it; the summary shows the user what they lose and what they save, and the user decides.
+- After a full review blocks the turn, whether a reviewer found problems or a check before the reviewers failed, the agent finishes the turn again with one short line about its fixes that names every rejected finding with the reason. The repeat review reads that reply, and the summary for the user waits until the review accepts the result. After a quick check blocks a finished change, the next reply is that summary; after it blocks a plan, the agent revises the plan and shows it again.
+- The summary for the user describes the final state as if there had been no review: what was done, which decisions were made, which checks passed, what remains and the next step. It leaves out review rounds, the findings and the fixes made for them.
- Run the linter and formatter for each directory the diff touches before finishing.
### The best code is unwritten
@@ -112,12 +114,16 @@ The user decides; the task is never cut without their consent. Simplify code wit
### Refactoring within a feature
-The system improves gradually, along with ordinary tasks. If code the task touches stands in the way of the task or breaks the rules of the module docs or an accepted ADR, the refactoring is part of the same task; no separate task for later. The refactoring is limited to the code the task works with and does not touch other agents' changes in the working tree. Agree a large rework that goes beyond the task with the user first.
+The system improves gradually, along with ordinary tasks. If code the task touches stands in the way of the task or breaks the rules of the module docs or an accepted ADR, the refactoring is part of the same task; no separate task for later. The refactoring is limited to the code the task works with and does not touch other agents' changes in the working tree. The agent refactors the touched code while implementing, without asking the user, and lists no refactoring suggestions for it. Its summary names only a refactoring that goes beyond the change, together with its cost, because such a rework needs the user's agreement first.
### Other agents' changes in the working tree
Several agents sometimes work in one branch at once. A file or change the agent did not create within the current request belongs to someone else. Never delete, revert, format, stage or commit someone else's changes. If they must be moved aside with `git stash` before a commit, ask the user first.
+### Agent memory
+
+The agent writes no rules, preferences or facts to its local memory outside the repository, such as `~/.claude/projects/*/memory`. Other agents and people cannot read that memory, Claude Code and Codex keep separate ones, and it drifts from the repository rules. A rule or preference that must outlive the session goes, with the user's consent, into an `AGENTS.md` file or a repository skill.
+
### Naming
Name variables and functions for **intent**, not mechanism. Naming is the biggest readability lever — avoid generic placeholders (`data`, `handle`, `process`, `tmp`, `helper`, `manager`), type-suffix noise (`nameStr`, `agentList`, `tokenObj`), and mechanism-flavored names (`tickNow`, `hbResp`, `dataObj`).
@@ -244,6 +250,8 @@ One rule is written in one place. Other documents link to it instead of retellin
A request to write a spec, write up a change or write its artifacts goes through the `openspec-propose` skill, and an edit to a finished change through `openspec-update-change`. This way the change gets every artifact in OpenSpec format at once.
+When the user asks to pack a change, in any language, the agent first checks that every task in its `tasks.md` is checked; if one is not, it changes nothing and names the unchecked tasks. Otherwise it archives the change through the `openspec-archive-change` skill, and the pack request answers that skill's sync prompt: "Sync now" when the main specs need the delta specs, "Archive now" when they are already synced. Then it commits the implementation, the main specs and the archived change in one commit per the [Git commits skill](.agents/skills/git-commits/SKILL.md). The request is the user's consent to the sync and to that commit, so the agent asks about neither again. The commit leaves out changes the agent did not make, per [Other agents' changes in the working tree](#other-agents-changes-in-the-working-tree), and the agent does not push.
+
### Discussing a task in explore
When the agent works through a task with the user in `/opsx:explore` or the `openspec-explore` skill, it builds the answer from the essence to the mechanics:
diff --git a/openspec/changes/archive/2026-10-18-update-agent-workflow-rules/.openspec.yaml b/openspec/changes/archive/2026-10-18-update-agent-workflow-rules/.openspec.yaml
new file mode 100644
index 00000000..5c881ba7
--- /dev/null
+++ b/openspec/changes/archive/2026-10-18-update-agent-workflow-rules/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-18
diff --git a/openspec/changes/archive/2026-10-18-update-agent-workflow-rules/design.md b/openspec/changes/archive/2026-10-18-update-agent-workflow-rules/design.md
new file mode 100644
index 00000000..0df93ff7
--- /dev/null
+++ b/openspec/changes/archive/2026-10-18-update-agent-workflow-rules/design.md
@@ -0,0 +1,77 @@
+## Context
+
+See proposal.md for the motivation and the delta specs for the behavior contract.
+
+The rules sit in these places today:
+
+- `AGENTS.md:87-89` "After each run: suggest refactorings" tells the agent to list refactorings and not apply them. `AGENTS.md:113-115` "Refactoring within a feature" makes the refactoring part of the task, and `AGENTS.md:111` asks the agent to simplify code within the task itself. The module docs already lean the second way: `backend/AGENTS.md` "Refactor tests as you touch them" and `frontend/AGENTS.md:248`.
+- The reply after a block comes from hook texts. The quick checks block with "Fix the result and finish the turn again" (`.agent-hooks/review_gate.py:637`). A failed check before a full review uses "Fix the failure and finish the turn again" (`:918`). The full reviews block with `block_instruction` (`:1031`, `:1056`) and ask for a summary with `summary_instruction` (`:1037-1039`, `:1062-1066`). That summary covers "what the full review found in each round and how you resolved it". The hook tests pin the old wording at `review_gate_test.py:807`, `:1057` and `:1123`.
+- "Review hooks" in `AGENTS.md:91-102` says what the agent does with findings, and nothing about the shape of the reply.
+- Commits follow `.agents/skills/git-commits/SKILL.md`, and `openspec/config.yaml` apply guidance says "Never commit or push without explicit approval". Nothing describes packing a finished change.
+- `.claude/skills/humanizer/SKILL.md` is a relative symlink to `.agents/skills/humanizer/SKILL.md`. `git-commits` has no entry under `.claude/skills`, so Claude Code does not list it as a skill.
+
+The rules this change adds come from the sibling project's `AGENTS.md`, its hook texts and its `openspec/config.yaml`, translated and fitted to this repository's sections.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- One rule for refactoring touched code, with no contradicting section left.
+- Every hook text that asks for a reply asks for the reply shape the `agent-workflow` spec defines.
+- Each new rule written once, in the section an agent reads for that situation.
+
+**Non-Goals:**
+
+- New hook behavior. Only texts change in the hook script; triggers, gates and state stay as they are.
+- Rewriting the module docs. Their refactoring lines already agree with the new rule.
+
+## Decisions
+
+### The refactoring rule lives in "Refactoring within a feature", and the listing section goes
+
+"After each run: suggest refactorings" is deleted. "Refactoring within a feature" gains two sentences. The agent refactors the touched code while implementing, without asking. Its summary names only refactoring beyond the change, with the cost, because that needs agreement. `openspec/config.yaml` gets one context line that points to the section, the way its last context line already points to "Review hooks".
+
+Rejected: narrowing the listing section to out-of-scope code and keeping it. The two sections would still describe one decision from two places, and "One rule is written in one place" (`AGENTS.md`, "Documentation consistency") forbids that. Rejected: putting the rule only in `openspec/config.yaml`, as the sibling project did. Agents read that file only inside the OpenSpec workflow, and plain requests would keep the old behavior.
+
+### The reply shape is written in "Review hooks" and repeated in every hook text that asks for a reply
+
+"Review hooks" gets two bullets. After a full review blocks the turn, the agent replies with one short line about its fixes and names the rejected findings with reasons, because the repeat review reads that reply. The summary for the user describes the final state as if there had been no review. The hook texts carry the same instruction at the moment it applies:
+
+- the quick check block at `review_gate.py:637` is shared by every stop gate, and its subject comes from `get_stop_subject` (`review_gate.py:569-589`). For the subject "finished change" it asks for a new reply written for the user, as a summary of the final state, without retelling the findings or fixes. For the subject "plan", which Codex shows in its final message, it keeps asking the agent to revise the plan and show it again, as the ExitPlanMode check does at `review_gate.py:555`. The "OpenSpec proposal" subject of the necessity check gets the summary wording, because its reply reports artifacts the agent wrote;
+- the check failure at `:918` and both `block_instruction` strings ask for one short line about the fixes and the rejected findings with reasons, and say that the summary comes after acceptance;
+- both `summary_instruction` strings ask for the summary as if there had been no review. The implementation summary covers what was done, decisions, checks passed, `minor` findings left and the next step. The proposal summary covers what is proposed and the decisions, and still lists every `scope` finding with what the user loses and saves.
+
+The rejected findings stay in the short reply, which is the only reply the repeat review reads.
+
+Rejected: keeping review rounds in the summary and only shortening them. The user does not act on a fixed finding, and the block messages already show each round in the transcript. Rejected: dropping the short line and letting the agent write a full summary after every block. The repeat review would then read a user summary and lose the list of rejected findings it must judge.
+
+### "Pack" is a paragraph in the OpenSpec section, and the commit format stays in the Git commits skill
+
+The OpenSpec section of `AGENTS.md` gains the "pack" command. When the user asks to pack a change, in any language, the agent first checks that every task is checked; if not, it stops and names the unchecked tasks. Then it archives the change through `openspec-archive-change`. That skill already syncs the delta specs inline and verifies the main specs before it moves the change (`.agents/skills/openspec-archive-change/SKILL.md:93-132`). The pack request answers the skill's sync prompt: "Sync now" when the specs need it, "Archive now" when they are already synced. Then the agent commits the implementation, the main specs and the archive in one commit per the Git commits skill. The request is the consent to commit. Changes the agent did not make stay out per "Other agents' changes in the working tree", and the agent does not push. The apply guidance in `openspec/config.yaml` gets the same exception: the "pack" request counts as approval to commit, not to push.
+
+Rejected: running `openspec-sync-specs` before the archive skill. The archive skill syncs on its own, and after a separate sync it would still stop at its "Archive now / Sync anyway / Cancel" prompt. Rejected: a separate skill for packing. The command is two steps that existing skills already perform, so a paragraph that links them is enough. Rejected: pushing as part of the command. Pushing publishes the work, and `AGENTS.md` keeps that a separate decision.
+
+### Running commands gets its own short section next to the command table
+
+A new section "Running commands" under "Development environment" holds both rules: checks run as ordinary foreground commands, and a backend, frontend or other long-lived process the agent started for a check is stopped before the task ends. "Several agents, one set of containers" stays about shared test resources.
+
+Rejected: an exception for long runs in the background, as the sibling project has for its full suite. Agents here run only package tests and linters, which are short.
+
+### Agent memory gets a section in "Engineering philosophy"
+
+A section "Agent memory" says the agent writes nothing to local memory outside the repository, such as `~/.claude/projects/*/memory`. A lasting rule or preference goes, with the user's consent, into `AGENTS.md` or a skill. The reason is stated with it: other agents and people cannot read local memory, and it drifts from the repository rules.
+
+Rejected: allowing local memory for personal preferences only. Claude Code and Codex keep separate memories, so the two clients would behave differently in one repository.
+
+### `git-commits` reaches Claude Code through a symlink, like `humanizer`
+
+`.claude/skills/git-commits/SKILL.md` becomes a relative symlink to `../../../.agents/skills/git-commits/SKILL.md`, the same shape as the existing `humanizer` link.
+
+Rejected: moving every skill into one `.skills/` directory with symlinks from both client directories, as the sibling project does. That also needs regenerating the `openspec-*` skills, which are generated files and carry a hand-added Humanizer preflight. It is out of scope.
+
+## Risks / Trade-offs
+
+- [The user's global `~/.claude/CLAUDE.md` still says to list refactorings and not apply them] → Out of the repository's reach. The summary of this change tells the user, and the project rule is the more specific one for this repository.
+- [Existing local memory entries keep loading after the memory rule lands] → The rule stops new entries. Moving or deleting the old ones is the user's decision, named in the summary.
+- [A summary without review history hides that a rejected finding was argued away] → Rejected findings with reasons stay in the short reply, which the repeat review judges. A finding the repeat review keeps blocks again.
+- [An agent packs a change whose implementation review has not accepted it] → Packing refuses a change with unchecked tasks, and the implementation review runs on the turn that checks the last task, before the user can ask to pack.
diff --git a/openspec/changes/archive/2026-10-18-update-agent-workflow-rules/proposal.md b/openspec/changes/archive/2026-10-18-update-agent-workflow-rules/proposal.md
new file mode 100644
index 00000000..393b1a59
--- /dev/null
+++ b/openspec/changes/archive/2026-10-18-update-agent-workflow-rules/proposal.md
@@ -0,0 +1,43 @@
+## Why
+
+The root `AGENTS.md` gives agents two opposite instructions about refactoring. "After each run: suggest refactorings" (`AGENTS.md:87-89`) tells the agent to list refactorings and not apply them, while "Refactoring within a feature" (`AGENTS.md:113-115`) makes the refactoring part of the same task. Agents follow the first one, so touched code stays unrefactored and the summary ends with a list the user has to turn into work.
+
+The summary an agent writes after a full review also retells every review round, because the hook asks for it (`.agent-hooks/review_gate.py:1037-1039`, `:1062-1066`). The user wants the result, not the history of findings and fixes. The sibling project the same team works in has already fixed both problems. It also has rules this repository lacks: a "pack" command that archives a finished change and commits it in one step, foreground checks, stopping dev processes an agent started, and keeping lasting rules in the repository instead of an agent's local memory. This change brings those rules here.
+
+## Governing docs
+
+This change answers to the root [`AGENTS.md`](../../../AGENTS.md). It touches no code under `backend/`, `agent/`, `frontend/` or `website/`, so the module docs do not govern it.
+
+## What Changes
+
+- Delete "After each run: suggest refactorings" from the root `AGENTS.md`. "Refactoring within a feature" gains the rule that the agent refactors touched code while implementing, without asking, and names in its summary only refactoring that goes beyond the change and needs the user's agreement. `openspec/config.yaml` points to that section.
+- After a blocked full review the agent finishes with one short line about its fixes and names the findings it rejected, because the repeat review reads that reply. The summary for the user describes the final result as if there had been no review. The quick checks ask for the same kind of reply after a block. The hook texts, the "Review hooks" section of `AGENTS.md` and both full review specs change accordingly.
+- Add the "pack" command: sync the change's delta specs into the main specs, archive the change, and commit the code, the main specs and the archive in one commit in the format of the Git commits skill. The command itself is the user's consent to that commit. It does not push.
+- Add a rule that the agent runs tests, linters and builds as ordinary foreground commands, and stops any backend or frontend process it started for a check before the task ends.
+- Add a rule that the agent writes nothing to its local memory outside the repository. A rule or preference that must outlive the session goes into `AGENTS.md` or a skill, with the user's consent.
+- Expose the `git-commits` skill to Claude Code through a symlink in `.claude/skills`, the way `humanizer` already is.
+
+### Out of scope
+
+- Moving the skills into a single `.skills/` directory, upgrading the OpenSpec CLI and regenerating the `openspec-*` skills. Those files are generated, and regenerating them drops the hand-added Humanizer preflight.
+- Moving the user's existing local memory entries into the repository. The user decides which of them become rules.
+- The user's global `~/.claude/CLAUDE.md`, which also tells agents to list refactorings rather than apply them. It lives outside the repository.
+- Running tests from the review hook and a test reviewer. The change `run-change-tests-in-review` covers them.
+
+## Capabilities
+
+### New Capabilities
+
+- `agent-workflow`: how the agent refactors touched code, what its summary after a review contains, the "pack" command, foreground checks and dev processes, where lasting rules live, and which repository skills each agent client can load.
+
+### Modified Capabilities
+
+- `implementation-review`: the reply after a block is one short line for the repeat review, and the summary after acceptance describes the result without review rounds.
+- `proposal-review`: the same for the summary of a proposal; options to cut the feature are still listed separately.
+
+## Impact
+
+- `AGENTS.md`: one section deleted, rules added to "Refactoring within a feature", "Review hooks" and "OpenSpec", new short sections for running commands and agent memory.
+- `openspec/config.yaml`: a context line about refactoring, and the apply guidance on commits names the "pack" command.
+- `.agent-hooks/review_gate.py` and `review_gate_test.py`: block and summary texts.
+- `.claude/skills/git-commits/SKILL.md`: new symlink.
diff --git a/openspec/changes/archive/2026-10-18-update-agent-workflow-rules/specs/agent-workflow/spec.md b/openspec/changes/archive/2026-10-18-update-agent-workflow-rules/specs/agent-workflow/spec.md
new file mode 100644
index 00000000..ab66a1c9
--- /dev/null
+++ b/openspec/changes/archive/2026-10-18-update-agent-workflow-rules/specs/agent-workflow/spec.md
@@ -0,0 +1,75 @@
+## Purpose
+
+Defines how an agent finishes work in this repository: it refactors the code it touches instead of listing suggestions, reports the result rather than the review history, packs a finished change into one commit on request, keeps the user able to see and stop what it runs, and keeps lasting rules where every agent and person can read them.
+
+## ADDED Requirements
+
+### Requirement: The agent refactors touched code within the change
+When code the change touches stands in the way of the change or breaks the rules of the module docs or an accepted ADR, the agent SHALL refactor it while implementing the change, without asking the user and without a separate task for later. The agent's summary MUST NOT list refactoring suggestions for code inside the change. The summary SHALL name only a refactoring that goes beyond the change, together with what it would cost, because such a refactoring needs the user's agreement first.
+
+#### Scenario: Duplicated code in a touched function
+- **WHEN** the agent edits a function and finds that it duplicates a helper next to it
+- **THEN** the agent replaces the duplicate with the helper in the same change, and its summary lists no refactoring suggestion about it
+
+#### Scenario: A rework beyond the change
+- **WHEN** the agent finds that a module the change does not touch needs a larger rework
+- **THEN** the agent does not do the rework, and its summary names it with its cost for the user to decide
+
+### Requirement: The user summary describes the result, not the review
+After a review hook blocked the turn and the agent fixed or rejected the findings, the summary the user reads SHALL describe the final state of the result: what was done, which decisions were made, which checks passed, what remains and the next step. The summary MUST NOT retell review rounds, the findings or the fixes made for them. After a quick check blocks a finished change, the agent's next reply SHALL be such a summary. After a quick check blocks a plan, the agent SHALL revise the plan and show it again. After a full review blocks the turn, whether a reviewer found problems or a check before the reviewers failed, the agent's next reply SHALL be one short line about its fixes that names every rejected finding with the reason, because the repeat review reads that reply; the summary comes once the full review accepts the result.
+
+#### Scenario: The diff check blocks a turn
+- **WHEN** the diff check blocks the turn because a test is missing, and the agent adds the test and finishes the turn again
+- **THEN** the agent's reply is a summary of the finished work for the user and does not mention the diff check or its finding
+
+#### Scenario: A quick check blocks a plan in the final message
+- **WHEN** in Codex the necessity check blocks a plan the agent wrote in its final message
+- **THEN** the block text asks the agent to revise the plan and show it again, not to write a summary of a result
+
+#### Scenario: The full implementation review blocks a turn
+- **WHEN** the full implementation review blocks the turn with two findings, and the agent fixes one and rejects the other
+- **THEN** the agent's reply is one short line that names the fix and the rejected finding with its reason
+
+#### Scenario: A linter fails before the full review
+- **WHEN** the backend linter fails before the full implementation review starts its reviewers, and the agent fixes the lint error
+- **THEN** the agent's reply is one short line about the fix
+
+### Requirement: The pack command archives and commits a finished change
+When the user asks to pack a change, in whatever language the request is written, and every task of the change is checked, the agent SHALL archive the change with its delta specs synced into the main specs, and commit the implementation, the main specs and the archived change in one commit whose message follows the repository's commit format. The request SHALL count as the user's consent to the sync and to that commit, so the agent does not ask about either again. The agent MUST NOT include changes it did not make within the user's requests, and MUST NOT push. When a task of the change is unchecked, the agent MUST NOT sync, archive or commit anything, and SHALL name the unchecked tasks to the user.
+
+#### Scenario: Pack a finished change
+- **WHEN** every task of a change is checked and the user writes "pack"
+- **THEN** the main specs contain the change's requirements, the change sits in the archive, and one new commit holds the code, the specs and the archive, with nothing pushed
+
+#### Scenario: Pack an unfinished change
+- **WHEN** a change has two unchecked tasks and the user writes "pack"
+- **THEN** the main specs, the change directory and the Git history stay as they were, and the agent names the two unchecked tasks
+
+#### Scenario: Another agent's edit in the working tree
+- **WHEN** the user asks to pack a change while the working tree also holds an edit the agent did not make
+- **THEN** the commit leaves that edit out, and it stays uncommitted in the working tree
+
+### Requirement: The user sees and owns what the agent runs
+The agent SHALL run tests, linters and builds as ordinary foreground commands, so the user sees which command runs and that the agent is working. When the agent starts the backend, the frontend or another long-lived process to check its work, it SHALL stop that process before it finishes the task. Long-lived processes the user wants running are started by the user.
+
+#### Scenario: The agent runs package tests
+- **WHEN** the agent runs the tests of a backend package
+- **THEN** the command runs in the foreground of the agent's console, not as a background task
+
+#### Scenario: The agent started the frontend dev server
+- **WHEN** the agent started the frontend dev server to check a page
+- **THEN** the dev server is no longer running when the agent hands the task over
+
+### Requirement: Lasting rules live in the repository
+The agent MUST NOT write rules, preferences or facts to its local memory outside the repository. A rule or preference that must outlive the session SHALL go, with the user's consent, into an `AGENTS.md` file or a repository skill, where every agent and person working in the repository reads it.
+
+#### Scenario: The user states a lasting preference
+- **WHEN** the user says that every future change should do something a certain way
+- **THEN** the agent proposes the edit to `AGENTS.md` or a skill and writes nothing to its local memory
+
+### Requirement: Every repository skill is available to each agent client
+Each of the repository's own skills, that is every skill except the generated `openspec-*` skills, SHALL be loadable as a skill both in Claude Code and in Codex, from one source file, so the two clients never read different versions of it.
+
+#### Scenario: The commit skill in Claude Code
+- **WHEN** Claude Code lists the skills it can load in this repository
+- **THEN** the list contains the Git commits skill, and it reads the same file Codex reads
diff --git a/openspec/changes/archive/2026-10-18-update-agent-workflow-rules/specs/implementation-review/spec.md b/openspec/changes/archive/2026-10-18-update-agent-workflow-rules/specs/implementation-review/spec.md
new file mode 100644
index 00000000..25388b93
--- /dev/null
+++ b/openspec/changes/archive/2026-10-18-update-agent-workflow-rules/specs/implementation-review/spec.md
@@ -0,0 +1,20 @@
+## MODIFIED Requirements
+
+### Requirement: Which findings block the turn
+A reviewer SHALL return findings, each with a category (`bug`, `spec_mismatch`, `missing_test`, `docs`, `minor`), a path and a description. The hook SHALL block the turn when at least one finding is not `minor`, and pass the agent every finding with `minor` marked optional. When the turn is not blocked, the user SHALL see the `minor` findings. The block text SHALL require the agent to resolve every finding without asking the user: fix the code or, when the implementation is right, the change's delta spec. The block text SHALL also require the agent to finish the turn again with one short line about its fixes that names every rejected finding with the reason, and to leave the summary for the user until the review accepts the change. With no findings or only `minor` ones, the review SHALL count as accepted. When the review accepts the change after at least one block within this user request, the hook SHALL block the turn once and ask the agent to write the user a summary of the implementation as if there had been no review: what was done for the change's tasks, which decisions were made, which checks passed, which `minor` findings were left, and the next step, without review rounds, findings or the fixes made for them. The hook SHALL pass the `minor` findings in that request.
+
+#### Scenario: Only minor findings
+- **WHEN** every finding is `minor`, and no earlier review in this request blocked the turn
+- **THEN** the state is stored as accepted and the user sees the findings
+
+#### Scenario: Accepted after fixes
+- **WHEN** a repeat review accepts a change the previous review blocked
+- **THEN** the hook blocks the turn once and asks the agent for a summary of the implementation that leaves out review rounds and the fixes made for them, and the next turn without edits is not blocked
+
+#### Scenario: A bug is found
+- **WHEN** a reviewer returns a `bug` finding
+- **THEN** the turn is blocked, and the agent gets every finding with the instruction to resolve them itself and to finish the turn with one short line about the fixes and the rejected findings
+
+#### Scenario: The reviewer cannot run
+- **WHEN** the reviewer process crashes or times out
+- **THEN** the review is not accepted and the agent gets the failure reason
diff --git a/openspec/changes/archive/2026-10-18-update-agent-workflow-rules/specs/proposal-review/spec.md b/openspec/changes/archive/2026-10-18-update-agent-workflow-rules/specs/proposal-review/spec.md
new file mode 100644
index 00000000..210e9406
--- /dev/null
+++ b/openspec/changes/archive/2026-10-18-update-agent-workflow-rules/specs/proposal-review/spec.md
@@ -0,0 +1,24 @@
+## MODIFIED Requirements
+
+### Requirement: Repeat and summary of the full proposal review
+After a blocked review the next run SHALL check the previous findings and the change's files that changed after that review, not the whole proposal again. The block text SHALL require the agent to finish the turn again with one short line about its fixes that names every rejected finding with the reason, and to leave the summary for the user until the review accepts the proposal. There SHALL be at most two repeats per user request, after which the hook SHALL stop the agent and show the remaining findings. When the review accepts the proposal after at least one block in this request, or returns `scope` findings, the hook SHALL block the turn once and ask the agent to write the user a summary of the proposal as if there had been no review: what is proposed and which decisions were made, without review rounds, findings or the fixes made for them, and separately each option to cut the feature with what the user loses and saves. The next turn without edits to the change's files MUST NOT be blocked.
+
+#### Scenario: A gap blocks the turn
+- **WHEN** the proposal review blocks the turn with a `gap` finding
+- **THEN** the block text asks the agent to resolve the finding without asking the user and to finish the turn with one short line about the fixes that names each rejected finding with its reason, and not to write the user summary yet
+
+#### Scenario: Accepted after fixes
+- **WHEN** a repeat review accepts a proposal the previous review blocked
+- **THEN** the hook once asks the agent for a summary of the proposal that leaves out review rounds and the fixes made for them, and the next turn without edits is not blocked
+
+#### Scenario: Accepted at once without cuts
+- **WHEN** the first review returns only `minor` findings
+- **THEN** the turn is not blocked and the user sees the findings
+
+#### Scenario: Accepted after fixes with an option to cut the feature
+- **WHEN** a repeat review accepts a proposal the previous review blocked, and returns a `scope` finding
+- **THEN** the summary request asks to list that option with what the user loses and saves, and to leave out the review rounds and the fixes made for them
+
+#### Scenario: Repeat limit
+- **WHEN** the third proposal review in a row within one user request blocks the turn again
+- **THEN** the hook stops the agent and shows the remaining findings
diff --git a/openspec/changes/archive/2026-10-18-update-agent-workflow-rules/tasks.md b/openspec/changes/archive/2026-10-18-update-agent-workflow-rules/tasks.md
new file mode 100644
index 00000000..baa7c96e
--- /dev/null
+++ b/openspec/changes/archive/2026-10-18-update-agent-workflow-rules/tasks.md
@@ -0,0 +1,42 @@
+The hook test command below runs from the repository root: `python3 -m unittest discover -s .agent-hooks -p '*_test.py'`.
+
+## 1. Reply shape in the hook texts
+
+- [x] 1.1 Rewrite the quick check block text at `.agent-hooks/review_gate.py:637` per design.md. For the subjects "finished change" and "OpenSpec proposal", the agent fixes the result and finishes the turn again with a new reply written for the user, as a summary of the final state, without retelling the findings or the fixes. For the subject "plan", the agent revises the plan and shows it again. Add these tests:
+ - extend `test_blocks_turn_with_reviewer_reason_when_reviewer_rejects` in `DiffGateTest` to assert that the block reason asks for a summary of the final state and no longer says "Fix the result" (`agent-workflow` scenario "The diff check blocks a turn");
+ - a test where a Codex plan turn is blocked by the necessity check, asserting that the reason asks to revise the plan and show it again and does not ask for a summary ("A quick check blocks a plan in the final message").
+
+ Verify with the hook test command.
+- [x] 1.2 Rewrite the check failure text at `review_gate.py:918` and both `block_instruction` strings (`:1031`, `:1056`) per design.md: finish the turn again with one short line about the fixes that names every rejected finding with its reason, and leave the summary for the user until the review accepts the result. Extend these tests to assert the "one short line" instruction, the rejected findings with reasons, and that no summary is asked for yet:
+ - `test_blocks_turn_and_requires_agent_to_resolve_findings_when_reviewer_finds_bug`, covering the `implementation-review` scenario "A bug is found" and the `agent-workflow` scenario "The full implementation review blocks a turn";
+ - `test_blocks_turn_with_output_tail_when_linter_fails`, covering the `agent-workflow` scenario "A linter fails before the full review";
+ - `test_blocks_turn_and_requires_agent_to_resolve_simplify_finding_without_asking_user`, plus a new test where a `gap` finding blocks the proposal review, covering the `proposal-review` scenario "A gap blocks the turn".
+
+ Verify with the hook test command.
+- [x] 1.3 Rewrite both `summary_instruction` strings (`review_gate.py:1037-1039`, `:1062-1066`) to ask for a summary as if there had been no review, with the contents design.md lists for each. The proposal summary still lists every `scope` finding with what the user loses and saves. Rename and update the tests that pin the old wording at `review_gate_test.py:807`, `:1057` and `:1123`, so they assert the "as if there had been no review" wording and that "each round" is gone. They cover the scenarios "Accepted after fixes" of both `implementation-review` and `proposal-review`. Add a test where a repeat proposal review accepts with a `scope` finding, asserting the summary request lists the option with what the user loses and saves and asks to leave out review rounds ("Accepted after fixes with an option to cut the feature"). Verify with the hook test command, and with `grep -n "each round\|whole implementation, not only\|whole proposal, not only" .agent-hooks/review_gate.py` returning nothing.
+
+## 2. Agent instructions
+
+- [x] 2.1 Delete "After each run: suggest refactorings" (`AGENTS.md:87-89`). Add to "Refactoring within a feature" the two sentences from design.md: the agent refactors the touched code while implementing, without asking the user, and its summary names only refactoring that goes beyond the change, together with its cost. Add the context line to `openspec/config.yaml` that points to that section. Verify with these searches:
+ - `grep -n "suggest refactorings\|don't silently apply" AGENTS.md` returns nothing;
+ - `grep -n "while implementing, without asking" AGENTS.md` and `grep -n "goes beyond the change, together with its cost" AGENTS.md` each find the new sentence;
+ - `grep -n "Refactoring within a feature" openspec/config.yaml` finds the new line.
+- [x] 2.2 Add the two bullets about the reply after a block and the summary without review history to "Review hooks" in `AGENTS.md`, per design.md. Verify with `grep -n "one short line" AGENTS.md` and `grep -n "as if there had been no review" AGENTS.md` each finding its bullet.
+- [x] 2.3 Add the "pack" paragraph to the OpenSpec section of `AGENTS.md` per design.md. It covers:
+ - refusing a change with unchecked tasks;
+ - `openspec-archive-change` with the pack request as the answer to its sync prompt;
+ - one commit per the Git commits skill;
+ - "Other agents' changes in the working tree";
+ - no push.
+
+ In `openspec/config.yaml` apply guidance, state that a "pack" request is approval to commit, not to push. Verify with `grep -n 'pack' AGENTS.md | grep openspec-archive-change` finding the paragraph and `grep -n "approval to commit, not to push" openspec/config.yaml` finding the guidance.
+- [x] 2.4 Add the "Running commands" section under "Development environment" (foreground checks; stop long-lived processes the agent started for a check) and the "Agent memory" section under "Engineering philosophy" (no local memory outside the repository; lasting rules go into `AGENTS.md` or a skill with the user's consent), per design.md. Verify with `grep -n "^### Running commands\|^### Agent memory" AGENTS.md` finding both headings.
+- [x] 2.5 Search the repository for other mentions of the changed rules and bring them in line per "Documentation consistency": the module docs, `adr/`, the repository's own skills and the hook prompts. Verify with `grep -rn -i "suggest refactor\|list refactor\|each review round\|whole implementation, not only" --include='*.md' --include='*.py' --include='*.yaml' . | grep -v '^./openspec/'` returning nothing.
+
+## 3. Skill exposure
+
+- [x] 3.1 Create `.claude/skills/git-commits/SKILL.md` as a relative symlink to `../../../.agents/skills/git-commits/SKILL.md`, the same shape as the `humanizer` link. Verify with `readlink .claude/skills/git-commits/SKILL.md` printing that target and `head -3 .claude/skills/git-commits/SKILL.md` printing the skill's front matter. This covers the `agent-workflow` scenario "The commit skill in Claude Code".
+
+## 4. Change validation
+
+- [x] 4.1 Verify with `openspec validate update-agent-workflow-rules --strict` passing and the hook test command passing.
diff --git a/openspec/config.yaml b/openspec/config.yaml
index 500d8959..b123d9e7 100644
--- a/openspec/config.yaml
+++ b/openspec/config.yaml
@@ -32,6 +32,8 @@ context: |
- Review hooks gate plans, finished turns, full proposals and full
implementations. Resolve their findings as the "Review hooks" section
of AGENTS.md says.
+ - Refactor the code the change touches while implementing, as the
+ "Refactoring within a feature" section of AGENTS.md says.
rules:
proposal:
@@ -62,7 +64,7 @@ operations:
guidance:
- Run the linter for every directory the diff touches before finishing.
- Resolve every blocking review hook finding before finishing; never apply a scope finding without the user's consent.
- - Never commit or push without explicit approval. No AI attribution trailers in commit messages.
+ - Never commit or push without explicit approval. A "pack" request, as the OpenSpec section of AGENTS.md describes it, is approval to commit, not to push. No AI attribution trailers in commit messages.
archive:
guidance:
- Confirm the module AGENTS.md files were updated if the change introduced a convention.
diff --git a/openspec/specs/agent-workflow/spec.md b/openspec/specs/agent-workflow/spec.md
new file mode 100644
index 00000000..a55dfde9
--- /dev/null
+++ b/openspec/specs/agent-workflow/spec.md
@@ -0,0 +1,76 @@
+# agent-workflow Specification
+
+## Purpose
+Defines how an agent finishes work in this repository: it refactors the code it touches instead of listing suggestions, reports the result rather than the review history, packs a finished change into one commit on request, keeps the user able to see and stop what it runs, and keeps lasting rules where every agent and person can read them.
+
+## Requirements
+
+### Requirement: The agent refactors touched code within the change
+When code the change touches stands in the way of the change or breaks the rules of the module docs or an accepted ADR, the agent SHALL refactor it while implementing the change, without asking the user and without a separate task for later. The agent's summary MUST NOT list refactoring suggestions for code inside the change. The summary SHALL name only a refactoring that goes beyond the change, together with what it would cost, because such a refactoring needs the user's agreement first.
+
+#### Scenario: Duplicated code in a touched function
+- **WHEN** the agent edits a function and finds that it duplicates a helper next to it
+- **THEN** the agent replaces the duplicate with the helper in the same change, and its summary lists no refactoring suggestion about it
+
+#### Scenario: A rework beyond the change
+- **WHEN** the agent finds that a module the change does not touch needs a larger rework
+- **THEN** the agent does not do the rework, and its summary names it with its cost for the user to decide
+
+### Requirement: The user summary describes the result, not the review
+After a review hook blocked the turn and the agent fixed or rejected the findings, the summary the user reads SHALL describe the final state of the result: what was done, which decisions were made, which checks passed, what remains and the next step. The summary MUST NOT retell review rounds, the findings or the fixes made for them. After a quick check blocks a finished change, the agent's next reply SHALL be such a summary. After a quick check blocks a plan, the agent SHALL revise the plan and show it again. After a full review blocks the turn, whether a reviewer found problems or a check before the reviewers failed, the agent's next reply SHALL be one short line about its fixes that names every rejected finding with the reason, because the repeat review reads that reply; the summary comes once the full review accepts the result.
+
+#### Scenario: The diff check blocks a turn
+- **WHEN** the diff check blocks the turn because a test is missing, and the agent adds the test and finishes the turn again
+- **THEN** the agent's reply is a summary of the finished work for the user and does not mention the diff check or its finding
+
+#### Scenario: A quick check blocks a plan in the final message
+- **WHEN** in Codex the necessity check blocks a plan the agent wrote in its final message
+- **THEN** the block text asks the agent to revise the plan and show it again, not to write a summary of a result
+
+#### Scenario: The full implementation review blocks a turn
+- **WHEN** the full implementation review blocks the turn with two findings, and the agent fixes one and rejects the other
+- **THEN** the agent's reply is one short line that names the fix and the rejected finding with its reason
+
+#### Scenario: A linter fails before the full review
+- **WHEN** the backend linter fails before the full implementation review starts its reviewers, and the agent fixes the lint error
+- **THEN** the agent's reply is one short line about the fix
+
+### Requirement: The pack command archives and commits a finished change
+When the user asks to pack a change, in whatever language the request is written, and every task of the change is checked, the agent SHALL archive the change with its delta specs synced into the main specs, and commit the implementation, the main specs and the archived change in one commit whose message follows the repository's commit format. The request SHALL count as the user's consent to the sync and to that commit, so the agent does not ask about either again. The agent MUST NOT include changes it did not make within the user's requests, and MUST NOT push. When a task of the change is unchecked, the agent MUST NOT sync, archive or commit anything, and SHALL name the unchecked tasks to the user.
+
+#### Scenario: Pack a finished change
+- **WHEN** every task of a change is checked and the user writes "pack"
+- **THEN** the main specs contain the change's requirements, the change sits in the archive, and one new commit holds the code, the specs and the archive, with nothing pushed
+
+#### Scenario: Pack an unfinished change
+- **WHEN** a change has two unchecked tasks and the user writes "pack"
+- **THEN** the main specs, the change directory and the Git history stay as they were, and the agent names the two unchecked tasks
+
+#### Scenario: Another agent's edit in the working tree
+- **WHEN** the user asks to pack a change while the working tree also holds an edit the agent did not make
+- **THEN** the commit leaves that edit out, and it stays uncommitted in the working tree
+
+### Requirement: The user sees and owns what the agent runs
+The agent SHALL run tests, linters and builds as ordinary foreground commands, so the user sees which command runs and that the agent is working. When the agent starts the backend, the frontend or another long-lived process to check its work, it SHALL stop that process before it finishes the task. Long-lived processes the user wants running are started by the user.
+
+#### Scenario: The agent runs package tests
+- **WHEN** the agent runs the tests of a backend package
+- **THEN** the command runs in the foreground of the agent's console, not as a background task
+
+#### Scenario: The agent started the frontend dev server
+- **WHEN** the agent started the frontend dev server to check a page
+- **THEN** the dev server is no longer running when the agent hands the task over
+
+### Requirement: Lasting rules live in the repository
+The agent MUST NOT write rules, preferences or facts to its local memory outside the repository. A rule or preference that must outlive the session SHALL go, with the user's consent, into an `AGENTS.md` file or a repository skill, where every agent and person working in the repository reads it.
+
+#### Scenario: The user states a lasting preference
+- **WHEN** the user says that every future change should do something a certain way
+- **THEN** the agent proposes the edit to `AGENTS.md` or a skill and writes nothing to its local memory
+
+### Requirement: Every repository skill is available to each agent client
+Each of the repository's own skills, that is every skill except the generated `openspec-*` skills, SHALL be loadable as a skill both in Claude Code and in Codex, from one source file, so the two clients never read different versions of it.
+
+#### Scenario: The commit skill in Claude Code
+- **WHEN** Claude Code lists the skills it can load in this repository
+- **THEN** the list contains the Git commits skill, and it reads the same file Codex reads
diff --git a/openspec/specs/implementation-review/spec.md b/openspec/specs/implementation-review/spec.md
index 0864d6de..6a01a5b5 100644
--- a/openspec/specs/implementation-review/spec.md
+++ b/openspec/specs/implementation-review/spec.md
@@ -74,7 +74,7 @@ The full review reviewers SHALL run on Opus with `medium` effort in Claude Code
- **THEN** the reviewer runs on Opus with `low` effort
### Requirement: Which findings block the turn
-A reviewer SHALL return findings, each with a category (`bug`, `spec_mismatch`, `missing_test`, `docs`, `minor`), a path and a description. The hook SHALL block the turn when at least one finding is not `minor`, and pass the agent every finding with `minor` marked optional. When the turn is not blocked, the user SHALL see the `minor` findings. The block text SHALL require the agent to resolve every finding without asking the user: fix the code or, when the implementation is right, the change's delta spec. With no findings or only `minor` ones, the review SHALL count as accepted. When the review accepts the change after at least one block within this user request, the hook SHALL block the turn once and ask the agent to write the user a summary of the whole implementation, including each review round, and pass the `minor` findings in that request.
+A reviewer SHALL return findings, each with a category (`bug`, `spec_mismatch`, `missing_test`, `docs`, `minor`), a path and a description. The hook SHALL block the turn when at least one finding is not `minor`, and pass the agent every finding with `minor` marked optional. When the turn is not blocked, the user SHALL see the `minor` findings. The block text SHALL require the agent to resolve every finding without asking the user: fix the code or, when the implementation is right, the change's delta spec. The block text SHALL also require the agent to finish the turn again with one short line about its fixes that names every rejected finding with the reason, and to leave the summary for the user until the review accepts the change. With no findings or only `minor` ones, the review SHALL count as accepted. When the review accepts the change after at least one block within this user request, the hook SHALL block the turn once and ask the agent to write the user a summary of the implementation as if there had been no review: what was done for the change's tasks, which decisions were made, which checks passed, which `minor` findings were left, and the next step, without review rounds, findings or the fixes made for them. The hook SHALL pass the `minor` findings in that request.
#### Scenario: Only minor findings
- **WHEN** every finding is `minor`, and no earlier review in this request blocked the turn
@@ -82,11 +82,11 @@ A reviewer SHALL return findings, each with a category (`bug`, `spec_mismatch`,
#### Scenario: Accepted after fixes
- **WHEN** a repeat review accepts a change the previous review blocked
-- **THEN** the hook blocks the turn once and asks the agent for a summary of the whole implementation, and the next turn without edits is not blocked
+- **THEN** the hook blocks the turn once and asks the agent for a summary of the implementation that leaves out review rounds and the fixes made for them, and the next turn without edits is not blocked
#### Scenario: A bug is found
- **WHEN** a reviewer returns a `bug` finding
-- **THEN** the turn is blocked, and the agent gets every finding with the instruction to resolve them itself
+- **THEN** the turn is blocked, and the agent gets every finding with the instruction to resolve them itself and to finish the turn with one short line about the fixes and the rejected findings
#### Scenario: The reviewer cannot run
- **WHEN** the reviewer process crashes or times out
diff --git a/openspec/specs/proposal-review/spec.md b/openspec/specs/proposal-review/spec.md
index f7af1e33..c5305892 100644
--- a/openspec/specs/proposal-review/spec.md
+++ b/openspec/specs/proposal-review/spec.md
@@ -60,16 +60,24 @@ A reviewer SHALL return findings, each with a category, a path and a description
- **THEN** the hook does not require a fix and once asks the agent for a summary that shows this option to the user
### Requirement: Repeat and summary of the full proposal review
-After a blocked review the next run SHALL check the previous findings and the change's files that changed after that review, not the whole proposal again. There SHALL be at most two repeats per user request, after which the hook SHALL stop the agent and show the remaining findings. When the review accepts the proposal after at least one block in this request, or returns `scope` findings, the hook SHALL block the turn once and ask the agent to write the user a summary of the whole proposal: what is proposed, what each review round found and how it was resolved, and separately each option to cut the feature with what the user loses and saves. The next turn without edits to the change's files MUST NOT be blocked.
+After a blocked review the next run SHALL check the previous findings and the change's files that changed after that review, not the whole proposal again. The block text SHALL require the agent to finish the turn again with one short line about its fixes that names every rejected finding with the reason, and to leave the summary for the user until the review accepts the proposal. There SHALL be at most two repeats per user request, after which the hook SHALL stop the agent and show the remaining findings. When the review accepts the proposal after at least one block in this request, or returns `scope` findings, the hook SHALL block the turn once and ask the agent to write the user a summary of the proposal as if there had been no review: what is proposed and which decisions were made, without review rounds, findings or the fixes made for them, and separately each option to cut the feature with what the user loses and saves. The next turn without edits to the change's files MUST NOT be blocked.
+
+#### Scenario: A gap blocks the turn
+- **WHEN** the proposal review blocks the turn with a `gap` finding
+- **THEN** the block text asks the agent to resolve the finding without asking the user and to finish the turn with one short line about the fixes that names each rejected finding with its reason, and not to write the user summary yet
#### Scenario: Accepted after fixes
- **WHEN** a repeat review accepts a proposal the previous review blocked
-- **THEN** the hook once asks the agent for a summary of the whole proposal, and the next turn without edits is not blocked
+- **THEN** the hook once asks the agent for a summary of the proposal that leaves out review rounds and the fixes made for them, and the next turn without edits is not blocked
#### Scenario: Accepted at once without cuts
- **WHEN** the first review returns only `minor` findings
- **THEN** the turn is not blocked and the user sees the findings
+#### Scenario: Accepted after fixes with an option to cut the feature
+- **WHEN** a repeat review accepts a proposal the previous review blocked, and returns a `scope` finding
+- **THEN** the summary request asks to list that option with what the user loses and saves, and to leave out the review rounds and the fixes made for them
+
#### Scenario: Repeat limit
- **WHEN** the third proposal review in a row within one user request blocks the turn again
- **THEN** the hook stops the agent and shows the remaining findings