okffs

Close a GitHub issue by issue number. Under OKFFS_AUTO_PR, if the issue's branch still has only an untouched auto-created draft PR (no real commits beyond okffs's init commit), that empty draft PR is also closed and the branch deleted. A ready PR, or any branch with real work, is left untouched.

Post a comment to a GitHub issue. Use after committing to a working branch to log what was done. Pass a marker to UPSERT instead: the comment carrying that hidden marker is edited in place, or created if absent — use for a single running status comment per issue rather than an append-only thread.

Stage tracked, modified files (untracked/new files require include_untracked: true), build a commit message from the provided message (used verbatim) or the staged file list, commit, push to the issue branch, and post a rich progress comment to the linked issue. Refuses to stage files matching a secrets deny-list (.env*, *.env, *.pem, *.key, id_rsa*, *credentials*, *.p12, *.pfx) unless explicitly overridden, and returns the full staged file list.

Persist okffs configuration to the .env file in the current working directory — the write backend for the /okffs:setup conversational wizard. Reuses the same manifest + serializer as the `okffs setup` CLI, so both paths produce identical files: okffs owns ONLY a marked block, and the user's own variables and comments outside it are preserved verbatim. Pass `set` (a map of okffs env var → value) for variables to configure, and/or `declined` (a list of keys) for variables the user explicitly chose to skip (written as commented placeholders so a later sync won't re-ask them). Existing configured values that you don't pass are left untouched. Keys are validated against the manifest — unknown keys are rejected. Typically called by the /okffs:setup prompt after interviewing the user; not usually called directly. Secrets (GITHUB_TOKEN) are masked in the response. Multisite: pass `app` to write `{app}/.env` (that app directory's own .env, which inherits the root's) instead — OKFFS_APP is set to the app automatically. Unless `ensure_gitignore` is false, a missing depth-agnostic `.env` rule is appended to the repo's .gitignore so no .env (root or app) can be committed.

Create a GitHub issue and automatically create a matching branch. Before calling this tool, infer appropriate labels from the issue title and description using GitHub's default labels: bug, documentation, duplicate, enhancement, good first issue, help wanted, invalid, question, wontfix. Pass the inferred labels in the labels parameter unless the user has specified their own. Also infer a `priority` for the issue from its urgency and impact (board options: Urgent, High, Medium, Low), and infer an `effort` from the expected amount of work (board options: High, Medium, Low), and infer a `type` — the native GitHub Issue Type — from what kind of work it is (org types: Task, Bug, Feature; e.g. a fix → Bug, a new capability → Feature, a broad multi-issue effort → Epic, a small chore → Task), passing the value(s) in the matching parameter. okffs matches these against the board's / org's actual options and falls back to OKFFS_DEFAULT_PRIORITY / OKFFS_DEFAULT_EFFORT / OKFFS_DEFAULT_TYPE when you omit them — so if you genuinely can't judge, omit the field rather than guessing. If the user mentions that this issue is blocked by, blocking, or a child of another issue, call link_issues after creating this issue to set the relationship. Returns the issue URL, issue number, and branch name.

Create multiple GitHub issues and matching branches from a list of tasks. Before calling this tool, infer appropriate labels for each task from its title and description using GitHub's default labels: bug, documentation, duplicate, enhancement, good first issue, help wanted, invalid, question, wontfix. Pass inferred labels per task in the labels field unless the user has specified their own. When the Project board is enabled (OKFFS_PROJECT_AUTO_ADD=true), each issue is added to the board like create_issue does — infer a per-task priority/effort where you can, falling back to OKFFS_DEFAULT_PRIORITY/EFFORT. Also infer a per-task native GitHub Issue Type (Task/Bug/Feature/…) where the org defines them, falling back to OKFFS_DEFAULT_TYPE. Confirms before creating.

