akasper / akasper/plate

gh-plate: Thin extension repository + automated publishing for working `gh plate` install

Open
#596 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Epic status:implemented
Dominant language
Python
Stars
1
Forks
0
Avg merge
8m
Merged PRs (30d)
3

Description

Summary

The documented command gh extension install akasper/plate fails with the hard error:

extension name must start with gh-

GitHub CLI requires that any repository used for gh extension install OWNER/REPO must have a REPO name starting with gh- (the extension command name is derived from it). plate does not qualify.

This repository's own research explicitly called out the constraint (see docs/research/stack-selection.md §gh extension repo naming + the open questions on repository topology for the gh surface). The two options were repo rename or a thin gh-plate wrapper repository.

We are choosing the thin wrapper path because the user explicitly ruled out both local-only installation as the supported story and renaming the implementation repository on GitHub.

Goal

Unblock real usage of the human/script-facing gh plate surface with a published, reliable install path, while keeping the implementation + plate-core PyPI package in this repository.

Three Child Issues (exactly as requested)

  • Task: Create the akasper/gh-plate thin repository on GitHub.
  • Documentation: Update all user-facing documentation (README, SPEC, examples) to document gh extension install akasper/gh-plate as the correct command. Also document the two-repo model clearly.
  • Feature: Implement automation (and any small launcher improvements) so the thin repo stays perfectly in sync with releases of this repo. Version numbers must match; drift must be impossible via normal process.

Critical Isolation Rule for the Automation (Feature child)

Any post-merge / post-release work that copies launcher code, updates versions, or otherwise touches the thin repo:

  • Lives only in this repository (.github/workflows/, supporting scripts, etc.).
  • Must be explicitly and prominently marked as PLATE-CORE-PUBLISHING-ONLY (or equivalent strong language).
  • Is not part of the PLATE methodology, AGENTS.md, the general release ceremony, or adopter guidance.
  • Must not be copied or mirrored into src/plate_core/template_payload/.github/workflows/, the template, design docs as "how to publish gh extensions for your PLATE project", or AGENTS.md.

Downstream PLATE-adopting repositories simply run the documented gh extension install against the thin repo. They do not maintain or run any sync automation. This Epic's automation is publishing infrastructure specific to the official plate_core / akasper/plate surfaces.

Acceptance Criteria

  • A clean gh extension install akasper/gh-plate (from any machine with Python + pip) produces a working gh plate that can run health, release status, pr babysit, etc.
  • All references in README.md and SPEC.md (and any other primary user docs) show the thin-repo install command.
  • The thin repo (akasper/gh-plate) exists with a correct minimal launcher + explanatory README.
  • Every release of this repository (the plate-core package + tag) automatically results in the thin repo receiving the corresponding launcher content and a matching version marker/tag. No manual steps required after the release PR merges.
  • The automation workflow(s) and scripts contain clear, reviewable isolation markers stating they are specific to this repo's publishing needs and are not part of general PLATE process or the adopter template.
  • The Epic is delivered via small atomic PRs following full PLATE rules (proper labels on PRs and issues, Closes #N in bodies, fragments under .agentic/releases/unreleased/ where the change affects user-facing surfaces or process, etc.).
  • Research doc (docs/research/stack-selection.md) is updated with a short "Resolved by" note linking this Epic.

References

  • Triggering terminal error and constraints from the user session on 2026-06-15.
  • docs/research/stack-selection.md (the gh extension naming section and repository topology open questions).
  • Root gh-plate entrypoint script (the intended launcher shape).
  • Current release process (.github/workflows/release.yml, scripts/cut_release.py, etc.).
  • Existing three-surface model in README and SPEC.

This is intentionally a small, focused Epic to restore a working published gh plate experience.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with docs/research/stack-selection.md, the root gh-plate entrypoint, .github/workflows/release.yml, and scripts/cut_release.py to understand the chosen wrapper and current release flow. Done means the thin repository, user-facing install documentation, and explicitly isolated publishing automation satisfy the listed acceptance criteria without changing the adopter template or general PLATE process.

Written by the indexing model from the issue text.

Assessment

Tech stack
github, github-actions, python
Domain
ci-cd, cli, documentation, release
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.