Github Project Provisioning

GitHub Project Provisioning

Safety contract

• Start with inspect or plan. Neither command may mutate GitHub or tracked files.
• Never run apply until the user explicitly approves the displayed plan and exact target.
• Re-display the authenticated account, owner, repositories, Project title, and every planned mutation before approval.
• Treat mismatched identity, target, config digest, state digest, missing permissions, and duplicate names as hard failures.
• Do not delete, rename, archive, or silently repair views/workflows.
• Do not create a live Organization Project while merely authoring or testing this skill. A user-requested bootstrap is an operational change and still requires the inspect/plan/explicit-approval gate.
• --confirm-target prevents target mix-ups; it is not an authorization mechanism. Human approval remains a host-level interaction requirement. The content-derived plan_id prevents an approved plan file from being edited before apply.

Prerequisites

• Install the complete github-operations plugin. A copied skill directory is intentionally unsupported.
• Require Python 3.11+, gh, an authenticated GitHub account, and Project scopes.
• Use an explicit config or .agents/github-operations.json at the current git root. Read the config contract before creating one.

Workflow

Resolve scripts/run.py against this skill directory before executing it; do not run a bare relative path from the target repository's working directory.

1. Inspect the target and authentication read-only:

   python3 <skill-dir>/scripts/run.py inspect --config <config>
   

2. Produce the read-only plan:

   python3 <skill-dir>/scripts/run.py plan --config <config>
   

3. Summarize the returned identity, target, template or bootstrap, repositories, operations, browser-required work, plan_id, and expiry. Ask for explicit approval.

4. Only after approval, copy the exact target value into --confirm-target:

   python3 <skill-dir>/scripts/run.py apply --plan-id <id> --confirm-target '<owner/project-title>'
   

5. Run verify. Treat the API result as partial when it reports browser-required work. Report built-in workflow target statuses, view grouping, and any auto-add configuration separately. Use browser-operations for those state changes and obtain confirmation for each change.

If Project bootstrap/copy or repository linking stops partway through, display the journal and current Project, obtain approval, and use resume with the original content-derived plan ID. Resume reconciles an already-created Project instead of creating or copying it again.

If apply reports a stale lock, first verify that the recorded process is no longer running. After explicit target confirmation, clear only that target with run.py unlock --target '<target>' --confirm-target '<target>'; never delete an active lock.

Contract behavior

• When project.template is present, it is resolved uniquely by owner and title and copied without draft items.
• When project.template is omitted, a missing target Project is created from the semantic contract. Never substitute a Project from another Organization merely to satisfy the template requirement.
• Bootstrap creates/reconciles fields and views through the public API, preserving existing option IDs during field updates. It must not carry over items, repositories, views, workflows, descriptions, or history from another Project.
• Views and built-in workflows are a verification contract. If the copied structure drifts and the public API cannot safely repair it, stop with manual remediation.
• The public API verifies workflow names and enabled flags, but not the Status target configured in the browser. Workflow entries may declare set_status; this value must be verified manually. The standard contract uses the following transitions: Item added → Inbox; Pull request linked to issue → linked Issue In Review; Code changes requested → In Progress; Pull request merged → Done; Item closed → Done; Item reopened → In Progress. The sub-issue and auto-close workflows are disabled.
• For bootstrap, view grouping and built-in workflow configuration must be emitted as browser-required operations and completed through browser-operations after apply. Do not report full verification until those operations are verified.
• Repository auto-add is opt-in. Omit auto_add to keep it disabled. When requested, configure only the default repository unless the plan explicitly supports additional auto-add workflows; supplement other repositories through Issue Forms, explicit Issue registration, or manual addition.
• Area labels and repository-specific routing are outside this skill.