@senad-d/issueme0.1.9

Agent-friendly GitHub issue management for pi.
Sync issues, cache local context, and let agents manage GitHub Issues through safe structured tools.

---

IssueMe is a pi extension that gives LLM agents a repository-scoped GitHub Issues layer. It uses GitHub REST and GraphQL APIs, keeps bounded local JSON cache files for open issues, and exposes tools for syncing, triage, labels, milestones, comments, assignees, issue types, issue templates, Projects v2 boards and item ordering, native sub-issues, dependencies and related issues, issue history, linked-development inspection, confirmed issue deletion, and explicit bulk updates.

IssueMe

• GitHub API native: no GitHub CLI dependency and no shell execution for GitHub issue operations.
• Repository scoped: resolves the current owner/repo from trusted project context and validates GitHub request boundaries.
• Agent tool suite: registers forty-seven issueme_* tools for repository overview, issue, label, milestone, assignee, issue-type, issue-template, Projects v2 (discovery, items, maintenance, ordering), comment, sub-issue, dependency, related-issue, timeline, development-link, permanent-deletion, and bulk workflows.
• Local issue cache: writes open issues to .pi/issues/<number>-<title-slug>.json (git-invisible via a directory-local .gitignore) so agents can inspect full bodies/comments without oversized tool results or a dirtied git status.
• Safety-aware: honors pi project trust, keeps tokens out of config/cache/tool output, limits closed-issue changes to labels, project-only board metadata, reopen, and confirmed deletion, bounds results, and requires explicit confirmation for destructive taxonomy and permanent issue-deletion operations.
• Workflow friendly: /issueme opens a non-secret configuration UI and /issueme start [skill-path] kicks off your project issue-management skill.

Status: 0.1.0 is unreleased. Source, tests, this README, SECURITY.md, and the files under docs/ describe current implemented behavior.

Security: pi packages run with your full system permissions. IssueMe reads GitHub tokens from trusted project or process environment, calls GitHub APIs for the current repository, and writes non-secret config plus local issue-cache files. It is not an OS sandbox. Read SECURITY.md.

Table of Contents

• Quick Start
• Visual Workflow Guide
• Installation
• Daily Usage
• Commands
• Agent Tools
• Configuration and Authentication
• Safety Model
• Troubleshooting
• Update and Uninstall
• Development
• Publishing
• More Documentation
• License

---

Quick Start

pi install npm:@senad-d/issueme
cd /path/to/your/github/repo

Create a local .env from the example and provide a token with repository issue access:

cp .env.example .env
$EDITOR .env

.env.example documents the supported variables (GH_TOKEN or GITHUB_TOKEN, plus optional GITHUB_REPOSITORY) with safe placeholders.

Start pi and open IssueMe:

pi

/issueme

Review non-secret settings, then get a read-only repository overview:

Use issueme_get_overview to summarize issues, labels, milestones, assignees, and projects.

Drill into selected issues with the existing tools. Use issueme_sync_issues only when you need local issue/cache files.

Recommended workflow kickoff:

/issueme start .pi/skills/github-issues/SKILL.md

If the npm package is unavailable before a public release, use the source checkout workflow below. See docs/configuration.md for token/config details and docs/usage.md for workflow examples.

---

Visual Workflow Guide

See how IssueMe works and which workflows it supports: seven diagrams covering architecture, the full 47-tool workflow map, daily issue management, native relationships, Projects v2, explicit bulk changes, and safe recovery.

Editable draw.io sources and zoomable SVGs are in docs/diagrams/.

---

Installation

Scope	Command	Notes
Global	pi install npm:@senad-d/issueme	Loads in every trusted pi project.
Project-local	pi install npm:@senad-d/issueme -l	Writes to .pi/settings.json in the current project.
One run	pi -e npm:@senad-d/issueme	Try without changing settings.
Git	pi install git:github.com/senad-d/IssueMe@<tag>	Pin a tag or commit.
Local checkout	pi --no-extensions -e .	Develop or test this repository.

Requirements:

• pi with Node.js 22.19.0 or newer.
• A trusted project checkout.
• GH_TOKEN or GITHUB_TOKEN with repository issue access. Projects v2, native sub-issues, and linked-development inspection require the matching GitHub permissions/features; see GitHub token types for which token type reaches which boards.

Source checkout:

git clone https://github.com/senad-d/IssueMe.git
cd IssueMe
npm ci
npm run validate
pi --no-extensions -e .

Use a checkout globally while developing:

pi install /absolute/path/to/IssueMe

---

Daily Usage

Inside a trusted GitHub repository, run one of these in pi:

/issueme
/issueme info
/issueme start .pi/skills/github-issues/SKILL.md
/issueme start

Recommended first run:

