Skip to content

Commit b97625f

Browse files
feature: scaffold release candidate and snapshot handoff flow (#316)
* documentation: add PR bootstrap changelog whitespace * docs: adding the basic release workflow, a agent skill for setting up a pr, updating the yank process, and the related docs * docs: bump * feat: adding a snapshot feature for context handoff between sessions * docs: docs bump and ignore logs * fix: copilot suggestion resolution * fix: more copilot fixes * docs: updated plan * fix: copilot found some missing checks * docs: adding a scope creep monitor * fix: more checks and ref fixes * docs: adding the plan to remove the go project * fix: initialization from copilot * fix: copilot suggested fixes for managing snapshot text and the output for the release * feat: updated the skill to keep the changelog more concise rather than additive and made those changes to the changelog * fix: more metadata and wording fixes
1 parent 1333fd8 commit b97625f

14 files changed

Lines changed: 584 additions & 12 deletions

File tree

.agents/README.md

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# Agents Instructions
2-
Last updated: 2026-03-28
2+
Last updated: 2026-04-08
33

44
## Scope
55
- Source of truth for agent guidance and skill locations in this repository.
@@ -17,10 +17,19 @@ Last updated: 2026-03-28
1717
- Skills must reside under `.agents/skills/<name>/SKILL.md`.
1818
- Additional instruction files should live under `.agents/` when needed.
1919

20+
## Work snapshot guidance
21+
- Local handoff file: `.agents/work-snapshot.local.md`.
22+
- Read it at session start when present to recover intent/next steps.
23+
- Treat `updated_at` as advisory; validate with current git/PR state before acting.
24+
- Prefer git/GitHub state as source-of-truth, and use snapshot mostly for context.
25+
- Refresh it after major milestones and before ending a session.
26+
2027
## Skills index
2128
- Version Bump: `.agents/skills/version-bump/SKILL.md`
2229
- Update Changelog: `.agents/skills/update-changelog/SKILL.md`
2330
- Sync Labels: `.agents/skills/sync-labels/SKILL.md`
31+
- WIP PR Setup: `.agents/skills/wip-pr-setup/SKILL.md`
32+
- Work Snapshot: `.agents/skills/work-snapshot/SKILL.md`
2433
- Manifest: `.agents/skills/manifest.md`
2534

2635
## Expectations for SKILL.md
Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
#! /usr/bin/env bash
2+
3+
set -euo pipefail
4+
5+
usage() {
6+
cat <<'EOF'
7+
Usage: .agents/scripts/update-work-snapshot.sh [--context "..."] [--goal "..."]
8+
9+
Updates the managed section of .agents/work-snapshot.local.md.
10+
If --context/--goal are omitted, existing values are preserved when present.
11+
EOF
12+
}
13+
14+
context_override=""
15+
goal_override=""
16+
17+
while [ "$#" -gt 0 ]; do
18+
case "$1" in
19+
--context)
20+
if [ "$#" -lt 2 ]; then
21+
echo "Error: --context requires a value" >&2
22+
exit 1
23+
fi
24+
context_override="${2:-}"
25+
shift 2
26+
;;
27+
--goal)
28+
if [ "$#" -lt 2 ]; then
29+
echo "Error: --goal requires a value" >&2
30+
exit 1
31+
fi
32+
goal_override="${2:-}"
33+
shift 2
34+
;;
35+
-h | --help)
36+
usage
37+
exit 0
38+
;;
39+
*)
40+
echo "Error: Unknown argument: $1" >&2
41+
usage >&2
42+
exit 1
43+
;;
44+
esac
45+
done
46+
47+
repo_root="$(git rev-parse --show-toplevel)"
48+
snapshot_file="${repo_root}/.agents/work-snapshot.local.md"
49+
50+
branch="$(git -C "${repo_root}" rev-parse --abbrev-ref HEAD)"
51+
updated_at="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
52+
53+
existing_goal=""
54+
existing_context=""
55+
if [ -f "${snapshot_file}" ]; then
56+
existing_goal="$(awk '/^- goal: / {sub(/^- goal: /, ""); print; exit}' "${snapshot_file}" || true)"
57+
existing_context="$(awk '/^- context: / {sub(/^- context: /, ""); print; exit}' "${snapshot_file}" || true)"
58+
fi
59+
60+
goal="${goal_override:-$existing_goal}"
61+
context_line="${context_override:-$existing_context}"
62+
63+
if [[ "${goal}" == *$'\n'* ]] || [[ "${goal}" == *$'\r'* ]]; then
64+
echo "Error: --goal must be a single line" >&2
65+
exit 1
66+
fi
67+
68+
if [[ "${context_line}" == *$'\n'* ]] || [[ "${context_line}" == *$'\r'* ]]; then
69+
echo "Error: --context must be a single line" >&2
70+
exit 1
71+
fi
72+
73+
if [ -z "${goal}" ]; then
74+
goal="Set this with --goal \"...\"."
75+
fi
76+
77+
if [ -z "${context_line}" ]; then
78+
context_line="Updated via script; add a one-line note with --context \"...\" when needed."
79+
fi
80+
81+
issue="n/a"
82+
if [[ "${branch}" =~ -([0-9]+)$ ]]; then
83+
issue="#${BASH_REMATCH[1]}"
84+
fi
85+
86+
pr="n/a"
87+
pr_state="n/a"
88+
pr_mergeable="n/a"
89+
pr_review="n/a"
90+
pr_number=""
91+
pr_url=""
92+
93+
if command -v gh >/dev/null 2>&1; then
94+
pr_data="$(gh pr view --json number,url,state,mergeable,reviewDecision --template '{{if .number}}{{.number}}{{"\t"}}{{.url}}{{"\t"}}{{.state}}{{"\t"}}{{.mergeable}}{{"\t"}}{{.reviewDecision}}{{end}}' 2>/dev/null || true)"
95+
if [ -n "${pr_data}" ]; then
96+
IFS=$'\t' read -r pr_number pr_url pr_state pr_mergeable pr_review <<EOF
97+
${pr_data}
98+
EOF
99+
fi
100+
101+
if [ -n "${pr_number}" ] && [ "${pr_number}" != "null" ]; then
102+
pr="#${pr_number}"
103+
fi
104+
if [ -n "${pr_url}" ] && [ "${pr_url}" != "null" ] && [ "${pr}" != "n/a" ]; then
105+
pr="${pr} ${pr_url}"
106+
fi
107+
fi
108+
109+
managed_block=$(cat <<EOF
110+
<!-- managed:start -->
111+
# Work Snapshot (Local)
112+
113+
- branch: ${branch}
114+
- issue: ${issue}
115+
- pr: ${pr}
116+
- goal: ${goal}
117+
- context: ${context_line}
118+
- pr_state: ${pr_state}
119+
- pr_mergeable: ${pr_mergeable}
120+
- pr_review: ${pr_review}
121+
- updated_at: ${updated_at}
122+
<!-- managed:end -->
123+
EOF
124+
)
125+
126+
manual_block=$(cat <<'EOF'
127+
128+
## Manual Notes
129+
- done:
130+
-
131+
- current_state:
132+
-
133+
- next:
134+
1.
135+
EOF
136+
)
137+
138+
if [ ! -f "${snapshot_file}" ]; then
139+
printf '%s\n%s\n' "${managed_block}" "${manual_block}" >"${snapshot_file}"
140+
echo "Created ${snapshot_file}"
141+
exit 0
142+
fi
143+
144+
if ! command -v python3 >/dev/null 2>&1; then
145+
echo "Error: python3 is required to update ${snapshot_file}" >&2
146+
exit 1
147+
fi
148+
149+
python3 - "${snapshot_file}" "${managed_block}" "${manual_block}" <<'PY'
150+
from pathlib import Path
151+
import sys
152+
153+
path = Path(sys.argv[1])
154+
managed = sys.argv[2]
155+
manual = sys.argv[3]
156+
text = path.read_text(encoding="utf-8") if path.exists() else ""
157+
158+
start = "<!-- managed:start -->"
159+
end = "<!-- managed:end -->"
160+
161+
if start in text and end in text:
162+
before, rest = text.split(start, 1)
163+
_, after = rest.split(end, 1)
164+
after = after.lstrip("\n")
165+
if not after.strip():
166+
after = manual.strip("\n") + "\n"
167+
else:
168+
after = after.rstrip("\n") + "\n"
169+
if before:
170+
new_text = before + managed + "\n" + after
171+
else:
172+
new_text = managed + "\n" + after
173+
else:
174+
tail = text.strip("\n")
175+
if tail:
176+
new_text = managed + "\n\n" + tail + "\n"
177+
else:
178+
new_text = managed + "\n" + manual.strip("\n") + "\n"
179+
180+
path.write_text(new_text, encoding="utf-8")
181+
PY
182+
183+
echo "Updated ${snapshot_file}"

