Package RepoMan as a DAM starter kit (curated/repoman)

Package RepoMan as a DAM starter kit (curated/repoman)

Goal

Make "create a RepoMan agent on DAM" one click from the
dam-starter-kits catalog, instead of
the manual checklist used while dogfooding (install plugin, /repoman setup, pin
lychee with mise, write a wrapper, register 5 schedules + a precheck by hand).

Approach

Ship a kit.yaml in rossoctl/repoman itself (the catalog's preferred shape: one
commit pins the kit, the definition and the bundled skills), then add one line to the
catalog's catalog.yaml:

  - url: https://github.com/rossoctl/repoman

Proposed kit.yaml (first draft)

# yaml-language-server: $schema=https://raw.githubusercontent.com/dam-agents/dam-starter-kits/main/kit.schema.json
schemaVersion: v1
id: repoman
name: RepoMan
tagline: Your repos' maintenance crew — links, Dependabot, PR reviews, reports.
description: >-
  Runs RepoMan's maintenance programs across a set of GitHub repos you enroll
  once: repo-sync, link-health scanner/fixer, dep-bump scanner/fixer, labeled
  PR review, an automation health dashboard and a weekly org report. It files
  and closes issues, opens fork-based fix PRs, and never merges.
category: software
icon: code            # TBD: is there a wrench/truck icon?
docsUrl: https://github.com/rossoctl/repoman
harnesses: [claude-code, pi]   # dogfooded on DAM w/ Claude Code + Pi
seed:
  self: true
  into: work          # TBD: home vs work (see open questions)
bundledSkills:
  path: skills        # repoman, link-health-*, dep-bump-*, github-pr-review, repo-sync, ...
install:
  command: bash dam/install.sh   # mise pin for lychee >= 0.23.0, sanity-check gh/jq/python
egressPreset: trusted # npm, PyPI, GitHub, Anthropic...
egressRules:
  - host: web.archive.org     # link-health fixer: Wayback lookups
  - host: archive.org
  # Every other external link lychee checks is refused by the proxy; the
  # scanner records those as "unchecked", never "broken" (see Work items).
onboarding:
  prompt: >-
    Read dam/ONBOARDING.md and follow it to the end. It runs the /repoman
    five-question setup (repos_dir under $HOME, fork_owner, repos/org to enroll,
    programs to enable, output mode same|central), runs repoman-check.sh per
    enabled program, enables the matching schedules below, and posts a summary.
    Guarded by the $HOME/.repoman-onboarded sentinel, so safe to repeat.
connections:
  - accepts: [github, github-enterprise]
    required: true
    note: >-
      A bot/machine account with `repo` (+ `read:org` for the weekly report).
      Needs write on enrolled repos to create labels/issues, and a fork owner
      for fix PRs. Not the account that authors the PRs it reviews.
  - accepts: [slack]
    note: Run summaries and failure alerts.
channels:
  - type: slack
    note: Team channel for run reports and "what broke?" questions.
schedules:            # crons are UTC; same cadence as the dogfood agent
  - name: repoman-repo-sync-daily
    cron: "7 2 * * *"
    sessionMode: fresh
    task: Run `bash dam/run-program.sh repo-sync` and report failures only.
  - name: repoman-dep-bump-daily
    cron: "43 3 * * *"
    sessionMode: fresh
    enabled: false    # turned on by onboarding if enabled
    precheck: bash dam/precheck.sh dep-bump
    task: Run `bash dam/run-program.sh dep-bump` and post the summary.
  - name: repoman-link-health-weekly
    cron: "13 3 * * 1"
    sessionMode: fresh
    enabled: false
    precheck: bash dam/precheck.sh link-health
    task: Run `bash dam/run-program.sh link-health` and post the summary.
  - name: repoman-pr-review-hourly
    cron: "23 * * * *"
    sessionMode: fresh
    enabled: false
    precheck: bash dam/precheck.sh pr-review   # exit 0 only if a PR has ready-for-ai-review
    task: Review every PR the precheck listed with the github-pr-review skill.
  - name: repoman-automation-health-weekly
    cron: "7 5 * * 1"
    sessionMode: fresh
    enabled: false
    precheck: bash dam/precheck.sh automation-health
    task: Run `bash dam/run-program.sh automation-health` and publish the dashboard.

Work items

• kit.yaml at repo root; validate against kit.schema.json (add a CI step mirroring the catalog's validate.yml).
• dam/ folder (DAM-specific glue, keeps the plugin harness-neutral):
  • install.sh + mise.toml — lychee pin (interim, until https://github.com/rossoctl/repoman/issues/3 lands and lychee is dropped). Note: mise tools are lost on VM restart, so run-program.sh must re-run mise install (the dogfood wrapper already does).
  • run-program.sh — resolve the engine from the seeded checkout (skills/repoman/scripts/repoman-run.sh), not the Claude Code plugin cache (the cache hash path changes on update, and doesn't exist on Pi).
  • precheck.sh <program> — cheap gates (exit 1 = skip, no model turn): pr-review = labeled PR exists; enabled-check reading ~/.repoman/programs/<name>.json for the rest.
  • ONBOARDING.md — wraps the /repoman setup, sentinel, schedule reconciliation (enable only the programs the user turned on).
• link-health: treat egress refusals as "unchecked", not "broken". Under trusted + egressRules, a link to an unlisted host gets a proxy refusal (closed connection / 403 from the gateway). The scanner must classify those separately so it doesn't file false-positive [link-health] issues:
  • detect the gateway's refusal signature in lychee output and bucket it as unchecked (not broken);
  • never open, and never auto-close, an issue based on an unchecked result;
  • report the unchecked count + top hosts in the run summary / dashboard, so the owner can widen egressRules (or switch to all) after create;
  • add a test fixture under tests/ for a refused host. The engine change lands in rossoctl/automation and is vendored with vendor-engine.sh.
• State lives in ~/.repoman/ (persisted); repos_dir must default under /home/agent so clones survive restarts.
• README: "Run on DAM" section + link to the catalog entry.
• PR to dam-agents/dam-starter-kits adding the catalog line.

Gotchas found while dogfooding (week 43–44)

• Egress: link-health (lychee + Wayback/archive.org) hits arbitrary hosts. Decided (2026-10-28): trusted + egressRules for the archive hosts, and the scanner treats proxy refusals as "unchecked" (the work item above; implemented as part of https://github.com/rossoctl/repoman/issues/3). Rejected alternatives: limit link-health to internal/GitHub links only; all + deny rules (full coverage but too loose a default). The owner can widen egress after create.
• Permissions: with READ-only access label creation fails (repoman-check.sh --create-missing-labels); issue creation still works. Onboarding should run the capability check and say which programs are degraded.
• lychee isn't on the base image → install step + mise for now; tracked for removal in https://github.com/rossoctl/repoman/issues/3.
• Schedules: platform holds kit schedules until onboarding completes; programs the user doesn't enable should stay enabled: false.

Open questions

1. Kit location: decided, kit.yaml lives in rossoctl/repoman.
2. seed.into: home (definition = /home/agent, like code-guardian) or work?
3. Egress preset: decided, trusted + egressRules + "unchecked" classification.
4. The catalog README lists parameters (values onboarding asks for), but kit.schema.json doesn't define it yet — use onboarding prompts for now?
5. Bundle the RepoMan Wiki (llm-wiki) agent as an optional companion, or keep it a separate kit?
6. Harnesses: add bob/codex once tested?

Contributions follow repo conventions: DCO sign-off + Assisted-By: trailer.