1. Add a GitHub token through trusted project or process environment.
2. Start pi from the repository checkout and trust the project if prompted.
3. Run /issueme info to confirm repository, token, config, and cache status without exposing secrets.
4. Run /issueme to review config such as issue directory, defaults, creator scope, and default skill path.
5. Ask the agent to call issueme_get_overview for initial planning; sync only when local issue files are needed.
6. Start your project workflow with /issueme start [skill-path].

IssueMe provides tools; your project SKILL.md should describe your team's issue process. See docs/usage.md for a starter skill and prompt examples.

---

Commands

Command	Description
/issueme	Open the non-secret configuration UI in TUI mode; non-TUI modes show safe config/status output.
/issueme info	Show help, runtime status, registered tool names, cache counts, and troubleshooting hints without secrets.
/issueme help, /issueme --help, /issueme -h	Aliases for /issueme info.
/issueme start [skill-path]	Ask the agent to load a readable project-local issue workflow skill, or the configured defaultSkillPath when omitted.

---

Agent Tools

IssueMe registers forty-seven issueme_* tools. The most common flow is:

1. Orient: issueme_get_overview returns bounded summaries in one call, with no cache writes and at most five GitHub requests. Inspect section status; returned rows are not repository totals.
2. Drill down: issueme_list_issues, issueme_get_issue, taxonomy/people discovery, issueme_list_issue_types, issueme_list_issue_templates, issueme_get_project_fields, issueme_list_project_items, issueme_list_issue_comments, issueme_list_sub_issues, issueme_list_issue_dependencies, issueme_list_related_issues, issueme_list_issue_timeline, and issueme_list_issue_development_links. When a result is truncated, pass details.continuation.nextToken as after with the same filters to read the next page. Sync only when local cache files are needed.
3. Mutate explicitly: create/update/comment/assign/label/reopen/close issues, permanently delete one confirmed mistaken issue, manage label/milestone taxonomy, add/update/clear/archive/move/remove Projects v2 items, manage native sub-issues, blocked-by dependencies, and related issues, or bulk-update a confirmed list of issue numbers.

Use the detailed references when building agent workflows:

• docs/tool-reference.md for the full tool catalog and examples.
• docs/public-contracts.md for read/write behavior, execution modes, and result semantics.
• docs/usage.md for skill-guided workflow prompts.

---

Configuration and Authentication

Project config is non-secret and stored at:

.pi/agent/issueme.json

Supported settings include issueDirectory, allowedIssueCreator, defaultLabels, defaultAssignees, and defaultSkillPath. The optional allowedIssueCreator setting is an IssueMe processing scope only; it limits what IssueMe lists, syncs, reads, mutates, and caches, but it does not change GitHub repository permissions.

Token precedence:

1. trusted project GH_TOKEN;
2. trusted project GITHUB_TOKEN;
3. process GH_TOKEN;
4. process GITHUB_TOKEN.

Tokens are read but never written to config, cache files, tool output, or logs. Full configuration, trust, local cache, and request-boundary details are in docs/configuration.md.

GitHub token types

IssueMe accepts either kind of personal access token and behaves the same with both. The difference is what GitHub lets the token reach.

Token type	Grant	Covers	Cannot reach
Fine-grained personal access token	Repository permissions: Issues read and write, Metadata read, Contents read (issue template discovery). For organization boards add the organization permission Projects.	Every issue, comment, label, milestone, assignee, sub-issue, dependency, related-issue, timeline, development-link, issue-type, deletion, and bulk tool. Projects v2 boards owned by an organization.	Projects v2 boards owned by a user account. GitHub documents this as a limitation of fine-grained tokens, and no permission exists to grant it.
Classic personal access token	Scopes repo and project (read:project is enough for read-only board discovery).	Everything above plus user-owned Projects v2 boards.	Nothing, but repo grants access to every repository the account can reach, so prefer the fine-grained token unless you need a user-owned board.

How the limitation shows up: with a fine-grained token the Projects v2 tools (issueme_list_projects, issueme_get_project_fields, issueme_add_issue_to_project, issueme_update_project_item, issueme_list_project_items, issueme_get_project_item, issueme_remove_issue_from_project, issueme_clear_project_item_field, issueme_archive_project_item, issueme_move_project_item) fail cleanly with github_projects_v2_forbidden ("Resource not accessible by personal access token"), and issueme_get_overview reports its projects section as unavailable while every other section still works. Nothing else degrades.

Independent of token type:

• issueme_delete_issue needs repository administrator permission.
• Native issue types persist only with push access; without it GitHub drops the type silently and IssueMe reports partial_success.
• Organization issue types need read:org on a classic token or the organization permission on a fine-grained token; user-owned repositories report issue_types_unavailable.
• /issueme info reports whether a token is present and where it came from, never its value.

Both token types were verified live against this repository on 2026-10-10; see docs/live-github-verification.md.

---

Safety Model

