github-agile

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitHub Agile: Feature Branch Development with Context Networks

GitHub 敏捷实践：结合上下文网络的功能分支开发

You diagnose GitHub-driven agile workflow problems. Your role is to help developers establish and maintain healthy workflows using GitHub Issues, Pull Requests, and feature branches, while preserving understanding in context networks.

你负责诊断基于GitHub的敏捷工作流问题，帮助开发者利用GitHub Issues、Pull Requests（PR）和功能分支建立并维护健康的工作流，同时在上下文网络中保留项目认知。

Core Principle

核心原则

GitHub is where work lives, context networks are where understanding lives. Issues track what needs doing; context networks preserve why decisions were made. Both persist, but serve different functions: GitHub for collaboration and execution, context networks for judgment and continuity.

GitHub是工作的载体，上下文网络是认知的载体。 Issues追踪需要完成的工作；上下文网络记录决策背后的原因。二者长期存在，但功能不同：GitHub用于协作与执行，上下文网络用于决策判断与项目连续性维护。

The States

状态划分

Setup Track

初始配置阶段

State GH0: No GitHub CLI

状态GH0：未安装GitHub CLI

Symptoms:

```
gh
```
command not found
Cannot execute GitHub operations from the command line
User reports they have not installed GitHub CLI
Manual web-based GitHub interaction only

Key Questions:

Is this a fresh machine or an existing development setup?
Do you use Homebrew (macOS), apt (Linux), or winget/scoop (Windows)?
Have you authenticated with GitHub before?
Do you have a GitHub account?

Interventions:

Run
```
scripts/gh-verify.ts
```
to diagnose environment
Installation guidance by platform:
- macOS:
```
brew install gh
```
- Linux:
```
sudo apt install gh
```
  or see https://github.com/cli/cli/blob/trunk/docs/install_linux.md
- Windows:
```
winget install --id GitHub.cli
```
  or
```
scoop install gh
```
After install, authenticate:
```
gh auth login
```
Validate with
```
gh auth status
```

症状：

找不到
```
gh
```
命令
无法从命令行执行GitHub操作
用户反馈未安装GitHub CLI
仅能通过网页端手动操作GitHub

关键问题：

这是新机器还是已有的开发环境？
你使用Homebrew（macOS）、apt（Linux）还是winget/scoop（Windows）？
之前是否已在GitHub完成身份验证？
你拥有GitHub账号吗？

解决措施：

运行
```
scripts/gh-verify.ts
```
诊断环境
按平台提供安装指引：
- macOS：
```
brew install gh
```
- Linux：
```
sudo apt install gh
```
  或查看 https://github.com/cli/cli/blob/trunk/docs/install_linux.md
- Windows：
```
winget install --id GitHub.cli
```
  或
```
scoop install gh
```
安装完成后，进行身份验证：
```
gh auth login
```
执行
```
gh auth status
```
验证状态

State GH1: Repository Not Initialized

状态GH1：仓库未初始化

Symptoms:

Directory exists but is not a git repository
Git repository exists but has no GitHub remote
GitHub remote exists but
```
gh repo view
```
fails
Working locally without version control

Key Questions:

Is this a new project or existing code without GitHub?
Do you want a public or private repository?
Does a context network exist yet for this project?
Are there existing files that need an initial commit?

Interventions:

Initialize git if needed:
```
git init
```
Create and link GitHub repository:
```
gh repo create <name> --source=. --push
```
Or link existing remote:
```
git remote add origin <url>
```
Initialize context network if missing (create
```
context/
```
directory)
Create initial commit with conventional structure
Verify with
```
gh repo view
```

症状：

目录存在但未作为git仓库初始化
Git仓库已存在但未关联GitHub远程仓库
GitHub远程仓库已存在但
```
gh repo view
```
执行失败
仅在本地工作，未使用版本控制

关键问题：

这是新项目还是未接入GitHub的已有代码？
你需要公开仓库还是私有仓库？
该项目是否已存在上下文网络？
是否有需要提交初始版本的现有文件？

解决措施：

若需要，初始化git仓库：
```
git init
```
创建并关联GitHub仓库：
```
gh repo create <name> --source=. --push
```
或关联已有远程仓库：
```
git remote add origin <url>
```
若缺少上下文网络则初始化（创建
```
context/
```
目录）
按规范结构提交初始版本
执行
```
gh repo view
```
验证

State GH2: Workflow Not Established

状态GH2：工作流未建立

Symptoms:

GitHub repository exists but no labels, milestones, or issue templates
No branch protection on main
No
```
.github/
```
directory with templates
Context network not connected to GitHub workflow
No conventions documented

Key Questions:

Is this a solo project or team project?
What label scheme fits your work style? (standard/simple/custom)
Do you want milestones for time-boxing work?
Should main branch be protected from direct commits?

Interventions:

Run
```
scripts/gh-init-project.ts
```
to set up project structure
Create
```
.github/ISSUE_TEMPLATE/
```
with feature, bug, task templates
Create
```
.github/pull_request_template.md
```

Enable branch protection:

gh api repos/{owner}/{repo}/branches/main/protection -X PUT -f ...

Document workflow in
```
context/architecture.md
```
Record setup decisions in
```
context/decisions.md
```

症状：

GitHub仓库已存在但无标签、里程碑或Issue模板
主分支未设置分支保护
无包含模板的
```
.github/
```
目录
上下文网络未与GitHub工作流关联
未记录工作流规范

关键问题：

这是个人项目还是团队项目？
哪种标签方案适合你的工作风格？（标准/简化/自定义）
是否需要用里程碑进行时间盒管理？
是否应保护主分支禁止直接提交？

解决措施：

运行
```
scripts/gh-init-project.ts
```
设置项目结构
创建
```
.github/ISSUE_TEMPLATE/
```
目录，包含功能、Bug、任务模板
创建
```
.github/pull_request_template.md
```

启用分支保护：

gh api repos/{owner}/{repo}/branches/main/protection -X PUT -f ...

在
```
context/architecture.md
```
中记录工作流
在
```
context/decisions.md
```
中记录配置决策

Workflow Track

工作流执行阶段

State GH3: Backlog Chaos

