agentsclimarketplace

Promote

Skill davcs86/xstockstrat/.claude/skills/promote

Create the production promotion PR from main-dev to main. Usage — /promote. Detects whether the GitHub Action already opened one, validates branch state, runs buf breaking against main to prove proto compatibility, generates the dated CHANGELOG.md entry (features, bug fixes, proto changes, DB migrations), and serves as the manual fallback for flipping code-completed features to launched. Use this whenever the user asks to promote, release, ship, cut a production deploy, push main-dev to main, write release notes or a changelog entry, or check whether promoting would break proto consumers — even phrased as "let's go live" or "is main-dev safe to ship". Feature branch → main-dev PRs are not promotions; those belong to sdd-execute.From its SKILL.md

Install
npx -y skills add davcs86/xstockstrat --skill promote

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

  • no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

12.9 KB, as published. Nobody here has run it

You are creating a production promotion PR from main-dev to main for the xstockstrat platform. This skill uses main as the tooling baseline — buf breaking checks against main, and the PR targets main.


P0. Detect automation state

Before doing anything else, check whether the GitHub Action already handled P1–P6:

# Check for an open promote PR created by the automation
OPEN_PR=$(gh pr list --base main --head main-dev --state open --json url,title --jq '.[0].url')

# Check for a recent failed workflow run
FAILED_RUN=$(gh run list --workflow=promote.yml --status=failure --limit=1 --json url,conclusion,createdAt --jq '.[0].url')

If OPEN_PR is non-empty → The GitHub Action succeeded. Skip P1–P6 entirely. Print: "GitHub Action created the PR: <url>. Proceeding with feature tracking (P7) only." Go directly to P7 using the PR URL from OPEN_PR.

If OPEN_PR is empty AND FAILED_RUN is non-empty → The GitHub Action ran but failed. Print: "Automation failed. Run logs: <FAILED_RUN url>. Falling back to manual P1–P6." Proceed with P1–P6 below, then P7. At the end of P6 report: "Completed P1–P6 manually (automation failure fallback)."

If both are empty → The automation has not been triggered. Ask the user: "No promotion PR found and no recent workflow run detected. Should I:

  1. Trigger the GitHub Action (promote.yml) and wait for it to complete, then do P7
  2. Handle P1–P6 here directly

Which would you prefer?"

  • If the user chooses trigger:

    gh workflow run promote.yml --ref main-dev
    

    Then poll every 15 seconds until the run completes:

    gh run list --workflow=promote.yml --limit=1 --json status,conclusion,url --jq '.[0]'
    
    • If the run succeeds → do P7.
    • If the run fails → print the run URL and offer to fall back to P1–P6.
  • If the user chooses handle here → proceed with P1–P6 below, then P7.



P1. Validate state

Fetch both branches:

git fetch origin main main-dev

Check that main-dev is ahead of main:

git log origin/main..origin/main-dev --oneline

If the output is empty: stop — "main-dev has no commits ahead of main. Nothing to promote."

Check for an existing open PR from main-dev to main:

git ls-remote --heads origin main-dev

Also check via gh if an open PR already exists:

gh pr list --base main --head main-dev --state open

If an open PR exists: stop and print — "A promote PR is already open: <URL>. Close or merge it before creating a new one."


P2. Collect changelog inputs

Merge commits since last promotion:

git log origin/main..origin/main-dev --merges --oneline

New migrations since main:

git diff --name-only origin/main origin/main-dev -- services/*/migrations/

Filter to only *.up.sql files.

Proto changes since main:

git diff --name-only origin/main origin/main-dev -- packages/proto/

Filter to only *.proto files (not generated stubs).

Features at code-completed:

egrep -l '^code-completed$' docs/roadmap/features/*/status.md

Single shell call across all features — see docs/roadmap/features/CLAUDE.md § Bulk Status Reads, Case 1. Then, for only the matching directories, read each feature.md and collect:

  • Entries where **Type** is feature (or **Type** is absent — default is feature). Extract slug and Summary first sentence.
  • Entries where **Type** is bug. Extract slug, Summary first sentence, and **Severity**.

