github-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitHub Workflow (Task → Environment Setup → Fix → PR)

GitHub 工作流（任务 → 环境准备 → 修复 → PR）

Goal

目标

Standard flow from "task link or description" to "create PR (no merge)". Task source is any data source: first determine the query method via global config or find-skills, write to global config after confirmation, then use it directly next time.

Output: Branch created,

TODO.md

written, PR link targeting

dev

(origin only).

实现从「任务链接或描述」到「创建PR（不合并）」的标准流程。任务源支持任意数据源：首先通过全局配置或find-skills确定查询方法，确认后写入全局配置，下次可直接使用。

输出结果：已创建分支、已写入

TODO.md

、指向

dev

分支的PR链接（仅针对origin）。

Prerequisites

前置条件

This workflow depends on GitHub PR creation (Step 4). Ensure one of the following before or when the user first runs the workflow:

GitHub skill is available in the user’s skills directory (e.g.
```
~/.agents/skills/github/
```
or your agent’s equivalent). The user can install it via:
- ```
npx skills add hairyf/skills --skill github-cli -g
```
  (or your environment’s skill discovery), then install the suggested skill.
gh
CLI is installed and authenticated:
- Install: GitHub CLI
- Then run:
```
gh auth login
```

When to check: At the start of the workflow (e.g. after the user provides the task), optionally run

gh auth status

. If it fails or the user has no GitHub skill, prompt: "To create the PR in Step 4, the GitHub skill or
gh
CLI is required. Install the GitHub skill (see Prerequisites above) or install and log in with
gh auth login
. You can continue with Steps 1–3 now and set this up before Step 4." Then continue; if Step 4 is reached and

gh

is still missing, use the edge case handling below.

本工作流依赖GitHub PR创建功能（步骤4）。在用户首次运行工作流之前或之时，需确保满足以下任一条件：

GitHub skill已存在于用户的技能目录中（例如
```
~/.agents/skills/github/
```
或你的Agent对应的目录）。用户可通过以下方式安装：
- ```
npx skills add hairyf/skills --skill github-cli -g
```
  （或你的环境对应的技能发现命令），然后安装推荐的技能。
gh
CLI已安装并完成认证：
- 安装地址：GitHub CLI
- 然后运行：
```
gh auth login
```

检查时机：在工作流开始时（例如用户提供任务后），可选择运行

gh auth status

。如果认证失败或用户未安装GitHub skill，提示用户：“要完成步骤4的PR创建，需使用GitHub skill或
gh
CLI。请安装GitHub skill（参见上述前置条件）或安装并通过
gh auth login
完成登录。你可以先继续执行步骤1-3，在步骤4之前完成配置。” 之后继续流程；如果到步骤4时仍未配置

gh

CLI，使用下方的边缘情况处理方案。

Global Data Source Config (Persistent)

全局数据源配置（持久化）

Path:
```
~/.bonfire/source.json
```
(user-level, applies across projects)
Purpose: Once the user confirms a data source's query method, write it here; for the same type of input next time, use it directly and skip find-skills.

Example config (ClickUp):

json

{
  "dataSourceType": "clickup",
  "description": "ClickUp task link",
  "matchPatterns": ["clickup.com/t/", "app.clickup.com"],
  "taskIdPlaceholder": "<task_id>",
  "commands": {
    "get": "node ~/.bonfire/skills/clickup/query.mjs get <task_id> --subtasks",
    "comments": "node ~/.bonfire/skills/clickup/query.mjs comments <task_id>"
  },
  "envCheck": "~/.bonfire/skills/clickup/.env"
}

```
matchPatterns
```
: If input URL or text contains any of these, treat as match and run commands from this config.
```
commands.get
```
/
```
commands.comments
```
: Replace
```
task_id
```
with the ID parsed from input, then execute.
```
envCheck
```
: Optional; if present, check that the .env at this path is configured; if not, prompt the user.

路径：
```
~/.bonfire/source.json
```
（用户级配置，适用于所有项目）
用途：用户确认数据源的查询方法后，将其写入该文件；下次遇到同类型输入时，直接使用该配置，跳过find-skills步骤。

配置示例（ClickUp）：

json

{
  "dataSourceType": "clickup",
  "description": "ClickUp task link",
  "matchPatterns": ["clickup.com/t/", "app.clickup.com"],
  "taskIdPlaceholder": "<task_id>",
  "commands": {
    "get": "node ~/.bonfire/skills/clickup/query.mjs get <task_id> --subtasks",
    "comments": "node ~/.bonfire/skills/clickup/query.mjs comments <task_id>"
  },
  "envCheck": "~/.bonfire/skills/clickup/.env"
}

```
matchPatterns
```
：如果输入的URL或文本包含其中任意一项，则匹配该配置并执行对应的命令。
```
commands.get
```
/
```
commands.comments
```
：将
```
task_id
```
替换为从输入中解析出的ID，然后执行命令。
```
envCheck
```
：可选配置；如果存在，检查该路径下的.env文件是否已配置；若未配置，提示用户完成配置。

