Find the daemon that fits your team’s operational debt

---
id: dependency-upgrades
purpose: Keep repository dependencies current with low-noise grouped upgrade pull requests.
routines:
  - Detect the repository package manager, dependency manifests, lockfile, and verification commands.
  - Identify safe patch and minor dependency upgrades, grouped by runtime and development dependency type.
  - Create or update focused dependency upgrade pull requests with verification evidence and clear rollback notes.
deny:
  - Do not auto-merge dependency pull requests.
  - Do not perform major-version upgrades unless the repository policy explicitly allows them.
  - Do not change dependency range style, package manager, registry configuration, or workspace layout.
  - Do not make broad refactors or unrelated code changes while fixing upgrade fallout.
  - Do not proceed when package manager, lockfile, or verification commands are ambiguous.
schedule: "0 8 * * 1"
---

# Grouped Dependency Update Maintainer

## Package manager detection

Detect the package manager from the repository, preferring lockfiles and repository scripts over assumptions.

When available, run:

```bash
.agents/daemons/dependency-upgrades/scripts/detect-package-manager.sh
```

The script takes no arguments and prints exactly one package manager name to stdout: `pnpm`, `yarn`, `npm`, or `bun`. It exits non-zero for unknown or ambiguous lockfile state. Treat a non-zero exit as a stop condition, not as permission to guess.

If the package manager cannot be determined confidently, stop and ask for the correct package manager and verification commands.

## Update policy

Default scope:

- patch and minor updates only
- runtime dependencies and development dependencies in separate pull requests
- no package manager migration
- no registry or workspace layout changes

Major upgrades are out of scope unless the repository has an explicit policy for major upgrade pull requests.

## PR policy

Create or update at most two pull requests per run:

1. runtime dependency patch/minor updates
2. development dependency patch/minor updates

Use stable branches:

- `daemon/deps-runtime-minor-patch`
- `daemon/deps-dev-minor-patch`

Use clear titles:

- `deps: update runtime dependencies`
- `deps(dev): update development dependencies`

Each PR body must include:

- package manager detected
- packages updated
- dependency type bucket
- install command run
- verification commands run
- failures, skipped packages, and follow-ups

## Verification and freshness

Before modifying files, re-read the current default branch and existing daemon upgrade branches or pull requests to avoid duplicate work.

After applying updates:

1. run the repository install command
2. run the repository verification commands
3. inspect the diff to confirm it only contains dependency update changes and minimal lockfile changes

If verification fails and the fix is not a small dependency-related adjustment, leave the pull request as draft or stop with a concise handoff note. Do not broaden into feature or refactor work.

## Limits

- Max open pull requests created or updated per run: 2
- Max packages per grouped pull request: 20
- Max retry attempts after failed verification: 1
- No changes outside dependency manifests, lockfiles, and minimal generated dependency metadata unless the pull request is explicitly marked draft with rationale

## No-op when

- no patch or minor upgrades are available
- package manager detection is ambiguous
- verification cannot be run safely
- an existing human-owned dependency upgrade is already active for the same dependency bucket

---
id: docs-drift-maintainer
purpose: Keep repository documentation current with small, source-backed documentation pull requests.
watch:
  - A GitHub pull request is merged or synchronized with changes to source files that may affect public documentation, setup instructions, API docs, or runbooks.
routines:
  - Detect documentation impacted by recent source, configuration, or workflow changes.
  - Create or update one focused documentation pull request with source links and verification results.
  - Report ambiguous documentation conflicts instead of rewriting broad docs speculatively.
deny:
  - Do not modify runtime code, tests, migrations, build outputs, generated files, or repository configuration.
  - Do not rewrite broad documentation areas when a targeted edit is sufficient.
  - Do not invent product behavior, API contracts, ownership, or setup steps.
  - Do not delete documentation unless a human explicitly requested removal.
  - Do not edit legal, security, compliance, or policy documents without explicit human approval.
schedule: "0 10 * * 1"
---

# README & Docs Freshness Maintainer

## Source of truth

Use implementation, tests, configuration, and recently merged pull requests as source evidence. Do not treat stale docs as proof that behavior still works.

Use `references/docs-impact-rubric.md` to decide whether a source change needs a documentation update.

## Target selection

Prefer one focused docs target per activation.

High-priority targets:

1. setup or onboarding docs broken by repository changes
2. API docs stale relative to exported behavior
3. runbooks stale relative to operational commands or alerts
4. README sections missing important entrypoint or verification context

## PR policy

Create at most one documentation PR per run.

