Review Checklist

​

Frequently broken rules

1. Put the durable daemon contract in frontmatter. Identity, purpose, wake conditions, core routines, hard prohibitions, and schedules belong in id, purpose, watch, routines, deny, and schedule, not body prose.
2. Do not duplicate frontmatter in the body. If a body section restates purpose, watch, routines, or deny, delete it or move only the missing hard rule into frontmatter.
3. Do not restate the wake model in the body. The body must not repeat the watch list, restate the schedule, or describe the daemon’s activation mode as prose.
4. Keep the body short and behavioral. Every body paragraph must change how the daemon decides, verifies, communicates, limits scope, coordinates, or no-ops. Remove generic filler, repeated policy, tutorial notes, and setup instructions.
5. purpose must be one short outcome statement. It must describe the end state the daemon exists to maintain, not a list of scans, API calls, messages, implementation mechanics, historical context, activation details, deny rules, quiet/no-op policy, or other runtime guidance.
6. Write routines as concrete wake-time operations. Each routine must be finite and verifiable. Advice belongs in body guidance; negative guardrails belong in deny or body policy.
7. Use explicit, resolving references and destinations. Daemon IDs, docs paths, pinned refs, example names, issue or project identifiers, Slack channels, GitHub labels, and repo-specific configuration must be current and unambiguous.

​

1. Inspect every changed daemon file

1. Reviewers must inspect the canonical .agents/daemons/<daemon-id>/DAEMON.md file.
2. Reviewers must inspect changed scripts/** and references/** files.
3. Reviewers must read nearby support files when the changed behavior depends on them and must flag stale, hidden, contradictory, or disconnected guidance.
4. The PR must stay narrowly scoped to the requested daemon change; unrelated or unnecessary additions must be removed.

​

2. Review the DAEMON.md contract

​

Required file shape

1. DAEMON.md must live at .agents/daemons/<daemon-id>/DAEMON.md.
2. DAEMON.md must start with ----delimited YAML frontmatter that parses to an object/map.
3. DAEMON.md must have a non-empty Markdown body below the closing delimiter.

​

Authored fields and structural rules

4. The frontmatter must include id, purpose, and routines.
5. id must exactly match the <daemon-id> path slug.
6. The frontmatter must include at least one activation field: watch or schedule.
7. routines must be a YAML list with at least one non-empty string. When present, watch and deny must also be YAML lists of non-empty strings.
8. The frontmatter must use the canonical authored field names and must not invent fields or substitute name, description, triggers, actions, or disallowed for id, purpose, watch, routines, or deny.

​

Field quality

10. purpose must be one short outcome statement. It must describe the end state the daemon exists to maintain, not how the daemon works, why it was created, when it wakes, when it stays silent, or what it must not do.
11. routines must contain only concrete, finite, verifiable operations the daemon performs when it wakes. Advice belongs in the body; negative guardrails belong in deny or body policy.
12. deny must cover plausible adjacent risky shortcuts and must fail closed for important ambiguity.
13. watch must use semantic matching language and describe provider-visible observable events rather than raw webhook labels or derived-state queries that belong in execution-time checks.
14. watch entries must not be vague, brittle, catch-all, or broadly overlapping in ways that can produce duplicate activations.
15. When present, schedule must use standard five-field cron in UTC. If both day-of-month and day-of-week are restricted, reviewers must account for ordinary cron day-of-month OR day-of-week semantics.

​

Validate with the CLI

bunx @charlie-labs/daemons validate .agents/daemons/<daemon-id>/DAEMON.md

​

3. Review body guidance

1. The Markdown body must contain runtime policy rather than setup instructions or tutorials.
2. The body must not duplicate frontmatter content. If body guidance restates purpose, watch, routines, deny, or schedule, reviewers must delete it or move only the missing hard rule into frontmatter.
3. The body must add targeted guidance only where it materially improves behavior: decision terms, output format, communication and silent no-op policy, verification and freshness, limits, target selection and ignore patterns, coordination and concurrency, human authority, and clarifying examples.
4. The body must define ambiguous terms once and must remove duplicative or overly verbose content. It must rely on frontmatter and linked canonical sources instead of restating them.

​

4. Review support files

1. Reviewers must inspect the full daemon support tree when it changes.

.agents/daemons/<daemon-id>/
  DAEMON.md
  scripts/
  references/

​

scripts/

2. Scripts must be used for executable, deterministic helpers.
3. Scripts must document required inputs, output shape, pagination or completeness expectations, and safe behavior when complete context is unavailable.

​

references/

5. References must be used for read-only policy, templates, guides, examples, or other context.
6. DAEMON.md must say when and how to use any reference the daemon relies on.

​

5. Review repeatability and safety

1. Wake context must be treated as activation context rather than mutation authorization. Current provider state must be refetched immediately before consequential writes.
2. Limits must be added when work or visible noise can sprawl.
3. For branch mutation, force-push must be denied by default. If repository policy permits it, the daemon must require fresh remote state and --force-with-lease. It must state whether fork or cross-repository branches are out of scope.

​

Learn more

• Daemons: concepts, wake model, and DAEMON.md as the control surface.
• Choosing daemons: how to identify and scope daemon opportunities.
• Writing and editing DAEMON.md: guidance for clear, narrow, safe daemon files.
• DAEMON.md reference: exact authored contract, validation rules, and support-tree semantics.
• Testing and iterating on daemons: testing, observation, and iteration guidance.