Non-invasive patchmill mode for working on repositories one doesn't control.

[jimfulton]

I contribute to projects I don't control, or where I share control with others, where adding labels or including a .patchmill directory is impossible or impractical.

I'd use patchmill more if it was possible to use patchmill for individual issues without otherwise affecting repository management or checking in patchmill configuration.

AFAIK, this would involve:

• Using issue comments rather than tags, at least optionally, and
• Not requiring checking in .patchmill.

I'd be happy to work on this.

[rochecompaan]

@jimfulton I'd welcome the contribution!

Here are some points to consider before starting:

1. patchmill init does enable excluding .patchmill from git. It prompts you with:

   How should Patchmill files be handled by git?
     1) Add config and skills to git (recommended for shared config)
     2) Add Patchmill files to .gitignore
     3) Add Patchmill files to .git/info/exclude (local only)
   Choose 1, 2, or 3 [1]:
   

   Option 3 keeps everything out of the repo and its history.

2. The label dependency is the harder half of your request: workflow state (agent-ready, spec/plan approval, in-progress, blocked) is currently entirely label-driven, and run-once refuses unlabeled issues. Splitting the issue tracker from the code host, and including a local tracker like beads, is in phase II of the roadmap: https://github.com/rochecompaan/patchmill/blob/main/docs/roadmap.md#phase-ii-bring-work-from-anywhere With a local tracker, nothing would touch the shared repo's issues at all. An alternative is comment-based state as you suggest. I'd love to know which of these matches your ideal workflow.

3. I dogfood patchmill while developing patchmill. Since you'll be the first person I collaborate with, this will be an interesting test of using patchmill to collaborate. I'll write up a possible workflow for us to discuss. In simple terms: write a spec and plan using the /patchmill-plan and /patchmill-upload skills, mark it as approved, then kick off a run with patchmill run-once --issue <issuenr>. See https://patchmill.dev/using-patchmill/interactive-skills/. That said, I'm completely open to any ideas on how to make collaboration as productive as possible.

[jimfulton]

Good news on not having to check in .patchmill. I suspected and should have double checked.

WRT labels, my plan, without looking at the code 😄, would be to introduce an intermediate utility module that hides whether labels or comments are used.

I'm happy to follow whatever process you like. Not exactly sure when I'll get to this. 😄

[rochecompaan]

Since labels are Patchmill’s durable workflow state, we still need a local place to store that state. Rather than reimplementing labels as comments on an issue we do not control, I recommend separating the code-host and work-source configuration and adding a local work source.

Conceptually, the configuration would change from:

{
  "host": {
    "provider": "github-gh",
    "login": ""
  }
}

to something like:

{
  "codeHost": {
    "provider": "github-gh"
  },
  "workSource": {
    "provider": "beads"
  }
}

The existing host setting could remain as a compatibility shorthand for using the same provider for both roles.

We already have much of the necessary separation in the code. Issue operations use IssueHostProvider, pull-request body operations use PullRequestBodyHostProvider, and repository setup uses RepositorySetupHostProvider. There are also separate factory entry points for these capabilities. The remaining coupling is that they all receive the same host: { provider, login } configuration and construct the same GitHub or Forgejo provider. run-once also combines the issue and pull-request capabilities into one RunOnceHostProvider.

The main work would therefore be to split that configuration and factory wiring, introduce a work-source contract that exposes normalized readiness, workflow state, approvals, priority, and dependencies instead of raw labels, and use provider-qualified work-item identifiers. Patchmill could then keep its claim, approval, in-progress, blocked, and completed states locally while the code host handles repository and pull-request operations.

The roadmap currently names Beads as the reference local tracker. I checked its current documentation: Beads is Git-integrated and assumes a local Git repository, but it does not require write access to the upstream repository. Its contributor mode keeps issue data in a separate planning repository and can exclude Beads files through .git/info/exclude, leaving the upstream repository unchanged. That may be sufficient for this use case. However, it still couples the work source to Git and a separate planning repository. We should validate whether that is the experience we want and, if necessary, revisit the reference integration in favor of a more Git-independent tracker such as Kata or taskdb. A generic local-command adapter would let us support these without making Patchmill depend directly on any one tracker.

I’ll write up the development process in the meantime so that it is ready when you have time to work on this.

[jimfulton]

We do control individual issues. We can make any comments we want, and I really like the idea of tracking progress in issues!

What we don't control is repository configuration, which includes labels.

The only reason I want .patchmill to be local is to not have a tool I use intrude on repo source. Checking in .patchmill is a bit like checking in a IDE configuration, which happens often enough in some projects, but I don't like it.

[rochecompaan]

That distinction helps. Patchmill already lets us map each workflow role to a label name in the local patchmill.config.json. If a repository has suitable existing labels and you can apply and remove them, this should work without changing Patchmill or the repository configuration.

Here is a possible starting point using GitHub’s default labels where their meanings match:

{
  "host": {
    "provider": "github-gh",
    "login": ""
  },
  "labels": {
    "ready": "help wanted",
    "needsInfo": "question",
    "unsuitable": "<existing manual-only label>",
    "in-progress": "<existing in-progress label>",
    "done": "<existing completed label>",
    "blocked": "<existing blocked label>",
    "types": [
      "bug",
      "documentation",
      "enhancement"
    ],
    "priorities": []
  },
  "workflow": {
    "specApproval": {
      "required": false,
      "reviewLabel": "<existing spec-review label>",
      "approvedLabel": "<existing spec-approved label>"
    },
    "planApproval": {
      "required": false,
      "reviewLabel": "<existing plan-review label>",
      "approvedLabel": "<existing plan-approved label>"
    }
  }
}

The entries without angle brackets are standard GitHub labels. GitHub’s default set does not provide good equivalents for in-progress, completed, blocked, priority, or spec/plan approval states. I do not think we should repurpose labels such as duplicate, good first issue, or wontfix, because Patchmill would change their established meanings.

Hopefully you can ask the repo owner to add labels useful for tracking.

During patchmill init, you can choose option 3 to put Patchmill’s files in .git/info/exclude, decline label creation, edit this local mapping, and run patchmill doctor without --fix to check it. Nothing needs to be committed to the repository.

There is one other constraint: GitHub requires triage access to apply or dismiss labels. Permission to comment on an issue does not by itself grant permission to change its labels. Therefore, the current implementation already covers your use case if the repository has enough suitable existing labels and you can apply them. If either condition is false, then your proposed comment-backed state abstraction is still needed.