Context-Driven Development

Recurring work with a bounded contract

Context-Driven Automations

Scheduling an AI task is easy. Operating a recurring workflow that knows what it may inspect, what it may change, what evidence it must produce, and when it must stop takes design.

Write the contractRead the essay

01 · The difference

A schedule is a trigger, not permission.

A scheduled job answers when to wake up. It does not answer which repository is in scope, whether the checkout is safe to edit, which credentials may be used, whether a production change is approved, or what should happen when evidence is missing.

Context-Driven Automation adds that missing operating contract. It keeps routine inspection and reporting cheap while stopping before external, destructive, financial, messaging, deployment, or release actions unless the required approval is explicit.

Useful rule: automate observation and preparation by default; make consequential mutations deliberate, attributable, and reviewable.

02 · The contract

Specify six fields before the first run.

  1. Trigger. State the schedule or event and the timezone/date source it uses.
  2. Scope. Name the exact repo, paths, datasets, accounts, and read/write permissions. A broad phrase like “clean up the project” is not a scope.
  3. Acceptance evidence. Require the report, changed files, test output, screenshot, remote readback, or other artifact that lets a reviewer decide whether the run succeeded.
  4. Stop conditions. Stop on a dirty boundary, ownership collision, missing credential, stale source, failed quality gate, unexpected access, or an instruction that expands the mission.
  5. Approval boundary. Separate preparation from sending, publishing, deploying, purchasing, merging, deleting, or changing production state. Name who can clear the gate.
  6. Retention. Decide where the run receipt, durable learning, and unresolved blocker live so the next run does not start from zero.

03 · Example

A repository-health automation.

This example can inspect a repository and prepare a review packet. It deliberately stops before editing or opening a pull request.

name: weekly-repo-health
schedule: "Monday 09:00"
timezone: "America/New_York"

scope:
  repository: "/workspaces/payments-api"
  read: ["AGENTS.md", "src/**", "test/**", "package.json"]
  write: ["reports/repo-health/**"]
  forbidden: ["production", "secrets", "deletes", "deploy"]

quality_gates:
  - "run the repository's pinned test command"
  - "run the repository's typecheck or lint command"
  - "cite each finding with a file path and line"
  - "record baseline failures separately"

outputs:
  - "reports/repo-health/YYYY-MM-DD.md"
  - "a short blocker list for the owner"

stop_if:
  - "checkout is dirty outside the report path"
  - "tests fail for a new reason"
  - "a credential or external write is required"

The output can recommend a focused change. A later human-approved task can implement it with a fresh read of the repository state; the scheduled report does not smuggle that authority across the boundary.

04 · Safe patterns

Start where evidence is cheap and reversible.

Good first automations

  • Dependency, link, or schema reports that write only to a review folder.
  • Recurring test, typecheck, lint, or build health receipts.
  • Source freshness checks that flag stale claims without rewriting content.
  • Inbox or issue triage that prepares a bounded queue for a human.

Keep approval-gated

  • Deploys, merges, releases, and changes to DNS, production data, or credentials.
  • Messages, purchases, cancellations, or public publishing.
  • Destructive cleanup, migrations with rollback risk, and account changes.
  • Any action where the automation cannot prove the target and owner precisely.

Monitoring can be persistent without being autonomous. The watcher should key on durable state, report transitions, and stop or escalate when its predicate becomes ambiguous.

05 · Failure modes

Most automation incidents start before the first command.

  • Stale context: the schedule reads an old plan and makes a correct decision about yesterday's system. Fix it with a fresh preflight and an explicit date/source rule.
  • Scope drift: a report discovers a nearby problem and silently edits a second surface. Fix it with a write allowlist and a stop condition for new paths.
  • False success: a filtered command hides a failed test, or a route returns a generic page that looks valid. Fix it by capturing the command exit status and checking the artifact's identity.
  • Credential creep: a routine report starts asking for a production token. Fix it by treating missing authority as a blocker, not as an invitation to search for another access path.

06 · Launch checklist

Make the first run easy to audit.

  • The prompt names outcome, method, evidence, non-goals, and approval gates.
  • The automation can prove the exact checkout, branch, account, or dataset it touched.
  • Every mutation has a single owner and a rollback or recovery story.
  • Failures are visible in the receipt, and an empty report cannot look like success.
  • A fresh read-only review can verify the output without trusting the worker's narrative.

Read What Is Context-Driven Development?, make the repository agent-ready, and use the SWE skills for recurring engineering checks.