monoco-toolkit 0.3.2__tar.gz → 0.3.3__tar.gz

monoco_toolkit-0.3.3/.agent/workflows/release_0.3.2.md

@@ -0,0 +1,36 @@
+---
+description: Release Toolkit version 0.3.2 - tag main and publish
+---
+
+1. Create a release chore issue
+   ```bash
+   monoco issue create chore -t "Release Toolkit v0.3.2"
+   ```
+2. Set the project version
+   // turbo
+   ```bash
+   python Toolkit/scripts/set_version.py 0.3.2
+   ```
+3. Run release validation checks
+   // turbo
+   ```bash
+   Toolkit/scripts/run_release_checks.sh 0.3.2
+   ```
+4. Commit version changes and push to `main`
+   ```bash
+   git add .
+   git commit -m "chore: bump version to 0.3.2"
+   git push origin main
+   ```
+5. Create and push git tag `v0.3.2`
+   // turbo
+   ```bash
+   git tag -a v0.3.2 -m "Release Toolkit v0.3.2"
+   git push origin v0.3.2
+   ```
+6. Close the release issue with solution
+   ```bash
+   monoco issue close <ISSUE_ID> --solution "Released version 0.3.2 with tag v0.3.2"
+   ```
+
+*Note*: Replace `<ISSUE_ID>` with the actual ID returned from step 1.

{monoco_toolkit-0.3.2/.gemini → monoco_toolkit-0.3.3/.claude}/skills/monoco_core/SKILL.md

@@ -42,6 +42,24 @@ Monoco 是一个开发者生产力工具包，提供:
   - 从 agent 配置文件中移除托管块
   - 清理已分发的 skills
 
+### Git 工作流集成
+
+Monoco 强制执行 **Feature Branch 工作流**以确保代码隔离和质量:
+
+- **`monoco init`**: 自动安装 Git Hooks
+  - **pre-commit**: 运行 Issue Linter 和代码格式检查
+  - **pre-push**: 执行测试套件和完整性验证
+  - 所有 Hooks 可通过 `.monoco/config.yaml` 配置
+
+- **分支隔离策略**:
+  - ⚠️ **强制要求**: 使用 `monoco issue start <ID> --branch` 创建隔离环境
+  - 自动创建规范化分支名: `feat/<id>-<slug>`
+  - **主干保护**: Linter 会阻止在 `main`/`master` 分支上的直接代码修改
+
+- **文件追踪**: `monoco issue sync-files` 自动同步 Git 变更到 Issue 元数据
+
+> 📖 **详细工作流**: 参见 `monoco-issue` skill 获取完整的 Issue 生命周期管理指南。
+
 ## 配置结构
 
 配置以 YAML 格式存储在:
@@ -59,7 +77,21 @@ Monoco 是一个开发者生产力工具包，提供:
 
 ## 最佳实践
 
+### 基础操作
+
 1. **优先使用 CLI 命令**，而不是手动编辑文件
 2. **配置更改后运行 `monoco sync`** 以更新 agent 环境
 3. **将 `.monoco/config.yaml` 提交到版本控制**，保持团队一致性
 4. **保持全局配置最小化** - 大多数设置应该是项目特定的
+
+### Git 工作流 (⚠️ CRITICAL for Agents)
+
+5. **严格遵循分支隔离**:
+   - ✅ 始终使用: `monoco issue start <ID> --branch`
+   - ❌ 禁止在 `main`/`master` 分支直接修改代码
+   - 📝 提交前运行: `monoco issue sync-files` 更新文件追踪
+
+6. **质量门禁**:
+   - Git Hooks 会自动运行检查,不要尝试绕过 (`--no-verify`)
+   - 提交前确保 `monoco issue lint` 通过
+   - 使用 `monoco issue submit` 生成交付报告