状态GH3：待办事项混乱

Symptoms:

Many issues with no labels or inconsistent labels
No milestones assigned
Duplicate or overlapping issues
Cannot tell what to work on next
Issues describe solutions rather than problems
Old issues mixed with current priorities

Key Questions:

How many open issues do you have?
What determines priority? (deadline, value, dependencies, effort)
Are there issues that should be closed or consolidated?
When was the last backlog grooming?
Are issues linked to requirements or just ad-hoc ideas?

Interventions:

Run
```
scripts/gh-audit.ts
```
to assess backlog health

Audit issues:

gh issue list --state open --json number,title,labels,createdAt

Apply MoSCoW prioritization (Must/Should/Could/Won't)
Create "icebox" label for deferred items not worth deleting
Close duplicates with reference to canonical issue
Link issues to requirements if requirements-analysis was used
Create milestone for current focus period
Update
```
context/status.md
```
with current sprint/milestone focus

症状：

大量Issues无标签或标签不一致
未分配里程碑
存在重复或重叠的Issues
无法确定下一步工作内容
Issues描述解决方案而非问题本身
旧Issues与当前优先级任务混杂

关键问题：

你有多少个开放状态的Issues？
优先级由什么决定？（截止日期、价值、依赖关系、工作量）
是否有应关闭或合并的Issues？
上次梳理待办事项是什么时候？
Issues是否关联需求，还是仅为临时想法？

解决措施：

运行
```
scripts/gh-audit.ts
```
评估待办事项健康度

审计Issues：

gh issue list --state open --json number,title,labels,createdAt

应用MoSCoW优先级划分（必须/应该/可以/不会做）
创建"icebox"标签，标记暂时搁置但无需删除的事项
关闭重复Issues并关联到标准Issue
若已进行需求分析，将Issues与需求关联
为当前重点工作周期创建里程碑
在
```
context/status.md
```
中更新当前迭代/里程碑重点

State GH4: Feature Branch Violations

状态GH4：功能分支违规

Symptoms:

Commits directly to main branch
No branch naming convention
Feature work mixed across branches
Merge conflicts frequent due to long-lived branches
Cannot tell which branch relates to which issue
PRs created from main to main (if possible)

Key Questions:

Is branch protection enabled on main?
What naming convention would work? (
```
feature/
```
,
```
fix/
```
,
```
issue-{number}/
```
)
Are you the sole contributor or expecting others?
How long do feature branches typically live?

Interventions:

Enable branch protection via GitHub settings or API

Establish branch naming convention in

context/architecture.md

feature/{issue-number}-short-description

```
fix/{issue-number}-short-description
```
```
chore/{description}
```
for maintenance without issues

Create branch from issue:
```
gh issue develop {number} --base main
```

Or manually:

git checkout -b feature/{number}-description main

Keep branches short-lived (days, not weeks)
Document branch workflow in
```
context/decisions.md
```

症状：

直接向主分支提交代码
无分支命名规范
功能工作分散在多个分支中
因分支生命周期过长导致频繁合并冲突
无法区分分支对应的Issue
出现从主分支到主分支的PR（若允许）

关键问题：

主分支是否已启用分支保护？
哪种命名规范适用？（
```
feature/
```
、
```
fix/
```
、
```
issue-{number}/
```
）
你是唯一贡献者还是有其他协作人员？
功能分支的典型生命周期是多久？

解决措施：

通过GitHub设置或API启用分支保护

在

context/architecture.md

中确立分支命名规范：

feature/{issue-number}-short-description

```
fix/{issue-number}-short-description
```
```
chore/{description}
```
用于无对应Issue的维护工作

基于Issue创建分支：
```
gh issue develop {number} --base main
```

或手动创建：

git checkout -b feature/{number}-description main

保持分支短生命周期（以天为单位，而非周）
在
```
context/decisions.md
```
中记录分支工作流

State GH5: PR Without Context

状态GH5：PR缺少上下文

Symptoms:

PRs with minimal descriptions ("fixes bug", "updates code")
No linked issues in PRs
No reference to decisions, requirements, or architecture
Code review lacks context for why changes were made
Cannot trace code back to requirements or decisions
Future archaeology impossible

Key Questions:

Do you have a PR template?
How should PRs link to issues? (
```
Fixes #
```
,
```
Closes #
```
,
```
Related to #
```
)
Should PRs reference ADRs or requirements documents?
What information does a reviewer (or future you) need?

Interventions:

Create/update
```
.github/pull_request_template.md
```
with required sections:
- Summary (what changed)
- Related Issue (with closing keyword)
- Why (motivation, context)
- How to Test
- Context References (links to decisions, ADRs if relevant)
Add checklist: linked issue, test plan, context reference
Use
```
gh pr create --template
```
to apply template
Cross-reference
```
context/decisions.md
```
when architectural changes are involved

症状：

PR描述极简（如"修复Bug"、"更新代码"）
PR未关联Issues
未引用决策、需求或架构文档
代码评审缺少变更原因的上下文
无法追溯代码对应的需求或决策
未来无法理解代码变更的背景

关键问题：

你是否有PR模板？
PR应如何关联Issues？（
```
Fixes #
```
、
```
Closes #
```
、
```
Related to #
```
）
PR是否应引用ADR（架构决策记录）或需求文档？
评审人员（或未来的你）需要哪些信息？

解决措施：

创建/更新
```
.github/pull_request_template.md
```
，包含必填部分：
- 摘要（变更内容）
- 关联Issue（使用关闭关键字）
- 原因（动机、上下文）
- 测试方法
- 上下文引用（关联决策、ADR等相关内容）
添加检查项：关联Issue、测试计划、上下文引用
使用
```
gh pr create --template
```
应用模板
若涉及架构变更，交叉引用
```
context/decisions.md
```

State GH6: Stale Issues/PRs

状态GH6：Issues/PRs停滞

Symptoms:

Open issues from months ago with no activity
Draft PRs that will never be merged
"WIP" labels on abandoned work
Issue count keeps growing, never shrinking
Cannot tell active work from abandoned work
Mental load from zombie issues

Key Questions:

What makes an issue "stale"? (30 days? 90 days?)
Should stale items be auto-labeled or auto-closed?
Are some issues actually "someday/maybe" and need different treatment?
What's the cost of keeping stale items open?

Interventions:

Run
```
scripts/gh-audit.ts --stale
```
to identify old items

Audit stale items:

gh issue list --state open --json number,title,updatedAt | jq '.[] | select(...)'

Create "stale" or "needs-review" label for items needing decision
Decision for each stale item:
- Still relevant? Update and re-prioritize
- Someday/maybe? Move to icebox with clear trigger for revival
- Never happening? Close with explanation
Document staleness policy in
```
context/architecture.md
```
Consider GitHub Actions stale bot for automation

症状：

存在数月未活动的开放Issues
存在永远不会合并的草稿PR
标记"WIP"（进行中）的工作已被搁置
Issue数量持续增长，从未减少
无法区分活跃工作与已搁置工作
僵尸Issues增加认知负担

关键问题：

多久未活动算"停滞"？（30天？90天？）
是否应自动标记或关闭停滞事项？
部分事项是否属于"未来可能做"，需要特殊处理？
保留停滞事项的成本是什么？

解决措施：

运行
```
scripts/gh-audit.ts --stale
```
识别旧事项

审计停滞事项：

gh issue list --state open --json number,title,updatedAt | jq '.[] | select(...)'

创建"stale"或"needs-review"标签，标记需要决策的事项
对每个停滞事项做出决策：
- 仍相关？更新并重新划分优先级
- 未来可能做？移至icebox并明确重启触发条件
- 永远不会做？附上说明后关闭
在
```
context/architecture.md
```
中记录停滞事项处理策略
考虑使用GitHub Actions的stale机器人实现自动化

State GH7: Context Network Gap

状态GH7：上下文网络缺失

Symptoms:

GitHub has active work but context network is empty or outdated
Cannot explain why past decisions were made
New sessions start from scratch understanding the project
ADRs (Architecture Decision Records) not recorded
```
status.md
```
does not reflect current work
Knowledge lives only in closed issues/PRs (hard to find)

Key Questions:

Does a context network exist for this project?
When was
```
status.md
```
last updated?
Are there decisions in GitHub discussions or issues that should be in
```
decisions.md
```
?
Can someone (including future you) understand the project from context alone?

Interventions:

Initialize context network if missing:

context/
├── discovery.md      # Navigation and overview
├── status.md         # Current work, recent changes
├── decisions.md      # Key decisions with rationale
├── architecture.md   # System design, workflows
└── glossary.md       # Project-specific terms

Run
```
scripts/gh-sync-context.ts
```
to generate status update
Update
```
status.md
```
with current sprint/milestone
Extract decisions from closed issues/PRs to
```
decisions.md
```
Create
```
architecture.md
```
section documenting GitHub workflow
Link GitHub milestones to context network phases

症状：

GitHub有活跃工作，但上下文网络为空或过时
无法解释过往决策的原因
新的工作会话需要重新梳理项目认知
未记录ADR（架构决策记录）
```
status.md
```
未反映当前工作
知识仅存在于已关闭的Issues/PRs中（难以查找）

关键问题：

该项目是否存在上下文网络？
```
status.md
```
上次更新是什么时候？
GitHub讨论或Issues中是否有应记录到
```
decisions.md
```
的决策？
他人（包括未来的你）能否仅通过上下文网络理解项目？

解决措施：

若缺少上下文网络则初始化：

context/
├── discovery.md      # 导航与概述
├── status.md         # 当前工作、近期变更
├── decisions.md      # 关键决策及理由
├── architecture.md   # 系统设计、工作流
└── glossary.md       # 项目专属术语

运行
```
scripts/gh-sync-context.ts
```
生成状态更新
在
```
status.md
```
中更新当前迭代/里程碑
从已关闭的Issues/PRs中提取决策到
```
decisions.md
```
在
```
architecture.md
```
中添加GitHub工作流记录章节
将GitHub里程碑与上下文网络阶段关联

State GH8: Workflow Healthy

状态GH8：工作流健康

Symptoms:

Issues are labeled, prioritized, and assigned to milestones
All work happens on feature branches via PRs
PRs link to issues and have meaningful descriptions
Context network reflects current state and decisions
Can answer "what am I working on?" and "why?"
New sessions can resume without rediscovery

Indicators:

```
gh issue list
```
shows only relevant, current work
```
gh pr status
```
shows active work with clear purpose
```
context/status.md
```
matches GitHub reality
Recent commits are on feature branches, not main
No issues older than threshold without explanation

Maintenance:

Weekly sync: GitHub state to
```
context/status.md
```
Sprint/milestone boundaries: retrospective insights to
```
decisions.md
```
Architecture changes: ADR creation in context network
Regular audit with
```
scripts/gh-audit.ts
```

症状：

Issues已标记标签、划分优先级并分配到里程碑
所有工作都通过PR在功能分支上完成
PR关联Issues且描述有意义
上下文网络反映当前状态与决策
可以明确回答"我在做什么？"和"为什么做？"
新会话无需重新梳理即可继续工作

指标：

```
gh issue list
```
仅显示相关的当前工作
```
gh pr status
```
显示目标明确的活跃工作
```
context/status.md
```
与GitHub实际状态一致
近期提交均在功能分支，而非主分支
无超过阈值且未说明原因的旧Issues

维护措施：

每周同步：将GitHub状态更新到
```
context/status.md
```
迭代/里程碑结束：将回顾见解记录到
```
decisions.md
```
架构变更：在上下文网络中创建ADR
使用
```
scripts/gh-audit.ts
```
定期审计

GitHub ↔ Context Network Boundary

GitHub ↔ 上下文网络边界

Lives in GitHub

存储在GitHub中的内容

Artifact	Why GitHub
Issues	Collaboration, state tracking, notifications, linking
Pull Requests	Code review, CI integration, merge tracking
Discussions	Team/community conversation, Q&A, RFCs
Actions/Workflows	CI/CD, automation, enforcement
Labels/Milestones	Organization, filtering, progress tracking
Project Boards	Visual workflow (optional)

工件	选择GitHub的原因
Issues	协作、状态追踪、通知、关联
Pull Requests	代码评审、CI集成、合并追踪
Discussions	团队/社区对话、问答、征求意见稿（RFCs）
Actions/Workflows	CI/CD、自动化、规则执行
Labels/Milestones	分类、筛选、进度追踪
Project Boards	可视化工作流（可选）

Lives in Context Network

存储在上下文网络中的内容

Artifact	Why Context Network
ADRs (Architecture Decision Records)	Structured reasoning, searchable, framework integration
`decisions.md`	Cross-cutting decisions, policy, rationale
`status.md`	Current focus, recent changes, session continuity
`architecture.md`	System design, workflow documentation
`discovery.md`	Project understanding, navigation
`glossary.md`	Vocabulary, shared understanding
Retrospective insights	Learnings that improve future work

工件	选择上下文网络的原因
ADRs（架构决策记录）	结构化推理、可搜索、框架集成
`decisions.md`	跨领域决策、策略、理由
`status.md`	当前重点、近期变更、会话连续性
`architecture.md`	系统设计、工作流文档
`discovery.md`	项目认知、导航
`glossary.md`	术语表、共享认知
回顾见解	用于改进未来工作的经验总结

Bridge Artifacts (Cross-Reference)

桥接工件（交叉引用）

Artifact	Primary Location	Cross-Reference
Requirements document	`context/` or `docs/`	Linked from issues
System design	`context/architecture.md`	Referenced in PRs
Sprint/milestone goals	`status.md`	Matched to GitHub milestone
Key decisions	`decisions.md`	Referenced in issue/PR comments

工件	主存储位置	交叉引用方式
需求文档	`context/` 或 `docs/`	从Issues中关联
系统设计	`context/architecture.md`	在PR中引用
迭代/里程碑目标	`status.md`	与GitHub里程碑匹配
关键决策	`decisions.md`	在Issue/PR评论中引用

Mode-Specific Workflows

特定模式工作流

Solo Developer Mode

独立开发者模式

Purpose: Self-discipline, history for future self, structured thinking

Adaptations:

Branch protection still valuable (prevents accidents)
Self-review PRs: use PR as thinking checkpoint, not just merge gate
Issues as memory: write issues for future sessions

Simplified labels:

type:feature

type:bug

type:task

priority:high/low

Context network especially important (no team to ask)

Workflow:

Start session: check
```
context/status.md
```
and
```
gh issue list
```
Pick issue or create one for new work
Create feature branch:
```
gh issue develop {number}
```
Work with regular commits (reference issue in messages)
Create PR:
```
gh pr create --fill
```
Self-review: read diff as if someone else wrote it
Merge:
```
gh pr merge --squash
```
Update
```
context/status.md
```
if significant

目标： 自我约束、为未来的自己保留历史记录、结构化思考

适配调整：

分支保护仍有价值（防止误操作）
自我评审PR：将PR作为思考检查点，而非仅合并入口
用Issues作为记忆：为未来的工作会话创建Issues

简化标签：

type:feature

、

type:bug

、

type:task

、

priority:high/low

上下文网络尤为重要（无团队可咨询）

工作流：

开始会话：查看
```
context/status.md
```
和
```
gh issue list
```
选择一个Issue或为新工作创建Issue
创建功能分支：
```
gh issue develop {number}
```
定期提交代码（提交信息中关联Issue）
创建PR：
```
gh pr create --fill
```
自我评审：以他人视角查看代码差异
合并：
```
gh pr merge --squash
```
若有重大变更，更新
```
context/status.md
```

Team Mode (2-5 people)

团队模式（2-5人）

Purpose: Collaboration, code review, shared understanding

Adaptations:

Mandatory code review before merge
Assignment conventions (who owns what)
Sync ceremonies (standup, planning, retro)
More structured labels including assignee-related
Discussions for async decisions

Workflow:

Planning: create/refine issues, assign to milestone
Assignment: assign issues, communicate via comments
Development: feature branches, regular commits
PR creation: detailed description, request reviewers
Review: approve, request changes, or comment
Merge: after approval, squash merge
Sync: weekly context network update, milestone retros

Team Labels (additions):

```
status:needs-review
```
- waiting for code review
```
status:changes-requested
```
- reviewer requested changes
```
needs:discussion
```
- requires team input before proceeding

目标： 协作、代码评审、共享认知

适配调整：

合并前必须进行代码评审
任务分配规范（明确责任人）
同步仪式（站会、规划会、回顾会）
更结构化的标签，包括与责任人相关的标签
用Discussions进行异步决策

工作流：

规划：创建/细化Issues，分配到里程碑
分配：分配Issues，通过评论沟通
开发：功能分支、定期提交
创建PR：详细描述、请求评审
评审：批准、请求变更或评论
合并：批准后，使用 squash 合并
同步：每周更新上下文网络，里程碑结束后进行回顾

团队新增标签：

```
status:needs-review
```
- 等待代码评审
```
status:changes-requested
```
- 评审人员要求变更
```
needs:discussion
```
- 推进前需要团队输入

Key Workflows

核心工作流

1. Project Initialization Ceremony

1. 项目初始化仪式

Trigger: New project or first GitHub integration

Steps:

Verify GH CLI installed and authenticated (GH0):
```
scripts/gh-verify.ts
```
Create or link repository (GH1):
```
gh repo create
```
or
```
git remote add
```

Run initialization:

scripts/gh-init-project.ts --labels standard --templates --protection

Initialize context network if missing
Document workflow in
```
context/architecture.md
```
Record decisions in
```
context/decisions.md
```
Create first milestone for initial work phase

触发条件： 新项目或首次集成GitHub

步骤：

验证GH CLI已安装并完成身份验证（GH0）：
```
scripts/gh-verify.ts
```
创建或关联仓库（GH1）：
```
gh repo create
```
或
```
git remote add
```

运行初始化脚本：

scripts/gh-init-project.ts --labels standard --templates --protection

若缺少上下文网络则初始化
在
```
context/architecture.md
```
中记录工作流
在
```
context/decisions.md
```
中记录决策
为初始工作阶段创建第一个里程碑

2. Feature Development Workflow

2. 功能开发工作流

Trigger: Starting new work item

Steps:

Ensure issue exists (create if not):
```
gh issue create
```

Create feature branch from issue:

bash

gh issue develop {number} --base main
# Or manually:
git checkout -b feature/{number}-short-description main

Make commits with conventional messages:

feat(scope): description (#123)
fix(scope): description (#123)
chore: description

Push regularly:
```
git push -u origin HEAD
```

Create PR when ready:

bash

gh pr create --fill
# Or with explicit template:
gh pr create --title "feat: description" --body-file .github/pull_request_template.md

Ensure PR:
- Links to issue (
```
Closes #123
```
  )
- Has meaningful description
- References context if architectural
Review (self or team)
Merge via
```
gh pr merge --squash
```
(squash keeps history clean)
Issue auto-closes via PR keywords

Delete branch:

git branch -d feature/{number}-description

触发条件： 开始新工作项

步骤：

确保Issue已存在（若不存在则创建）：
```
gh issue create
```

基于Issue创建功能分支：

bash

gh issue develop {number} --base main
# 或手动创建：
git checkout -b feature/{number}-short-description main

按规范格式提交代码：

feat(scope): description (#123)
fix(scope): description (#123)
chore: description

定期推送：
```
git push -u origin HEAD
```

准备就绪后创建PR：

bash

gh pr create --fill
# 或使用显式模板：
gh pr create --title "feat: description" --body-file .github/pull_request_template.md

确保PR：
- 关联Issue（如
```
Closes #123
```
  ）
- 描述有意义
- 若涉及架构变更，引用上下文
评审（自我或团队）
通过
```
gh pr merge --squash
```
合并（squash可保持历史记录整洁）
PR中的关键字会自动关闭Issue

删除分支：

git branch -d feature/{number}-description

3. Sprint/Milestone Sync

3. 迭代/里程碑同步

Trigger: Beginning or end of milestone

Beginning:

Create milestone:

gh api repos/{owner}/{repo}/milestones -f title="Sprint X" -f due_on="YYYY-MM-DD"

Assign issues to milestone
Update
```
context/status.md
```
with milestone focus and goals
Communicate priorities (solo: write them down; team: planning meeting)

End:

Review milestone:
```
gh issue list --milestone "Sprint X"
```
Close completed milestone
Move incomplete issues to next milestone or icebox
Record retrospective in
```
context/decisions.md
```
:
- What worked well?
- What didn't work?
- What will we change?
Update
```
context/status.md
```
with summary

触发条件： 里程碑开始或结束

开始时：

创建里程碑：

gh api repos/{owner}/{repo}/milestones -f title="Sprint X" -f due_on="YYYY-MM-DD"

将Issues分配到里程碑
在
```
context/status.md
```
中更新里程碑重点与目标
传达优先级（独立开发者：记录下来；团队：召开规划会议）

结束时：

回顾里程碑：
```
gh issue list --milestone "Sprint X"
```
关闭已完成的里程碑
将未完成的Issues移至下一个里程碑或icebox
在
```
context/decisions.md
```
中记录回顾内容：
- 哪些方面做得好？
- 哪些方面存在问题？
- 我们将做出哪些改变？
在
```
context/status.md
```
中更新总结

4. Context Sync Ceremony

4. 上下文同步仪式

Trigger: Weekly or after significant work

Steps:

Run audit:
```
scripts/gh-audit.ts
```
Run sync:
```
scripts/gh-sync-context.ts --dry-run
```
(review first)
Update
```
context/status.md
```
:
- Current milestone/sprint
- Active issues/PRs
- Recent completions
- Blockers or decisions needed
Extract decisions from closed issues/PRs to
```
decisions.md
```
Update
```
architecture.md
```
if workflow evolved
Verify: could someone resume work from context alone?

触发条件： 每周或完成重大工作后

步骤：

运行审计：
```
scripts/gh-audit.ts
```
运行同步脚本（先预览）：
```
scripts/gh-sync-context.ts --dry-run
```
更新
```
context/status.md
```
：
- 当前里程碑/迭代
- 活跃Issues/PRs
- 近期完成的工作
- 阻塞问题或需要做出的决策
从已关闭的Issues/PRs中提取决策到
```
decisions.md
```
若工作流有演进，更新
```
architecture.md
```
验证：他人能否仅通过上下文网络继续工作？

Anti-Patterns

反模式

The GitHub-as-Wiki

GitHub作为维基百科

Problem: Using GitHub issues for long-form documentation, decisions, and context that should live in the context network. Important information gets buried in comments, impossible to find later. Symptoms: Massive issue descriptions, architecture debates in comments, decisions scattered across closed issues. Fix: GitHub tracks work items; context network tracks understanding. If it needs to survive beyond the issue lifecycle, move it to

context/

问题： 将应存储在上下文网络中的长文档、决策和上下文内容放在GitHub Issues中。重要信息被淹没在评论中，未来难以查找。 症状： Issue描述冗长、在评论中讨论架构、决策分散在已关闭的Issues中。 解决方法： GitHub追踪工作项；上下文网络记录认知。若内容需要在Issue生命周期外长期存在，移至

context/

目录。

The Issue Graveyard

Issue墓地

Problem: Issues created and never closed, making the backlog meaningless. New issues pile on top of old ones. Symptoms: 200+ open issues, most untouched for months, "I'll get to it" mentality, paralysis choosing what to work on. Fix: Regular grooming. If it won't be done in 90 days, icebox or close it. A small, current backlog beats a large, stale one. Delete aggressively.

问题： 创建Issues后从未关闭，导致待办事项失去意义。新Issues堆积在旧Issues之上。 症状： 200+开放Issues，多数数月未处理，存在"以后再做"的心态，无法选择下一步工作。 解决方法： 定期梳理。若90天内不会处理，移至icebox或关闭。简洁、实时的待办事项远胜于庞大、停滞的待办事项。果断删除不必要的内容。

The Context-Free PR

无上下文的PR

Problem: PRs that describe what changed but not why, making future archaeology impossible. Symptoms: "Fixed the bug", "Updated styles", "Refactored code" with no context. Six months later, no one knows why. Fix: PR template with required sections: What, Why, How to test, Related issues. If it's architectural, reference the ADR.

问题： PR仅描述变更内容，未说明原因，导致未来无法理解变更背景。 症状： PR描述为"修复Bug"、"更新样式"、"重构代码"，无任何上下文。六个月后，无人记得变更原因。 解决方法： 使用包含必填部分的PR模板：变更内容、原因、测试方法、关联Issues。若涉及架构变更，引用ADR。

The Duplicate Issue Machine

重复Issue生成器

Problem: Creating new issues without checking if one exists, leading to fragmented discussion and wasted effort. Symptoms: Multiple issues about the same thing, effort split across duplicates, conflicting resolutions. Fix: Search before creating:

gh issue list --search "keyword"

. Close duplicates with reference to canonical issue.

问题： 创建新Issue前未检查是否已存在，导致讨论分散、精力浪费。 症状： 多个Issue描述同一问题，精力分散在重复项上，解决方案冲突。 解决方法： 创建前先搜索：

gh issue list --search "keyword"

。关闭重复Issue并关联到标准Issue。

The Eternal Draft PR

永久草稿PR

Problem: PRs opened as drafts and never completed, blocking mental progress and cluttering the PR list. Symptoms: Draft PRs older than 30 days, WIP labels that become permanent, scope creep making PRs unmergeable. Fix: Time-box drafts. If not ready in 2 weeks, close and re-scope. Small PRs that can merge beat large PRs that cannot.

问题： 以草稿形式打开PR后从未完成，阻碍心理进展并使PR列表杂乱。 症状： 草稿PR已存在30天以上，WIP标签成为永久标记，范围蔓延导致PR无法合并。 解决方法： 为草稿设置时间限制。若两周内未准备就绪，关闭并重新规划范围。可合并的小PR远胜于无法合并的大PR。

The Branch Protection Bypass

绕过分支保护

Problem: Disabling branch protection "just this once" and committing directly to main. Creates precedent for future bypasses. Symptoms: Commits to main without PRs, broken builds on main, "I'll fix it in the next commit". Fix: Branch protection exists for a reason. Even solo developers benefit from the PR workflow for history, review checkpoint, and rollback capability.

问题： "就这一次"关闭分支保护，直接向主分支提交代码。为未来的绕过行为开了先例。 症状： 无需PR直接向主分支提交代码，主分支构建失败，存在"下次提交再修复"的心态。 解决方法： 分支保护存在是有原因的。即使是独立开发者，也能从PR工作流中受益，保留历史记录、检查点和回滚能力。

The Disconnected Context

脱节的上下文

Problem: Context network exists but is not updated, becoming fiction rather than documentation. Worse than no context because it's misleading. Symptoms:

status.md

shows work completed months ago,

decisions.md

missing recent architectural changes, new sessions can't trust context. Fix: Make context sync part of the workflow, not an afterthought. End-of-session ritual: does

status.md

reflect reality?

问题： 上下文网络已存在但未更新，成为虚构文档而非实际记录。比没有上下文更糟，因为会产生误导。 症状：

status.md

显示数月前已完成的工作，

decisions.md

缺少近期架构变更，新会话无法信任上下文内容。 解决方法： 将上下文同步作为工作流的一部分，而非事后补充。会话结束仪式：

status.md

是否反映实际状态？

Available Tools

可用工具

gh-verify.ts

Verifies GitHub CLI installation and authentication status.

bash

deno run --allow-run scripts/gh-verify.ts
deno run --allow-run scripts/gh-verify.ts --json

Output:

CLI installation status and version
Authentication status and current user
Default repository (if in a repo directory)
Recommendations if anything is missing

Exit codes: 0 (all good), 1 (gh missing), 2 (not logged in), 3 (no repo context)

验证GitHub CLI的安装和身份验证状态。

bash

deno run --allow-run scripts/gh-verify.ts
deno run --allow-run scripts/gh-verify.ts --json

输出：

CLI安装状态和版本
身份验证状态和当前用户
默认仓库（若在仓库目录中）
若有缺失，提供建议

退出码： 0（一切正常）、1（缺少gh）、2（未登录）、3（无仓库上下文）

gh-init-project.ts

Initializes GitHub project with labels, templates, and branch protection.

bash

deno run --allow-run --allow-read --allow-write scripts/gh-init-project.ts
deno run --allow-run --allow-read --allow-write scripts/gh-init-project.ts --labels standard --templates --protection
deno run --allow-run --allow-read --allow-write scripts/gh-init-project.ts --mode team --labels standard

Options:

```
--labels [standard|simple|minimal]
```
- Label scheme to create
```
--templates
```
- Create issue and PR templates
```
--protection
```
- Enable branch protection on main
```
--mode [solo|team]
```
- Adjust defaults for working style
```
--dry-run
```
- Show what would be created without creating

Creates:

Labels via
```
gh label create
```
```
.github/ISSUE_TEMPLATE/
```
with feature, bug, task templates
```
.github/pull_request_template.md
```
Branch protection rules (if
```
--protection
```
)

初始化GitHub项目，包含标签、模板和分支保护。

bash

deno run --allow-run --allow-read --allow-write scripts/gh-init-project.ts
deno run --allow-run --allow-read --allow-write scripts/gh-init-project.ts --labels standard --templates --protection
deno run --allow-run --allow-read --allow-write scripts/gh-init-project.ts --mode team --labels standard

选项：

```
--labels [standard|simple|minimal]
```
- 要创建的标签方案
```
--templates
```
- 创建Issue和PR模板
```
--protection
```
- 为主分支启用分支保护
```
--mode [solo|team]
```
- 根据工作风格调整默认设置
```
--dry-run
```
- 显示将创建的内容但不实际创建

创建内容：

通过
```
gh label create
```
创建标签
```
.github/ISSUE_TEMPLATE/
```
目录，包含功能、Bug、任务模板
```
.github/pull_request_template.md
```
分支保护规则（若使用
```
--protection
```
）

gh-audit.ts

Audits current GitHub state against healthy workflow indicators.

bash

deno run --allow-run scripts/gh-audit.ts
deno run --allow-run scripts/gh-audit.ts --json
deno run --allow-run scripts/gh-audit.ts --stale 30

Options:

```
--json
```
- Output as JSON for scripting
```
--stale [days]
```
- Flag items with no activity for N days (default: 30)
```
--verbose
```
- Show detailed item-by-item analysis

Checks:

Open issue count and label coverage
Open PR status (draft, linked issues, age)
Recent commits (which branch, direct to main?)
Milestone usage and progress
Stale item identification

Output: Health score (0-100) with specific recommendations

根据健康工作流指标审计当前GitHub状态。

bash

deno run --allow-run scripts/gh-audit.ts
deno run --allow-run scripts/gh-audit.ts --json
deno run --allow-run scripts/gh-audit.ts --stale 30

选项：

```
--json
```
- 以JSON格式输出，便于脚本处理
```
--stale [days]
```
- 标记N天未活动的事项（默认：30天）
```
--verbose
```
- 显示详细的逐项分析

检查内容：

开放Issue数量和标签覆盖率
开放PR状态（草稿、关联Issues、存在时间）
近期提交（分支信息、是否直接提交到主分支）
里程碑使用情况和进度
停滞事项识别

输出： 健康分数（0-100）及具体建议

gh-sync-context.ts

Generates context network updates from GitHub state.

bash

deno run --allow-run --allow-write scripts/gh-sync-context.ts
deno run --allow-run scripts/gh-sync-context.ts --dry-run
deno run --allow-run --allow-write scripts/gh-sync-context.ts --status --decisions

Options:

```
--dry-run
```
- Output what would be written without writing
```
--status
```
- Generate
```
status.md
```
update section
```
--decisions
```
- Extract decisions from closed issues with "decision" label
```
--output [dir]
```
- Directory to write to (default:
```
context/
```
)

Generates:

Status update content for
```
status.md
```
Decision candidates from closed issues
Milestone summary

根据GitHub状态生成上下文网络更新。

bash

deno run --allow-run --allow-write scripts/gh-sync-context.ts
deno run --allow-run scripts/gh-sync-context.ts --dry-run
deno run --allow-run --allow-write scripts/gh-sync-context.ts --status --decisions

选项：

```
--dry-run
```
- 输出将写入的内容但不实际写入
```
--status
```
- 生成
```
status.md
```
更新内容
```
--decisions
```
- 从带有"decision"标签的已关闭Issues中提取决策
```
--output [dir]
```
- 写入目录（默认：
```
context/
```
）

生成内容：

```
status.md
```
的状态更新内容
从已关闭Issues中提取的候选决策
里程碑摘要

Example Interactions

示例交互

Solo Developer: Starting Fresh

独立开发者：从零开始

Developer: "I have a local project I want to put on GitHub and start using proper workflow."

Diagnosis: State GH1 (Repository Not Initialized)

Approach:

Run
```
scripts/gh-verify.ts
```
- confirm CLI ready
Ask: "Public or private repository?"

Create repo:

gh repo create my-project --source=. --private --push

Run

scripts/gh-init-project.ts --mode solo --labels simple --templates

Initialize context network: create
```
context/
```
with
```
status.md
```
,
```
decisions.md
```
Document in
```
context/architecture.md
```
: "Using GitHub Issues for tracking, feature branches for all changes, PRs for merge and history."
Create first issue for current work
Demonstrate branch workflow:
```
gh issue develop 1
```

开发者： "我有一个本地项目，想放到GitHub上并开始使用规范的工作流。"

诊断： 状态GH1（仓库未初始化）

方案：

运行
```
scripts/gh-verify.ts
```
- 确认CLI已就绪
询问："仓库设为公开还是私有？"

创建仓库：

gh repo create my-project --source=. --private --push

运行

scripts/gh-init-project.ts --mode solo --labels simple --templates

初始化上下文网络：创建
```
context/
```
目录及
```
status.md
```
、
```
decisions.md
```
在
```
context/architecture.md
```
中记录："使用GitHub Issues追踪工作，所有变更都在功能分支上完成，通过PR进行合并和历史记录管理。"
为当前工作创建第一个Issue
演示分支工作流：
```
gh issue develop 1
```

Team: Backlog Cleanup

团队：待办事项清理

Developer: "We have 150 open issues and no one knows what's important."

Diagnosis: State GH3 (Backlog Chaos)

Approach:

Run
```
scripts/gh-audit.ts --stale 60
```
- identify scope
Ask: "What's the current priority? What must ship soon?"
Create milestone for immediate focus
Triage issues:
- Critical for milestone → assign to milestone, add priority label
- Valid but not now → icebox label
- Stale with no path forward → close with explanation
- Duplicates → close with reference to canonical
Update
```
context/status.md
```
with focus
Establish grooming cadence: weekly 15-minute review

开发者： "我们有150个开放Issues，没人知道哪些是重要的。"

诊断： 状态GH3（待办事项混乱）

方案：

运行
```
scripts/gh-audit.ts --stale 60
```
- 确定范围
询问："当前的优先级是什么？哪些内容必须尽快交付？"
为近期重点工作创建里程碑
分类Issues：
- 对里程碑至关重要 → 分配到里程碑，添加优先级标签
- 有效但非当前重点 → 标记icebox标签
- 停滞且无推进路径 → 附上说明后关闭
- 重复项 → 关闭并关联到标准Issue
在
```
context/status.md
```
中更新工作重点
确立梳理节奏：每周15分钟评审

Solo Developer: Context Decay

独立开发者：上下文衰退

Developer: "I came back to this project after a month and have no idea what I was doing."

Diagnosis: State GH7 (Context Network Gap)

Approach:

Check GitHub state:
```
gh issue list
```
,
```
gh pr status
```
Run
```
scripts/gh-sync-context.ts --dry-run
```
to see current state
Initialize or update context network:
- ```
status.md
```
  : What's the current milestone? Active issues?
- ```
decisions.md
```
  : Any architectural decisions in closed PRs?
Review closed issues/PRs from last session for context
Update
```
status.md
```
with "Last session" summary
Establish habit: end each session by updating
```
status.md
```

开发者： "我一个月后回到这个项目，完全不知道之前在做什么。"

诊断： 状态GH7（上下文网络缺失）

方案：

查看GitHub状态：
```
gh issue list
```
、
```
gh pr status
```
运行
```
scripts/gh-sync-context.ts --dry-run
```
查看当前状态
初始化或更新上下文网络：
- ```
status.md
```
  ：当前里程碑是什么？活跃Issues有哪些？
- ```
decisions.md
```
  ：已关闭的PR中是否有架构决策？
回顾上次会话的已关闭Issues/PRs获取上下文
在
```
status.md
```
中添加"上次会话"摘要
养成习惯：每次会话结束后更新
```
status.md
```

Output Persistence

输出持久化

Output Discovery

输出位置发现

Before doing any other work:

Check for
```
context/output-config.md
```
in the project
If found, look for this skill's entry
If not found, ask: "Where should I save GitHub workflow output?"
- Suggest:
```
context/
```
  for context network files,
```
.github/
```
  for GitHub configuration
Store preference in
```
context/output-config.md
```

在进行任何其他工作之前：

检查项目中是否存在
```
context/output-config.md
```
若存在，查找本技能的配置项
若不存在，询问："GitHub工作流输出应保存到哪里？"
- 建议：
```
context/
```
  用于上下文网络文件，
```
.github/
```
  用于GitHub配置
将偏好设置存储在
```
context/output-config.md
```
中

Primary Output

主要输出

Output	Location
Issue templates	`.github/ISSUE_TEMPLATE/`
PR template	`.github/pull_request_template.md`
Workflow documentation	`context/architecture.md` (GitHub workflow section)
Setup decisions	`context/decisions.md`
Status updates	`context/status.md`
Audit reports	`context/github-audit-{date}.md` (if persisted)

输出	位置
Issue模板	`.github/ISSUE_TEMPLATE/`
PR模板	`.github/pull_request_template.md`
工作流文档	`context/architecture.md` （GitHub工作流章节）
配置决策	`context/decisions.md`
状态更新	`context/status.md`
审计报告	`context/github-audit-{date}.md` （若需持久化）

Conversation vs. File

对话与文件的分界

Goes to File	Stays in Conversation
Templates ( `.github/` )	Diagnosis discussion
Workflow documentation	Label scheme exploration
Context network updates	Triage decisions
Audit reports (if requested)	Quick status checks

写入文件	保留在对话中
模板（ `.github/` ）	诊断讨论
工作流文档	标签方案探讨
上下文网络更新	分类决策
审计报告（若请求）	快速状态检查

What You Do NOT Do

以下是你不会做的事

You do not create issues without user confirmation
You do not merge PRs automatically
You do not delete issues, PRs, or branches without explicit request
You do not change branch protection without explicit request
You do not skip verification of
```
gh
```
availability (always check GH0 first)
You do not assume GitHub access without
```
gh auth status
```
check
You do not replace the context network with GitHub-only storage
You do not create commits on main branch (enforce feature branch workflow)
You do not push to remote without user awareness
You diagnose, recommend, and execute with confirmation - the developer decides

未经用户确认，不创建Issues
不自动合并PRs
未经明确请求，不删除Issues、PRs或分支
未经明确请求，不修改分支保护设置
不会跳过
```
gh
```
可用性验证（始终先检查GH0）
不通过
```
gh auth status
```
验证就假设拥有GitHub访问权限
不会仅用GitHub存储替代上下文网络
不会向主分支提交代码（强制执行功能分支工作流）
不会在用户不知情的情况下推送到远程仓库
你负责诊断、建议，并在用户确认后执行 - 最终决定权在开发者手中

Integration with Other Skills

与其他技能的集成

From requirements-analysis

来自requirements-analysis

requirements-analysis Output	github-agile Input
Problem Statement	Creates initial issue(s) describing the problem
Need Hierarchy	Maps to issue priority labels
Constraint Inventory	Documents in `context/` , references in issues
Validated Requirements	Creates feature issues, links to requirements doc

requirements-analysis输出	github-agile输入
问题陈述	创建描述问题的初始Issues
需求层级	映射到Issue优先级标签
约束清单	记录在 `context/` 中，在Issues中引用
已验证的需求	创建功能Issues，关联到需求文档

From system-design

来自system-design

system-design Output	github-agile Input
ADRs	Stored in `context/adr/` or `docs/adr/` , referenced in PRs
Component Map	Informs issue breakdown by component
Walking Skeleton	First milestone with linked issues
Integration Points	Documented in `context/architecture.md`

system-design输出	github-agile输入
ADRs	存储在 `context/adr/` 或 `docs/adr/` ，在PRs中引用
组件图	指导按组件拆分Issues
行走骨架	第一个关联Issues的里程碑
集成点	记录在 `context/architecture.md` 中

To requirements-analysis

输出到requirements-analysis

When GitHub state reveals requirements problems:

github-agile State	Trigger	requirements-analysis State
GH3 (Backlog Chaos)	Issues describe solutions not problems	RA0-RA1
GH3 (Backlog Chaos)	Cannot prioritize (everything important)	RA4

当GitHub状态揭示需求问题时：

github-agile状态	触发条件	requirements-analysis状态
GH3（待办事项混乱）	Issues描述解决方案而非问题	RA0-RA1
GH3（待办事项混乱）	无法划分优先级（所有内容都重要）	RA4

To system-design

输出到system-design

When GitHub state reveals design problems:

github-agile State	Trigger	system-design State
GH5 (PR Without Context)	PR involves undocumented architecture decisions	SD4
GH4 (Branch Violations)	Frequent merge conflicts	SD3 (Missing Integration Points)

当GitHub状态揭示设计问题时：

github-agile状态	触发条件	system-design状态
GH5（PR缺少上下文）	PR涉及未记录的架构决策	SD4
GH4（分支违规）	频繁出现合并冲突	SD3（缺少集成点）

References

参考资料

This skill operationalizes:

GitHub CLI documentation: https://cli.github.com/manual/
Context Networks framework:
```
references/context-networks/
```
Feature branch workflow best practices
Conventional Commits: https://www.conventionalcommits.org/

本技能实现了以下内容的落地：

GitHub CLI文档：https://cli.github.com/manual/
上下文网络框架：
```
references/context-networks/
```
功能分支工作流最佳实践
规范提交：https://www.conventionalcommits.org/