Create a pull request for the current issue branch. Reads the issue, its comments, and commits to generate a PR title and body. Always includes Closes #N. If OKFFS_UPDATE_DOCS is true, writes a per-issue changelog fragment under .changes/unreleased/ — under the issue's app directory in a multisite repo: the session's OKFFS_APP, else the registered app named by the issue's label (assembled into CHANGELOG.md at release time by prepare_release — not a direct CHANGELOG.md edit), plus SECURITY.md for security-related changes, and commits them onto the branch before creating the PR. If a PR already exists for the branch (e.g. a draft opened by create_issue under OKFFS_AUTO_PR=true), it is updated and marked ready for review instead of erroring. By default, a branch with no commits ahead of base is refused (a PR needs a diff); pass allow_empty: true to instead push an empty init commit so the branch diverges and open a **draft** tracking PR — the same mechanism create_issue uses under OKFFS_AUTO_PR, for backfilling a PR onto a branch that was created empty. Posts a summary comment to the issue. If the issue has no okffs-created branch link (no **Branch:** line — e.g. a pre-okffs issue or a hand-made branch), pass an explicit branch, or check out a branch named {issue-number}-… and okffs infers it; either way it backfills the **Branch:** line. If the PR targets OKFFS_PROTECTED_BRANCH, okffs still opens it (opening is safe and reversible) and adds a reminder that the merge/tag stay with the user — OKFFS_PROTECTED_BRANCH governs autonomous merging, never PR creation.

Delete a branch and close its matching GitHub issue. Destructive — requires confirmed: true.

Close a GitHub issue and delete its matching branch. Destructive — requires confirmed: true.

Open (and, when opted in, merge) an ISSUE-LESS fix PR into the base branch (e.g. develop) — the mirror of promote_branch, which does the base→protected promotion. Use this for a small fix that doesn't warrant its own issue (e.g. review-comment cleanups) instead of dropping to raw `gh pr create` + `gh pr merge`: it is deliberately issue-less (no issue lookup, no Closes #N, no **Branch:** line required), authenticates with okffs's token, and — when the board is enabled — adds the PR to the Projects v2 board. head defaults to the current branch; base defaults to OKFFS_BASE_BRANCH (or the repo default). It NEVER targets OKFFS_PROTECTED_BRANCH — that stays promote_branch + a manual, user-driven merge. Opening the PR is always safe and unconditional. The merge is then attempted under the SAME gates and opt-in as merge_pull_request: it only merges when OKFFS_AUTO_MERGE_BASE=true, OKFFS_PROTECTED_BRANCH is set, and the PR is green (all checks pass), conflict-free, not blocked/behind, and has every review thread resolved — using OKFFS_BASE_MERGE_METHOD. If merge is off or a gate isn't met, the PR is left open with an actionable reason (re-run once it's green, or merge it with merge_pull_request by passing pr_number set to that PR's number).

Fetch full details of a GitHub issue by number — title, body, labels, assignees, branch, and status.

Link two GitHub issues with a relationship by editing the issue body. Supports blocked_by (this issue is blocked by another), blocking (this issue is blocking another), and parent (set a parent issue). Relationships are stored in a '## Relationships' section in the issue body.

List all open GitHub issues, each with its branch, any linked open or draft PR, its board column (project), its Priority, its native Issue Type (Task/Bug/Feature/…, when the org defines them), and its relationships (parent, children, blocked-by, blocking) shown as a tree. Issues are ordered by Priority (Urgent → High → Medium → Low → unset) so the most important work surfaces first — factor Priority in when deciding what to do next. Replaces the need for a separate PR-listing tool.

Fetch review feedback for a pull request: inline review comment threads (each with comment ids, file/line, author, body, and resolved/unresolved state) plus overall review summaries. Use this to read PR review comments before addressing them. Typical workflow: read with this tool, fix the code for the valid comments, commit/push with commit_and_update, reply to each addressed thread with reply_to_review_comment, post an overall summary with comment_issue (PRs accept issue comments), and — only if OKFFS_RESOLVE_THREADS is enabled — mark threads resolved with resolve_review_thread.