monoco_toolkit-0.3.3/.claude/skills/monoco_issue/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: monoco-issue
+description: Monoco Issue System 的官方技能定义。将 Issue 视为通用原子 (Universal Atom)，管理 Epic/Feature/Chore/Fix 的生命周期。
+---
+
+# 自我管理 (Monoco Issue System)
+
+使用此技能在 Monoco 项目中创建和管理 **Issue** (通用原子)。该系统参考 Jira 表达体系，同时保持 "建设者 (Builder)" 和 "调试者 (Debugger)" 思维模式的隔离。
+
+## 核心本体论 (Core Ontology)
+
+Monoco 不仅仅复刻 Jira，而是基于 **"思维模式 (Mindset)"** 重新定义工作单元。
+
+### 1. 战略层 (Strategy)
+
+#### 🏆 EPIC (史诗)
+
+- **Mindset**: _Architect_ (架构师)
+- **定义**: 跨越多个周期的宏大目标。它不是单纯的"大任务"，而是"愿景的容器"。
+- **产出**: 定义了系统的边界和核心价值。
+
+### 2. 价值层 (Value)
+
+#### ✨ FEATURE (特性)
+
+- **Mindset**: _Product Owner_ (产品负责人)
+- **定义**: 用户视角的价值增量。必须是可独立交付 (Shippable) 的垂直切片。
+- **Focus**: "Why" & "What" (用户想要什么？)。
+- **Prefix**: `FEAT-`
+
+### 3. 执行层 (Execution)
+
+#### 🧹 CHORE (杂务)
+
+- **Mindset**: _Builder_ (建设者)
+- **定义**: **不产生**直接用户价值的工程性事务。
+- **场景**: 架构升级、写构建脚本、修复 CI/CD 流水线。
+- **Focus**: "How" (为了支撑系统运转，必须做什么)。
+- **Prefix**: `CHORE-`
+
+> 注: 取代了传统的 Task 概念。
+
+#### 🐞 FIX (修复)
+
+- **Mindset**: _Debugger_ (调试者)
+- **定义**: 预期与现实的偏差。它是负价值的修正。
+- **Focus**: "Fix" (恢复原状)。
+- **Prefix**: `FIX-`
+
+> 注: 取代了传统的 Bug 概念。
+
+---
+
+**关系链**:
+
+- **主要**: `EPIC` (愿景) -> `FEATURE` (价值交付单元)
+- **次要**: `CHORE` (工程维护/支撑) - 通常独立存在。
+- **原子性原则**: Feature = Design + Dev + Test + Doc + i18n。它们是一体的。
+
+## 工作流策略 (Workflow Policies)
+
+### 1. 严格 Git 工作流 (Strict Git Workflow)
+
+Monoco 强制采用 **Feature Branch** 模式。
+
+- **Start**: 必须使用 `monoco issue start <ID> --branch` 启动任务。这会自动创建 `feat/<ID>-<slug>` 分支。
+- **禁止主干开发**: **严禁** 直接在 `main`, `master`, `production` 分支上修改代码。Linter 会拦截此类行为。
+- **Submit**: 在提交 PR 前，运行 `monoco issue submit <ID>` 进行清理和预发布检查。
+
+### 2. 文件追踪 (File Tracking)
+
+为了保证上下文的自包含性 (Self-Contained Context)，Agent 必须记录修改过的文件。
+
+- **机制**: Issue Ticket 的 Front Matter 包含 `files: []` 字段。
+- **自动化 (推荐)**: 在 Feature Branch 中运行 `monoco issue sync-files`。它会自动对比当前分支与 Base 分支的差异并更新列表。
+- **手动 (备选)**: 如果进行非分支开发，Agent 必须**主动**将修改的文件路径写入 `files` 列表。
+
+## 准则 (Guidelines)
+
+### 目录结构
+
+`Issues/{CapitalizedPluralType}/{lowercase_status}/`
+
+- `{TYPE}`: `Epics`, `Features`, `Chores`, `Fixes`
+- `{STATUS}`: `open`, `backlog`, `closed`
+
+### 路径流转
+
+使用 `monoco issue`:
+
+1. **Create**: `monoco issue create <type> --title "..."`
+   - Params: `--parent <id>`, `--dependency <id>`, `--related <id>`, `--sprint <id>`, `--tags <tag>`
+
+2. **Transition**: `monoco issue open/close/backlog <id>`
+
+3. **View**: `monoco issue scope`
+
+4. **Validation**: `monoco issue lint`
+
+5. **Modification**: `monoco issue start/submit/delete <id>`
+
+6. **Sync**: `monoco issue sync-files [id]` (同步代码变更到 Issue 文件)
+
+7. **Validation**: `monoco issue lint` (强制执行合规性检查)
+
+## 合规与结构校验 (Validation Rules)
+
+为了确保数据严谨性，所有 Issue Ticket 必须遵循以下强制规则:
+
+### 1. 结构一致性 (Structural Consistency)
+
+- 必须包含一个二级标题 (`##`)，内容必须与 Front Matter 中的 ID 和 Title 严格匹配。
+- 格式: `## {ID}: {Title}`
+- 示例: `## FEAT-0082: Issue Ticket Validator`
+
+### 2. 内容完整性 (Content Completeness)
+
+- **Checkbox 数量**: 每个 Ticket 必须包含至少 2 个 Checkbox（通常代表 AC 和 Tasks）。
+- **评审记录**: 当 `stage` 为 `review` 或 `done` 时，必须包含 `## Review Comments` 标题且内容不能为空。
+
+### 3. Checkbox 语法与层级 (Checkbox Matrix)
+
+- 仅限使用: `- [ ]`, `- [x]`, `- [-]`, `- [/]`。
+- **层级继承**: 若存在嵌套 Checkbox，父项状态必须正确反映子项的聚合结果（例如: 任一子项为 `[/]` 则父项必为 `[/]`；子项全选则父项为 `[x]`）。
+
+### 4. 状态矩阵 (State Matrix)
+
+`status` (物理存放目录) 与 `stage` (Front Matter 字段) 必须兼容:
+
+- **open**: Draft, Doing, Review, Done
+- **backlog**: Draft, Doing, Review
+- **closed**: Done
+
+### 5. 环境策略 (Environment Policy)
+
+Linter 包含环境感知防护：
+
+- 🛑 **Dirty Main Protection**: 当检测到处于受保护分支 (`main`/`master`) 且存在未提交变更时，Lint 将失败并阻止操作。