Step 1: Get Task Content from Link or Description

步骤1：从链接或描述中获取任务内容

1.1 Check Global Config

1.1 检查全局配置

Read
```
~/.bonfire/source.json
```
.
If it exists and current input (URL or pasted text) matches any
```
matchPatterns
```
:
- Parse task ID from input (common: last path segment of URL or
```
t/<id>
```
  ).
- Use
```
commands.get
```
  ,
```
commands.comments
```
  (replace
```
task_id
```
  with parsed value) to fetch task title, description, status, comments, etc.
- Skip 1.2 (do not run find-skills), go to 1.3 output.

读取
```
~/.bonfire/source.json
```
文件。
如果配置存在，且当前输入（URL或粘贴的文本）匹配任意
```
matchPatterns
```
项：
- 从输入中解析任务ID（通常为URL的最后一个路径段或
```
t/<id>
```
  部分）。
- 使用
```
commands.get
```
  、
```
commands.comments
```
  （将
```
task_id
```
  替换为解析出的ID）获取任务标题、描述、状态、评论等信息。
- 跳过1.2步骤（不运行find-skills），直接进入1.3步骤的输出环节。

1.2 Not Configured or No Match: Discover Data Source (find-skills)

1.2 未配置或无匹配项：发现数据源（find-skills）

Analyze input: Is it a URL or plain text?
- URL: Infer type from domain/path (e.g. clickup, jira, notion, linear, asana).
- Plain text: Infer from keywords (e.g. "ClickUp task", "Jira requirement").
Find skill: Use find-skills to find how to "query tasks from this data source":
- Run:
```
npx skills find <type or keyword>
```
  e.g.
```
npx skills find clickup
```
  ,
```
npx skills find jira task
```
  ,
```
npx skills find task management
```
  .
- If a matching skill exists (e.g. ~/.bonfire/skills/clickup/), prefer SKILL.md or scripts to confirm get-task / get-comments commands.
Present options: List the found skills or command usage (including install and usage) briefly; ask the user to confirm which method to use for "task title, description, comments".
After confirmation, save to global:
- Fill
```
dataSourceType
```
  ,
```
matchPatterns
```
  ,
```
commands
```
  , optional
```
envCheck
```
  using the structure above.
- Write to
```
~/.bonfire/source.json
```
  .
- Tell the user: "Data source config saved; next time for the same type of task it will be used directly and find-skills will be skipped."
Run the confirmed method once to get task info.

分析输入：判断输入是URL还是纯文本？
- URL：从域名/路径推断类型（例如ClickUp、Jira、Notion、Linear、Asana）。
- 纯文本：从关键词推断类型（例如“ClickUp任务”、“Jira需求”）。
查找技能：使用find-skills查找“从该数据源查询任务”的方法：
- 运行命令：
```
npx skills find <type or keyword>
```
  示例：
```
npx skills find clickup
```
  、
```
npx skills find jira task
```
  、
```
npx skills find task management
```
  。
- 如果找到匹配的技能（例如~/.bonfire/skills/clickup/），优先查看SKILL.md或脚本确认get-task / get-comments命令。
展示选项：简要列出找到的技能或命令用法（包括安装和使用方法）；询问用户确认使用哪种方法获取“任务标题、描述、评论”。
确认后保存到全局配置：
- 按照上述配置结构填写
```
dataSourceType
```
  、
```
matchPatterns
```
  、
```
commands
```
  、可选的
```
envCheck
```
  。
- 将配置写入
```
~/.bonfire/source.json
```
  。
- 告知用户：“数据源配置已保存；下次遇到同类型任务时将直接使用该配置，跳过find-skills步骤。”
运行确认后的方法，获取任务信息。

1.3 Output

1.3 输出结果

Task title, status, project/list (if any), issue description (body + comment summary).
kebab-case short description for branch name (from title or ask user to supply).

Fallback: If .env is not configured or find-skills has no usable result, prompt the user to provide "task title, description, and short description for branch"; you can still proceed to Step 2 (branch and TODO.md can use pasted or later-filled content).

任务标题、状态、项目/列表（如有）、问题描述（正文+评论摘要）。
用于分支名称的短横线命名法（kebab-case）简短描述（从任务标题生成，或询问用户提供）。

备选方案：如果.env文件未配置或find-skills未找到可用结果，提示用户提供“任务标题、描述以及用于分支的简短描述”；仍可继续执行步骤2（分支和TODO.md可使用粘贴的内容或后续补充的内容）。

Step 2: Prepare Environment (Create Branch, Write TODO.md)

步骤2：准备环境（创建分支、编写TODO.md）

Branch:

git checkout dev

→

git pull origin dev

→

git checkout -b fix/<short-desc-kebab-case>

(or

feature/...

depending on task type).

TODO.md: Create
```
TODO.md
```
at project root with this structure:

markdown

undefined

分支操作：

git checkout dev

→

git pull origin dev

→

git checkout -b fix/<short-desc-kebab-case>

（或根据任务类型使用

feature/...

前缀）。

