@fitlab-ai/agent-infra 0.3.0

package/templates/.github/workflows/pr-title-check.yml

@@ -0,0 +1,42 @@
+name: PR Title Check
+
+on:
+  pull_request_target:
+    types: [opened, edited, synchronize]
+
+permissions:
+  pull-requests: write
+  statuses: write
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v6.1.1
+        with:
+          # 允许的提交类型
+          types: |
+            feat
+            fix
+            docs
+            style
+            refactor
+            perf
+            test
+            chore
+            build
+            ci
+            revert
+
+          # 不限制 scope，允许任意模块名
+          # requireScope: false - scope 是可选的
+
+          # 标题描述长度 5-100 字符
+          subjectPattern: '^.{5,100}$'
+          subjectPatternError: '标题描述长度应在 5-100 字符之间'
+
+          # 支持 WIP 前缀标记进行中的工作
+          wip: true
+
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/templates/.mailmap

@@ -0,0 +1,4 @@
+Claude <noreply@anthropic.com>
+Codex <noreply@openai.com>
+Gemini <noreply@google.com>
+OpenCode <noreply@opencode.ai>

package/templates/.opencode/COMMAND_STYLE_GUIDE.md

@@ -0,0 +1,232 @@
+# Command Style Guide
+
+This guide defines conventions for writing OpenCode command files in the `.opencode/commands/` directory.
+
+## File Format
+
+Every command file uses Markdown with YAML frontmatter:
+
+```markdown
+---
+description: Brief one-line description
+agent: general
+subtask: false
+---
+
+Command instructions here.
+```
+
+### Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `description` | Yes | One-line summary (under 80 chars) |
+| `agent` | Yes | Always `general` unless specialized |
+| `subtask` | Yes | `false` for top-level commands |
+
+## Executable Commands vs Code Blocks
+
+### Use `!` prefix for commands that MUST be executed
+
+```markdown
+!date -u +"%Y-%m-%dT%H:%M:%SZ"
+!git status --short
+!gh issue view 123 --json number,title,body
+```
+
+The `!` prefix tells OpenCode to run the command directly. Use this for:
+- Getting dynamic information (timestamps, git status)
+- Performing actions (creating files, calling APIs)
+- Running build/test commands
+
+### Use markdown code blocks for illustrative examples
+
+````markdown
+Example output format:
+```
+Task ID: TASK-20260101-120000
+Status: active
+```
+````
+
+Code blocks are NOT executed. Use them for:
+- Showing expected output formats
+- Documenting templates
+- Illustrating patterns the AI should follow
+
+## Parameter Handling
+
+### Positional parameters
+
+Reference with `$ARGUMENTS`:
+
+```markdown
+Parse the task ID from `$ARGUMENTS`.
+```
+
+### Validation
+
+Always validate required parameters early:
+
+```markdown
+If `$ARGUMENTS` is empty, respond:
+"Please provide a task ID. Example: /check-task TASK-20260101-120000"
+Then STOP.
+```
+
+## Timestamp Handling
+
+**NEVER** hardcode dates or years.
+
+Correct:
+```markdown
+!date -u +"%Y-%m-%dT%H:%M:%SZ"
+```
+
+Wrong:
+```markdown
+Set the date to 2026-03-06.
+```
+
+## GitHub API Paths
+
+**ALWAYS** use `{owner}/{repo}` placeholders. Resolve dynamically:
+
+```markdown
+!gh api repos/{owner}/{repo}/dependabot/alerts/$ARGUMENTS
+```
+
+To get owner/repo:
+```markdown
+!gh repo view --json owner,name -q '.owner.login + "/" + .name'
+```
+
+## Step Numbering and Readability
+
+### Use numbered steps for sequential operations
+
+```markdown
+## Steps
+
+1. **Validate input** - Check that the task ID is provided.
+
+2. **Read task file** - Find and read the task.md file.
+
+3. **Update status** - Modify the task metadata.
+```
+
+### Use bold for step titles
+
+Each step should have a clear bold title followed by a description.
+
+### Keep steps atomic
+
+Each step should do one thing. If a step is too complex, break it into sub-steps.
+
+## Error Handling Patterns
+
+### Check prerequisites before acting
+
+```markdown
+1. **Verify task exists**
+
+Search for the task file:
+- `.agent-workspace/active/{task-id}/task.md`
+- `.agent-workspace/blocked/{task-id}/task.md`
+- `.agent-workspace/completed/{task-id}/task.md`
+
+If not found, respond:
+"Task {task-id} not found. Please check the task ID."
+Then STOP.
+```
+
+### Report errors clearly
+
+```markdown
+If the command fails, report:
+- What went wrong
+- Possible causes
+- Suggested next steps
+
+Do NOT silently continue.
+```
+
+## Common Patterns
+
+### Task file lookup pattern
+
+```markdown
+Search for the task in this order:
+1. `.agent-workspace/active/{task-id}/task.md`
+2. `.agent-workspace/blocked/{task-id}/task.md`
+3. `.agent-workspace/completed/{task-id}/task.md`
+```
+
+### Status update pattern
+
+```markdown
+Update `task.md` YAML frontmatter:
+- `current_step`: {step-name}
+- `assigned_to`: opencode
+- `updated_at`: {current timestamp from date command}
+```
+
+### Next-step suggestion pattern
+
+```markdown
+**Next step:**
+Use `/plan-task {task-id}` to design the technical plan.
+```
+
+## Anti-Patterns
+
+### DO NOT
+
+- Hardcode dates, years, or timestamps
+- Hardcode repository owner/name in API paths
+- Skip parameter validation
+- Auto-commit without user confirmation
+- Use tool-specific syntax (e.g., Claude's Read/Edit/Write tool names)
+- Reference tech-stack-specific commands without TODO markers
+- Include emoji in command files (keep them professional)
+- Write overly long steps -- break them up
+
+### DO
+
+- Use `!` for all executable commands
+- Validate parameters before proceeding
+- Provide clear error messages
+- Include "STOP" after error conditions
+- Keep commands concise and scannable
+- Use placeholders for project-specific values
+- Add TODO markers for tech-stack-specific sections
+
+## Tech-Stack Agnostic Commands
+
+For commands that depend on the project's tech stack (build tools, test runners, package managers), use TODO markers:
+
+```markdown
+3. **Run tests**
+
+<!-- TODO: Replace with your project's test command -->
+!npm test
+```
+
+This tells users they need to customize the command for their project.
+
+## Command Review Checklist
+
+Before submitting a new command, verify:
+
+- [ ] Frontmatter has `description`, `agent`, and `subtask`
+- [ ] All executable commands use `!` prefix
+- [ ] All illustrative examples use code blocks (no `!`)
+- [ ] Parameters are validated with clear error messages
+- [ ] Timestamps are generated dynamically
+- [ ] GitHub API paths use `{owner}/{repo}` placeholders
+- [ ] Steps are numbered and have bold titles
+- [ ] Error cases are handled with "STOP" directives
+- [ ] No hardcoded dates, repo names, or tool-specific references
+- [ ] Tech-stack-specific sections have TODO markers
+- [ ] Both EN and ZH-CN versions are created
+- [ ] Command is concise -- no unnecessary prose

package/templates/.opencode/COMMAND_STYLE_GUIDE.zh-CN.md

@@ -0,0 +1,232 @@
+# 命令编写风格指南
+
+本指南定义了 `.opencode/commands/` 目录中 OpenCode 命令文件的编写规范。
+
+## 文件格式
+
+每个命令文件使用带 YAML 前置元数据的 Markdown 格式：
+
+```markdown
+---
+description: 简要描述
+agent: general
+subtask: false
+---
+
+命令指令内容。
+```
+
+### 前置元数据字段
+
+| 字段 | 必需 | 说明 |
+|------|------|------|
+| `description` | 是 | 一行摘要（80 字符以内） |
+| `agent` | 是 | 除非有专门代理，否则为 `general` |
+| `subtask` | 是 | 顶层命令为 `false` |
+
+## 可执行命令 vs 代码块
+
+### 使用 `!` 前缀标记必须执行的命令
+
+```markdown
+!date -u +"%Y-%m-%dT%H:%M:%SZ"
+!git status --short
+!gh issue view 123 --json number,title,body
+```
+
+`!` 前缀告诉 OpenCode 直接运行该命令。适用于：
+- 获取动态信息（时间戳、git 状态）
+- 执行操作（创建文件、调用 API）
+- 运行构建/测试命令
+
+### 使用 markdown 代码块展示说明性示例
+
+````markdown
+预期输出格式：
+```
+Task ID: TASK-20260101-120000
+Status: active
+```
+````
+
+代码块不会被执行。适用于：
+- 展示预期输出格式
+- 记录模板
+- 说明 AI 应遵循的模式
+
+## 参数处理
+
+### 位置参数
+
+通过 `$ARGUMENTS` 引用：
+
+```markdown
+从 `$ARGUMENTS` 中解析任务 ID。
+```
+
+### 验证
+
+始终在早期验证必需参数：
+
+```markdown
+如果 `$ARGUMENTS` 为空，回复：
+"请提供任务 ID。示例：/check-task TASK-20260101-120000"
+然后 STOP。
+```
+
+## 时间戳处理
+
+**绝对不要**硬编码日期或年份。
+
+正确做法：
+```markdown
+!date -u +"%Y-%m-%dT%H:%M:%SZ"
+```
+
+错误做法：
+```markdown
+将日期设为 2026-03-06。
+```
+
+## GitHub API 路径
+
+**始终**使用 `{owner}/{repo}` 占位符。动态解析：
+
+```markdown
+!gh api repos/{owner}/{repo}/dependabot/alerts/$ARGUMENTS
+```
+
+获取 owner/repo：
+```markdown
+!gh repo view --json owner,name -q '.owner.login + "/" + .name'
+```
+
+## 步骤编号和可读性
+
+### 使用编号标记顺序操作
+
+```markdown
+## 步骤
+
+1. **验证输入** - 检查是否提供了任务 ID。
+
+2. **读取任务文件** - 查找并读取 task.md 文件。
+
+3. **更新状态** - 修改任务元数据。
+```
+
+### 使用粗体标记步骤标题
+
+每个步骤应有清晰的粗体标题，后跟描述。
+
+### 保持步骤原子化
+
+每个步骤只做一件事。如果步骤太复杂，拆分为子步骤。
+
+## 错误处理模式
+
+### 在操作前检查前置条件
+
+```markdown
+1. **验证任务存在**
+
+按以下顺序搜索任务文件：
+- `.agent-workspace/active/{task-id}/task.md`
+- `.agent-workspace/blocked/{task-id}/task.md`
+- `.agent-workspace/completed/{task-id}/task.md`
+
+如果未找到，回复：
+"任务 {task-id} 不存在，请检查任务 ID。"
+然后 STOP。
+```
+
+### 清晰地报告错误
+
+```markdown
+如果命令失败，报告：
+- 出了什么问题
+- 可能的原因
+- 建议的后续步骤
+
+不要静默继续。
+```
+
+## 常见模式
+
+### 任务文件查找模式
+
+```markdown
+按以下顺序搜索任务：
+1. `.agent-workspace/active/{task-id}/task.md`
+2. `.agent-workspace/blocked/{task-id}/task.md`
+3. `.agent-workspace/completed/{task-id}/task.md`
+```
+
+### 状态更新模式
+
+```markdown
+更新 `task.md` YAML 前置元数据：
+- `current_step`: {步骤名}
+- `assigned_to`: opencode
+- `updated_at`: {通过 date 命令获取的当前时间戳}
+```
+
+### 下一步建议模式
+
+```markdown
+**下一步：**
+使用 `/plan-task {task-id}` 设计技术方案。
+```
+
+## 反模式
+
+### 不要
+
+- 硬编码日期、年份或时间戳
+- 在 API 路径中硬编码仓库 owner/name
+- 跳过参数验证
+- 未经用户确认就自动提交
+- 使用特定工具语法（如 Claude 的 Read/Edit/Write 工具名）
+- 引用特定技术栈的命令但不加 TODO 标记
+- 在命令文件中使用 emoji（保持专业）
+- 写过长的步骤——应该拆分
+
+### 要
+
+- 对所有可执行命令使用 `!` 前缀
+- 在继续之前验证参数
+- 提供清晰的错误消息
+- 在错误条件后包含 "STOP"
+- 保持命令简洁且易于浏览
+- 对项目特定的值使用占位符
+- 对技术栈特定的部分添加 TODO 标记
+
+## 技术栈无关的命令
+
+对于依赖项目技术栈的命令（构建工具、测试运行器、包管理器），使用 TODO 标记：
+
+```markdown
+3. **运行测试**
+
+<!-- TODO: Replace with your project's test command -->
+!npm test
+```
+
+这告诉用户需要根据自己的项目定制该命令。
+
+## 命令审查清单
+
+提交新命令前，请验证：
+
+- [ ] 前置元数据包含 `description`、`agent` 和 `subtask`
+- [ ] 所有可执行命令使用 `!` 前缀
+- [ ] 所有说明性示例使用代码块（无 `!`）
+- [ ] 参数已验证，有清晰的错误消息
+- [ ] 时间戳动态生成
+- [ ] GitHub API 路径使用 `{owner}/{repo}` 占位符
+- [ ] 步骤已编号且有粗体标题
+- [ ] 错误情况使用 "STOP" 指令处理
+- [ ] 无硬编码的日期、仓库名或工具特定引用
+- [ ] 技术栈特定的部分有 TODO 标记
+- [ ] 已创建英文和中文两个版本
+- [ ] 命令简洁——无多余的描述

package/templates/.opencode/README.md

@@ -0,0 +1,76 @@
+# OpenCode Commands
+
+This directory contains command files for [OpenCode](https://opencode.ai), an AI-powered coding assistant.
+
+## Structure
+
+```
+.opencode/
+  README.md                          # This file
+  COMMAND_STYLE_GUIDE.md             # Guide for writing commands
+  commands/
+    {command}.md                     # English command files
+    {command}.zh-CN.md               # Chinese command files
+```
+
+## Command Format
+
+Each command file uses Markdown with YAML frontmatter:
+
+```markdown
+---
+description: Brief description of what the command does
+agent: general
+subtask: false
+---
+
+Step-by-step instructions for the AI agent.
+Use `!` prefix for shell commands that should be executed directly.
+Use markdown code blocks for illustrative examples that should NOT be auto-executed.
+```
+
+## Available Commands
+
+### Project Setup
+- `update-agent-infra` - Update project configuration
+
+### Development
+- `commit` - Commit current changes to Git
+- `test` - Run unit tests (TODO: tech-stack specific)
+- `test-integration` - Run integration tests (TODO: tech-stack specific)
+
+### Task Management
+- `create-task` - Create a task from natural language description
+- `import-issue` - Import a GitHub Issue as a task
+- `analyze-task` - Analyze task requirements
+- `plan-task` - Design a technical plan for a task
+- `implement-task` - Implement a task based on the plan
+- `review-task` - Review task implementation
+- `refine-task` - Address review feedback
+- `complete-task` - Mark task as completed and archive
+- `check-task` - Check task status
+- `block-task` - Mark task as blocked
+
+### Pull Requests and Sync
+- `create-pr` - Create a Pull Request
+- `sync-pr` - Sync task progress to PR comments
+- `sync-issue` - Sync task progress to Issue comments
+
+### Security
+- `import-dependabot` - Import Dependabot alerts
+- `close-dependabot` - Close Dependabot alerts
+- `import-codescan` - Import Code Scanning alerts
+- `close-codescan` - Close Code Scanning alerts
+
+### Release and Maintenance
+- `release` - Create a release (TODO: tech-stack specific)
+- `create-release-note` - Generate release notes
+- `refine-title` - Refine Issue/PR titles
+- `upgrade-dependency` - Upgrade a dependency (TODO: tech-stack specific)
+
+## Conventions
+
+- Commands are **tool-agnostic** and **tech-stack agnostic**
+- Commands with `TODO` markers require project-specific customization
+- All timestamps are generated dynamically (never hardcoded)
+- GitHub API paths use `{owner}/{repo}` placeholders

package/templates/.opencode/README.zh-CN.md

@@ -0,0 +1,77 @@
+# OpenCode 命令
+
+本目录包含 [OpenCode](https://opencode.ai) AI 编码助手的命令文件。
+
+## 目录结构
+
+```
+.opencode/
+  README.md                          # 英文说明
+  README.zh-CN.md                    # 本文件
+  COMMAND_STYLE_GUIDE.md             # 命令编写指南
+  commands/
+    {command}.md                     # 英文命令文件
+    {command}.zh-CN.md               # 中文命令文件
+```
+
+## 命令格式
+
+每个命令文件使用带 YAML 前置元数据的 Markdown 格式：
+
+```markdown
+---
+description: 命令功能的简要描述
+agent: general
+subtask: false
+---
+
+AI 代理的分步指令。
+使用 `!` 前缀标记需要直接执行的 shell 命令。
+使用 markdown 代码块展示不需要自动执行的示例。
+```
+
+## 可用命令
+
+### 项目设置
+- `update-agent-infra` - 更新项目配置
+
+### 开发
+- `commit` - 提交当前变更到 Git
+- `test` - 运行单元测试（TODO: 需适配技术栈）
+- `test-integration` - 运行集成测试（TODO: 需适配技术栈）
+
+### 任务管理
+- `create-task` - 从自然语言描述创建任务
+- `import-issue` - 导入 GitHub Issue 为任务
+- `analyze-task` - 分析任务需求
+- `plan-task` - 为任务设计技术方案
+- `implement-task` - 根据方案实施任务
+- `review-task` - 审查任务实现
+- `refine-task` - 处理审查反馈
+- `complete-task` - 标记任务完成并归档
+- `check-task` - 查看任务状态
+- `block-task` - 标记任务为阻塞
+
+### PR 和同步
+- `create-pr` - 创建 Pull Request
+- `sync-pr` - 同步任务进度到 PR 评论
+- `sync-issue` - 同步任务进度到 Issue 评论
+
+### 安全
+- `import-dependabot` - 导入 Dependabot 告警
+- `close-dependabot` - 关闭 Dependabot 告警
+- `import-codescan` - 导入 Code Scanning 告警
+- `close-codescan` - 关闭 Code Scanning 告警
+
+### 发布和维护
+- `release` - 创建发布版本（TODO: 需适配技术栈）
+- `create-release-note` - 生成发布说明
+- `refine-title` - 优化 Issue/PR 标题
+- `upgrade-dependency` - 升级依赖（TODO: 需适配技术栈）
+
+## 约定
+
+- 命令是**工具无关**和**技术栈无关**的
+- 带 `TODO` 标记的命令需要根据项目具体技术栈进行定制
+- 所有时间戳动态生成（禁止硬编码）
+- GitHub API 路径使用 `{owner}/{repo}` 占位符

package/templates/.opencode/commands/analyze-task.md

@@ -0,0 +1,11 @@
+---
+description: "Analyze an existing task and output a requirement analysis document"
+agent: general
+subtask: false
+---
+
+Analyze task $1.
+
+Read and execute the analyze-task skill from `.agents/skills/analyze-task/SKILL.md`.
+
+Follow all steps defined in the skill exactly.

package/templates/.opencode/commands/analyze-task.zh-CN.md

@@ -0,0 +1,11 @@
+---
+description: "分析已有任务并输出需求分析文档，支持多轮分析产物。 当用户要求分析某个任务时触发。参数：task-id。"
+agent: general
+subtask: false
+---
+
+分析任务 $1。
+
+读取并执行 `.agents/skills/analyze-task/SKILL.md` 中的 analyze-task 技能。
+
+严格按照技能中定义的所有步骤执行。

package/templates/.opencode/commands/block-task.md

@@ -0,0 +1,11 @@
+---
+description: "Mark task as blocked and record blocking reason"
+agent: general
+subtask: false
+---
+
+Block task: $ARGUMENTS
+
+Read and execute the block-task skill from `.agents/skills/block-task/SKILL.md`.
+
+Follow all steps defined in the skill exactly.

package/templates/.opencode/commands/block-task.zh-CN.md

@@ -0,0 +1,11 @@
+---
+description: "标记任务为阻塞状态并记录阻塞原因，将其从 active 目录移动到 blocked 目录。 当任务因技术问题、需求不清晰、缺少资源或待定决策而无法继续时使用。 参数：task-id，可选的阻塞原因。"
+agent: general
+subtask: false
+---
+
+阻塞任务：$ARGUMENTS
+
+读取并执行 `.agents/skills/block-task/SKILL.md` 中的 block-task 技能。
+
+严格按照技能中定义的所有步骤执行。