{monoco_toolkit-0.3.2/.qwen → monoco_toolkit-0.3.3/.gemini}/skills/monoco_core/SKILL.md

@@ -42,6 +42,24 @@ Monoco 是一个开发者生产力工具包，提供:
   - 从 agent 配置文件中移除托管块
   - 清理已分发的 skills
 
+### Git 工作流集成
+
+Monoco 强制执行 **Feature Branch 工作流**以确保代码隔离和质量:
+
+- **`monoco init`**: 自动安装 Git Hooks
+  - **pre-commit**: 运行 Issue Linter 和代码格式检查
+  - **pre-push**: 执行测试套件和完整性验证
+  - 所有 Hooks 可通过 `.monoco/config.yaml` 配置
+
+- **分支隔离策略**:
+  - ⚠️ **强制要求**: 使用 `monoco issue start <ID> --branch` 创建隔离环境
+  - 自动创建规范化分支名: `feat/<id>-<slug>`
+  - **主干保护**: Linter 会阻止在 `main`/`master` 分支上的直接代码修改
+
+- **文件追踪**: `monoco issue sync-files` 自动同步 Git 变更到 Issue 元数据
+
+> 📖 **详细工作流**: 参见 `monoco-issue` skill 获取完整的 Issue 生命周期管理指南。
+
 ## 配置结构
 
 配置以 YAML 格式存储在:
@@ -59,7 +77,21 @@ Monoco 是一个开发者生产力工具包，提供:
 
 ## 最佳实践
 
+### 基础操作
+
 1. **优先使用 CLI 命令**，而不是手动编辑文件
 2. **配置更改后运行 `monoco sync`** 以更新 agent 环境
 3. **将 `.monoco/config.yaml` 提交到版本控制**，保持团队一致性
 4. **保持全局配置最小化** - 大多数设置应该是项目特定的
+
+### Git 工作流 (⚠️ CRITICAL for Agents)
+
+5. **严格遵循分支隔离**:
+   - ✅ 始终使用: `monoco issue start <ID> --branch`
+   - ❌ 禁止在 `main`/`master` 分支直接修改代码
+   - 📝 提交前运行: `monoco issue sync-files` 更新文件追踪
+
+6. **质量门禁**:
+   - Git Hooks 会自动运行检查,不要尝试绕过 (`--no-verify`)
+   - 提交前确保 `monoco issue lint` 通过
+   - 使用 `monoco issue submit` 生成交付报告

