Spec tools and hooks: what they automate

Start with the change being made

Consider a bug in the fictional invoice-export service from Part 5: an administrator whose account access has been revoked can still download an export through an old link. The requirement is already clear: EXP-05 requires current account authorisation for every new download request. The agent does not need to invent a policy. It needs to find where the implementation stopped enforcing the existing one.

In this example, the API checks authorisation but the direct download path bypasses it. An agent can add a regression test around the API, see it pass and mistake that for evidence that the defect is fixed. A useful tool should help the developer find that second path, apply the right requirement and retain evidence of the repair.

Part 6 keeps the applicable requirement, affected code, actual checks and acceptance decision in the existing task or pull request. The tools considered here can supply parts of that record and prompt review when it falls out of date.

What existing spec tools provide

With EXP-05 settled, the first choice is whether the failure needs a structured investigation. Kiro’s maintenance guidance allows straightforward fixes through ordinary chat. If the cause and affected paths are understood, there is no need to create a new specification just to repair them. Existing specs can also be refined and their implementation tasks synchronised as the work changes.

When the cause is uncertain, Kiro’s bugfix workflow gives the investigation more structure. It separates current, expected and preserved behaviour, then develops a design and tasks. For the download defect, preserved behaviour includes an authorised user’s ability to download: a fix that denies every request would satisfy a denial test and still be wrong.

For new behaviour, Kiro’s feature workflow writes requirements in EARS notation, as used in Part 2’s contact contract.

There are two places for additional scrutiny. If the account and export requirements disagree about when access is checked, Kiro’s requirement analysis can surface that contradiction, alongside ambiguity and missing cases. Once a rule is settled, its IDE’s property-based testing can exercise generated cases against properties derived from the requirements. The property and its scope still matter: thousands of cases through the API will not exercise a direct path the test never calls. Kiro’s documentation explicitly recognises the risk of a weak or incorrect property passing.

After implementation, a discovered mismatch needs to survive as unfinished work. Spec Kit’s convergence procedure examines the code against the specification, plan and tasks, under the project’s constitution. It appends remediation tasks while leaving the specification, plan and application code unchanged. A missed EXP-05 obligation can therefore become a repair task without changing the rule to accommodate the defect.

When an agreed requirement changes, the maintenance problem is different: the next task must find the current rule. OpenSpec separates proposed changes from maintained capability specifications. Synchronisation incorporates changes into those specifications; verification examines the implementation; archiving closes out the change. Verification is a separate operation and does not block archive, so an archived change alone cannot answer whether both download paths were checked.

This comparison follows the documented workflows. It gives no basis for claiming that one tool would find this defect faster; it shows where investigation, corrective work and the maintained rule can live.

Where skills and hooks fit

A skill supplies reusable instructions for a job. For this repair, orchestration should route the agent to investigate the two entry points and then request conformance review against EXP-05. Behavioural examples distinguish a new request made after revocation from a transfer authorised before it. Those jobs have different outputs: a next action, a comparison with the rule, and cases that make the rule testable.

The other responsibilities become useful if the product wants revocation to interrupt a transfer already under way. Clarification must settle that stronger expectation and its scope; specification writing records the agreed change; specification review looks for contradictions and missing cases before dependent work proceeds. Once the cause, applicable rule and behaviour to preserve are understood, the repair can proceed without reopening specification decisions. Six available responsibilities do not imply six steps per change.

A review skill should report a disagreement without editing either side to make it disappear. If that boundary must be enforced, the host needs to deny write access; an instruction to remain read-only is insufficient. Kiro supports skills, so these responsibilities are not peculiar to a Codex setup.

After an edit to the authorisation helper, a hook could return a notice naming EXP-05 and the consumers that need another look. The edit event reaches a matcher, which selects a handler; that handler runs a command or agent prompt and returns context for review. Kiro hooks support both kinds of action. Which events and handlers are available depends on the host.

The notice brings the declared relationships into the review. Establishing that the consumer list is complete and the checks are adequate remains review work; the notice carries no authenticated approval.