.agents/skills/manifest.md

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# Skills Manifest
2-
Last updated: 2026-03-28
2+
Last updated: 2026-04-08
33

44
- **version-bump**
55
- Path: `.agents/skills/version-bump/SKILL.md`
@@ -10,3 +10,9 @@ Last updated: 2026-03-28
1010
- **sync-labels**
1111
- Path: `.agents/skills/sync-labels/SKILL.md`
1212
- Summary: Sync issue/PR labels for kind, priority, status, and change-type rules; `size/*` labels are CI-managed and PR-only.
13+
- **wip-pr-setup**
14+
- Path: `.agents/skills/wip-pr-setup/SKILL.md`
15+
- Summary: Set up branch/PR workflow for in-progress work, including docs bump checks and doing-state label sync.
16+
- **work-snapshot**
17+
- Path: `.agents/skills/work-snapshot/SKILL.md`
18+
- Summary: Refresh a compact git-ignored local handoff snapshot for fast session resume.

.agents/skills/update-changelog/SKILL.md

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,12 @@ description: Updates the existing changelog entry for the current version after
1111
## Purpose
1212
Update the current version changelog entry without changing the version.
1313

14+
## Entry quality bar
15+
- Treat the current-version entry as curated release notes, not an append-only scratchpad.
16+
- Consolidate related bullets into outcome-focused statements (prefer user/contributor impact over implementation minutiae).
17+
- Remove duplicate or near-duplicate bullets and keep section wording consistent.
18+
- Keep entries concise (target roughly 3-6 bullets per section when work volume allows).
19+
1420
## When to use
1521
- Version already bumped for this branch/working copy and you need to record additional changes.
1622
- The branch has a current-version changelog entry that is not merged to `main` yet; update that same entry instead of creating another version header.
@@ -34,10 +40,11 @@ Update the current version changelog entry without changing the version.
3440
3. If the version exists in branch changelog (including when it is not yet merged to `main`), update that same entry in place.
3541
4. If branch entry is missing but `main` already has that version entry, cherry-pick/recreate that entry at the top and then update it.
3642
5. If branch and `main` both lack that version entry, stop and run [Version Bump Skill](../version-bump/SKILL.md).
37-
6. Update Added/Changed/Fixed bullets with concise, user-visible changes; avoid duplicate bullets and keep style consistent.
38-
7. When updating an existing entry, keep the version unchanged and set the entry date to today's date (`YYYY-MM-DD`, UTC).
39-
8. If adding more changes later without bumping a new version, update that same entry again and refresh the date to today's date.
40-
9. Validate with `git diff`; run tests if code changed.
43+
6. Consolidate the entry before finalizing: merge overlapping bullets, collapse low-level implementation-only bullets into higher-level outcomes, and remove duplicates.
44+
7. Update Added/Changed/Fixed bullets with concise, user-visible or contributor-impacting changes; keep style and tense consistent.
45+
8. When updating an existing entry, keep the version unchanged and set the entry date to today's date (`YYYY-MM-DD`, UTC).
46+
9. If adding more changes later without bumping a new version, update that same entry again (rewrite/refine, not append-only) and refresh the date to today's date.
47+
10. Validate with `git diff`; run tests if code changed.
4148