monoco_toolkit-0.3.3/.gemini/skills/monoco_issue/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: monoco-issue
+description: Monoco Issue System 的官方技能定义。将 Issue 视为通用原子 (Universal Atom)，管理 Epic/Feature/Chore/Fix 的生命周期。
+---
+
+# 自我管理 (Monoco Issue System)
+
+使用此技能在 Monoco 项目中创建和管理 **Issue** (通用原子)。该系统参考 Jira 表达体系，同时保持 "建设者 (Builder)" 和 "调试者 (Debugger)" 思维模式的隔离。
+
+## 核心本体论 (Core Ontology)
+
+Monoco 不仅仅复刻 Jira，而是基于 **"思维模式 (Mindset)"** 重新定义工作单元。
+
+### 1. 战略层 (Strategy)
+
+#### 🏆 EPIC (史诗)
+
+- **Mindset**: _Architect_ (架构师)
+- **定义**: 跨越多个周期的宏大目标。它不是单纯的"大任务"，而是"愿景的容器"。
+- **产出**: 定义了系统的边界和核心价值。
+
+### 2. 价值层 (Value)
+
+#### ✨ FEATURE (特性)
+
+- **Mindset**: _Product Owner_ (产品负责人)
+- **定义**: 用户视角的价值增量。必须是可独立交付 (Shippable) 的垂直切片。
+- **Focus**: "Why" & "What" (用户想要什么？)。
+- **Prefix**: `FEAT-`
+
+### 3. 执行层 (Execution)
+
+#### 🧹 CHORE (杂务)
+
+- **Mindset**: _Builder_ (建设者)
+- **定义**: **不产生**直接用户价值的工程性事务。
+- **场景**: 架构升级、写构建脚本、修复 CI/CD 流水线。
+- **Focus**: "How" (为了支撑系统运转，必须做什么)。
+- **Prefix**: `CHORE-`
+
+> 注: 取代了传统的 Task 概念。
+
+#### 🐞 FIX (修复)
+
+- **Mindset**: _Debugger_ (调试者)
+- **定义**: 预期与现实的偏差。它是负价值的修正。
+- **Focus**: "Fix" (恢复原状)。
+- **Prefix**: `FIX-`
+
+> 注: 取代了传统的 Bug 概念。
+
+---
+
+**关系链**:
+
+- **主要**: `EPIC` (愿景) -> `FEATURE` (价值交付单元)
+- **次要**: `CHORE` (工程维护/支撑) - 通常独立存在。
+- **原子性原则**: Feature = Design + Dev + Test + Doc + i18n。它们是一体的。
+
+## 工作流策略 (Workflow Policies)
+
+### 1. 严格 Git 工作流 (Strict Git Workflow)
+
+Monoco 强制采用 **Feature Branch** 模式。
+
+- **Start**: 必须使用 `monoco issue start <ID> --branch` 启动任务。这会自动创建 `feat/<ID>-<slug>` 分支。
+- **禁止主干开发**: **严禁** 直接在 `main`, `master`, `production` 分支上修改代码。Linter 会拦截此类行为。
+- **Submit**: 在提交 PR 前，运行 `monoco issue submit <ID>` 进行清理和预发布检查。
+
+### 2. 文件追踪 (File Tracking)
+
+为了保证上下文的自包含性 (Self-Contained Context)，Agent 必须记录修改过的文件。
+
+- **机制**: Issue Ticket 的 Front Matter 包含 `files: []` 字段。
+- **自动化 (推荐)**: 在 Feature Branch 中运行 `monoco issue sync-files`。它会自动对比当前分支与 Base 分支的差异并更新列表。
+- **手动 (备选)**: 如果进行非分支开发，Agent 必须**主动**将修改的文件路径写入 `files` 列表。
+
+## 准则 (Guidelines)
+
+### 目录结构
+
+`Issues/{CapitalizedPluralType}/{lowercase_status}/`
+
+- `{TYPE}`: `Epics`, `Features`, `Chores`, `Fixes`
+- `{STATUS}`: `open`, `backlog`, `closed`
+
+### 路径流转
+
+使用 `monoco issue`:
+
+1. **Create**: `monoco issue create <type> --title "..."`
+   - Params: `--parent <id>`, `--dependency <id>`, `--related <id>`, `--sprint <id>`, `--tags <tag>`
+
+2. **Transition**: `monoco issue open/close/backlog <id>`
+
+3. **View**: `monoco issue scope`
+
+4. **Validation**: `monoco issue lint`
+
+5. **Modification**: `monoco issue start/submit/delete <id>`
+
+6. **Sync**: `monoco issue sync-files [id]` (同步代码变更到 Issue 文件)
+
+7. **Validation**: `monoco issue lint` (强制执行合规性检查)
+
+## 合规与结构校验 (Validation Rules)
+
+为了确保数据严谨性，所有 Issue Ticket 必须遵循以下强制规则:
+
+### 1. 结构一致性 (Structural Consistency)
+
+- 必须包含一个二级标题 (`##`)，内容必须与 Front Matter 中的 ID 和 Title 严格匹配。
+- 格式: `## {ID}: {Title}`
+- 示例: `## FEAT-0082: Issue Ticket Validator`
+
+### 2. 内容完整性 (Content Completeness)
+
+- **Checkbox 数量**: 每个 Ticket 必须包含至少 2 个 Checkbox（通常代表 AC 和 Tasks）。
+- **评审记录**: 当 `stage` 为 `review` 或 `done` 时，必须包含 `## Review Comments` 标题且内容不能为空。
+
+### 3. Checkbox 语法与层级 (Checkbox Matrix)
+
+- 仅限使用: `- [ ]`, `- [x]`, `- [-]`, `- [/]`。
+- **层级继承**: 若存在嵌套 Checkbox，父项状态必须正确反映子项的聚合结果（例如: 任一子项为 `[/]` 则父项必为 `[/]`；子项全选则父项为 `[x]`）。
+
+### 4. 状态矩阵 (State Matrix)
+
+`status` (物理存放目录) 与 `stage` (Front Matter 字段) 必须兼容:
+
+- **open**: Draft, Doing, Review, Done
+- **backlog**: Draft, Doing, Review
+- **closed**: Done
+
+### 5. 环境策略 (Environment Policy)
+
+Linter 包含环境感知防护：
+
+- 🛑 **Dirty Main Protection**: 当检测到处于受保护分支 (`main`/`master`) 且存在未提交变更时，Lint 将失败并阻止操作。