The timing determines what a hook can enforce. A pre-tool check can deny a selected invocation before it runs. A post-tool notice arrives after the action has happened. A Stop hook, such as Codex’s continuation mechanism, can ask the agent to continue when it tries to finish a turn; by itself, it does not prevent a merge.

A required repository check can make a failing command block a merge where repository policy enforces it. That is a stronger boundary, but the test still has to exercise the relevant behaviour. Moving the API-only test into CI would enforce a check that misses the direct download defect.

Follow the requirement when the code changes

For the ordinary repair, keep EXP-05 unchanged and trace both download entry points. The expected denial must come from the agreed authorisation rule. If an agent writes the implementation and invents its expected results from that implementation, the resulting tests can merely confirm its own mistake. Asking another agent to agree does not give the expectation an independent basis.

For this fictional service, the agreed rule yields the following expected behaviour; this example has not been executed:

Given an administrator obtained an invoice download link
And their account access has since been revoked
When they start a new download through that link
Then the service denies access to the export

Review must establish where the request is denied and whether the other entry point obeys the same rule. A passing test for an authorised user’s download answers a different question.

Now suppose a later repair changes an authorisation helper shared by the API and direct download paths. The authorisation specification is untouched. A selector that watches only specification edits will miss the reason to review EXP-05 again.

A relationship map can connect that helper to its consumers and their requirements. Version the map with the code so review can compare the previous and current relationships. That comparison can keep a removed consumer visible: deleting a relationship must not quietly erase the obligation from review. The map supplies candidates. The reviewer still needs to follow the actual callers, including alternate entry points the map may have missed. A missing mapped path is a scope problem to resolve, not an empty result to treat as success.

Suppose both download checks pass, then another change to the shared helper is merged. The previous execution remains a true observation about the earlier code. It no longer establishes what the combined change does.

Recording the command, result and relevant input state lets a check identify that mismatch. A changed workspace fingerprint means the recorded inputs differ; it does not demonstrate that EXP-05 was violated. Even an unrelated edit can invalidate a broad fingerprint. Conversely, matching recorded inputs cannot account for an external authorisation service that changed outside the recorded scope. The reviewer must judge which evidence needs refreshing and state what remains unverified.

A resumed session needs that same information. “Tests passed” leaves the next agent guessing which tests and which code. A compact task record lets it recover the applicable rule and prior result, then check whether intervening work changed the basis for acceptance. The historical fixture record in Part 6 shows why this matters: an API-only check passed while the alternate path remained broken.

Choose the automation you can maintain

Start with a recurring failure in the team’s existing review. Look for patterns such as the repeated reminders in Part 6. If shared helpers repeatedly escape consumer review, an affected-requirement notice has a specific job. If old test results keep being reused after edits, comparing their recorded inputs with the current state can expose stale evidence for the reviewer to reassess.

If the team adopts a relationship map, the author of a shared-dependency change owns checking its relationships and updating those that changed. The reviewer checks that work alongside the code. Hooks add their own cost: configuration can break, notices can repeat and scans can delay feedback. Bound that work and make failures visible. A failed scan should leave an explicit gap in the review, rather than silence that looks like “nothing affected.”

Try the underlying check during ordinary review before making it automatic. Then assess what the trigger adds: did the notice cause someone to examine a missed consumer, or did it repeat information already in the task? Keep the review procedure otherwise unchanged so the benefit of the notice can be judged. Include the time spent maintaining the map and handling false alarms.

An agent might produce a change quickly and still leave someone else hours of review and repair. Include that work, and the effort of getting the change into use, when deciding whether a tool saved time.

The result also has to help the user. In Part 5’s fictional reconciliation example, the export meets the proposed column rules but leaves out the reference finance needs to identify an invoice. Checks against those rules can pass while the file remains unusable for reconciliation. Having finance try the file exposes the missing requirement.

Remove a check when its maintenance and interruptions outweigh the useful findings. If a safety-critical obligation depends on that check, assign another way to enforce it before removal. The useful endpoint is a review in which someone can explain why this change satisfies the applicable requirement—and can identify the evidence still missing when they cannot.