This document describes the side effects, required permissions, and permission-bypass behavior of Wholework skills. Reviewers and users should read this before running Wholework in their repositories.

Wholework skills execute operations that have real side effects on your GitHub repository and local filesystem. These are categorized below.

Skills invoke the GitHub CLI to perform the following categories of operations:

• Issues — create, edit (title, body, labels, assignees), and close issues
• Pull Requests — create, review, merge, and close pull requests
• Labels — add and remove labels (phase/*, size/*, type/*) on issues and PRs
• GitHub Projects V2 — read and update project field values (e.g., Size, Status)
• Comments — post comments to issues and PRs

These operations are performed on the repository where Wholework is installed. You need gh auth with at least repo scope (and project scope for Projects V2 updates).

Skills perform the following git operations locally:

• Commits — create signed commits (git commit -s) during the /code phase
• Branches — create and delete feature branches and worktree branches
• Push — push commits to origin (target branch is main by default, or the branch specified with --base)
• Rebase — rebase the worktree branch when a fast-forward merge is not possible

Skills write to the following locations on your local filesystem:

• .tmp/ — temporary files used during skill execution (auto-cleaned after use)
• docs/spec/ — spec files generated by /spec and updated by /code and /verify
• Worktrees — isolated git worktrees created under .claude/worktrees/ during skill execution

The /auto skill chains all phases (spec → code → review → merge → verify) into a single autonomous run. Each phase is invoked as a subprocess via claude -p. Two permission modes are available, selectable via the permission-mode key in .wholework.yml.

Set in .wholework.yml:

# bypass mode (default — backward compatible)
permission-mode: bypass

# auto mode (recommended for Max users)
permission-mode: auto

Uses --dangerously-skip-permissions, which bypasses all Claude Code permission prompts:

• File reads/writes, shell commands, and tool calls execute without asking for confirmation
• All side effects described above occur without user approval per operation
• Phase-to-phase context is isolated (each subprocess starts fresh)

This is the default to avoid breaking changes for existing users.

Uses --permission-mode auto, which runs the Claude Code auto-mode classifier. Auto mode applies guardrails: operations are classified as ALLOW, soft_deny (requires approval), or BLOCK. This is safer than bypass because the evaluation framework remains active.

Conflict resolution with allow rules: Auto mode's default soft_deny rules conflict with two wholework operations:

• Git Push to Default Branch — /code with patch route pushes directly to main
• External System Writes — each phase runs in a fresh subprocess, so Issues/PRs created in a prior phase are treated as "not created in this session"

To resolve these conflicts, copy the recommended allow rules template into .claude/settings.local.json (gitignored — auto mode rules are not read from checked-in settings files):

# Merge the template into your settings.local.json
# Template location: docs/guide/auto-mode-template.json

After applying the template, restart Claude Code (settings are cached at session start and are not hot-reloaded).

permission-mode auto with the minimal allow rules template is safer than bypass for two reasons:

1. least privilege: bypass removes all guards; auto + minimal allow rules grants exceptions only for the specific operations wholework needs (gh issue, gh pr, gh label, gh api, gh run, git push origin main). Destructive patterns not listed in the template retain their soft_deny classification.
2. Defense in depth: allow rules are pinpoint exceptions within the auto-mode evaluation framework. bypass skips the evaluator entirely — there is no framework to catch unexpected actions.

Note: if allow rules are written broadly (e.g., gh * or git push * blanket allow), this safety advantage narrows. The template enumerates only the subcommand-level patterns wholework actually uses.

Wholework does not store or transmit credentials. All GitHub operations use the gh CLI's existing authenticated session.

If you discover a security vulnerability in Wholework, please open a GitHub Issue or contact the maintainers directly. Do not include sensitive information in public issue reports.