ghpm-init

ghpm-init

PREREQUISITE: Read ../ghpm-shared/SKILL.md for prerequisites and error handling.

Initialize a GitHub Projects v2 project for use with ghpm skills. Auto-discovers schema and generates config files.

Arguments

• Project URL (e.g., https://github.com/orgs/<org>/projects/<number>)
• If no arguments, ask the user for the project URL or owner + number.

Workflow

Phase 1: Validate Access

1. Parse arguments to extract owner and project number from URL or positional args.
2. Run gh auth status to verify authentication. If this fails, tell the user to run gh auth login and stop.
3. Run gh project view <number> --owner <owner> --format json to verify access and get project metadata (id, title). If this fails with 403/404, tell the user to check token scopes (read:project, project) and project access.
4. Determine the owner type from the project view output. This matters for Phase 3: use organization(login: "<owner>") for org-owned projects or user(login: "<owner>") for user-owned projects.

Phase 2: Discover Schema

1. Run gh project field-list <number> --owner <owner> --format json to get all fields with IDs, types, and options.
2. Identify the workflow field: find the ProjectV2SingleSelectField named "Status". If multiple candidates or none found, ask the user which field drives the kanban workflow.
3. Separate the workflow field from other fields.

Phase 3: Discover Views

1. Run GraphQL query to fetch all views. Use the owner type determined in Phase 1 to choose the correct root field:

gh api graphql -f query='
{
  organization(login: "<owner>") {
    projectV2(number: <number>) {
      views(first: 50) {
        nodes {
          id
          name
          number
          layout
          filter
          groupByFields(first: 5) {
            nodes {
              ... on ProjectV2Field { name }
              ... on ProjectV2SingleSelectField { name }
              ... on ProjectV2IterationField { name }
            }
          }
          sortByFields(first: 5) {
            nodes {
              field {
                ... on ProjectV2Field { name }
                ... on ProjectV2SingleSelectField { name }
                ... on ProjectV2IterationField { name }
              }
              direction
            }
          }
        }
      }
    }
  }
}'