Autonomously merge a GREEN, review-resolved PR into the BASE branch (e.g. develop) using the configured per-tier merge method (OKFFS_BASE_MERGE_METHOD, default squash). Provide EXACTLY ONE of: issue_number (merge the issue's PR and complete the loop — comment on the issue and close it when the base isn't the repo default) OR pr_number (merge-only mode for an ISSUE-LESS fix PR into the base branch — skips the issue lookup, comment, and close, and needs no **Branch:** line). This is the ONE okffs action that merges — every other tool only opens PRs and hands back. It is therefore heavily gated and OPT-IN: it does nothing unless OKFFS_AUTO_MERGE_BASE=true. It NEVER merges OKFFS_PROTECTED_BRANCH (e.g. main) — that stays a manual, user-driven merge/tag — and refuses entirely if OKFFS_PROTECTED_BRANCH is unset, so it can't merge into an unnamed protected branch. Before merging it independently verifies (not merely trusting branch-protection rules): the PR targets the base tier and not the protected branch; it is open, not a draft, and free of conflicts; all commit statuses AND check runs on the head are green (no failing or pending checks); the PR is not blocked by a required gate; and every review thread is resolved. Any unmet gate → it refuses with an actionable reason and does not merge. On success (issue mode) it merges, comments on the issue, and — when the base isn't the repo default (so GitHub's Closes #N won't auto-close) — closes the issue to complete the loop. Use for landing small review-fix / feature PRs into develop without a human merge; the develop→main promotion always stays with the user.

Plan a piece of work and create all the resulting GitHub issues (with branches, draft PRs when OKFFS_AUTO_PR=true, and board placement when OKFFS_PROJECT_AUTO_ADD=true) in one shot. Given a free-text description of the work, break it down yourself into a structured list of issues — each with a title, description, inferred labels, an inferred priority/effort where you can judge it, an inferred native GitHub Issue Type (Task/Bug/Feature/… — commonly Epic for the overall effort and Task/Story/Feature/Bug for its children), and any relationships between them — and pass that breakdown as the tasks array. Infer labels from GitHub's defaults: bug, documentation, duplicate, enhancement, good first issue, help wanted, invalid, question, wontfix. Express dependencies via per-task relationships, referencing other tasks by their 1-based position in the list. Two-step confirmation: call once to preview the plan, then re-call with confirmed: true to create everything.

