From gh
Initialize GitHub workspace to enable context enrichment for all GitHub operations. This skill should be used when: setting up a new workspace, first-time configuration, config.yaml is missing, or "workspace not initialized" errors occur. Trigger phrases: "initialize workspace", "setup GitHub", "first time setup", "init pulse-gh", "configure workspace", "cache project IDs", "workspace not initialized", "start github plugin", "get github working", "new workspace setup", "bootstrap github", "prepare github workspace", "github init", "enable project linking", "setup issue enrichment". Verifies gh CLI, jq, yq tools and authentication. Discovers projects and caches field IDs so issues/PRs can be automatically linked to projects. Run once per repository.
How this skill is triggered — by the user, by Claude, or both
Slash command
/gh:gh-initThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
One-time setup that enables context enrichment for all GitHub operations. Without this initialization,
One-time setup that enables context enrichment for all GitHub operations. Without this initialization, issues and PRs created are orphans with no project linking.
{PLUGIN_ROOT} = Plugin root directory (where plugin.json lives)
When this skill references files like {PLUGIN_ROOT}/lib/patterns/config-parsing.md,
read from the plugin root, not relative to this skill folder.
| Does | Does NOT |
|---|---|
| Verify CLI tools (gh, jq, yq) | Execute GitHub operations |
| Validate authentication and scopes | Refresh stale configs |
| Detect workspace from git or user input | Fetch views/automations/teams |
| Discover and cache project IDs | Build extended configs |
| Create config.yaml + user.yaml | Modify GitHub resources |
| Create workflows directory and install templates | Run workflows |
| Set up heartbeat logging directory | Configure advanced workflow options |
1. CONTEXT → 2. PREREQS → 3. INPUT → 4. DISCOVER → 5. CACHE → 5.5 HEARTBEAT → 5.7 HEALTHCHECK → 6. VERIFY
(detect) (tools) (confirm) (projects) (write) (workflows) (optional) (done)
│ │ │ │ │ │ │ │
STOP if STOP if STOP for STOP for - STOP for STOP for STOP: offer
ambiguous missing user OK selection template select user choice refresh/ops
Goal: Detect the GitHub workspace (organization or user) from context.
See: {PLUGIN_ROOT}/lib/patterns/workspace-detection.md
IMPORTANT: Before initializing, check if config already exists in current or parent directory:
if [[ -f ".hiivmind/github/config.yaml" ]]; then
echo "Config found in current directory"
EXISTING_CONFIG=".hiivmind/github/config.yaml"
elif [[ -f "../.hiivmind/github/config.yaml" ]]; then
echo "Config found in parent directory"
EXISTING_CONFIG="../.hiivmind/github/config.yaml"
fi
CRITICAL — NEVER delete a .hiivmind/ directory. It is a shared namespace used by multiple plugins (github, corpus, etc.). Only .hiivmind/github/ is managed by this plugin. The .hiivmind/ directory may contain configurations for other plugins besides this one.
If config exists in parent:
Found existing workspace config in parent directory: ../.hiivmind/github/config.yaml
This is common for workspace setups where multiple repos share one config.
Options:
1. Symlink to parent (recommended for workspace setup)
2. Create local config for this repo only
3. Re-initialize parent config
4. Do nothing (use parent config via relative path resolution)
Which would you like? [1/2/3/4]
Option 1 implementation (symlink to parent):
# If .hiivmind/github already exists locally, back it up
if [[ -d ".hiivmind/github" && ! -L ".hiivmind/github" ]]; then
mv .hiivmind/github .hiivmind/github.bak
fi
mkdir -p .hiivmind
ln -sfn ../.hiivmind/github .hiivmind/github
This creates a symlink at .hiivmind/github pointing to ../.hiivmind/github, preserving any other content in the local .hiivmind/ directory (e.g., corpus configs). After symlinking, verify with ls -la .hiivmind/github and confirm it points to the parent. Then skip to Phase 6 (VERIFY).
Option 2: Proceed with normal initialization — creates a separate .hiivmind/github/config.yaml in this repo.
Option 3: Use $EXISTING_CONFIG path and re-run discovery against it, overwriting the parent config.
Option 4: Do nothing — other skills already resolve config from parent directories via relative path. Skip to Phase 6 (VERIFY).
If context is ambiguous (not in git repo, no remote, multiple remotes):
I couldn't detect a GitHub workspace from git context.
Please specify the GitHub organization or username to initialize:
Never auto-decide on workspace target. Always confirm with user.
Goal: Verify required tools and authentication.
See: {PLUGIN_ROOT}/lib/patterns/tool-detection.md
See: {PLUGIN_ROOT}/lib/patterns/authentication.md
repo, read:org, project, read:projectIf tools missing:
Missing required tools: [list]
Install instructions:
- gh: https://cli.github.com/
- jq: apt install jq / brew install jq
- yq: https://github.com/mikefarah/yq#install
If not authenticated:
gh CLI is not authenticated.
Run: gh auth login
If scopes missing:
Missing required scopes: [list]
Run: gh auth refresh --scopes 'repo,read:org,project,read:project'
Goal: Confirm workspace with user before proceeding.
Present detected workspace and ask for confirmation:
Detected workspace:
Owner: hiivmind
Type: organization
Source: git remote (origin)
Is this the workspace you want to initialize? [Y/n]
Wait for user confirmation before proceeding. If user says no, ask them to specify the correct workspace.
Goal: Discover projects and their field configurations.
Read Routing Guide
{PLUGIN_ROOT}/lib/references/api-routing.mdprojectsV2, organization, userExecute Query
{PLUGIN_ROOT}/lib/patterns/corpus-lookup.md){PLUGIN_ROOT}/lib/patterns/graphql-execution.mdIf uncertain about projectsV2 query syntax:
hiivmind-corpus-github-docs-navigateAfter discovering projects:
Found 3 projects:
1. Feature Planner (open) - 5 fields
2. Bug Tracker (open) - 4 fields
3. Archive (closed) - 3 fields
Which projects should I cache? [1,2 / all / none]
After selection:
Set default project for operations?
1. Feature Planner
2. Bug Tracker
[number / none]
Goal: Write configuration files.
See: {PLUGIN_ROOT}/lib/patterns/config-parsing.md
.hiivmind/github/ directoryconfig.yaml with:
user.yaml with authenticated user infofreshness.yaml with section timestamps.gitignore to exclude user.yaml.claude/settings.json with marketplace dependencyCreate or update .claude/settings.json to declare the hiivmind-pulse-gh marketplace as a recommended dependency:
{
"extraKnownMarketplaces": {
"hiivmind-pulse-gh": {
"source": {
"source": "github",
"repo": "hiivmind/gh"
}
}
},
"enabledPlugins": {
"hiivmind-pulse-gh@hiivmind-pulse-gh": true
}
}
Why this matters:
If .claude/settings.json exists:
extraKnownMarketplaces entry (preserve existing entries)enabledPlugins entry (preserve existing plugins)If file doesn't exist:
.claude/ directoryCopy the freshness template and stamp initial timestamps:
cp "{PLUGIN_ROOT}/templates/freshness.yaml.template" ".hiivmind/github/freshness.yaml"
Then update with current timestamp:
{{initialized_at}} in the header comment with the current ISO 8601 timestampcache.created_at to current timestampcache.last_updated_at to current timestampsections.workspace.last_checked to current timestamp (just discovered)sections.workspace.stale to falsesections.projects.last_checked to current timestamp (just discovered)sections.projects.stale to falsesections.repositories.last_checked to current timestamp (just discovered)sections.repositories.stale to falseAll other sections remain stale: true with last_checked: null until explicitly refreshed.
| File | Purpose | Git Status |
|---|---|---|
.hiivmind/github/config.yaml | Workspace config (shared) | Committed |
.hiivmind/github/user.yaml | User identity (personal) | Gitignored |
.hiivmind/github/freshness.yaml | Staleness tracking | Committed |
.claude/settings.json | Plugin dependencies | Committed |
.hiivmind/github/workflows/*.yaml | Heartbeat workflow configs | Committed |
.hiivmind/github/log/ | Heartbeat run logs | Gitignored |
Goal: Set up the heartbeat workflow system so event-driven automation is active from first session.
.hiivmind/github/workflows/ directory.hiivmind/github/log/ directory.hiivmind/github/log/ to .gitignorePresent workflow templates:
The heartbeat runs on every session start and can detect changes.
Install workflow templates? These control what the heartbeat monitors.
1. auto-refresh — Refresh config when sections go stale (recommended)
2. pr-lifecycle — Summarize open PRs on session start
3. issue-triage — Flag untriaged issues
4. ci-monitor — Check CI/CD run status
5. stale-check — Flag stale PRs/issues
6. release-monitor — Notify on new releases
7. dependabot-alerts — Flag open security vulnerabilities
8. deploy-monitor — Track deployment status changes
9. project-sync — Detect project board changes
Which templates to install? [1 / 1,2,3 / all / none]
{PLUGIN_ROOT}/templates/workflows/ to .hiivmind/github/workflows/poll-state.yaml is self-bootstrapped by heartbeat on first run — no action neededGoal: Offer a governance healthcheck for newly initialized workspaces. Non-blocking.
After heartbeat setup, offer to run the healthcheck:
Would you like to run a governance healthcheck?
This assesses repository maturity across:
- Security (branch protection, security policy, dependabot, secrets scanning)
- Governance (project linkage, triage labels, CODEOWNERS)
- Automation (CI/CD, releases)
- Documentation (README, LICENSE)
Run healthcheck now? [Y/n]
Invoke skill: hiivmind-pulse-gh:gh-healthcheck
After healthcheck completes, return to Phase 6 (VERIFY).
Skip — the user can run /gh healthcheck at any time.
Goal: Confirm initialization and offer next steps.
After successful init:
Initialization complete!
Workspace: hiivmind (organization)
Projects cached: 2
Default project: Feature Planner (#2)
Config files:
.hiivmind/github/config.yaml (shared)
.hiivmind/github/user.yaml (personal)
.hiivmind/github/freshness.yaml
.claude/settings.json (marketplace dependencies)
Heartbeat:
Workflows installed: 3 (auto-refresh, pr-lifecycle, ci-monitor)
Log directory: .hiivmind/github/log/
The hiivmind marketplace is now configured as a dependency.
Team members will be prompted to install it when they trust this repo.
Tip: To reduce approval prompts during heartbeat and operations,
add this to your .claude/settings.local.json allowlist:
"Edit(.hiivmind/github/**)"
This allows config, freshness, and workflow file edits without
manual approval each time.
What would you like to do next?
1. Run an operation (use /hiivmind-pulse-gh)
2. Fetch extended config (views, teams, automations)
3. Configure workflows (use /gh workflows)
4. Done for now
ls -la .hiivmind/github/
If config.yaml exists and is recent, workspace is already initialized.
To re-initialize (updates existing config):
/gh reinitialize workspace [owner]
All implementation details are in the examples library:
Introspection Examples (HEAVY):
| Example | Purpose |
|---|---|
{PLUGIN_ROOT}/lib/patterns/tool-detection.md | Check for gh, jq, yq |
{PLUGIN_ROOT}/lib/patterns/authentication.md | Verify auth and scopes |
{PLUGIN_ROOT}/lib/patterns/workspace-detection.md | Detect org/user from context |
{PLUGIN_ROOT}/lib/patterns/graphql-execution.md | Execute queries via temp file |
{PLUGIN_ROOT}/lib/patterns/config-parsing.md | Read/write YAML config |
Operations Examples (LIGHT):
| Example | Purpose |
|---|---|
{PLUGIN_ROOT}/lib/references/api-routing.md | API routing decisions (canonical source) |
{PLUGIN_ROOT}/lib/patterns/corpus-lookup.md | Look up API syntax when uncertain |
External Resources:
| Resource | Purpose |
|---|---|
hiivmind-corpus-github-docs-navigate | GitHub corpus skill for syntax lookup |
npx claudepluginhub hiivmind/hiivmind-pulse-gh --plugin ghInitializes and configures projects: detects tech stacks, scaffolds new apps, creates task files, sets branch strategies, handles git submodules, exports to other AI platforms.
Configures GitHub repository via gh CLI with main branch protection rules, issue/PR templates, standard labels, .gitignore, and metadata. For new or existing professional projects.
Interactive wizard that generates or updates the Automation Config block in CLAUDE.md, with template support for popular stacks and version-aware migration.