Help us improve
Share bugs, ideas, or general feedback.
From hatch3r
Creates a project board structure (GitHub Projects V2, Azure Boards, or GitLab Issue Boards) with hatch3r taxonomy, configurable via quick/defaults mode.
npx claudepluginhub hatch3r/hatch3rHow this skill is triggered — by the user, by Claude, or both
Slash command
/hatch3r:hatch3r-board-initThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default...
Regenerates a live GitHub board overview dashboard from current state. Scans open issues, computes health metrics, and updates the meta:board-overview issue. Part of the hatch3r delivery pipeline.
Sets up a new project for AI-agent-driven management: generates OKR files, config blocks, and GitHub project + labels. Use when initializing a repo or connecting GitHub as a command center.
Guides technical evaluation of code review feedback: read fully, restate for understanding, verify against codebase, respond with reasoning or pushback before implementing.
Share bugs, ideas, or general feedback.
Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per agents/shared/user-question-protocol.md — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
hatch3r's board commands operate as the implementation orchestration layer above platform agentic workflows. While platform-native agentic workflows (GitHub Agentic Workflows, Azure DevOps automations, GitLab Auto DevOps) handle continuous automation (triage, testing, documentation), hatch3r's board commands orchestrate the full delivery pipeline:
Platform agentic workflows and hatch3r are complementary: use platform workflows for continuous background automation, use hatch3r board commands for structured delivery orchestration.
Read the hatch3r-board-shared skill at the start of the run. It contains Board Configuration, Platform Detection, Platform Context, Board Sync Procedure, and tooling directives. Cache all values for the duration of this run.
Follow the Token-Saving Directives in hatch3r-board-shared.
If the user requests quick mode, defaults mode, or passes a --quick or --defaults flag: use all auto-detected values without prompting and proceed directly to execution with a single confirmation. Specifically:
.hatch3r/hatch.json (skip ASK in 1.1).board.projectNumber is null (skip ASK in 1.2).{repo} Board as the project name (skip ASK in 1.2a).git rev-parse --abbrev-ref origin/HEAD (skip ASK in 1.2b).This command runs in two phases: Planning (collect all answers) then Execution (perform all mutations). No mutations occur until the user confirms the full plan.
Run BEFORE Phase 1. Halt on the first failure with an actionable fix command. Do not prompt for board configuration choices until every prerequisite below succeeds.
Run the shared Prerequisite Check. Execute the Prerequisite Check block in hatch3r-board-shared §"Prerequisite Check (run at the start of every board command)" — verifies .hatch3r/hatch.json exists, owner/repo configured, and platform CLI authenticated (gh auth status / az account show / glab auth status).
Verify platform credentials at the env-var layer. The shared prereq check confirms the CLI is authenticated; this step additionally verifies the underlying credential is present for non-interactive runs:
If platform is github:
Run gh auth status first. If the CLI is already authenticated with the project scope, the env var fallback is not required and this step passes.
If gh auth status fails or the project scope is missing, check for GITHUB_TOKEN (preferred for CI) or GH_TOKEN. If neither is set, ASK the user using the agents/shared/user-question-protocol.md plain-text fallback shape:
**Question:** GitHub CLI is not authenticated and no GITHUB_TOKEN is set. How should I obtain credentials?
1. Run `gh auth login` interactively now — opens the GitHub OAuth flow in your browser.
2. Provide a Personal Access Token here — paste a PAT with the `project` scope; I will set GITHUB_TOKEN for this session only.
3. Abort — exit and configure credentials externally; re-run `hatch3r-board-init` afterward.
Default if no response: 1
If platform is azure-devops:
az account show. If it fails, check for AZURE_DEVOPS_PAT. If neither is configured, ASK using the same plain-text fallback shape with options: (1) az login interactively, (2) provide AZURE_DEVOPS_PAT, (3) abort. Default: 1.If platform is gitlab:
glab auth status. If it fails, check for GITLAB_TOKEN. If neither is configured, ASK using the same plain-text fallback shape with options: (1) glab auth login interactively, (2) provide GITLAB_TOKEN, (3) abort. Default: 1.Verify owner/repo identity. Read .hatch3r/hatch.json and confirm both top-level owner/repo (or board.owner/board.repo as fallback) are set and non-empty. If either is empty, ASK using the user-question-protocol plain-text fallback shape:
**Question:** Owner/repo are not configured in `.hatch3r/hatch.json`. How should I capture them?
1. Provide owner and repo now — paste in this turn; I will write them to `.hatch3r/hatch.json` after Phase 1 confirmation.
2. Run `npx hatch3r config` first — abort, configure repo identity, then re-run `hatch3r-board-init`.
Default if no response: 1
Set pager-bypass env vars. Before the first CLI invocation, export GH_PAGER=cat and PAGER=cat per hatch3r-board-shared §"Pager-Bypass Directive". Required for reliable gh api --jq output capture.
Record prerequisite outcomes. Write each check's outcome (passed / failed-then-resolved / aborted) to the run cache errors entry so the end-of-run summary can surface auth-related warnings.
This step is mandatory and non-skippable. Quick / Defaults Mode (§"Quick / Defaults Mode" above) skips Phase 1 ASKs but does NOT skip Step 0 — credential and identity verification run unconditionally before any board mutation.
Collect all configuration choices upfront. No GitHub API calls or file writes in this phase (except reads needed to present options).
.hatch3r/hatch.json and cache the board config.platform from .hatch3r/hatch.json. Default to github if missing. Cache for the run.hatch3r-board-shared: Use top-level owner/repo first. Fall back to board.owner/board.repo if top-level values are empty.{owner}, repo={repo}, platform={platform}."ASK: "I need the owner/namespace and repository/project for this board. Please provide: (1) owner (org/namespace/username), (2) repo/project name."
Update the in-memory config with the provided values.
If platform is github:
board.projectNumber is already set in .hatch3r/hatch.json, default to B (Connect to existing project #{board.projectNumber}).board.projectNumber is null or missing, default to A (Create new).If platform is azure-devops:
board.projectNumber (repurposed as Azure DevOps project name) is set, default to B (Connect to existing Azure Boards project).If platform is gitlab:
board.projectNumber (repurposed as GitLab Board ID) is set, default to B (Connect to existing board).No separate prompt — the mode is included in the consolidated plan confirmation (Step 1.6) where the user can override it.
If mode is A (Create new), default the project name to {repo} Board.
If platform is azure-devops: Use the Azure DevOps project name. If the project already exists in the organization, skip creation and configure the board within the existing project.
No separate prompt — the project name is included in the consolidated plan confirmation (Step 1.6) where the user can override it.
git rev-parse --abbrev-ref origin/HEAD and strip the origin/ prefix. If the command fails (e.g., no remote configured), fall back to board.defaultBranch from .hatch3r/hatch.json, then to "main".board.defaultBranch and used by board-pickup (checkout, PR base) and other agents.No separate prompt — the detected branch is included in the consolidated plan confirmation (Step 1.6).
src/, packages/, apps/) for top-level directories that represent distinct areas (e.g., frontend, backend, api, infra, cli, docs). Exclude non-area directories (node_modules, .git, dist, build, .github, .hatch3r, coverage, __tests__).board.areas already has entries in .hatch3r/hatch.json, use those as the default and note the source.No separate prompt — area labels are included in the consolidated plan confirmation (Step 1.6).
Default to "no migration." If the user needs to migrate issues from an existing project, they can specify it when customizing the plan in Step 1.6.
No separate prompt — migration is included in the consolidated plan confirmation (Step 1.6).
A board overview issue (labeled meta:board-overview) will be created by default. No user prompt needed.
This is the single user-facing confirmation for the entire Planning phase. All auto-detected and defaulted values are presented here for the user to confirm or customize in one prompt.
Present the full plan summary:
Board Init Plan:
Platform: {platform} (github / azure-devops / gitlab)
Owner/Namespace:{owner}/{repo}
Default branch: {defaultBranch} (auto-detected via git / from hatch.json / default)
Mode: {A: Create new / B: Connect to #{N}} (auto-detected: {reason})
Project name: {project name, or "N/A" when Mode B}
Status options: Backlog, Ready, In Progress, In Review, Done
Label taxonomy: {count} labels/tags (types, executors, statuses, priorities, risks, meta)
Area labels: {auto-detected list or "none"} (source: {codebase scan / hatch.json / none})
Migration: {from Project #X / "none" (default)}
Board overview: yes (default)
ASK: "Here is the full board init plan with auto-detected values. Confirm to begin execution, or specify any settings to customize (e.g., 'change branch to master', 'add area: mobile', 'use existing project #5', 'migrate from project #3')."
Execute all planned mutations in sequence. No further questions unless a mutation fails.
--resume flag. When invoked with --resume, board-init checks board.workflows.itemClosedEnabled in .hatch3r/hatch.json. If true, Phase 2.1 through 2.5 are skipped (project, status field, labels, migration, config write-back have already succeeded) and execution jumps directly to the workflow verification gate (§2.2 step 6 above) for the GitHub platform, then proceeds to §2.6 (Create Board Overview Issue) on success. If the gate still fails, the command re-halts with the same actionable message. Non-GitHub platforms ignore --resume and run Phase 2 normally.
Platform-specific: Project creation/connection
If platform is github:
query { repository(owner: "{owner}", name: "{repo}") { id } }
Use the GitHub MCP graphql tool with owner: {board.owner}, repo: {board.repo}.{repo} Board):
mutation { createProjectV2(input: { ownerId: "<repo_owner_node_id>", title: "{project_name}" }) { projectV2 { id number } } }
The ownerId must be the owner's node ID (org or user), not the repository node ID. Fetch the owner node ID first if needed:
query { repositoryOwner(login: "{owner}") { id } }
id (node ID) and number from the response.query { user(login: "{owner}") { projectV2(number: {N}) { id number } } }
Use organization instead of user if the owner is an org. Try user first; if it fails, retry with organization.id and number.If platform is azure-devops:
az devops project show --org https://dev.azure.com/{namespace} --project {project}
az devops project create --org https://dev.azure.com/{namespace} --name "{project_name}" --source-control git --process Agile
az devops configure --defaults organization=https://dev.azure.com/{namespace} project={project}.board.projectNumber.az devops project show --org https://dev.azure.com/{namespace} --project {project}.If platform is gitlab:
glab repo view {namespace}/{project}
glab api projects/{project_id}/boards --method POST --field name="{project_name}"
Where {project_id} is the numeric GitLab project ID (obtain via glab api projects/{namespace}%2F{project} --jq '.id').board.projectNumber.glab api projects/{project_id}/boards --jq '.[].id'.Platform-specific: Status configuration
If platform is github:
Query the project's fields to find the "Status" single-select field:
query {
node(id: "<project_id>") {
... on ProjectV2 {
fields(first: 50) {
nodes {
... on ProjectV2SingleSelectField {
id name options { id name }
}
}
}
}
}
}
Look for a field named "Status" (case-insensitive match).
If no Status field exists, create one via the createProjectV2Field mutation with type SINGLE_SELECT.
Verify these status options exist on the field: Backlog, Ready, In Progress, In Review, Done.
updateProjectV2Field mutation (or the appropriate mutation for adding options to a single-select field) to add them.Capture the field ID and each option's ID.
Programmatic workflow verification (GitHub only): GitHub's GraphQL API does not expose a mutation to enable Projects V2 workflows (only deleteProjectV2Workflow is public), so this step verifies the required workflows exist and are enabled. If missing or disabled, the command halts with an actionable error and supports --resume.
a. Query active workflows:
query {
node(id: "<project_id>") {
... on ProjectV2 {
workflows(first: 20) {
nodes { id name enabled }
}
}
}
}
b. Required workflows:
name == "Item closed" with enabled == truename == "Pull request merged" with enabled == true
c. If either is missing or disabled, halt with:"GitHub Projects V2 requires these built-in workflows to keep board status in sync with issue/PR state, but the GraphQL API does not expose a mutation to enable them. Manual step required:
- Open https://github.com//projects//workflows (use
orgs/<owner>path for org-owned projects).- Enable 'Item closed' -- map to Status = Done.
- Enable 'Pull request merged' -- map to Status = Done.
- Re-run:
hatch3r-board-init --resume." d. On success, record in memory for the Phase 2.5 config write-back:
board.workflows.itemClosedEnabled = trueboard.workflows.pullRequestMergedEnabled = trueIf platform is azure-devops:
az boards work-item type list --org https://dev.azure.com/{namespace} --project {project}
New, Ready → Active, In Progress → Active, In Review → Resolved, Done → Closed.board.statusOptions for use by other board commands.Active state. The distinction is maintained via hatch3r tags on work items. For board-level visibility, consider configuring Azure Boards column splits: in the Board Settings, split the "Active" column into "Active - Ready" and "Active - In Progress" using tag-based rules. Projects with custom Azure DevOps process templates can alternatively add a "Ready" state to the work item type.If platform is gitlab:
glab api projects/{project_id}/boards/{board_id}/lists --method POST --field label_id={label_id}
status::triage), Ready (status::ready), In Progress (status::in-progress), In Review (status::in-review), Done (status::done).board.statusOptions.Closes #N. The status::in-review scoped label will remain on closed issues. This drift is detected and fixed by board-groom during the health-fix action. For automated cleanup, consider setting up a GitLab CI pipeline trigger on issue close events to apply status::done. Note: scoped labels require GitLab Premium or Ultimate tier.board.labels in .hatch3r/hatch.json.| Category | Labels |
|---|---|
| Type | type:bug, type:feature, type:refactor, type:qa, type:docs, type:infra |
| Executor | executor:agent, executor:human, executor:hybrid |
| Status | status:triage, status:ready, status:in-progress, status:in-review, status:done, status:blocked |
| Priority | priority:p0, priority:p1, priority:p2, priority:p3 |
| Risk | risk:low, risk:med, risk:high |
| Meta | meta:board-overview, has-dependencies |
Platform-specific: Label/tag creation
If platform is github:
gh label list -R {owner}/{repo} (or get_label / list_labels MCP). Create only missing labels via gh label create -R {owner}/{repo} --name "{label}" --color "{hex}" (or create_label MCP).If platform is azure-devops:
az boards area project create --org https://dev.azure.com/{namespace} --project {project} --name "{area}".If platform is gitlab:
glab label list -R {namespace}/{project}. Create only missing labels via glab label create -R {namespace}/{project} --name "{label}" --color "{hex}".status::ready instead of status:ready, type::bug instead of type:bug.Use consistent colors per category:
| Category | Color scheme | Hex examples |
|---|---|---|
type:* | Blue shades | #0052CC, #1D76DB, #5319E7, #0075CA, #006B75, #0E8A16 |
executor:* | Green shades | #0E8A16, #2EA44F, #7CFC00 |
status:* | Yellow/Orange shades | #FBCA04, #F9D0C4, #E4E669, #FFA500, #D93F0B |
priority:* | Red shades (p0 darkest) | #B60205, #D93F0B, #E99695, #F9D0C4 |
risk:* | Purple shades | #5319E7, #7B68EE, #D4C5F9 |
meta:* / has-dependencies | Gray | #BFD4F2, #C5DEF5 |
area:{name} labels for each (teal/cyan color, e.g., #006B75). Add area names to board.areas in the in-memory config.
az boards area project create.Skip if the user chose "no" in Phase 1, step 1.4.
Platform-specific: Migration procedure
If platform is github:
query {
node(id: "<source_project_id>") {
... on ProjectV2 {
items(first: 100, after: <cursor>) {
pageInfo { hasNextPage endCursor }
nodes {
id
content { ... on Issue { id number title } ... on PullRequest { id number title } }
fieldValues(first: 20) {
nodes {
... on ProjectV2ItemFieldSingleSelectValue { name field { ... on ProjectV2SingleSelectField { name } } }
}
}
}
}
}
}
}
Paginate until all items are retrieved. Resolve the source project node ID from the project number first (same approach as Step 2.1 Option B).addProjectV2ItemById mutation:
mutation { addProjectV2ItemById(input: { projectId: "<new_project_id>", contentId: "<issue_node_id>" }) { item { id } } }
updateProjectV2ItemFieldValue mutation.If platform is azure-devops:
az boards query --org https://dev.azure.com/{namespace} --project {source_project} --wiql "SELECT [System.Id], [System.Title], [System.State] FROM WorkItems".az boards work-item create --org https://dev.azure.com/{namespace} --project {project} --type "User Story" --title "{title}" --description "{description}".If platform is gitlab:
glab issue list -R {source_namespace}/{source_project} --all.glab issue create -R {namespace}/{project} --title "{title}" --description "{description}" --label "{labels}".Prepare the updated config with all captured IDs:
board.owner/board.repo for backward compatibility.board.defaultBranch — from Phase 1 step 1.2b (default: "main")board.projectNumber — from the created/connected projectboard.statusFieldId — from the Status fieldboard.statusOptions.backlog — option IDboard.statusOptions.ready — option IDboard.statusOptions.inProgress — option IDboard.statusOptions.inReview — option IDboard.statusOptions.done — option IDboard.workflows.itemClosedEnabled -- from §2.2 step 6 (GitHub only; omit or set false on other platforms)board.workflows.pullRequestMergedEnabled -- from §2.2 step 6 (GitHub only; omit or set false on other platforms)board.areas — if area labels were createdWrite the file. Preserve any keys outside the board section.
Platform-specific: Search for existing overview issue
If platform is github:
meta:board-overview via gh search issues -R {owner}/{repo} "label:meta:board-overview state:open" (fall back to search_issues MCP).If platform is azure-devops:
meta:board-overview: az boards query --org https://dev.azure.com/{namespace} --project {project} --wiql "SELECT [System.Id] FROM WorkItems WHERE [System.Tags] CONTAINS 'meta:board-overview' AND [System.State] <> 'Closed'".If platform is gitlab:
Search for an existing open issue labeled meta:board-overview: glab issue list -R {namespace}/{project} --label "meta:board-overview" --state opened.
If found: Skip creation. One board overview issue at a time. Proceed to Step 2.7.
If not found: Create a board overview issue:
If platform is github: Use gh issue create -R {owner}/{repo} or issue_write MCP with method: create.
If platform is azure-devops: Use az boards work-item create --org https://dev.azure.com/{namespace} --project {project} --type "User Story" --title "..." --fields "System.Tags=meta:board-overview".
If platform is gitlab: Use glab issue create -R {namespace}/{project} --label "meta:board-overview".
[Board Overview] {repo} Project Boardmeta:board-overview## Board Overview
**Project:** {owner}/{repo}
**Last refreshed:** {current ISO date}
---
## Status Summary
| Status | Count |
|--------|-------|
| Backlog / Triage | 0 |
| Ready | 0 |
| In Progress | 0 |
| In Review | 0 |
| Externally Blocked | 0 |
| **Total Open** | **0** |
---
## Implementation Lanes
No ready issues yet. Run `board-fill` to populate the board.
---
*This issue is auto-maintained by hatch3r board commands. Do not close.*
hatch3r-board-shared and set its status to Backlog.Print a complete summary:
Board Init Complete:
Project: {owner}/{repo} (Project #{number})
Status field: configured (5 options)
Labels created: N new, M existing
Areas: [list or "none"]
Migration: N issues migrated from Project #X (or "skipped")
Board overview: #{issueNumber}
Config: .hatch3r/hatch.json updated
This skill delegates per task size:
Source: .claude/rules/fan-out-discipline.md (P8 B2); agents/shared/efficiency-patterns.md.
project scope for Projects V2). For gh CLI: run gh auth refresh -s project.az login status or AZURE_DEVOPS_PAT. Verify organization/project access.glab auth login status or GITLAB_TOKEN. Verify project access..hatch3r/hatch.json content outside the board key when writing config back.createProjectV2 / addProjectV2ItemById / updateProjectV2ItemFieldValue mutations and the owner-node-ID requirement in Phase 2.project scope requirement (gh auth refresh -s project) and the GITHUB_TOKEN/GH_TOKEN PAT fallback in the authentication and error-handling steps.