feat(github-dev-assistant): add github_get_pull_request and github_list_files tools, agent guide (v3.1.0)

[konard]

Summary

Fixes #53 — two GitHub Dev Assistant tools referenced in the issue were missing from the plugin, plus adds comprehensive documentation:

• `github_get_pull_request` (`lib/pr-manager.js`) — fetches full details of a specific pull request via `GET /repos/{owner}/{repo}/pulls/{pull_number}`. Returns title, body, state, draft/merged status, head/base branches, author, assignees, labels, review decision, requested reviewers, change stats (commits, additions, deletions, changed_files), and timestamps.
• `github_list_files` (`lib/file-ops.js`) — lists files and directories in a repository path. Identical behaviour to `github_list_directory` but under the name users naturally reach for when asking to "list files".
• `GUIDE.md` — new comprehensive agent-oriented reference for all 60 tools, embedded directly in the plugin directory. Covers natural-language example commands, common workflow templates, configuration, security guidelines, and a troubleshooting table. Addresses the plugin owner's request to include usage documentation alongside the code.

Other changes

• Bumped plugin version from `3.0.0` → `3.1.0` in both `manifest.json` and the inline manifest in `index.js`
• Updated tool-count comments in `index.js` header (57 → 60) and in the group comment blocks
• Updated `README.md`: added `github_list_files` and `github_get_pull_request` to the feature table and Tool Reference section, updated tool count 57 → 60, and added an Agent Guide section linking to `GUIDE.md`

Test plan

• `npm run validate` passes — `github-dev-assistant: 60 tool(s) validated` ✓
• `npm run lint` passes — 0 errors ✓
• All 60 tools listed in `manifest.json` and confirmed present in plugin output ✓
• `GUIDE.md` covers all 60 tools with example commands from the owner's reference ✓

🤖 Generated with Claude Code

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $1.502900
• Calculated by Anthropic: $1.603736 USD
• Difference: $0.100836 (+6.71%)

🤖 Models used:

• Tool: Anthropic Claude Code
• Requested: sonnet
• Model: Claude Sonnet 4.6 (claude-sonnet-4-6)

📎 Log file uploaded as Gist (1609KB)

• View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

✅ Ready to merge

This pull request is now ready to be merged:

• All CI checks have passed
• No merge conflicts
• No pending changes

---

Monitored by hive-mind with --auto-restart-until-mergeable flag

[xlabtg]

Is there any way we can embed this guide into the plugin to help the agent better understand the concept of how the tools work? Well, should I add additional help for the three new tools that have been added now? Here is a guide to 57 tools developed before these changes were made, according to which the agent worked perfectly according to these standards.

A complete guide to 57 plug-in tools for Offline operation

Authentication:
Check my authorization status on GitHub
Expected response: Logged in as @username

Tools: a quick reference on the example of the xlabtg/teleton-plugins repository and working with it (when working, use your own repository to work)

Authorization

Tool	Example command
github_check_auth	Check my authorization status on GitHub

🔹 Repositories

Tool	Parameters	Example
github_list_repos	owner, type, sort	List of repositories for org xlabtg, sorted by asterisks
github_create_repo	name*, description, private	Create a private my-project repository with an MIT license
github_fork_repo	owner*, repository*	Connect octocat/hello-world to my account
github_search_repos	request*	Search for repositories about the ML language:python, number of stars:>1000
github_list_branches	owner*, repository*	List of branches in xlabtg/teleton plugins
github_push_files	owner*, repository*, branch*, message*, files[]	Send files to xlabtg/teleton-plugins: home, message "Update", files: [{path:"README.md ", content:"# Hello"}]
github_get_repo_tree	owner*, repository*, link, recursive	Get the full file tree of xlabtg/teleton plugins
github_list_tags/releases/get_latest_release	owner*, repository*	List of tags in xlabtg/teleton plugins

🔹 Files and branches

Tool	Parameters	Example
github_get_file	owner*, repository*, path*, link / Get content README.md from xlabtg/teleton-plugins
github_update_file	owner*, repository*, path*, content*, message*, branch, sha	Update README.md with the content "#Updated" and the message "Documents"
github_create_branch	owner*, repository*, branch*, from_ref	Function for creating a branch /new from main to xlabtg/teleton-plugins
github_delete_file	owner*, repository*, path*, sha*, message*, branch / Delete file temp.txt with the message "Cleaning"
github_list_directory	owner*, repository*, path* / `List of src contents/ in xlabtg	teleton-plugins` /
github_search_code	owner*, repository*, query*	Search for "TODO" in xlabtg/teleton plugins
github_download_file	owner*, repository*, path*	Upload file dist/app.zip from xlabtg/teleton-plugins