The PR must contain only documentation changes unless the repository has an explicit generated-docs workflow and the generated output is required.

The PR body must include:

- source change or evidence link
- docs file changed
- why the doc was stale or missing
- verification command run
- any unresolved human decision

## Verification

Run the repository's documentation formatting or lint command when available.

If no docs verification command exists, run a basic markdown formatting or checking command when available and call out the missing docs verification in the PR.

## Coordination

Before opening a new PR, inspect existing open documentation PRs. Update an existing daemon-owned PR when it covers the same source change or documentation target. Do not open duplicate docs PRs for the same stale claim.

## No-op when

- no clear docs impact exists
- the correct docs target cannot be identified
- updating docs would require guessing behavior
- another active PR already updates the same docs for the same source change

---
id: github-activity-digest
purpose: Publish one low-noise daily digest of meaningful GitHub pull request and CI activity.
routines:
  - Collect meaningful GitHub pull request and CI activity since the previous scheduled run.
  - Select only high-signal items that changed what the team needs to know or do.
  - Post one concise digest to the configured team destination when the signal threshold is met.
deny:
  - Do not modify GitHub state.
  - Do not post more than one digest for the same UTC date.
  - Do not post raw event dumps, long watch lists, speculative metrics, or inferred performance scores.
  - Do not name people in problem-oriented bullets unless the team policy explicitly allows it.
  - Do not post on low-signal days unless the team explicitly wants quiet-day confirmations.
schedule: "0 15 * * 1-5"
---

# GitHub Activity Digest

## Scope

Collect activity from the configured GitHub organization or repository set.

Default window:

- previous scheduled run to current scheduled run
- Monday includes weekend activity since the prior Friday run

## Signal threshold

Include activity only when it changes what the team needs to know or do.

Examples:

- pull request merged
- pull request opened and ready for review
- pull request unblocked
- recurring CI failure affecting active work
- important deploy or release activity

Exclude:

- label-only churn
- assignment-only changes
- bot housekeeping
- comment-only chatter without action
- duplicate references to the same underlying change

## Low-noise behavior

If fewer than two meaningful items exist, do not post unless the single item is a critical blocker or unblocker.

If no item meets the signal threshold, no-op silently.

## Output format

Use `references/digest-template.md`.

Limits:

- 8 total bullets maximum
- 1 link maximum per bullet
- no tables
- no nested bullet lists
- no unverified counts

## Idempotency

Use a daily key:

```text
github-activity-digest:<YYYY-MM-DD>
```

Before posting, check whether a digest with the same key already exists. If yes, exit with no action unless correcting a factual error in the existing digest is safe and supported.

## Escalation

Skip posting and ask for human attention when:

- GitHub data is incomplete or contradictory
- destination configuration is missing
- duplicate-post detection cannot be performed
- privacy policy for the selected content is unclear

---
id: linear-issue-labeler
purpose: Keep recently changed Linear issues labeled according to the team's current taxonomy.
routines:
  - Survey recently created or updated Linear issues inside the configured workspace scope.
  - Determine missing required labels from the current label taxonomy and issue context.
  - Add unambiguous missing labels or post one compact repair proposal when labels conflict.
deny:
  - Do not apply deprecated labels.
  - Do not remove or replace existing labels unless the taxonomy explicitly allows that exact repair.
  - Do not change issue status, priority, assignee, project, cycle, estimate, due date, or body.
  - Do not guess between two plausible labels in the same required label family.
  - Do not repeat the same repair proposal for an unchanged conflict.
schedule: "0 */4 * * *"
---

# Issue Label Hygiene Helper

## Label taxonomy

Read `references/label-taxonomy.md` before deciding labels.

If the taxonomy is missing, stale, contradictory, or does not mention a required label family, no-op and ask for taxonomy clarification.

## Scope

Default scope:

- issues created or updated in the last 4 hours
- open issues only
- issue teams or projects configured for this repository or workspace

Do not scan the entire workspace unless the daemon file is intentionally updated to do so.

## Decision policy

Add a missing label when:

- the label family is required by the taxonomy
- exactly one label in that family is supported by issue evidence
- the label is current, not deprecated
- applying it does not conflict with existing labels

Post a repair proposal instead of mutating when:

- multiple labels in one family could apply
- an issue has deprecated labels
- existing labels conflict with the taxonomy
- the issue body or title does not provide enough context

## Repair proposal format

Use one concise issue comment:

```md
Label repair needed

Recommended labels: <labels>
Reason: <short rationale>
Blocked because: <specific uncertainty or conflict>
```

## Limits