For each result, capture the full feature directory path as FEATURE_DIR (e.g. docs/roadmap/features/001-add-ikbr-account-support). Derive the display slug by stripping the leading NNN- prefix from the directory basename (e.g. 001-add-ikbr-account-support → add-ikbr-account-support). Use FEATURE_DIR for all file read/write operations; use the stripped slug for CHANGELOG display.

Commit count:

git log origin/main..origin/main-dev --oneline | wc -l

P3. Run buf breaking against main (tooling points to main)

cd packages/proto
buf breaking . --against '../../.git#branch=origin/main,subdir=packages/proto'
  • If no breaking changes: continue.
  • If breaking changes found: print the output, then ask the user: "Breaking proto changes detected. These require sign-off per docs/runbooks/proto-versioning.md before this PR can merge. Proceed with creating the PR anyway? (yes / no)" If user says no: stop.

P4. Format the changelog entry

Use today's date in YYYY-MM-DD format. Format the entry as:

## YYYY-MM-DD

### Features
- <slug>: <summary sentence> (`code-completed`)

(omit this section if no features at code-completed)

### Bug Fixes
- <slug> [<SEV-N>]: <summary sentence> (`code-completed`)

(omit this section if no bugs at code-completed)

### Proto Changes
- <filename.proto>

(omit this section if no proto changes)

### DB Migrations
- <service>: <migration-filename.up.sql>

(omit this section if no new migrations)

### Summary
<N> commits, <M> feature merges since last promotion.

If there are no features, bug fixes, proto changes, or migrations — just include the Summary line.


P5. Update CHANGELOG.md

Read CHANGELOG.md at the repo root.

If it does not exist, create it with this header:

# Changelog

All production promotions from `main-dev` to `main` are recorded here.
Each entry corresponds to one `main-dev → main` PR merge.

---

Check if an entry for today's date (## YYYY-MM-DD) already exists in the file:

grep "^## $(date +%Y-%m-%d)$" CHANGELOG.md