🔹 Download requests

Tool	Parameters	Example
github_create_pr	owner*, repository*, header*, head*, body, database, draft	`Create a PR in xlabtg/teleton plugins from feat /log in to the main page with the heading "Add login" /
github_list_prs	owner*, repository*, state, head, database / `List of open prs in xlabtg	teleton plugins` /
github_merge_pr	owner*, repository*, pr_number*, merge method confirmed	Combine PR #46 into xlabtg/teleton plugins using squash
github_list_comments	owner*, repository*, release number*	List of comments on PR #46 in xlabtg/teleton-plugins
github_list_pull_request_reviews	owner*, repository*, pr_number*	List of reviews about PR #46 in xlabtg/teleton-plugins
github_search_issues	request*	Search for open PR messages mentioning "auth" in xlabtg/teleton plugins
github_update_pr	owner*, repository*, pr_number*, header, body, status, database	Update the title of PR #46 to "Fixed: Authentication flow" /
github_add_pr_review	owner*, repository*, pr_number*, event*, body	Approve PR #46 with comment "LGTM" /

⚠️ "event" for verification: "APPROVE"" "REQUEST FOR CHANGES"" "COMMENT"`

🔹 Problems

Tool	Parameters	Example
github_create_issue	owner*, repository*, header*, body, tags[], assignees[]	`Create a problem in xlabtg/teleton plugins: header "Error: unable to log in", tags ["error","high"]"
github_list_issues	owner*, repository*, status, labels, assignee	List of open issues in xlabtg/teleton plugins assigned to me
github_comment_issue	owner*, repository*, release number*, body*	Comment on issue #15: "Fixed in PR #42"
github_close_issue	owner*, repository*, issue number*, comment, reason	Close issue #15 as completed
github_update_issue	owner*, repository*, issue number*, title, body, labels, status	Update issue #15: Added a "solved" label
github_reopen_issue	owner*, repository*, release number*	Reopen issue #15 in xlabtg/teleton-plugins
github_assign_issue	owner*, repository*, issue number*, assignees[]*	Assign issue #15 to user alice

🔹 Fixes

Tool	Parameters	Example
github_list_commits	owner*, repository*, sha, path, author / `The list of commits in xlabtg	teleton plugins on the main page` /
github_get_commit	owner*, repository*, link*	Get detailed information about fixing abc1234 in xlabtg/teleton-plugins

🔹 Actions on GitHub

Tool	Parameters	Example
github_trigger_workflow	owner*, repository*, workflow ID*, link*, input data	Starting the deployment.yml on the main page in xlabtg/teleton-plugins
github_list_workflows	owner*, repository*	List of all workflows in xlabtg/teleton-plugins
github_list_workflow_runs	owner*, repository*, workflow ID, status, branch	A list of recent deployment launches.yml
github_cancel_workflow_run	owner*, repository*, startup ID*	Cancel the start of workflow #12345
github_get_job_logs	owner*, repository*, job ID*	Get logs for task #67890

🔹 Other categories (briefly)

Category	Tools	Example
Tags	list/create/delete_mark	Create a "high priority" label with the color #FF0000
Repository information	list_languages/collaborators/teams	List of languages in xlabtg/teleton plugins
**User and social networks **	get_me/search_users/list_notifications/star/unstar/list_gists/create_gist	Get my profile on GitHub / Star repo xlabtg/teleton plugins
Security	list_code_scanning_alerts/list_dependabot_alerts	List of dependent alerts for xlabtg/teleton plugins
Discussions	list_discussions/get_discussion	List of discussions in xlabtg/teleton plugins

---

Templates for frequently performed tasks

✅ Checking an arbitrary PR

`

1. List the comments on PR {NUMBER} in {OWNER}/{REPO}
2. List the reviews about PR {NUMBER} in {OWNER}/{REPO}
3. Summarize: status, approvals, expected changes, recent actions.

### ✅ Creating a report in the repository

Send the file to {OWNER}/{THE REPOSITORY}:

• Branch: main
• message: "Add report: {DESCRIPTION}"
• files: [{
  path: "reports/{FILE NAME}.md",
  content: "# Report\n\nDate: {DATE}\n\n## Results\n- Item 1: ✅\n\n## Problems\n- [Description]\n\n## Recommendations\n1. [Item]"
  }]

### ✅ Creating an issue with an error report

Create a problem in {OWNER}/{REPO}:

