github

name	github
description	GitHub conventions for SimpleApps. Covers org structure, git safety, issue creation, PR workflows, and gh CLI usage. Use when creating issues, PRs, or working with GitHub repos.
allowed-tools	["Skill(project-defaults)","Skill(git-safety)","Read","Bash"]

First, use Skill("project-defaults") to load the project layout and Skill("git-safety") to load git guardrails.

GitHub

Organization

All SimpleApps repos live under simpleapps-com. Pattern: simpleapps-com/<repo-name>

Authentication

gh auth status          # Check auth
gh auth setup-git       # Fix git credential helper (run if push fails 401/403)

Project Layout

See simpleapps:project-defaults for the full directory layout, symlink setup, and permission defaults. Key point: the git repo is always at repo/. Use git -C repo for git operations from the project root.

Wiki

See simpleapps:wiki for wiki conventions, token budget, and maintenance rules.

Git Safety

See simpleapps:git-safety (loaded above). MUST NOT commit, push, create PRs, or merge unless the user explicitly asks.

Git Commands (no cd)

cd is denied. MUST use git -C repo for all git operations. For multi-line commit messages, write the message to the project-level tmp/ (sibling of repo/, NEVER repo/tmp/) and use git commit -F:

# Stage files
git -C repo add path/to/file.md

# Write the commit message with the Write tool (not echo/cat) to the
# project-level tmp/ (sibling of repo/):
# → tmp/commit-msg.txt

# Commit. NOTE: `git -C repo` resolves -F relative to repo/, so reference
# the project-level file as ../tmp/, NOT tmp/ (that would be repo/tmp/):
git -C repo commit -F ../tmp/commit-msg.txt

# Clean up
rm tmp/commit-msg.txt

This avoids shell quoting issues with HEREDOCs and cd permission blocks. The Write tool creates the tmp file safely. Keep scratch files in the project-level tmp/ (never repo/tmp/) so git add cannot sweep them into a commit.

Issues

MUST use --repo simpleapps-com/<repo> on every gh call. MUST ask the user which repo. Never assume.

MUST NOT use $() or inline content in gh commands. Any gh command that needs a body, comment, or multi-line text MUST use the file-based flag (--body-file, --comment-file, etc.). Write the content to tmp/ using the Write tool first, then pass the file path. This avoids $() command substitution which triggers a permission prompt every time. Delete the tmp file after the command succeeds.

Title

Conventional commit style: fix: description, feat: description, chore: description. Under 70 characters.

Body

## Problem
What is broken, missing, or needed?

## Expected Behavior
What SHOULD happen instead?

## Acceptance Criteria
- [ ] Concrete, testable criteria

## Context
Related issues, affected files, workarounds, reproduction steps.

Bug reports also include Steps to Reproduce and Current Behavior with error messages.

Commands

Write the body to tmp/issue-body.txt with the Write tool first, then:

gh issue create --repo simpleapps-com/<repo> --title "type: desc" --body-file tmp/issue-body.txt
gh issue list --repo simpleapps-com/<repo>
gh issue view <number> --repo simpleapps-com/<repo>
gh issue close <number> --repo simpleapps-com/<repo>

rm tmp/issue-body.txt after the create succeeds. There is no inline---body form of these commands in this project: the file-based flag is the only approved path.

For closing with a comment, use two calls (avoids $() permission prompts):

1. Write comment to tmp/issue-comment.txt using the Write tool
2. gh issue comment <number> --repo simpleapps-com/<repo> --body-file tmp/issue-comment.txt
3. gh issue close <number> --repo simpleapps-com/<repo>

Include Closes #N in commit body to auto-close issues.

Commenting on existing issues

Before adding a comment to a closed issue, check its state first with gh issue view. If the issue is closed but the problem still exists, reopen it with gh issue reopen before commenting. A comment on a closed issue is easily missed.

Cross-Repo Issues

Use /file-issue to automate this process. It creates the upstream issue, cross-links back to the local issue, and adds the blocked label. /triage surfaces blocked issues in its output.

When a project hits a blocker that depends on another team's repo, create two issues and keep working:

1. Local issue (in the site/project repo): describe the impact and what's blocked
2. Upstream issue (in the dependency repo): describe the ask, include reproduction steps or specifics
3. Cross-link: reference the other issue using simpleapps-com/repo#N syntax in both issue bodies
4. Don't block: continue with other tasks while waiting for the upstream fix

Target repos:

Dependency	Repo
Backend microservices	simpleapps-com/augur
Shared frontend packages	simpleapps-com/augur-packages
TypeScript API SDK	simpleapps-com/augur-api

Example cross-link in issue body: Upstream: simpleapps-com/augur#44 or Local impact: simpleapps-com/<site>#3

Pull Requests

gh pr create --repo simpleapps-com/<repo> --title "title" --body-file tmp/pr-body.txt
gh pr list --repo simpleapps-com/<repo>
gh pr view <number> --repo simpleapps-com/<repo>
gh pr merge <number> --repo simpleapps-com/<repo>

Write PR body to tmp/pr-body.txt using the Write tool first. MUST NOT use --body "$(cat ...)" or any $() substitution.

Cross-Linking with Basecamp

For client tasks originating in Basecamp, see simpleapps:workflow for the full cross-linking process.