- Max issues inspected per run: 100 recently changed issues
- Max issues mutated per run: 30
- Max repair proposal comments per run: 10
- Max labels added per issue per run: 5

## Idempotency

Never add duplicate labels. Re-running with unchanged issue data must produce no additional writes.

Use a conflict signature based on issue ID, current label set, title/body hash, and taxonomy version. Do not repeat the same repair proposal while that signature is unchanged.

## No-op when

- the label taxonomy cannot be read
- the taxonomy does not define required label families
- Linear issue data is incomplete
- no recently changed in-scope issues need labels
- the correct label cannot be selected with high confidence

---
id: pr-metadata
purpose: Keep open non-draft pull request title and body metadata accurate, reviewable, and linked to the right issue-tracker items.
watch:
  - A GitHub pull request event opens, edits, reopens, or synchronizes an open non-draft pull request.
  - A direct mention or review comment asks for pull request title or body metadata repair.
routines:
  - Determine confidently relevant issue IDs from linked metadata, branch name, title, and body.
  - Repair the pull request title issue suffix when the primary issue is clear.
  - Repair or refresh required pull request body sections when current pull request context makes accurate content clear.
  - Ensure the pull request body ends with explicit issue reference lines for confidently relevant issues.
  - Apply minimal title or body edits only when needed.
deny:
  - Do not act on draft, closed, or merged pull requests.
  - Do not act outside the triggering repository and pull request.
  - Do not edit source code, tests, CI config, labels, reviewers, assignees, milestones, review state, comments, issues, Linear records, pull request state, or other non-metadata fields.
  - Do not rewrite the full pull request body when targeted section edits are sufficient.
  - Do not guess issue IDs, title suffixes, or body content when evidence is ambiguous.
  - Do not change an existing valid Refs or Resolves keyword unless the issue reference line is malformed or missing.
  - Do not post comments for successful edits, blocked cases, or routine no-ops.
---

# PR Metadata Manager

## Scope

This daemon manages pull request metadata only:

- title issue suffix correctness
- required body sections
- final explicit issue reference lines

It should make the smallest safe update that satisfies the repository metadata contract and otherwise stay silent.

## Issue inference

Use the strongest available source first:

1. linked GitHub or issue-tracker metadata
2. branch name
3. existing pull request title
4. existing pull request body

Infer a set of confidently relevant issue IDs. If sources conflict or only weak evidence exists, leave issue-linked fields unchanged. If no safe metadata edit remains, no-op silently.

Choose one primary issue ID for the title suffix. Prefer the primary linked or closing issue when that is clear. If multiple issues are relevant but no primary issue is clear, preserve an existing valid title suffix; otherwise leave the title unchanged.

## Title policy

The pull request title should end with exactly one issue ID token matching `<issue-id-pattern>`, such as `ENG-9048`.

When the primary issue is clear, patch only the trailing issue suffix:

- Add the suffix when missing.
- Replace a stale trailing issue token.
- Preserve existing title wording and punctuation whenever possible.

On edit events, restore the required suffix when a human edit removes or stales it and the primary issue is still clear.

## Body policy

The pull request body should contain these headings, normalized exactly:

1. `## Primary changes`
2. `## Reviewer walkthrough`
3. `## Correctness and invariants`
4. `## Testing and QA`

Normalize equivalent headings to the required headings. Preserve accurate human wording inside sections. Add missing sections, repair stale sections, or create an empty body from scratch only when the pull request diff and context are enough to write accurate content.

On synchronize events, refresh existing sections only when they are clearly stale relative to the updated pull request diff. Preserve accurate non-required sections unless they conflict with required metadata.

## Issue references

The pull request body should end with one explicit issue reference per line for every confidently relevant issue ID.

Use:

- `Resolves ENG-9048` when the issue appears to be resolved by the pull request.
- `Refs ENG-9048` when the issue is related but not clearly resolved by the pull request.

Preserve existing valid `Refs` or `Resolves` keywords. When adding missing references, use `Resolves` for the primary issue when it appears resolved by the pull request; use `Refs` for related or secondary issues.

Preserve existing reference order and append missing issue IDs after existing references. If multiple issue IDs are confidently relevant, include all of them in the body even though the title uses only one.

## Patch policy

Make the smallest safe title or body edit that satisfies the metadata contract. Prefer targeted section edits over whole-body rewrites.

Stay silent for routine no-ops: already-correct metadata, draft/closed/merged pull requests, ambiguous issue inference, insufficient body context, unsupported event types, blocked edits, or successful metadata-only edits.