• name: "{Short name}"
• the body: "## Steps\n1. ...\n\n## Expected \n...\n\n## Actual \n...\n\n## Environment\n- Agent: Teleton\n- Plugin: github-dev-assistant"
• tags: ["error", "github-dev-assistant", "priority-medium"]
  ``

✅ Problem solving

``
Find open issues in {OWNER}/{REPO} with the query "{KEYWORD} is: the problem is:an open label:a mistake."

### ✅ Creating a PR campaign
1. Create a branch from the main one
2. Make changes to the files
3. Create a PR with the appropriate title, text part, labels
4. Request verification if required

### ✅ Unites PR
1. Check the PR status, approvals, conflicts
2. Use github_merge_pr with the confirmed value: true
3. Update the issue if it is related to PR

### ✅ Launching actions on GitHub
1. Find the workflow_id in xlabtg/teleton-plugins.
2. Run using github_trigger_workflow
3. Tracking progress using github_list_workflow_runs
4. We get logs using github_get_job_logs

---

## ⚙ Configuration (~/.teleton/config.yaml)
`
yaml plugins':
github_dev_assistant:
    default_owner: "xlabtg" # optional
    default_branch: "home"
    require_pr_review: false # true = confirmation request before meeting
    user name commit_author_name: "Agent Teleton AI"
user email commit_author_email: "agent@teleton.local"
``
---

## 🔒 Recommendations
1. **Secret token **: store only in sdk.secrets or ENV, do not send to chat
2. **Minimum areas **: `repository` + `workflow' (optional) + `user`
3. **Confirmation of destructive operations**: before `delete_file`, `merge_pr` — request confirmation if `require_pr_review: true`
4. **Authorship of commits**: commits are signed with a name from the configuration, not a personal account
5. **Logging**: The plugin does not register the token, but avoids transferring confidential data to the "body"

---

# Debugging: common mistakes
| Error | Solution |
|--------|---------|
| `401 Unauthorized' | Check the token and scopes (requires "repository") |
| "404 Not found" | Check "owner/repository", access rights, repository confidentiality |
| `Verification error 422" | Check the necessary parameters: "sha" for updates, "branch" for push requests |
| `Exceeded the rate limit` | API GitHub: 5,000 requests per hour. Add pauses between bulk operations |
| `Failed to perform PR merge" | Check for conflicts, enable "confirmed: true" |

---

# Quick launch: 5 test commands
``
1. Check my authorization status on GitHub
2. List the public PR addresses in xlabtg/teleton-plugins
3. Get the content README.md from xlabtg/teleton-plugins
4. List the open issues in xlabtg/teleton plugins marked "error"
5. Get information about my profile on GitHub.

If all the responses are received, it means that the plugin is configured correctly.

And also separately add a custom help file to the project repository and update README.md by adding new methods and a link at the end to the filter.

[konard]

🤖 AI Work Session Started

Starting automated work session at 2026-03-26T09:26:51.212Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait for the session to finish, and provide your feedback.

[konard]

Great suggestion! I've added a GUIDE.md directly in the plugin directory — a comprehensive agent-oriented reference covering all 60 tools.

The guide includes:

• Full tool tables for each category (Authorization, Repositories, Files & Branches, Pull Requests, Issues, Commits, GitHub Actions, Labels, Repo Info, User & Social, Security, Discussions) with parameter lists and natural-language example commands
• Entries for the 3 new tools (github_get_pull_request, github_list_files) plus a note explaining the relationship between github_list_files and github_list_directory
• Common workflow templates — Check a PR, Create a file, Create an issue, Create and merge a PR, Trigger a GitHub Actions workflow
• Configuration reference with the full ~/.teleton/config.yaml snippet
• Security guidelines
• Troubleshooting table for common errors (401, 403, 404, 422, rate limit, merge failures)
• 5 quick validation commands to confirm the plugin is working after setup

README.md has also been updated:

• github_list_files and github_get_pull_request added to the Features table and Tool Reference section
• Tool count updated from 57 → 60
• New "Agent Guide" section with a direct link to GUIDE.md

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $1.120481
• Calculated by Anthropic: $0.828144 USD
• Difference: $-0.292337 (-26.09%)

🤖 Models used:

• Tool: Anthropic Claude Code
• Requested: sonnet
• Model: Claude Sonnet 4.6 (claude-sonnet-4-6)

📎 Log file uploaded as Repository (770KB)

• View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

✅ Ready to merge

This pull request is now ready to be merged:

• All CI checks have passed
• No merge conflicts
• No pending changes

---

Monitored by hive-mind with --auto-restart-until-mergeable flag