Design principles
AgentsWorklog warns, but never blocks. That single constraint shapes the whole product — it's what lets the worklog sit safely beside tools that do enforce, without ever getting in their way.
Advisory, never blocking
Nothing in AgentsWorklog gates a merge, locks a file, or blocks a run. An overlap check returns a warning; a Notable raises a flag; the session summary points somewhere worth looking. Every one of these is a signal an agent weighs — never a rule it must obey and never a gate that stops it.
This is a deliberate ceiling on what the product is allowed to do, not a feature that's missing.
Why advisory-only
A blocking coordination layer sounds safer until you run it. Three problems make enforcement the wrong job for a worklog:
- False positives become outages. A blocker that's wrong even occasionally stops legitimate work. An advisor that's wrong occasionally just gets ignored that once — the cost of a mistake is bounded.
- Enforcement already has an owner. Branch protection, required reviews, and CI are where "you may not merge this" belongs. Duplicating that in a worklog splits the rules across two systems that can disagree.
- Advice composes; gates conflict. Any number of agents can read a warning and each make their own call. The moment a worklog can block, it becomes a single point of failure in everyone's workflow.
Staying advisory keeps AgentsWorklog cheap to adopt and impossible to get stuck behind.
Coexisting with Git, PRs, and CI
Because it never enforces, AgentsWorklog needs no permissions over your pipeline and changes none of your existing controls. Git still owns history; branch protection still owns what can merge; CI still owns what's correct. The worklog fills the one gap those tools leave — the window between "planning" and "opening a PR" — and leaves everything else exactly as it was.
Turning AgentsWorklog on can't break a build or block a deploy, because it has no authority to. The worst case is a warning nobody acts on — which is also the failure mode of any advice.
Short-lived on purpose
The second principle reinforces the first: entries expire. A tool that can't block also shouldn't accumulate, because stale advice is worse than none. Auto-expiry and auto-archive mean the worklog describes the present, so the warnings agents do read are worth reading.