If the entry exists: Replace the entire entry (from ## YYYY-MM-DD to the next --- separator or EOF) with the new changelog entry (from P4).

If the entry does not exist: Prepend the new changelog entry (from P4) immediately before the first ## YYYY-MM-DD entry heading in the file (i.e. right after the header/intro text) — followed by a blank line, a --- separator, and another blank line before the existing content resumes. Do not anchor on "the first --- line in the file": the header itself has no leading ---, so that line is actually the closing separator of whatever entry currently happens to be first, and inserting after it drops the new entry into the wrong position instead of at the top. If the file has no ## entries yet (freshly created), append the new entry at the end instead.

Write the file back.

Commit the update to main-dev:

git add CHANGELOG.md
git commit -m "chore: update CHANGELOG for <YYYY-MM-DD> promotion"
git push origin main-dev

P6. Create PR from main-dev → main

Build the PR body from the changelog entry plus these sections:

## Promotion Checklist

- [ ] All services smoke-tested on dev (paper trading) environment
- [ ] No open incidents or active maintenance mode on dev
- [ ] Config keys for new features registered in prod config service (see docs/runbooks/config-rollout.md)
- [ ] Proto breaking changes signed off (if any — see docs/runbooks/proto-versioning.md)

> ⚠️ **Merge strategy: "Create a merge commit" — NEVER squash or rebase.**
> Squash-merging breaks git ancestry and causes `main-dev` to appear permanently ahead of `main`.
> On GitHub: click the dropdown arrow next to the merge button → **"Create a merge commit"**.

## Changelog

<changelog entry from P4>

Create the PR:

gh pr create \
  --base main \
  --head main-dev \
  --title "release: promote main-dev to main (YYYY-MM-DD)" \
  --body "<PR body above>"

Print the PR URL.


P7. Update feature tracking (automatic on promotion PR merge)

This phase is now automated by CI. After the promotion PR merges to main:

  1. A GitHub Actions workflow (ci-validate-feature-status.yml) runs automatically on the main branch
  2. It detects features that were promoted (commits on main between the base and head of the promotion PR)
  3. For each promoted feature, it:
    • Updates status from code-completed → launched
    • Adds a status history entry with promotion PR link and commit SHA
    • Records **Committed to main** with the commit SHA
    • Records **Launched date** with today's date
    • Updates context.md with promotion session log
    • Commits and pushes the changes back to main

Manual fallback (if CI workflow fails): Run this skill on the main branch manually to update feature statuses.

For each feature or bug found at code-completed in P2:

Overwrite $FEATURE_DIR/status.md with launched (plain string).

Read its $FEATURE_DIR/feature.md (using the FEATURE_DIR captured in P2). Add a new row to the Status History table:

| YYYY-MM-DD | `code-completed` → `launched` | /promote + CI | Promoted via PR #NNN; committed SHA-HASH to main |

Update these fields:

**Committed to main**: <commit-sha>
**Launched date**: YYYY-MM-DD

Write the file back. Update $FEATURE_DIR/context.md:

## Session YYYY-MM-DD (CI: feature status automation)

- Promotion PR #NNN merged to main
- Feature promoted and committed: <commit-sha>
- Status updated: `code-completed` → `launched`
- Launched date: YYYY-MM-DD

P7.5. Promote acceptance scenarios (C-16 backstop)

The durable business-rule suites must gain each launching feature's @AC-* scenarios (C-16). The primary promotion is /sdd-execute at integration; this is the backstop for a feature that reached launched without it (and /sdd-archiver is a third, later net). It is idempotent — an already-promoted feature yields an all-DUP plan and writes nothing.

For each feature found at code-completed in P2 (i.e. flipping to launched):

  1. Spawn the scenario-promoter subagent via Task (read-only), passing its slug, feature number NNN, the path to $FEATURE_DIR/acceptance.feature, the affected services (from feature.md's Reviewers table), and the existing suite paths to dedup against (services/xstockstrat-<svc>/acceptance/*.feature + docs/sdd/business-rules/platform.feature).
  2. Apply its plan (orchestrator is the single writer, P-01): append each NEW scenario block verbatim to its target suite, creating a services/xstockstrat-<svc>/acceptance/ dir + file header on CREATE. Skip DUP/OVERLAP; surface any CONFLICT (a launching feature contradicting a standing promoted rule) to the user — never silently overwrite. Never rewrite/delete an existing promoted scenario.
  3. Stage the promoted suite files with this promotion's other doc changes. If nothing was NEW, note "scenarios already promoted" and move on.

P8. Announce result

Print a summary:

Promotion PR created: <PR URL>
Branch: main-dev → main
Changelog: CHANGELOG.md updated

Features included (code-completed):
  - <slug>: <summary>

Bug fixes included (code-completed):
  - <slug> [<SEV-N>]: <summary>

Next steps:
  1. Complete the Promotion Checklist in the PR description.
  2. Get at least 1 reviewer approval (branch protection enforced).
  3. After merging, confirm each feature's status.md reads 'launched' (CI does this automatically;
     this is the fallback check).
  4. The sync-main-to-maindev workflow runs automatically after the PR merges —
     it merges the resulting main commit back into main-dev so the branches
     stay in sync. No manual action needed unless the workflow reports a conflict.

Post-merge sync (automated)

After the promotion PR merges to main, the .github/workflows/sync-main-to-maindev.yml workflow fires automatically. It merges the new main tip back into main-dev, ensuring main-dev always contains every commit that is on main.

If the workflow fails (e.g. merge conflict from a commit pushed directly to main):

  1. Fetch both branches locally.
  2. Check out main-dev.
  3. Run git merge origin/main and resolve conflicts.
  4. Push: git push origin main-dev.

Keep looking

Skills are one crate of 608,475. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.