Built a GitLab/GitHub issue-tracking extension with checkpoint review and worktree isolation

[ricoyudog]

What I built

A set of custom schemas and AI skills that extend OpenSpec with full issue-tracking integration, checkpoint-based review, and git worktree isolation for parallel development.

Repo: openspec_gitflow_modified

Features

• Automatic issue tracking — /opsx-propose creates parent + child issues on GitLab (via glab) or GitHub (via gh). One parent per change, one child per Task Group.
• Checkpoint-based apply — Executes one Task Group at a time, posts a rich summary (objectives, completion, files produced) to the child issue, then pauses for review before continuing.
• Interactive review cycle — Automated quality checks (code quality, spec coverage, functional testing) + approve/reject/discuss flow per Task Group. Rejected groups trigger a repair loop that appends fix tasks.
• Workflow state labels — Issues follow a state machine: backlog → todo → in-progress → review → done.
• Platform auto-detection — Same /opsx-* commands work for both GitLab and GitHub. The platform is determined from config.yaml.
• Git worktree isolation (opt-in) — Each change can run in its own worktree for parallel development. On archive, the worktree is cleaned up but the branch is preserved for merging.

Why I built it

OpenSpec's artifact pipeline is excellent for structured planning. But once you start working in a team, you need:

1. Planning artifacts connected to your issue tracker — so stakeholders can follow progress without opening the repo
2. Review gates between Task Groups — not just continuous execution, but pause → review → approve → continue
3. Parallel development — multiple changes in flight without branch conflicts

This extension bridges that gap while keeping everything schema-driven.

How it works

/opsx-propose "Add JWT authentication"

flowchart LR
    A["/opsx-propose"] --> B["proposal.md\nspecs/\ndesign.md\ntasks.md"]
    B --> C["Issues created\n(parent + children)"]
    C --> D["/opsx-apply"]
    D --> E{"Group done?"}
    E -->|Yes| F["/opsx-review"]
    F --> G{"Approved?"}
    G -->|Yes, more groups| D
    G -->|Rejected| H["Fix tasks added"]
    H --> D
    G -->|All done| I["/opsx-archive"]

Loading

The schemas produce a 4-artifact pipeline: proposal → specs → design → tasks → apply. Each Task Group in tasks.md becomes a child issue, an apply session, and a review cycle.

Bundled schemas

Schema	Platform	CLI
gitlab-tracked	GitLab	glab
github-tracked	GitHub	gh

Both produce identical artifact structures — the only difference is which CLI is used for issue operations.

What I'd love to see upstream

The worktree isolation currently stores metadata in a .worktree.yaml sidecar file because the OpenSpec CLI doesn't have native worktree fields. It would be great if config.yaml or the change metadata could support a worktree section natively — happy to contribute a PR if there's interest.

Links

• Repo: https://github.com/ricoyudog/openspec_gitflow_modified
• Branch with all changes: https://github.com/ricoyudog/openspec_gitflow_modified/tree/feat/openspec-gitlab-integration
• Built on: OpenSpec v1.3.0