Run a specific work item

← Overview · First run · Configuration

Use Repo Maintainer for a defined bug, small feature, test gap, refactor or documentation change. It does not need an API changelog or recurring schedule. Keep the project setup stable and put the work request in a separate file.

For the shortest path, keep your normal .maintainer.yml and run:

repo-maintainer run --task task.md

The file's task text is appended to the configured repository instructions; editable paths, budgets and checks remain in effect. The configuration-file approach below is useful for recurring or separately configured work.

Separate setup from the task

For a Node application, copy work-item.yml to .maintainer/work.yml and work-item.md to .maintainer/task.md in your repository. Adapt the paths and commands; this example assumes npm ci, npm test and npm run lint work. Use the language examples for other projects.

The configuration points to the brief with:

instructions_file: .maintainer/task.md

The file is appended to the configured instructions. It is operator-authored task text, not a queue or an automatically imported issue. Copy relevant issue requirements and reproduction details into it; a link alone does not guarantee the issue is read. Keep credentials out of both files.

Describe a result that can be checked

For example, a search bug could have this brief:

When a search returns no results, show the existing empty-state component instead of a blank list. Preserve loading and error states. Add a regression test for an empty successful response and run the search tests and lint.

Name the current behavior, desired behavior, relevant files or reproduction steps, and acceptance criteria. Keep the change small enough for one review. If requirements are ambiguous, ask for a blocked report rather than invented product behavior. Split large redesigns and repository-wide rewrites first.

Run it once

After installing the tool and configuring the agent account:

repo-maintainer check --config .maintainer/work.yml
repo-maintainer run --config .maintainer/work.yml

Local runs use committed source. Review the report and patch, then follow the apply-and-validate steps. Use the same --config .maintainer/work.yml when running repo-maintainer validate for this task. Local runs do not publish a PR or consume an item from a backlog.

Run it through GitHub Actions

Use the hosted caller, set config_path: .maintainer/work.yml, and remove its schedule trigger so only workflow_dispatch remains. Commit the configuration and brief to the default branch and start that workflow manually. It runs the same proposal, independent validation and PR publication pipeline.

The example has a distinct branch prefix and blocker issue title so it does not reuse a recurring maintenance PR. Finish or close the existing work-item PR before replacing its brief with an unrelated task. Each configured branch prefix supports one open maintenance PR, not a parallel backlog of tasks.

For recurring upkeep, use a separate config with a stable instruction such as “fix one reproducible bug and add a regression test.” Do not schedule a fixed feature request indefinitely after it has been completed.

Current boundaries

Custom checks and optional reference sources already support general work. Configured paths still constrain every proposal. The patch boundary excludes hidden paths, symlinks and executable files and caps changes at 25 regular files and 500 KB. Nothing merges, deploys or releases automatically. An unchanged result means no change was made; review the evidence before treating a feature request's acceptance criteria as satisfied.

Issue discovery, task claiming, dependency ordering and automatic backlog management are not built in. Start with explicit briefs and manual dispatch; add orchestration when the workload actually needs it.