{monoco_toolkit-0.3.2 → monoco_toolkit-0.3.3}/.github/workflows/ci.yml

@@ -2,14 +2,14 @@ name: CI
 
 on:
   push:
-    tags: ["v*"]
+    tags: ['v*']
   pull_request:
-    branches: ["main"]
+    branches: ['main']
     paths-ignore:
-      - "**.md"
-      - "docs/**"
-      - "mkdocs.yml"
-      - "Kanban/docs/**"
+      - '**.md'
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'Kanban/docs/**'
 
 jobs:
   build-and-test:
@@ -29,7 +29,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version: '3.12'
 
       - name: Install Python Dependencies
         run: uv sync --all-extras --dev

{monoco_toolkit-0.3.2 → monoco_toolkit-0.3.3}/.github/workflows/deploy-vitepress.yml

@@ -4,13 +4,13 @@ on:
   push:
     branches: [main]
     paths:
-      - "site/**"
-      - ".github/workflows/deploy-vitepress.yml"
+      - 'site/**'
+      - '.github/workflows/deploy-vitepress.yml'
   pull_request:
     branches: [main]
     paths:
-      - "site/**"
-      - ".github/workflows/deploy-vitepress.yml"
+      - 'site/**'
+      - '.github/workflows/deploy-vitepress.yml'
   workflow_dispatch:
 
 permissions:

{monoco_toolkit-0.3.2 → monoco_toolkit-0.3.3}/.github/workflows/publish-npm.yml

@@ -3,7 +3,7 @@ name: Publish to NPM
 on:
   push:
     tags:
-      - "v*"
+      - 'v*'
 
 jobs:
   publish-kanban:
@@ -15,8 +15,8 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: "20"
-          registry-url: "https://registry.npmjs.org"
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
 
       - name: Install dependencies
         run: |

{monoco_toolkit-0.3.2 → monoco_toolkit-0.3.3}/.github/workflows/publish-pypi.yml

@@ -3,7 +3,7 @@ name: Publish to PyPI
 on:
   push:
     tags:
-      - "v*"
+      - 'v*'
 
 jobs:
   build-n-publish:
@@ -25,7 +25,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version: '3.12'
 
       - name: Install Dependencies
         run: uv sync --all-extras --dev

{monoco_toolkit-0.3.2 → monoco_toolkit-0.3.3}/.github/workflows/publish-vscode-extension.yml

@@ -3,7 +3,7 @@ name: Publish Toolkit VS Code Extension
 on:
   push:
     tags:
-      - "v*"
+      - 'v*'
   workflow_dispatch:
 
 jobs:
@@ -42,7 +42,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version: '3.12'
 
       - name: Install Python Dependencies
         run: uv sync --all-extras --dev
@@ -72,7 +72,7 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: 20
-          cache: "npm"
+          cache: 'npm'
           cache-dependency-path: extensions/vscode/package-lock.json
 
       - name: Install Dependencies

{monoco_toolkit-0.3.2 → monoco_toolkit-0.3.3}/.monoco/project.yaml

@@ -5,8 +5,12 @@ project:
   key: TOO
   name: Monoco Toolkit
   spike_repos:
