PostgreSQL backup tool with Point-In-Time-Recovery and restore verification
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
- WHEN the necessity check blocks a plan the agent submits through ExitPlanMode
- 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.mdor a skill and writes nothing to its local memory
Requirement: Every repository skill has one source file
Every skill of the repository, including the generated openspec-* skills, SHALL have one source file under .agents/skills/. Claude Code SHALL load it through .claude/skills, a symlink to that directory, so no copy can drift from the source.
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, read from
.agents/skills/git-commits/SKILL.md
Requirement: The agent can see and drive the local app
The repository SHALL register one browser automation server for Claude Code. With it, an agent opens pages of the local app and reads what the page shows, including a screenshot, the page structure, console messages and network requests. It also clicks, types and navigates. Claude Code SHALL start the server from the repository configuration. The server SHALL drive the Chrome browser installed on the host. Each agent session SHALL get its own temporary browser profile, which is discarded when the session's browser closes, so that two sessions running at once do not block each other and no sign-in carries over between sessions.
The repository SHALL hold a skill that tells the agent how to check the app in the browser:
- When the backend and frontend ports already answer from a
just runstarted in the agent's own worktree, the agent uses that app. - When they answer from another worktree, the agent leaves that app running, does not run the browser check, and tells the user the check was skipped because the running app serves another worktree's code.
- When only one of the two ports answers, the agent does not start
just runand does not run the browser check. It tells the user which port is held and that the check was skipped. - When neither port answers, the agent starts
just runwithout its interactive window and stops it before it finishes the task, leaving neither port held. - The agent signs in with the seeded dev account.
- When the app of the agent's own worktree lacks the dev account or a seeded database, the agent reruns the seed command against it instead of creating the items by hand.
A browser check SHALL add to the tests a task names and SHALL NOT replace them.
Scenario: Agent checks a page with no app running
- WHEN an agent needs to see a page and nothing answers on the backend and frontend ports
- THEN the agent starts
just runwithout its interactive window, signs in as the dev account, opens the page and reads what it shows - AND no process of that run remains when the agent hands the task over
Scenario: The developer's app runs in the same worktree
- WHEN an agent needs to see a page and the running app was started in the agent's own worktree
- THEN the agent uses that app and leaves it running when it hands the task over
Scenario: The running app belongs to another worktree
- WHEN an agent needs to see a page and the running app was started in another worktree
- THEN the agent does not stop that app and does not open the page
- AND the agent tells the user that the browser check was skipped because the app serves another worktree's code
Scenario: Only one port answers
- WHEN an agent needs to see a page, the frontend port answers and the backend port does not
- THEN the agent does not start
just runand does not open the page - AND the agent tells the user that the frontend port is held and the browser check was skipped
Scenario: A seeded database is missing
- WHEN an agent uses the app of its own worktree and the WAL-streaming database is missing from it
- THEN the agent reruns the seed command, and the database appears with backups switched on
Scenario: Two agents use the browser at once
- WHEN two agent sessions open the browser at the same time
- THEN both browsers start, each with its own empty profile
Requirement: The developer chooses a visible or headless browser
The browser the agent drives SHALL run headless unless the developer asks otherwise. The BROWSER_HEADLESS setting in the developer's .env file SHALL choose headless when true and a visible window when false. A value set in the environment the agent client starts from SHALL take precedence over the file. When neither sets it, the browser SHALL run headless. Any value other than true or false SHALL keep the browser server from starting, with an error that names BROWSER_HEADLESS. The example environment file SHALL contain the setting with its default value. The choice SHALL take effect the next time the agent client starts the browser server.
Scenario: Default setting
- WHEN neither the developer's
.envfile nor the environment setsBROWSER_HEADLESSand an agent opens a page - THEN no browser window appears on the developer's screen
Scenario: Developer wants to watch
- WHEN the developer sets
BROWSER_HEADLESS=falsein.envand the agent client restarts the browser server - THEN the agent's browser opens as a visible window
Scenario: Environment overrides the file
- WHEN
.envsetsBROWSER_HEADLESS=trueand the agent client is started withBROWSER_HEADLESS=falsein its environment - THEN the browser opens as a visible window
Scenario: Invalid value
- WHEN
.envsetsBROWSER_HEADLESS=maybeand the agent client starts the browser server - THEN the server does not start
- AND the error the client reports names
BROWSER_HEADLESS