project-init

project-init

Create a new GitHub Project v2, set up the standard fields, and link it to a repository. Also guide the built-in workflows (automatic status change, auto-add, auto-archive).

Prerequisites

• gh The CLI is installed and authenticated
• project The scope is granted (gh auth status check with)

Flow

Step 1: Check the project information

Confirm the following with the user:

• Project title
• Owner (User or Organization)
• Visibility (PUBLIC / PRIVATE)
• Description (optional)

If the owner is not specified, auto-detect:

gh repo view --json owner -q '.owner.login'

Step 2: Create the project

gh project create \
  --owner <owner> \
  --title "<タイトル>" \
  --format json

Get the project number from the output.

Step 3: Link to repository

gh project link <number> --owner <owner>

Step 4: Create the standard fields

Create the following fields in order:

# Status（デフォルトで存在する場合はスキップ）
gh project field-create <number> \
  --owner <owner> \
  --name "Status" \
  --data-type "SINGLE_SELECT" \
  --single-select-options "Todo,In Progress,In Review,Done"

# Priority
gh project field-create <number> \
  --owner <owner> \
  --name "Priority" \
  --data-type "SINGLE_SELECT" \
  --single-select-options "High,Medium,Low"

# Size
gh project field-create <number> \
  --owner <owner> \
  --name "Size" \
  --data-type "SINGLE_SELECT" \
  --single-select-options "XS,S,M,L,XL"

Note: The Status field may be created automatically by GitHub. If an error occurs, use the existing field as is.

Step 5: Set the project description

gh project edit <number> \
  --owner <owner> \
  --description "<説明文>" \
  --visibility <PUBLIC|PRIVATE>

Step 6: Set up the built-in workflows

GitHub Projects v2 has built-in workflows that require no code. Guide the user to enable the following in the project settings screen.

Settings URL: https://github.com/orgs/<owner>/projects/<number>/workflows (For personal projects: https://github.com/users/<owner>/projects/<number>/workflows）

Recommended built-in workflows

Workflow	Behavior	Default state	Recommendation
Item closed	When Issue/PR is closed, Status → Done	Enabled	Keep as is
Pull request merged	When PR is merged, Status → Done	Enabled	Keep as is
Item reopened	When an Issue is reopened, Status → Todo	Disabled	Recommended to enable
Item added to project	When an item is added, Status → Todo	Disabled	Recommended to enable
Auto-add to project	Automatically add Issues/PRs matching the filter	Disabled	Recommended to enable
Auto-archive items	Automatically archive N days after Done	Disabled	Optional
Auto-close issue	Automatically close the Issue when set to Done on the board	Disabled	Strongly recommended to enable

Important: If Auto-close is not enabled, the Issue will not be closed automatically even if you set Status to Done on the boardNot done. Required for two-way sync.

Auto-add filter example

is:issue,pr is:open repo:<owner>/<repo>

To filter by label:

is:issue,pr is:open label:sprint-1 repo:<owner>/<repo>

Step 7: Guidance for continuous automatic sync

If you need advanced synchronization that the built-in workflows cannot cover, such as PR lifecycle integration (opened→In Progress, review_requested→In Review),project-sync-issues Explain that GitHub Actions workflows can be generated with this skill.

Step 8: Report the creation results

Display the following information:

• Project URL
• Project number
• List of created fields
• Linked repositories
• Built-in workflow settings URL
• Recommended settings checklist

Notes

• Status option values can be customized according to user requests
• If an error occurs during field creation (e.g., it already exists), skip it and continue
• For Organization projects, appropriate permissions are required
• Built-in workflows cannot be configured via CLI/API, so configuration via the Web UI is required
• Requires network (mainly via API. See the later section "Running in a sandbox environment")

Verification

After Step 8 is complete, verify the creation results as follows:

gh project view <number> --owner <owner> --format json
gh project field-list <number> --owner <owner> --format json

It is complete if the project URL and field list (Status / Priority / Size) are output.

Running in a sandbox environment

This skill requires GitHub operations over the network (Project v2 creation and field configuration). The relevant commands are executed with the sandbox disabled on a per-command basis. It cannot be executed in an environment where network blocking cannot be lifted.