+    SWE-agent: https://github.com/SWE-agent/SWE-agent
+    SWE-bench: https://github.com/SWE-bench/SWE-bench
     agentskills: https://github.com/agentskills/agentskills
+    claude-agent-sdk-python: https://github.com/anthropics/claude-agent-sdk-python
     gemini-cli: https://github.com/google-gemini/gemini-cli
     qwen-code: https://github.com/QwenLM/qwen-code
+    ralph: https://github.com/snarktank/ralph
     skills: https://github.com/anthropics/skills
     vibe-kanban: https://github.com/BloopAI/vibe-kanban

{monoco_toolkit-0.3.2 → monoco_toolkit-0.3.3}/.monoco/workspace.yaml

@@ -5,6 +5,20 @@ i18n:
 telemetry:
   enabled: null
 
+domains:
+  items:
+    - name: backend.devops
+      description: DevOps and CI/CD infrastructure
+    - name: infrastructure.container
+      description: Containerization technologies (Docker, K8s)
+    - name: monoco.core
+      description: Monoco core logic
+    - name: monoco.cli
+      description: Monoco CLI interface
+    - name: intelligence
+      description: Artificial Intelligence and Agent capabilities
+  strict: false
+
 issue:
   types:
     - name: epic

monoco_toolkit-0.3.3/.prettierignore

@@ -0,0 +1,46 @@
+# Dependencies
+node_modules
+.venv
+venv
+env
+__pycache__
+
+# Build outputs
+dist
+build
+.next
+out
+.pytest_cache
+.ruff_cache
+.monoco
+
+# Media and binary files
+*.jpg
+*.jpeg
+*.png
+*.gif
+*.svg
+*.ico
+*.pdf
+*.whl
+
+# Git
+.git
+.gitmodules
+
+# Temporary or other
+.DS_Store
+*.log
+.agent
+.claude
+.gemini
+.qwen
+.references
+.reference
+Kanban
+Issues
+Typedown/website/.next
+Toolkit/site
+Toolkit/Kanban
+Toolkit/build
+Toolkit/dist

monoco_toolkit-0.3.3/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 100,
+  "endOfLine": "lf"
+}

{monoco_toolkit-0.3.2/.claude → monoco_toolkit-0.3.3/.qwen}/skills/monoco_core/SKILL.md

@@ -42,6 +42,24 @@ Monoco 是一个开发者生产力工具包，提供:
   - 从 agent 配置文件中移除托管块
   - 清理已分发的 skills
 
+### Git 工作流集成
+
+Monoco 强制执行 **Feature Branch 工作流**以确保代码隔离和质量:
+
+- **`monoco init`**: 自动安装 Git Hooks
+  - **pre-commit**: 运行 Issue Linter 和代码格式检查
+  - **pre-push**: 执行测试套件和完整性验证
+  - 所有 Hooks 可通过 `.monoco/config.yaml` 配置
+
+- **分支隔离策略**:
+  - ⚠️ **强制要求**: 使用 `monoco issue start <ID> --branch` 创建隔离环境
+  - 自动创建规范化分支名: `feat/<id>-<slug>`
+  - **主干保护**: Linter 会阻止在 `main`/`master` 分支上的直接代码修改
+
+- **文件追踪**: `monoco issue sync-files` 自动同步 Git 变更到 Issue 元数据
+
+> 📖 **详细工作流**: 参见 `monoco-issue` skill 获取完整的 Issue 生命周期管理指南。
+
 ## 配置结构
 
 配置以 YAML 格式存储在:
@@ -59,7 +77,21 @@ Monoco 是一个开发者生产力工具包，提供:
 
 ## 最佳实践
 
+### 基础操作
+
 1. **优先使用 CLI 命令**，而不是手动编辑文件
 2. **配置更改后运行 `monoco sync`** 以更新 agent 环境
 3. **将 `.monoco/config.yaml` 提交到版本控制**，保持团队一致性
 4. **保持全局配置最小化** - 大多数设置应该是项目特定的
+
+### Git 工作流 (⚠️ CRITICAL for Agents)
+
+5. **严格遵循分支隔离**:
+   - ✅ 始终使用: `monoco issue start <ID> --branch`
+   - ❌ 禁止在 `main`/`master` 分支直接修改代码
+   - 📝 提交前运行: `monoco issue sync-files` 更新文件追踪
+
+6. **质量门禁**:
+   - Git Hooks 会自动运行检查,不要尝试绕过 (`--no-verify`)
+   - 提交前确保 `monoco issue lint` 通过
+   - 使用 `monoco issue submit` 生成交付报告