Prepare a release: bump the version (package.json + package-lock.json when present, else a plain VERSION file — created on the first release if neither exists), roll the CHANGELOG ([Unreleased] → a dated version section with a fresh empty [Unreleased] and updated compare links), commit on a release branch, and open a PR. It does NOT tag or publish — tagging (which triggers the CI npm publish) stays a manual step after merge. Provide an explicit `version` or a `bump` level; if neither is given, a level is inferred from the [Unreleased] entries (### Added → minor, otherwise patch) and surfaced for confirmation. Multisite: pass `app` to release one registry app from the repo root (defaults to the session's OKFFS_APP). Two-step: call once to preview, re-call with confirmed: true to apply.

Open the release/promotion pull request from one long-lived branch into another — e.g. develop → main. Use this instead of raw `gh pr create` or create_pull_request for a base→protected promotion: it is deliberately ISSUE-LESS (no issue lookup, no Closes #N), authenticates with okffs's token, and adds the PR itself to the Projects v2 board so the gate is visible. By default it promotes OKFFS_BASE_BRANCH (head, e.g. develop) into OKFFS_PROTECTED_BRANCH — or the repo default branch if no protected branch is set — but head/base can be overridden. No confirmation is needed: opening a PR is safe and reversible. okffs opens the PR and hands back — it NEVER merges or tags; that stays with the user. If a promotion PR is already open for the head branch it is updated and returned rather than erroring (GitHub allows only one open PR per head→base pair). When OKFFS_PROMOTION_AUTO_REVIEW is true, OKFFS_PROMOTION_REVIEWERS (e.g. Copilot) are requested — only on a newly-created gate PR, never on re-runs, to avoid repeat (possibly billable) reviews; when OKFFS_PROMOTION_STATUS is set, the board card lands in that column. A re-run on an existing gate PR also reports its unresolved review threads (e.g. Copilot feedback that landed after the review was requested) and points at the address_pr_review loop — so re-running promote_branch is the way to check the release gate before handing the merge to the user. With OKFFS_TAG_RELEASE=true, a re-run AFTER the gate PR has been merged tags the release(s) it carried (v1.2.0, or finance-1.2.0 per app whose version changed) on the merge commit. With OKFFS_AUTO_MERGE_PROTECTED=true, a re-run on an EXISTING gate PR merges it into the protected branch (OKFFS_PROTECTED_MERGE_METHOD) once every gate passes — open, non-draft, no conflicts, all checks green, no pending requested review, every thread resolved — and, with OKFFS_TAG_RELEASE too, tags in the same call: the fully handled promotion. Never on the call that creates the PR.

Reply to an inline PR review comment thread. Pass the pull request number, the comment id (from list_pr_review_comments), and the reply body. Use after addressing a review comment to record what was changed (e.g. reference the fix commit). IMPORTANT: a reply does NOT resolve the thread — the thread stays open until you resolve it. The full loop is list_pr_review_comments → reply_to_review_comment → resolve_review_thread; even when OKFFS_RESOLVE_THREADS=true, resolving is a separate, explicit act (this tool leaves the thread open unless you ask it to resolve). To reply and resolve an addressed thread in one call, pass resolve: true (still gated by OKFFS_RESOLVE_THREADS). Prefer this tool over raw `gh api .../replies`, which skips the resolve path and silently leaves threads unresolved despite OKFFS_RESOLVE_THREADS=true.

Mark an inline PR review thread as resolved. Pass the thread_id from list_pr_review_comments. Gated by OKFFS_RESOLVE_THREADS: when that env var is not 'true', this tool declines and leaves the thread open for the user to read and resolve manually.

Set enumerated fields on an EXISTING issue: the GitHub Projects v2 board Priority and/or Effort, and/or the native GitHub Issue Type (Task/Bug/Feature/…). Use this to set these on issues that already exist — create_issue only sets them at creation time. Priority/Effort handle both project-native single-select fields and org-level Issue Fields (the latter needs OKFFS_CLASSIC_PAT + a classic admin:org PAT) and require OKFFS_PROJECT_ENABLED. Type is a native GitHub Issue Type (org-level; skipped cleanly on user repos / when unavailable) and works independently of the board. To move an issue's Status column, use update_project_status; to edit title/assignees/labels/milestone/body, use update_issue.

Mutate the core fields of an EXISTING GitHub issue — title, assignees, labels, milestone, and/or body. create_issue only sets these at creation time; this is how you change them afterward (e.g. rename an issue, add or change an assignee) without dropping to raw `gh issue edit`. Authenticates with okffs's configured token (GITHUB_TOKEN, or the gh CLI fallback when it's unset) and applies okffs conventions. Pass only the fields you want to change — omitted fields are left untouched. NOTE: labels and assignees REPLACE the whole set (they do not merge with the current values), so pass the complete desired list; an empty array [] clears them, and milestone: null clears the milestone. A body rewrite automatically preserves okffs-owned metadata (the **Branch:** line and the ## Relationships section) even when the new body omits them — pass preserve_metadata: false for a genuine raw replace. For board Priority/Effort use set_issue_fields, and for the board Status column use update_project_status — those are not issue fields.

Move an issue between GitHub Project board columns: Backlog, Ready, In Progress, or Review. Done is intentionally NOT settable here — it is owned by native GitHub board automation on PR merge / issue close. Drive this conversationally during the dev workflow: after create_issue places an issue on the board, offer to move it to "In Progress" when work starts, and to "Review" when a PR goes up. Requires OKFFS_PROJECT_ENABLED and the issue to already be on the board.