4249
## Outputs
4350
- Updated `CHANGELOG.md` entry for the current version reflecting all new work.

.agents/skills/version-bump/SKILL.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ Keep the BasicSetup CLI version and changelog in sync for releases.
3030
## Steps
3131
1. Set the new version: `yq -i '.BasicSetupCliVersion = "X.Y.Z"' bsctl/static/resources/constants.yaml`.
3232
2. Create a new top `CHANGELOG.md` entry for `X.Y.Z` with today’s date (`YYYY-MM-DD`) and Keep a Changelog section headers (`### Added`, `### Changed`, `### Fixed`).
33-
3. Immediately run [Update Changelog Skill](../update-changelog/SKILL.md) to populate/refine the entry from staged/working-tree changes and recent commits.
33+
3. Immediately run [Update Changelog Skill](../update-changelog/SKILL.md) to populate/refine and consolidate the entry from staged/working-tree changes and recent commits.
3434
4. Verify alignment: top changelog version matches `.BasicSetupCliVersion`; date is valid for CI validation (UTC +/- 1 day).
3535
5. Validate changes: at minimum `git diff`; run `make test` if code changed.
3636

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
name: wip-pr-setup
3+
description: Sets up a working branch/PR flow for in-progress changes (branch, remote, PR attempt, docs bump, and label sync) while optionally keeping local edits uncommitted.
4+
---
5+
6+
# WIP PR Setup Skill
7+
8+
## Owner/Contact
9+
- Repo maintainers (e.g., @mrlunchbox777).
10+
11+
## Purpose
12+
Standardize the setup flow for starting implementation work with branch management, PR linkage, docs bump validation, and issue/PR status label sync.
13+
14+
## When to use
15+
- Starting a new tracked implementation issue.
16+
- Preparing a branch and PR shell before final commits are ready.
17+
- Moving issue/PR state to `status/doing` at work start.
18+
19+
## Prerequisites
20+
- Tools: `git`, `gh` CLI authenticated.
21+
- Target issue exists.
22+
- Working tree state is known before branch creation.
23+
24+
## Inputs
25+
- Target issue number(s) for linkage (for example `#307`, parent tracker).
26+
- New branch name.
27+
- PR title/body draft.
28+
- Whether local edits should remain uncommitted/unpushed.
29+
- Whether to create a minimal bootstrap commit (for example, whitespace-only `CHANGELOG.md`) when PR creation is blocked by zero diff.
30+
31+
## Required context
32+
- Repository docs/version bump requirements (`bsctl/static/resources/constants.yaml`, `CHANGELOG.md`).
33+
- Label conventions and sync rules from `sync-labels` skill.
34+
- Whether GitHub can create a PR for the branch yet (must have commits ahead of base).
35+
36+
## Steps
37+
1. Create local branch and push upstream tracking branch.
38+
2. Attempt to create PR with `Relates #...` references.
39+
3. If PR creation fails because no commits differ from base, either:
40+
- report the block and continue local work setup, or
41+
- if requested, create and push a minimal bootstrap commit (for example, whitespace-only `CHANGELOG.md`) to unblock PR creation.
42+
4. Apply requested local edits without committing if specified.
43+
5. Run docs bump validation and update version/changelog when required.
44+
6. Reopen/annotate related issue when process continuity is needed.
45+
7. Sync labels to `status/doing` for issue and PR (if PR exists); for issue-only state, update issue labels only.
46+
8. Return a concise checklist of what was completed and what is pending (for example, PR creation blocked pending first commit).
47+
48+
## Safety Rules
49+
- Do not commit/push local code edits when user requested local-only changes.
50+
- If creating a bootstrap commit, keep it minimal/non-functional and clearly call out that it is a PR bootstrap commit.
51+
- Do not auto-close related issues unless explicitly requested.
52+
- Use `Relates #...` wording to avoid accidental issue closure.
53+
54+
## Outputs
55+
- Branch created locally and remotely.
56+
- PR created when possible, otherwise explicit reason it is not yet creatable.
57+
- Local change set prepared and validated.
58+
- Issue/PR labels synchronized to active work state.
Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
name: work-snapshot
3+
description: Updates a compact local handoff snapshot of current branch/PR/work state in a git-ignored file for fast session resume.
4+
---
5+
6+
# Work Snapshot Skill
7+
8+
## Owner/Contact
9+
- Repo maintainers (e.g., @mrlunchbox777).
10+
11+
## Purpose
12+
Keep a small, durable, local-only handoff note so work can resume quickly without relying on full chat history.
13+
14+
## When to use
15+
- At the start of a working session (refresh current state).
16+
- After major milestones (conflict resolution, docs bump, checks rerun, review updates).
17+
- Before ending a session.
18+
19+
## Prerequisites
20+
- `git` is available.
21+
- `python3` is available (required when updating an existing snapshot file).
22+
- Optional: `gh` authenticated to include PR state fields.
23+
24+
## Inputs
25+
- Optional one-line context via `--context "..."`.
26+
- Optional one-line goal via `--goal "..."`.
27+
28+
## Required context
29+
- Snapshot file path: `.agents/work-snapshot.local.md` (git ignored).
30+
- Updater script: `.agents/scripts/update-work-snapshot.sh`.
31+
32+
## Steps
33+
1. Run `.agents/scripts/update-work-snapshot.sh` to refresh managed fields.
34+
2. If needed, pass one-line updates:
35+
- `.agents/scripts/update-work-snapshot.sh --context "..."`
36+
- `.agents/scripts/update-work-snapshot.sh --goal "..."`
37+
3. Add or refine short bullets under `## Manual Notes` for done/current_state/next.
38+
4. Keep notes concise and action-oriented (no long transcripts).
39+
40+
## Safety Rules
41+
- Do not store secrets/tokens/credentials in the snapshot.
42+
- Keep this file local-only; it is intentionally git ignored.
43+
- Keep context to one line unless detail is strictly needed for handoff.
44+
45+
## Outputs
46+
- Updated `.agents/work-snapshot.local.md` with fresh branch/issue/PR/status metadata and timestamp.
47+
- Short manual notes suitable for quick resume.

0 commit comments

Comments
 (0)