# repo-management

> Reconcile repository issues, pull requests, merge requests, local git state, commits, and pushes across GitHub, GitLab, Gitea, Forgejo, Codeberg, Bitbucket, Azure DevOps, and SourceHut.

- Skill: `projectious-work/repo-management` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds add projectious-work/repo-management`
- Raw SKILL.md: https://api.skillmd.com/api/skills/projectious-work/repo-management/raw
- Safety review: pending (external: skill-scanner WARNING, skillspector WARNING)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: projectious-work (https://skillmd.com/u/projectious-work)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/projectious-work/repo-management

---


# Repo Management

## Intro

`repo-management` gives agents a provider-neutral workflow for routine
repository stewardship: inspect open issues and change requests, plan
safe actions, merge only ready work, commit local changes, and push.
Use it when the user asks to check all open issues or PRs, clean up a
repo, reconcile repository state, merge ready work, commit and push, or
perform repo-maintenance across providers.

## Overview

The default workflow is plan-first and guarded:

1. Call `detect_repo_provider(project_root, remote)` to identify the
   remote platform and available local CLI.
2. Call `inspect_repo_state(project_root)` to inspect branch, dirty
   state, upstream, ahead/behind status, remotes, and provider support.
3. Call `list_repo_issues()` and `list_repo_change_requests()` for the
   current provider when supported.
4. Call `plan_repo_reconcile(scope)` to build a concrete action plan.
5. Apply only actions that pass the safety rules below. Use
   `run_repo_reconcile(dry_run=false)` for guarded batch work, or call
   the narrow mutating tools directly.

When the task involves branch policy, review judgment, or release work,
also follow the local `git-workflow`, `code-review`, and
`release-semver` skill guidance.

`/pk-repo-reconcile` is the user command for the same workflow. Without
extra arguments it means `scope=all`: local git state, open issues,
open change requests, and push readiness. Users may narrow it with
`issues`, `prs`, `local`, or `push`.

### Provider support

| Provider | Detection | Read support | Mutating support |
|---|---|---|---|
| GitHub | `github.com` remotes | `gh issue list`, `gh pr list` | issue comments/close, PR merge, commit, push |
| GitLab | `gitlab.com` or `REPO_PROVIDER=gitlab` | capability report, local git | local commit/push only |
| Gitea | `REPO_PROVIDER=gitea` | capability report, local git | local commit/push only |
| Forgejo / Codeberg | `codeberg.org` or `REPO_PROVIDER=forgejo` | capability report, local git | local commit/push only |
| Bitbucket Cloud | `bitbucket.org` remotes | capability report, local git | local commit/push only |
| Azure DevOps | `dev.azure.com` or `visualstudio.com` remotes | capability report, local git | local commit/push only |
| SourceHut | `git.sr.ht` remotes | capability report, local git | local commit/push only |

Unsupported provider actions must return structured evidence instead
of pretending the work is complete. Agents should still commit and push
local changes through git when the repository policy allows it.

### MCP tools

| Tool | Purpose |
|---|---|
| `detect_repo_provider(project_root, remote)` | Detect remote host, owner/repo, provider, and local CLI availability. |
| `inspect_repo_state(project_root, include_remote)` | Inspect branch, dirty state, upstream, ahead/behind, remotes, and provider capabilities. |
| `list_repo_issues(state, limit)` | List open issues when the provider adapter supports it. |
| `list_repo_change_requests(state, limit)` | List open PRs/MRs/change requests when supported. |
| `plan_repo_reconcile(scope, dry_run)` | Produce the action plan and blockers without mutating. |
| `resolve_repo_issue(id, resolution, comment, close, confirmation)` | Comment and optionally close a supported issue. |
| `merge_change_request(id, method, auto_queue, confirmation)` | Merge or queue a supported ready change request. |
| `commit_local_changes(paths, message, checks)` | Run optional checks, stage paths, and commit local changes. |
| `push_current_branch(remote, branch)` | Push the current branch to its remote. |
| `run_repo_reconcile(dry_run, max_items, commit_message, push)` | Apply the guarded batch workflow. |

## Gotchas

- **Do not close issues without evidence.** A close action needs a
  linked merged change, a duplicate reference, a clear no-repro
  disposition, or explicit user instruction.
- **Do not merge drafts or WIP change requests.** Draft state is a hard
  blocker even if checks are green.
- **Do not bypass branch protection.** Never force-push, override
  required reviews, skip required checks, or bypass merge queues.
- **Do not assume GitHub-only behavior.** Detect the provider first and
  return unsupported evidence for adapters that are not configured.
- **Do not treat listing as resolving.** If issues or change requests
  remain open, report the plan or blocker that remains.
- **Do not push unrelated local work blindly.** Inspect `git status`
  and commit only the intended paths or the current complete worktree
  when the user asked for all local changes.
- **Do not run mutating batch actions without a dry-run plan.**
  `run_repo_reconcile(dry_run=false)` should report the plan it applied
  and every command result.
- **Do not hide external auth failures.** Missing `gh`, `glab`, `tea`,
  `bb`, `az`, or `hut` authentication is an actionable blocker, not a
  successful no-op.

## Full reference

### Safety policy

The skill is deliberately conservative:

- No force pushes.
- No direct API bypass of provider protection rules.
- No draft/WIP merge.
- No issue close without a comment or explicit resolution evidence.
- Mutating issue and merge tools require exact confirmation tokens:
  `close-issue:<id>` and `merge-change-request:<id>`.
- Provider-specific actions are serialized by the caller; batch tools
  return per-action evidence.

### Scope names

`plan_repo_reconcile()` and `/pk-repo-reconcile` accept these scopes:

| Scope | Includes |
|---|---|
| `all` | local, push, issues, and change requests |
| `local` | dirty state and commit readiness |
| `push` | ahead/behind and push readiness |
| `issues` | open issue listing and resolution candidates |
| `prs` | open pull requests, merge requests, or provider change requests |
| `change-requests` | Alias for `prs` |

### Provider notes

GitHub is the first fully mutating adapter because the `gh` CLI is
common in aibox environments and enforces provider-side checks. GitLab,
Gitea, Forgejo/Codeberg, Bitbucket Cloud, Azure DevOps, and SourceHut
are first-class provider identities in the schema and detection layer;
their remote issue and change-request mutation paths return
`unsupported` until the matching local CLI or API credential contract is
implemented.