Reorganize examples into folders with READMEs (#42)

* Reorganize examples into folders with READMEs

Move each CI example into its own directory with a platform-conventional
filename and a README explaining when to use it, how it works, and setup
steps. Update SKILL.md links to point to the new folder paths.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix inaccurate customization guidance in READMEs

- GitLab CI continuous: clarify that $CI_DEFAULT_BRANCH is a predefined
  variable and show how to replace it in the rule expression
- GitHub Actions scheduled: note that branch pattern changes must also
  update startsWith() guards and version derivation in the workflow

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Rework docs

* Rename example files to platform conventions

Use the filename each CI platform expects: `linear-release.yml` for
GitHub Actions workflows, `config.yml` for CircleCI, `.gitlab-ci.yml`
for GitLab CI.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: axelniklasson

examples/circleci-continuous/README.md

@@ -0,0 +1,22 @@
+# CircleCI — Continuous Pipeline
+
+Every deployment creates a completed release automatically.
+
+## When to use
+
+Use this when your team ships continuously — every push to main is a deploy, and each deploy should be tracked as its own release in Linear.
+
+## How it works
+
+On every push to `main`, the workflow downloads the Linear Release CLI and runs `sync`. This creates a new release from the commits since the last release and immediately marks it as complete.
+
+## Setup
+
+1. Create a release pipeline in Linear (Settings → Releases) and grab the access key.
+2. Add `LINEAR_ACCESS_KEY` as an environment variable in CircleCI (Project Settings → Environment Variables).
+3. Copy the contents of [`config.yml`](config.yml) into your `.circleci/config.yml` (or merge with your existing config).
+
+## Customization
+
+- **Branch name**: Change `main` in the branch filter if your default branch is different.
+- **Monorepo path filters**: Add `--include-paths` to the `sync` command to scope the release to specific directories.

examples/circleci-continuous.yml examples/circleci-continuous/config.ymlexamples/circleci-continuous.yml renamed to examples/circleci-continuous/config.yml

@@ -0,0 +1,40 @@
+# CircleCI — Scheduled Pipeline
+
+Releases follow a branch cut model where changes collect over time and move through stages before shipping.
+
+## When to use
+
+Use this when your team cuts release branches for stabilization. Main collects changes into the current release, release branches sync with an explicit version and auto-promote on creation.
+
+## How it works
+
+- **Push to `main`**: Syncs issues to the current started release (no explicit version).
+- **Push to `release/*`**: Derives the version from `CIRCLE_BRANCH` and syncs with that version. Detects branch creation by checking for previous pipelines via the CircleCI API, and auto-promotes to "code freeze" on first push.
+- **API trigger**: Runs `update` or `complete` with pipeline parameters for later stage transitions and final completion.
+
+### Triggering manual actions
+
+Use the CircleCI API to trigger stage transitions:
+
+```bash
+curl -X POST https://circleci.com/api/v2/project/gh/ORG/REPO/pipeline \
+  -H "Circle-Token: $CIRCLE_TOKEN" -H "Content-Type: application/json" \
+  -d '{"parameters": {"run-release-action": true, "action": "update", "stage": "qa", "release_version": "1.2.0"}}'
+```
+
+## Setup
+
+1. Create a release pipeline in Linear (Settings → Releases) and grab the access key.
+2. Add `LINEAR_ACCESS_KEY` and `CIRCLE_TOKEN` as environment variables in CircleCI (Project Settings → Environment Variables).
+3. Copy the contents of [`config.yml`](config.yml) into your `.circleci/config.yml` (or merge with your existing config).
+
+## Customization
+
+- **Branch patterns**: Change `release/` to match your release branch convention.
+- **Stage names**: Replace `code freeze` with whatever your first stage is called.
+- **Version derivation**: The example strips `release/` from the branch name. Adjust if your branch naming differs.
+- **Monorepo path filters**: Add the `include_paths` input to scope the release to specific directories.
+
+## Monorepo note
+
+CircleCI doesn't support path filtering natively. Use the `path-filtering` orb or split into separate workflows and use the API to conditionally trigger.

examples/circleci-scheduled/README.md

@@ -4,14 +4,11 @@
 # release branches derive version from CIRCLE_BRANCH.
 #
 # Trigger: Auto on push, API trigger for later stage transitions and completion.
-# Customize: Branch patterns, stage names, auto-promotion stage.
+# Customize: Branch patterns, stage names, auto-promotion stage, path inclusion.
 # Note: Set LINEAR_ACCESS_KEY and CIRCLE_TOKEN in CircleCI project settings.
 #
 # Branch creation detection: CircleCI has no built-in signal, so auto-promotion
 # checks the API for previous pipelines on the branch.
-#
-# Monorepo: CircleCI doesn't support path filtering natively. Use the `path-filtering`
-# orb or split into separate workflows and use the API to conditionally trigger.
 
 version: 2.1
 

examples/circleci-scheduled.yml examples/circleci-scheduled/config.ymlexamples/circleci-scheduled.yml renamed to examples/circleci-scheduled/config.yml

@@ -0,0 +1,22 @@
+# GitHub Actions — Continuous Pipeline
+
+Every deployment creates a completed release automatically.
+
+## When to use
+
+Use this when your team ships continuously — every push to main is a deploy, and each deploy should be tracked as its own release in Linear.
+
+## How it works
+
+On every push to `main`, the workflow runs `sync` via the official [Linear Release Action](https://github.com/linear/linear-release-action). This creates a new release from the commits since the last release and immediately marks it as complete.
+
+## Setup
+
+1. Create a release pipeline in Linear (Settings → Releases) and grab the access key.
+2. Add `LINEAR_ACCESS_KEY` as a repository secret (Settings → Secrets and variables → Actions → New repository secret).
+3. Copy [`linear-release.yml`](linear-release.yml) into `.github/workflows/`.
+
+## Customization
+
+- **Branch name**: Change `main` in the `branches` filter if your default branch is different.
+- **Monorepo path filters**: Add the `include_paths` input to scope the release to specific directories.

examples/github-actions-continuous/README.md

@@ -0,0 +1,34 @@
+# GitHub Actions — Scheduled Pipeline
+
+Releases follow a branch cut model where changes collect over time and move through stages before shipping.
+
+## When to use
+
+Use this when your team cuts release branches for stabilization. Main collects changes into the current release, a `release/*` branch is cut for stabilization, and branch creation auto-promotes to "code freeze".
+
+## How it works
+
+- **Push to `main`**: Syncs issues to the current started release (no explicit version).
+- **Push to `release/*`**: Derives the version from the branch name and syncs with that version. On branch creation, auto-promotes the release to "code freeze".
+- **Manual dispatch**: Runs `update` or `complete` with the specified stage and version, for later stage transitions and final completion.
+
+## Setup
+
+1. Create a release pipeline in Linear (Settings → Releases) and grab the access key.
+2. Add `LINEAR_ACCESS_KEY` as a repository secret (Settings → Secrets and variables → Actions → New repository secret).
+3. Copy [`linear-release.yml`](linear-release.yml) into `.github/workflows/`.
+
+## Customization
+
+- **Branch patterns**: Change `release/**` in the push trigger _and_ update every `startsWith(github.ref_name, 'release/')` guard and the `${GITHUB_REF_NAME#release/}` version derivation in the workflow to match your release branch convention.
+- **Stage names**: Replace `code freeze` with whatever your first stage is called.
+- **Version derivation**: The example strips `release/` from the branch name. Adjust if your branch naming differs.
+
+## Monorepo note
+
+GitHub Actions `paths` applies to all branches in a push trigger. To path-filter `main` without filtering release branches, split into two workflow files:
+
+1. **File 1 (main)**: Add `paths: [...]` to the push trigger, keep only the main sync step.
+2. **File 2 (release)**: Keep the release branch + `workflow_dispatch` logic as-is.
+
+Add `include_paths` to the action in both files.

examples/github-actions-continuous.yml …ub-actions-continuous/linear-release.ymlexamples/github-actions-continuous.yml renamed to examples/github-actions-continuous/linear-release.yml examples/github-actions-continuous.yml renamed to examples/github-actions-continuous/linear-release.yml

@@ -0,0 +1,22 @@
+# GitLab CI — Continuous Pipeline
+
+Every deployment creates a completed release automatically.
+
+## When to use
+
+Use this when your team ships continuously — every push to the default branch is a deploy, and each deploy should be tracked as its own release in Linear.
+
+## How it works
+
+On every push to the default branch, the job downloads the Linear Release CLI and runs `sync`. This creates a new release from the commits since the last release and immediately marks it as complete.
+
+## Setup
+
+1. Create a release pipeline in Linear (Settings → Releases) and grab the access key.
+2. Add `LINEAR_ACCESS_KEY` as a CI/CD variable in GitLab (Settings → CI/CD → Variables).
+3. Copy the contents of [`.gitlab-ci.yml`](.gitlab-ci.yml) into your `.gitlab-ci.yml` (or merge with your existing config).
+
+## Customization
+
+- **Branch rules**: The workflow uses GitLab's predefined `$CI_DEFAULT_BRANCH` variable, which automatically matches your repository's default branch. To target a different branch, replace `$CI_DEFAULT_BRANCH` in the rule expression with a hardcoded branch name (e.g. `if: $CI_COMMIT_BRANCH == "production"`).
+- **Monorepo path filters**: Add `--include-paths` to the `sync` command to scope the release to specific directories.