chore(tooling): add Cursor skills for GitHub setup and git/PR workflow#53
chore(tooling): add Cursor skills for GitHub setup and git/PR workflow#53Kneesal wants to merge 4 commits intoJesusFilm:mainfrom
Conversation
Co-authored-by: Cursor <cursoragent@cursor.com>
WalkthroughAdds two new Cursor skill docs for GitHub setup and an issue-first Git/PR workflow, and tightens GitHub workflow rules to require the Bounded Context issue template and assigning PRs to the authenticated user during PR creation. Changes
Sequence Diagram(s)(omitted — documentation and rule tweaks only; no new multi-component runtime control flow introduced) Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.cursor/skills/forge-git-issues-prs/SKILL.md:
- Around line 62-64: The snippet currently offers "git reset --hard
upstream/main" as an "or:" alternative to "git merge upstream/main" without
warning; update the SKILL.md text to add a clear caution before the git reset
command stating it will irreversibly discard all uncommitted and untracked local
changes, and instruct readers to commit or stash changes (or use merge) if they
want to preserve work; change the phrasing around "git reset --hard
upstream/main" from a casual "or:" to an explicit conditional like "Only use git
reset --hard upstream/main if you intend to discard local changes" and
optionally suggest safer alternatives (commit, stash, or merge).
- Line 8: Update the wording in SKILL.md so it clearly states that `gh-workflow`
is a Cursor rule (not a skill) — replace the phrase "Use with the mandatory
workflow in `forge-workflow` and `gh-workflow`" with something like "Use with
the mandatory workflow in `forge-workflow` and the Cursor rule `gh-workflow`" to
avoid agents searching for `gh-workflow` as a skill; keep the mention of
`forge-workflow` as-is.
In @.cursor/skills/github-setup-forge/SKILL.md:
- Around line 37-38: Replace the recommendation to use the insecure
"credential.helper store" with guidance to use the OS-native, secure credential
helpers instead; update the SKILL.md text (the line that currently suggests "git
config --global credential.helper store") to recommend using
platform-appropriate helpers (e.g., credential manager on Windows, osxkeychain
on macOS, libsecret/gnome-keyring on Linux) and explain that these keep the PAT
encrypted and managed by the OS rather than writing it to ~/.git-credentials in
plaintext.
…ub setup Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
.cursor/skills/forge-git-issues-prs/SKILL.md (1)
16-39:--templateis a no-op when--bodyis also specified in non-interactive mode.Underlying gh CLI code shows issue templates are matched by template name, so
"Bounded Context Work Item"is the correct value for--template. However, when--bodyis also provided, the CLI uses the supplied body directly and skips template pre-population entirely.This means the YAML form's required-field enforcement (which only applies in the GitHub web UI) is bypassed. The command still creates a correctly structured issue because
--bodymanually replicates the template's structure, but--templatecould be dropped from the non-interactive invocation to avoid implying template validation is enforced.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.cursor/skills/forge-git-issues-prs/SKILL.md around lines 16 - 39, The gh issue create invocation in the SKILL.md snippet uses both --template "Bounded Context Work Item" and --body, but the gh CLI ignores --template when --body is provided; update the example to either remove --template when using a non-interactive --body or remove --body to allow template-driven pre-population/validation (i.e., edit the gh issue create command shown in the snippet so it does not pass both --template and --body simultaneously).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.cursor/skills/github-setup-forge/SKILL.md:
- Line 43: There’s a markdownlint MD038 violation: a code span on the given line
contains leading/trailing spaces; open
.cursor/skills/github-setup-forge/SKILL.md, locate the inline code span on the
reported line (the backtick-delimited `...` segment) and remove any space
immediately after the opening backtick or before the closing backtick so the
span is `code` with no extra spaces.
- Line 46: Replace the problematic prompt that asks users to paste a GitHub
Personal Access Token into the chat with guidance that instructs users to set
the GITHUB_TOKEN environment variable or to run gh auth login --with-token
(reading the token from their local terminal stdin) instead; locate and edit the
sentence starting with "Ask the user: 'GitHub needs a Personal Access Token for
push...'" in SKILL.md and swap it for wording that directs them to export
GITHUB_TOKEN or use gh auth login --with-token so tokens are entered only in
their own terminal, not pasted into the chat.
- Line 51: The current check uses a destructive probe ("git push origin main")
which can push local commits; change it to a non-destructive check instead:
replace the "git push origin main" probe with a dry-run push ("git push
--dry-run origin main") or an alternative read-only check such as "git ls-remote
--heads origin main" or "gh repo fork --remote=true --dry-run" so you never
perform a real write; update the SKILL.md text and examples that mention "git
push origin main" to recommend the dry-run or ls-remote approach.
---
Duplicate comments:
In @.cursor/skills/forge-git-issues-prs/SKILL.md:
- Around line 62-64: The documentation currently suggests "git reset --hard
upstream/main" as an "or" alternative to "git merge upstream/main"; remove this
unsafe suggestion or replace it with a clear warning: either delete the "git
reset --hard upstream/main" line or keep it but add an explicit caution and
prerequisite (e.g., warn it will discard uncommitted/local commits and instruct
to use only if you have no local work or have stashed/saved changes). Update the
SKILL.md snippet around the commands "git merge upstream/main" and "git reset
--hard upstream/main" accordingly so readers are not encouraged to run a
destructive command without an explicit warning.
- Line 8: Update the SKILL.md text so it no longer treats gh-workflow as a
skill: change any phrasing that calls "gh-workflow" a skill to say it is a
Cursor rule (e.g., "gh-workflow is a Cursor rule"), and correct any location
hints or references that would make agents look under skills (leave
forge-workflow as a skill reference if correct). Search for occurrences of
"gh-workflow" and update those lines in SKILL.md to reference its rule semantics
and the rules directory rather than the skills directory.
In @.cursor/skills/github-setup-forge/SKILL.md:
- Line 47: The guidance recommending `git config --global credential.helper
store` must be changed because it writes tokens in plaintext; update the
SKILL.md line that currently reads "Ensure remote is HTTPS. To cache token: `git
config --global credential.helper store`; the next push will prompt and store
it." to instead warn that `credential.helper store` persists credentials in
plaintext and propose secure alternatives such as using the system credential
manager (e.g., `credential.helper manager-core` / Git Credential Manager) or
`credential.helper cache` for short-term caching, and show how to use a personal
access token with those secure helpers; keep the HTTPS reminder and replace the
insecure `store` recommendation with the secure options and a short warning
about plaintext storage.
---
Nitpick comments:
In @.cursor/skills/forge-git-issues-prs/SKILL.md:
- Around line 16-39: The gh issue create invocation in the SKILL.md snippet uses
both --template "Bounded Context Work Item" and --body, but the gh CLI ignores
--template when --body is provided; update the example to either remove
--template when using a non-interactive --body or remove --body to allow
template-driven pre-population/validation (i.e., edit the gh issue create
command shown in the snippet so it does not pass both --template and --body
simultaneously).
…kill - Use GITHUB_TOKEN or gh auth login --with-token instead of pasting token in chat - Use git push --dry-run for non-destructive write-access check Co-authored-by: Cursor <cursoragent@cursor.com>
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.cursor/skills/forge-git-issues-prs/SKILL.md:
- Around line 110-111: The example gh pr create commands that pass newlines as
literal `\n` inside double-quoted --body strings should be changed so the PR
body contains real newlines; update the examples that show `gh pr create ...
--body "Resolves `#52`\n\n## Summary\n\n..."` to either use ANSI C quoting (e.g.,
the shell $'...' form) or to write the body to a temporary file and use
`--body-file` (as shown in the guidance) so the body renders correctly; ensure
the examples reference the exact command patterns (`gh pr create --base main
--assignee `@me` --title ... --body ...` and the alternative `gh pr create --base
main --assignee `@me` --title ... --body-file ...`) so readers can find and
replace the offending usages.
- Around line 16-38: The suggested gh command is invalid because gh issue create
does not apply YAML issue forms (bounded-context.yml) via --template and also
rejects using --template together with --body; fix by removing --template when
you want to pass the full issue text via --body (use gh issue create --title ...
--body "...") or, if you need the YAML issue form, open the web flow with gh
issue create --web to select the "Bounded Context Work Item" form; adjust any
documentation/examples to reference bounded-context.yml as web-only and avoid
combining --template and --body.
In @.cursor/skills/github-setup-forge/SKILL.md:
- Line 46: The guidance currently recommends `echo YOUR_TOKEN | gh auth login
--with-token`, which can leak secrets into shell history; update the SKILL.md
text to remove that literal echo example and replace it with safer alternatives:
prefer the `gh auth login --web` browser flow, or show a `read -s` interactive
pattern (prompt user to enter token silently and pipe to `gh auth login
--with-token`) or advise setting GITHUB_TOKEN via a secure shell method, and
update the user prompt ("Tell me when you've done one of these.") to reference
these safer options; ensure the changed text replaces the exact command mention
(`echo YOUR_TOKEN | gh auth login --with-token`) and includes brief instructions
for each alternative.
---
Duplicate comments:
In @.cursor/skills/forge-git-issues-prs/SKILL.md:
- Line 62: Update the guidance that presents "git reset --hard upstream/main" as
an alternative to "git merge" by adding a clear, prominent destructive-data-loss
warning adjacent to that command; specifically, annotate the "git reset --hard
upstream/main" line to state that it will irreversibly discard uncommitted local
changes (recommend suggesting to stash or commit first and offering the safer
"git merge upstream/main" as default), so readers see the risk and recommended
mitigations immediately next to the command.
- Line 8: Update the documentation so that the reference to "gh-workflow" is
labeled as a Cursor rule (not a skill) and clarify lookup behavior: change the
phrase that treats both "forge-workflow" and "gh-workflow" as skills to
explicitly call out "gh-workflow" as a rule, add a short note describing where
agents should resolve rules vs skills, and adjust any example references in
SKILL.md (e.g., the line mentioning forge-workflow and gh-workflow) to prevent
agents from searching for "gh-workflow" under the skills registry.
In @.cursor/skills/github-setup-forge/SKILL.md:
- Line 47: The guidance currently suggests `git config --global
credential.helper store`, which writes plaintext tokens to ~/.git-credentials;
update the SKILL.md note that `credential.helper store` is insecure and instead
recommend using OS-native helpers (e.g., credential-manager/manager-core on
Windows, osxkeychain on macOS, or libsecret/gnome-keyring on Linux) and show
`git config --global credential.helper <helper>` as the preferred approach,
keeping `store` described only as a last-resort fallback and explicitly mention
the plaintext risk for ~/.git-credentials.
| ```bash | ||
| gh issue create --template "Bounded Context Work Item" --title "type(scope): description" --body "## Background | ||
|
|
||
| [Why this is needed] | ||
|
|
||
| ## Expected outcome | ||
|
|
||
| [Clear, testable outcome] | ||
|
|
||
| ## Acceptance criteria | ||
|
|
||
| - [ ] Criterion 1 | ||
| - [ ] Criterion 2 | ||
|
|
||
| ## Possible solution(s) | ||
|
|
||
| 1. Option A - ... | ||
| 2. Option B - ... | ||
|
|
||
| ## References | ||
|
|
||
| - Link to doc | ||
| - Related issue #N" |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Find bounded-context.yml file
fd -type f -name "*bounded-context*"Repository: JesusFilm/forge
Length of output: 229
🏁 Script executed:
#!/bin/bash
# If found, check the format and beginning of the file
find . -name "*bounded-context*" -type f -exec head -20 {} + 2>/dev/nullRepository: JesusFilm/forge
Length of output: 551
🌐 Web query:
gh issue create --template YAML issue forms support GitHub CLI
💡 Result:
gh issue create --template/-T does not support GitHub “issue forms” (YAML) templates. The --template flag only applies to templates that provide starting body text (i.e., the classic Markdown-based issue templates), not YAML form schemas. [1], [3]
YAML issue forms (.github/ISSUE_TEMPLATE/*.yml|*.yaml) are meant for the web “New issue” flow; when submitted, GitHub converts the form answers into Markdown in the created issue body. [2]
Workarounds
- Use the web form via CLI:
gh issue create --web(then pick the YAML form in the browser). [1] - Convert/maintain a Markdown issue template for CLI use (or generate the issue body yourself and pass it with
--body/--body-file). [1], [3]
Sources:
[1] GitHub CLI manual: gh issue create (options include --template and --web)
[2] GitHub Docs: Syntax for issue forms (YAML forms; responses converted to Markdown)
[3] GitHub Community discussion noting YAML templates don’t show up for gh issue create -T
🌐 Web query:
gh issue create --body overrides --template behavior
💡 Result:
gh issue create does not let --body (or --body-file) “override” an issue --template.
- If you pass
--templateand--body/--body-file,ghexits with an error: “--templateis not supported when using--bodyor--body-file”. [1] --templateis only used as starting body text whenghis going to collect/edit the body interactively (prompt flow) or when using--editorwith no explicit body provided. [1][2]
So the behavior is effectively:
- Non-interactive body provided (
--body/--body-file) → template is disallowed. [1] - No body provided → template can prefill the body for you to edit/submit. [1][2]
Sources:
[1] cli/cli source (pkg/cmd/issue/create/create.go) showing the explicit incompatibility check and how template content is applied only when Body == "".
[2] GitHub CLI manual page for gh issue create describing --template as “starting body text.”
gh issue create --template does not support YAML issue forms and cannot be used with --body.
Two distinct problems with the suggested command:
-
YAML issue forms are unsupported.
gh issue createdoes not work with YAML issue form files —--templateonly applies to classic Markdown-based templates. Sincebounded-context.ymlis a YAML issue form,gh issue create --template "Bounded Context Work Item"will not detect or use the template. YAML issue forms are designed for the web "New issue" flow only. -
--templateand--bodyare mutually exclusive. When both flags are supplied,gh issue createexits with an error: "--templateis not supported when using--bodyor--body-file". You cannot use them together.
The recommended approach for CLI usage is to omit --template and provide the full body manually via --body:
✏️ Suggested fix
-```bash
-gh issue create --template "Bounded Context Work Item" --title "type(scope): description" --body "## Background
-...
-```
+```bash
+# Note: gh issue create does not support YAML issue forms (bounded-context.yml).
+# Supply the body manually matching the template structure:
+gh issue create \
+ --title "type(scope): description" \
+ --body "## Background
+
+[Why this is needed]
+
+## Expected outcome
+
+[Clear, testable outcome]
+
+## Acceptance criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Possible solution(s)
+
+1. Option A - ...
+2. Option B - ...
+
+## References
+
+- Link to doc
+- Related issue `#N`"
+```
+
+**Via web (recommended for YAML forms):** Use `gh issue create --web` to open the browser, then select **Bounded Context Work Item** from the template picker — the YAML form is fully supported there.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ```bash | |
| gh issue create --template "Bounded Context Work Item" --title "type(scope): description" --body "## Background | |
| [Why this is needed] | |
| ## Expected outcome | |
| [Clear, testable outcome] | |
| ## Acceptance criteria | |
| - [ ] Criterion 1 | |
| - [ ] Criterion 2 | |
| ## Possible solution(s) | |
| 1. Option A - ... | |
| 2. Option B - ... | |
| ## References | |
| - Link to doc | |
| - Related issue #N" |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.cursor/skills/forge-git-issues-prs/SKILL.md around lines 16 - 38, The
suggested gh command is invalid because gh issue create does not apply YAML
issue forms (bounded-context.yml) via --template and also rejects using
--template together with --body; fix by removing --template when you want to
pass the full issue text via --body (use gh issue create --title ... --body
"...") or, if you need the YAML issue form, open the web flow with gh issue
create --web to select the "Bounded Context Work Item" form; adjust any
documentation/examples to reference bounded-context.yml as web-only and avoid
combining --template and --body.
| - **Direct push (write access):** `gh pr create --base main --assignee @me --title "type(scope): description" --body "Resolves #52\n\n## Summary\n\n...\n\n## Contracts Changed\n\n- [ ] yes\n- [x] no\n\n## Regeneration Required\n\n- [ ] yes\n- [x] no\n\n## Validation\n\n- [ ] ..."` | ||
| - **From fork:** `gh pr create --repo JesusFilm/forge --base main --head USERNAME:feat/52-short-slug --assignee @me --title "type(scope): description" --body "Resolves #52\n\n## Summary\n\n...\n\n## Contracts Changed\n\n...\n\n## Regeneration Required\n\n...\n\n## Validation\n\n..."` |
There was a problem hiding this comment.
\n escape sequences in double-quoted --body strings produce literal \n characters in most shells, not newlines.
In bash/zsh, \n inside "..." is passed verbatim; the PR/issue body will contain the literal string \n\n## Summary rather than blank lines and a header. Anyone who copies and runs these commands will get a malformed description.
✏️ Preferred approach: use ANSI C quoting or a body file
-`gh pr create --base main --assignee `@me` --title "type(scope): description" --body "Resolves `#52`\n\n## Summary\n\n...\n\n## Contracts Changed\n\n- [ ] yes\n- [x] no\n\n## Regeneration Required\n\n- [ ] yes\n- [x] no\n\n## Validation\n\n- [ ] ..."`
+`gh pr create --base main --assignee `@me` --title "type(scope): description" --body $'Resolves `#52`\n\n## Summary\n\n...\n\n## Contracts Changed\n\n- [ ] yes\n- [x] no\n\n## Regeneration Required\n\n- [ ] yes\n- [x] no\n\n## Validation\n\n- [ ] ...'`Or write the body to a temp file and use --body-file:
cat > /tmp/pr_body.md << 'EOF'
Resolves `#52`
## Summary
...
EOF
gh pr create --base main --assignee `@me` --title "type(scope): description" --body-file /tmp/pr_body.md📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - **Direct push (write access):** `gh pr create --base main --assignee @me --title "type(scope): description" --body "Resolves #52\n\n## Summary\n\n...\n\n## Contracts Changed\n\n- [ ] yes\n- [x] no\n\n## Regeneration Required\n\n- [ ] yes\n- [x] no\n\n## Validation\n\n- [ ] ..."` | |
| - **From fork:** `gh pr create --repo JesusFilm/forge --base main --head USERNAME:feat/52-short-slug --assignee @me --title "type(scope): description" --body "Resolves #52\n\n## Summary\n\n...\n\n## Contracts Changed\n\n...\n\n## Regeneration Required\n\n...\n\n## Validation\n\n..."` | |
| - **Direct push (write access):** `gh pr create --base main --assignee `@me` --title "type(scope): description" --body $'Resolves `#52`\n\n## Summary\n\n...\n\n## Contracts Changed\n\n- [ ] yes\n- [x] no\n\n## Regeneration Required\n\n- [ ] yes\n- [x] no\n\n## Validation\n\n- [ ] ...'` | |
| - **From fork:** `gh pr create --repo JesusFilm/forge --base main --head USERNAME:feat/52-short-slug --assignee `@me` --title "type(scope): description" --body $'Resolves `#52`\n\n## Summary\n\n...\n\n## Contracts Changed\n\n...\n\n## Regeneration Required\n\n...\n\n## Validation\n\n...'` |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.cursor/skills/forge-git-issues-prs/SKILL.md around lines 110 - 111, The
example gh pr create commands that pass newlines as literal `\n` inside
double-quoted --body strings should be changed so the PR body contains real
newlines; update the examples that show `gh pr create ... --body "Resolves
`#52`\n\n## Summary\n\n..."` to either use ANSI C quoting (e.g., the shell $'...'
form) or to write the body to a temporary file and use `--body-file` (as shown
in the guidance) so the body renders correctly; ensure the examples reference
the exact command patterns (`gh pr create --base main --assignee `@me` --title ...
--body ...` and the alternative `gh pr create --base main --assignee `@me` --title
... --body-file ...`) so readers can find and replace the offending usages.
|
|
||
| **Option C – HTTPS + token** | ||
|
|
||
| - **Ask the user:** "Create a Personal Access Token at https://github.com/settings/tokens (scope `repo`). Do not paste the token into the chat. Instead, in your terminal either (1) run `echo YOUR_TOKEN | gh auth login --with-token` so the token is read from stdin, or (2) set `export GITHUB_TOKEN=your_token` in your shell. Tell me when you've done one of these." Alternatively they can run one `git push` and enter the token when prompted (token stays in their terminal). |
There was a problem hiding this comment.
echo YOUR_TOKEN | gh auth login --with-token leaks the token into shell history.
Any literal token the user substitutes for YOUR_TOKEN will be recorded in ~/.bash_history / ~/.zsh_history. Prefer the --web browser flow or a read -s pattern that suppresses echo:
🔒 Safer alternatives
-**Ask the user:** "Create a Personal Access Token at https://github.com/settings/tokens (scope `repo`). Do not paste the token into the chat. Instead, in your terminal either (1) run `echo YOUR_TOKEN | gh auth login --with-token` so the token is read from stdin, or (2) set `export GITHUB_TOKEN=your_token` in your shell. Tell me when you've done one of these."
+**Ask the user:** "Create a Personal Access Token at https://github.com/settings/tokens (scope `repo`). Do not paste the token into the chat. In your own terminal, use one of these options (all avoid shell-history exposure):
+- (1) Browser flow (recommended): `gh auth login` and follow the prompts.
+- (2) Silent read: `read -s GH_TOKEN && echo "$GH_TOKEN" | gh auth login --with-token`
+- (3) Token file: save the token to a temp file and run `gh auth login --with-token < token.txt`, then delete the file.
+Avoid `echo <token> | ...` or `export GITHUB_TOKEN=<token>` as both are captured by shell history."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.cursor/skills/github-setup-forge/SKILL.md at line 46, The guidance
currently recommends `echo YOUR_TOKEN | gh auth login --with-token`, which can
leak secrets into shell history; update the SKILL.md text to remove that literal
echo example and replace it with safer alternatives: prefer the `gh auth login
--web` browser flow, or show a `read -s` interactive pattern (prompt user to
enter token silently and pipe to `gh auth login --with-token`) or advise setting
GITHUB_TOKEN via a secure shell method, and update the user prompt ("Tell me
when you've done one of these.") to reference these safer options; ensure the
changed text replaces the exact command mention (`echo YOUR_TOKEN | gh auth
login --with-token`) and includes brief instructions for each alternative.
|
moving to gh mcp instead of skills |
Resolves #52
Summary
Add two Cursor skills under
.cursor/skills/:github-setup-forge(guides users through GitHub env setup: git identity, SSH/HTTPS auth, fork vs direct push) andforge-git-issues-prs(teaches the agent how to create issues, branch, commit, open PRs, and link issues with Resolves #N). Enables contributors and agents to follow the issue-first workflow.Contracts Changed
Regeneration Required
Validation
Made with Cursor
Summary by CodeRabbit