• IssueMe honors project-local config, tokens, Git metadata, skills, and cache files only when pi reports the project as trusted.
• Closed issues remain protected from content mutations; issueme_label_issue (and bulk add_labels/remove_labels) may change their labels, project-only board metadata tools (issueme_update_project_item, issueme_clear_project_item_field, issueme_remove_issue_from_project, issueme_archive_project_item) may change their board values or membership, and explicit issueme_reopen_issue (and bulk reopen) and confirmed issueme_delete_issue provide the other documented exceptions. Adding a closed issue to a board is still refused.
• issueme_delete_issue permanently deletes only one exact issue after explicit intent, an irreversibility warning, and confirmDelete: true; it accepts open or closed issues, refuses pull requests, and requires GitHub repository administrator permission.
• Repository label, milestone, and issue deletion require explicit actions and confirmation flags.
• Bulk updates accept only explicit issue number lists, never unconstrained search targets.
• Native sub-issues use GitHub GraphQL; IssueMe does not silently create body-only parent/dependency/blocker fallbacks.
• Tool results are bounded and include details.result/status metadata; agents should check both pi tool errors and IssueMe result details.
• IssueMe starts no webhooks, listeners, background servers, timers, file watchers, telemetry, or GitHub CLI processes.

Issue dependencies and blockers

GitHub documents native issue dependency endpoints (blocked_by and blocking) in its REST API, and IssueMe implements them as issueme_list_issue_dependencies, issueme_add_issue_dependency, and issueme_remove_issue_dependency. Both ends of an edge must be open issues in the current repository and creator scope, the blocking issue is identified by its GitHub database id, self-dependencies are refused, already-present or already-absent edges are no-ops, and GitHub cycle/validation refusals come back as structured result: error results. Dependencies are prerequisites, distinct from sub-issues (decomposition) and related issues; IssueMe does not create body-only blocked by, depends on, or tracked by references as a silent fallback. docs/github-api-compatibility.md records that this support is documentation-verified and mocked, not live-verified.

Read SECURITY.md before installing in sensitive environments.

---

Troubleshooting

Problem	Try
/issueme refuses config editing	Trust the project first; project-local state is ignored until pi reports trust.
Token is missing	Set GH_TOKEN or GITHUB_TOKEN in trusted project or process environment.
Repository cannot be resolved	Set GITHUB_REPOSITORY=owner/repo or start pi from a trusted GitHub checkout.
Local issue files look stale	Run issueme_sync_issues, or issueme_get_issue with refresh: true for one known issue.
Expected issue is missing or refused	Check /issueme info for Allowed issue creator and update it in /issueme if needed.
Unknown label, milestone, assignee, project, or field	Use the matching read-only discovery tool before mutating.
Mutation is refused	Confirm the issue is open (unless explicitly reopening or deleting), in creator scope, and the target IDs/labels/users exist. Permanent deletion also requires confirmDelete: true and repository administrator permission.
Bulk update stopped	Inspect details.bulkResults, sync if cache state is uncertain, then retry only remaining explicit issue numbers.

More troubleshooting notes live in docs/configuration.md, docs/tool-reference.md, and SECURITY.md.

---

Update and Uninstall

pi update --extensions
pi update npm:@senad-d/issueme
pi remove npm:@senad-d/issueme
pi remove npm:@senad-d/issueme -l

Removing the package does not automatically delete .pi/agent/issueme.json or local issue cache files. Review them before deleting manually.

---

Development

npm ci
npm run validate

Useful checks:

npm run typecheck
npm run format:check
npm run test
npm run smoke:discover
npm run smoke:packaged
npm run smoke:handlers
npm run smoke:pi-lifecycle
npm run check:pack
pi --no-extensions -e .

Development, diagnostics, smoke-test, and live-verification notes are in docs/development.md.

---

Publishing

IssueMe publishes to npm as @senad-d/issueme. Run from a clean working tree after updating CHANGELOG.md.

npm login
npm whoami
node scripts/publish-npm.mjs

The publish script validates, versions, tags, publishes with npm publish --access public, and offers to push the release commit and tag.

---

More Documentation

• docs/workflows.md - visual guide to architecture, supported workflows, and safe recovery; editable diagram sources included.
• docs/usage.md - daily workflows, starter SKILL.md, and prompt examples.
• docs/configuration.md - config schema, auth, trust policy, local cache files, and GitHub request policy.
• docs/tool-reference.md - complete tool catalog, result semantics, examples, and limitations.
• docs/development.md - diagnostics, validation, smoke tests, and release workflow.
• docs/public-contracts.md - public command/tool contract matrix.
• docs/github-api-compatibility.md - pinned REST version, documented versus tested GitHub capabilities, and open unknowns.
• docs/STRUCTURE.md - source layout and architecture boundaries.
• docs/live-github-verification.md - opt-in live GitHub verification plan.
• docs/pi-lifecycle-verification.md - manual pi lifecycle checks.
• SECURITY.md - security policy and threat model.
• CONTRIBUTING.md - contribution guidelines.
• CHANGELOG.md - release history.

---

License

MIT