TODO.md：在项目根目录创建
```
TODO.md
```
，结构如下：

markdown

undefined

Task: <task title>

Task link: <user-provided link or "see description"> Status: <current status> Project: <project/list name, if any>

Problem description

Todo

Related files

Approach

Search for relevant keywords
Check API calls and type definitions
Inspect related components and pages
Understand data flow and display logic


- **Optional**: Update `.bonfire/index.md` with current branch and "Next Session Priorities".

---

Search for relevant keywords
Check API calls and type definitions
Inspect related components and pages
Understand data flow and display logic


- **可选操作**：更新`.bonfire/index.md`，记录当前分支和“下次会话优先级”。

---

Step 3: Wait for User to Finish Fixes

步骤3：等待用户完成修复

Agent does not change business code; the user completes the fix, self-test, and commit. After the user says "fix done", proceed to Step 4.

Agent不会修改业务代码；用户需完成修复、自测并提交代码。当用户表示“修复完成”后，进入步骤4。

Step 4: Create PR with GitHub Skill (Origin Only)

步骤4：使用GitHub Skill创建PR（仅针对Origin）

Precondition: Confirm current branch has the fix commits and will be pushed to origin.

Actions:

```
git push -u origin <branch>
```
(push to origin only).

gh pr create --base dev --head <branch> --title "<title>" --body "<body with task link etc>"

(do not pass

--repo

; use current repo = origin).

Constraint: Do not use
```
--repo <other-org/repo>
```
or any other remote for the PR. If
```
origin
```
is read-only or archived, output an error and suggest updating
```
origin
```
or creating the PR manually on the repo’s web UI.
End: Output the PR link; do not merge.

前置检查：确认当前分支已包含修复提交，且将推送到origin。

操作步骤：

```
git push -u origin <branch>
```
（仅推送到origin）。

gh pr create --base dev --head <branch> --title "<title>" --body "<body with task link etc>"

（不要传递

--repo

参数；使用当前仓库=origin）。

约束条件：不要使用
```
--repo <other-org/repo>
```
或其他远程仓库创建PR。如果
```
origin
```
是只读或已归档，输出错误信息并建议用户更新
```
origin
```
或在仓库的Web界面手动创建PR。
结束：输出PR链接；不要执行合并操作。

Edge Cases

边缘情况处理

Case	Handling
No global config and find-skills has no result	Ask user to provide task title, description, and short branch description; still create branch and TODO.md.
Data source .env not set or token invalid	Prompt to configure (e.g. .env at `envCheck` path), or ask user to provide task info directly.
`git pull origin dev` fails	Suggest checking network and `origin` access; or create branch from current local `dev` and note "latest not pulled".
Branch `fix/<name>` already exists	Ask whether to continue on existing branch or use a new name (e.g. `fix/<name>-v2` ).
`origin` is archived or read-only	Do not add another remote; report error and suggest updating `origin` or creating PR on the repo’s web UI.
User asks for PR before saying "fix done"	If there are new commits and user explicitly requests, run Step 4; otherwise remind to finish fix and commit first.
`gh` not installed or not logged in	See Prerequisites. Prompt to install the GitHub skill or run `gh auth login` ; or give steps to create PR from branch on GitHub web.

场景	处理方案
无全局配置且find-skills未找到结果	询问用户提供任务标题、描述以及用于分支的简短描述；仍可创建分支和TODO.md。
数据源.env文件未配置或令牌无效	提示用户完成配置（例如 `envCheck` 路径下的.env文件），或询问用户直接提供任务信息。
`git pull origin dev` 执行失败	建议用户检查网络和 `origin` 权限；或基于本地当前的 `dev` 分支创建分支，并标注“未拉取最新代码”。
分支 `fix/<name>` 已存在	询问用户是否继续使用现有分支或使用新名称（例如 `fix/<name>-v2` ）。
`origin` 已归档或只读	不要添加其他远程仓库；报告错误并建议用户更新 `origin` 或在仓库Web界面手动创建PR。
用户在表示“修复完成”前要求创建PR	如果存在新提交且用户明确要求，执行步骤4；否则提醒用户先完成修复并提交代码。
`gh` CLI未安装或未登录	参见前置条件部分。提示用户安装GitHub skill或运行 `gh auth login` ；或提供在GitHub Web界面从分支创建PR的步骤。

Reference

参考资料

Full spec and decision table: github-workflow-spec.md

Task data source example: project ClickUp skill

~/.bonfire/skills/clickup/SKILL.md

(

query.mjs get/comments

)

PR tool:
```
~/.agents/skills/github/SKILL.md
```
(
```
gh
```
CLI)
Discover more data source skills: use find-skills (
```
npx skills find <keyword>
```
)

完整规范和决策表：github-workflow-spec.md

任务数据源示例：项目ClickUp skill

~/.bonfire/skills/clickup/SKILL.md

（

query.mjs get/comments

）

PR工具：
```
~/.agents/skills/github/SKILL.md
```
（
```
gh
```
CLI）
发现更多数据源技能：使用find-skills（
```
npx skills find <keyword>
```
）