monoco-toolkit 0.3.9__py3-none-any.whl → 0.3.11__py3-none-any.whl

monoco/features/issue/resources/en/skills/monoco_workflow_issue_management/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: monoco_workflow_issue_management
+description: Issue Lifecycle Workflow (Flow Skill). Defines the complete Issue management process from creation to closure, ensuring task tracking and process compliance.
+type: workflow
+domain: issue
+version: 1.0.0
+---
+
+# Issue Lifecycle Workflow
+
+Standardized workflow for Issue lifecycle, ensuring "Open → Start → Develop → Submit → Review → Close" process.
+
+## Workflow State Machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> Open: Create Issue
+    
+    Open --> Start: Prepare Development
+    Open --> Open: Requirements Unclear<br/>(Wait for Clarification)
+    
+    Start --> Develop: Branch Created
+    Start --> Start: Branch Conflict<br/>(Resolve Conflict)
+    
+    Develop --> Submit: Development Complete
+    Develop --> Develop: Tests Fail<br/>(Fix Code)
+    
+    state "Oracle Loop" as ReviewLoop {
+        Submit --> Review: Submit for Review
+        Review --> Fix: Rejected
+        Fix --> Submit: Resubmit
+    }
+    
+    Review --> Close: Approved for Merge
+    
+    Close --> [*]: Cleanup Complete
+```
+
+## Execution Steps
+
+### 1. Open
+
+- **Goal**: Create clear, actionable Issue
+- **Input**: Requirement description, type, priority
+- **Output**: Issue Ticket file
+- **Checkpoints**:
+  - [ ] Use `monoco issue create <type> -t "Title"`
+  - [ ] Select appropriate type (epic/feature/chore/fix)
+  - [ ] Write clear description and acceptance criteria
+  - [ ] Set dependency relationships (if needed)
+  - [ ] Ensure at least 2 Checkboxes
+
+### 2. Start
+
+- **Goal**: Prepare development environment, create feature branch
+- **Checkpoints**:
+  - [ ] Run `monoco issue start <ID> --branch`
+  - [ ] Confirm branch is created and switched
+  - [ ] Verify not currently on main/master branch
+  - [ ] Check if dependency Issues are completed
+
+### 3. Develop
+
+- **Goal**: Implement feature or fix bug
+- **Strategy**: Iterative development, continuous testing
+- **Checkpoints**:
+  - [ ] Follow project code standards
+  - [ ] Write/update unit tests
+  - [ ] Run test suite, ensure it passes
+  - [ ] Commit code regularly (small commits)
+  - [ ] Update file tracking (`monoco issue sync-files`)
+
+### 4. Submit
+
+- **Goal**: Prepare for code review
+- **Checkpoints**:
+  - [ ] Run `monoco issue lint` to check compliance
+  - [ ] Fix all Lint errors
+  - [ ] Update task list status
+  - [ ] Run `monoco issue submit <ID>`
+  - [ ] Write change summary
+
+### 5. Review
+
+- **Goal**: Code quality and process compliance check
+- **Checkpoints**:
+  - [ ] Is functionality correctly implemented
+  - [ ] Does code meet design specifications
+  - [ ] Are tests sufficient
+  - [ ] Is documentation updated
+  - [ ] Does it follow project standards
+
+### 6. Close
+
+- **Goal**: Complete Issue, cleanup environment
+- **Checkpoints**:
+  - [ ] Code is merged to main branch
+  - [ ] Run `monoco issue close <ID> --solution completed --prune`
+  - [ ] Verify branch is cleaned up
+  - [ ] Update Review Comments (if needed)
+
+## Decision Branches
+
+| Condition | Action |
+|-----------|--------|
+| Requirements unclear | Return to Open, request clarification |
+| Branch creation fails | Check Git status, resolve conflicts |
+| Tests fail | Return to Develop, fix code |
+| Lint fails | Fix compliance issues, resubmit |
+| Review rejected | Return to Develop, modify per feedback |
+| Review passed | Enter Close, merge and cleanup |
+
+## Compliance Requirements
+
+- **Prohibited**: Directly modify code on main/master branch
+- **Required**: Use `monoco issue start --branch` to create feature branch
+- **Required**: All unit tests must pass before Submit
+- **Required**: Each Issue must have at least 2 Checkboxes
+- **Required**: Review/Done phase must include Review Comments
+- **Recommended**: Small commits, frequently sync file tracking
+
+## Related Commands
+
+```bash
+# Create Issue
+monoco issue create feature -t "Title"
+
+# Start development
+monoco issue start FEAT-0001 --branch
+
+# Sync file tracking
+monoco issue sync-files
+
+# Check compliance
+monoco issue lint
+
+# Submit for review
+monoco issue submit FEAT-0001
+
+# Close Issue
+monoco issue close FEAT-0001 --solution completed --prune
+```
+
+## Issue Type Guide
+
+| Type | Purpose | Prefix | Mindset |
+|------|---------|--------|---------|
+| Epic | Grand goals, vision container | EPIC- | Architect |
+| Feature | User value increment | FEAT- | Product Owner |
+| Chore | Engineering tasks | CHORE- | Builder |
+| Fix | Bug fixes | FIX- | Debugger |
+
+## Relationship with flow_engineer
+
+This workflow complements `flow_engineer`:
+- `issue-lifecycle-workflow`: Focuses on Issue management process
+- `flow_engineer`: Focuses on code implementation process
+
+Engineers should follow `flow_engineer`'s Investigate → Code → Test → Report → Submit process during the Develop phase.

monoco/features/issue/resources/en/skills/monoco_workflow_issue_refinement/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: monoco_workflow_issue_refinement
+description: Investigate and refine Issue, supplement technical details and implementation plan (Copilot Mode)
+type: workflow
+domain: issue
+version: 1.0.0
+---
+
+# Issue Refine Workflow
+
+Standardized workflow for technical investigation, architecture analysis and solution design for newly created or pending refinement Issues.
+
+**Applicable Scenario**: Copilot Mode (Human-led, AI-assisted)
+**Target Users**: Developers who need to deeply understand problems and formulate implementation plans
+
+## Workflow State Machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> Investigate: Start Refinement
+    
+    Investigate --> Analyze: Gather Information
+    Investigate --> Investigate: Insufficient Information<br/>(Continue Investigation)
+    
+    Analyze --> Architect: Architecture Design Required
+    Analyze --> Document: Direct Documentation
+    
+    Architect --> Document: Design Complete
+    
+    Document --> [*]: Issue Refinement Complete
+```
+
+## Execution Steps
+
+### 1. Investigate
+
+- **Goal**: Comprehensively gather information related to the Issue
+- **Input**: Issue Ticket, related code, documentation
+- **Output**: Information gathering report
+- **Checkpoints**:
+  - [ ] Read Issue description, understand core problem
+  - [ ] Identify related code modules and files
+  - [ ] Review related Issue/PR history
+  - [ ] Check external dependencies and constraints
+  - [ ] Collect similar implementation references (Spike)
+
+**Investigation Dimensions**:
+| Dimension | Investigation Content |
+|-----------|----------------------|
+| Code | Current implementation of related modules |
+| History | Related Issues, PRs, design documents |
+| Dependencies | External libraries, APIs, service dependencies |
+| Constraints | Performance requirements, security requirements, compatibility |
+| References | Best practices for similar features |
+
+### 2. Analyze
+
+- **Goal**: Analyze gathered information, identify key problems and solution options
+- **Checkpoints**:
+  - [ ] Analyze architecture inheritance (how to fit into existing architecture)
+  - [ ] Assess security impact
+  - [ ] Assess performance impact
+  - [ ] Assess maintainability
+  - [ ] Identify potential risks and mitigation measures
+
+**Analysis Framework**:
+
+#### Architecture Inheritance
+- Are existing architecture patterns applicable?
+- Is a new abstraction layer needed?
+- Impact on coupling with existing modules?
+
+#### Security Assessment
+- Input validation requirements
+- Access control requirements
+- Data protection requirements
+- Potential attack surface analysis
+
+#### Performance Assessment
+- Time complexity impact
+- Space complexity impact
+- Concurrency/parallelism requirements
+- Resource usage estimation
+
+#### Maintainability Assessment
+- Code complexity changes
+- Test coverage requirements
+- Documentation update requirements
+- Future extensibility
+
+### 3. Architect (Optional)
+
+- **Goal**: Architecture design for complex Issues
+- **Applicable**: Issues involving architecture changes or large features
+- **Checkpoints**:
+  - [ ] Determine technical solution selection
+  - [ ] Design interfaces and interaction protocols
+  - [ ] Plan data model changes
+  - [ ] Define implementation milestones
+
+**Outputs**:
+- Architecture Decision Record (ADR)
+- Interface design document
+- Data model changes
+- Milestone plan
+
+### 4. Document
+
+- **Goal**: Update analysis results to Issue
+- **Checkpoints**:
+  - [ ] Update technical task list
+  - [ ] Add architecture decision explanation
+  - [ ] Supplement risks and mitigation measures
+  - [ ] Update acceptance criteria (if needed)
+  - [ ] Add reference links and dependency descriptions
+  - [ ] Run `monoco issue lint` to verify compliance
+
+**Refined Issue Structure**:
+
+```markdown
+## Objective
+[Original Content]
+
+## Acceptance Criteria
+- [ ] Acceptance criterion 1
+- [ ] Acceptance criterion 2
+
+## Technical Analysis
+
+### Current State Analysis
+Describe current code state and related implementation.
+
+### Solution Selection
+| Solution | Pros | Cons | Decision |
+|----------|------|------|----------|
+| A | ... | ... | Adopted/Alternative |
+| B | ... | ... | Alternative/Abandoned |
+
+### Risk Assessment
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Risk1 | High/Medium/Low | Measure... |
+
+## Technical Tasks
+- [ ] Task 1
+- [ ] Task 2
+
+## References
+- Related Issue: #XXX
+- Reference Implementation: [Link]
+- ADR: [Link]
+```
+
+## Decision Branches
+
+| Condition | Action |
+|-----------|--------|
+| Insufficient information | Return to Investigate, continue gathering |
+| Architecture design needed | Enter Architect phase |
+| Solution is clear | Directly enter Document phase |
+| Blocking dependency found | Create dependency Issue, mark current Issue |
+| Problem too complex | Suggest splitting into multiple Issues |
+
+## Refinement Level Guide
+
+| Issue Type | Refinement Requirements |
+|------------|------------------------|
+| Epic | Must include architecture design, milestones, subtask decomposition |
+| Feature | Must include technical solution, risk assessment, task decomposition |
+| Chore | Must include implementation steps, impact scope |
+| Fix | Must include root cause analysis, fix solution, test cases |
+
+## Related Commands
+
+```bash
+# View Issue details
+monoco issue show <ID>
+
+# Check compliance
+monoco issue lint
+
+# Sync file tracking
+monoco issue sync-files
+
+# View related Spike
+monoco spike list
+```
+
+## Relationship with flow_engineer
+
+This workflow complements `flow_engineer`:
+- `issue-refine-workflow`: Focuses on Issue refinement phase, completing technical investigation before development
+- `flow_engineer`: Focuses on code implementation phase, executing Investigate → Code → Test → Report → Submit
+
+Information gathered during refinement phase will provide important input for the Engineer phase's Investigate.
+
+## Copilot Mode Tips
+
+As an AI Copilot, you should:
+1. **Explore proactively**: Help developers discover potential issues and edge cases
+2. **Provide comparisons**: Give multiple technical solutions, analyze pros and cons
+3. **Assist evaluation**: Help with security, performance impact assessment
+4. **Remind omissions**: Check for missing key information or risk points

monoco/features/issue/resources/hooks/post-checkout.sh

@@ -0,0 +1,39 @@
+#!/bin/sh
+# Issue Feature Post-Checkout Hook
+# Automatically syncs issue status when switching branches
+
+echo "[Monoco] Syncing issue status after branch checkout..."
+
+# Get the previous and current HEAD
+PREVIOUS_HEAD="$1"
+NEW_HEAD="$2"
+BRANCH_SWITCH="$3"  # 1 if branch switch, 0 if file checkout
+
+# Only sync on actual branch switches, not file checkouts
+if [ "$BRANCH_SWITCH" != "1" ]; then
+    echo "[Monoco] File checkout detected, skipping issue sync."
+    exit 0
+fi
+
+# Get current branch name
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "HEAD")
+
+echo "[Monoco] Switched to branch: $CURRENT_BRANCH"
+
+# Try to extract issue ID from branch name
+# Common patterns: FEAT-123, feat/FEAT-123, feature/FEAT-123, fix/FEAT-123
+ISSUE_ID=$(echo "$CURRENT_BRANCH" | grep -oE '[A-Z]+-[0-9]+' | head -1)
+
+if [ -n "$ISSUE_ID" ]; then
+    echo "[Monoco] Detected issue ID from branch: $ISSUE_ID"
+
+    # Check if issue exists and update its isolation ref if needed
+    $MONOCO_CMD issue sync-isolation "$ISSUE_ID" --branch "$CURRENT_BRANCH" 2>/dev/null || true
+fi
+
+# Run general sync to ensure files field is up to date
+echo "[Monoco] Running issue file sync..."
+$MONOCO_CMD issue sync-files 2>/dev/null || true
+
+echo "[Monoco] Issue sync complete."
+exit 0

monoco/features/issue/resources/hooks/pre-commit.sh

@@ -0,0 +1,41 @@
+#!/bin/sh
+# Issue Feature Pre-Commit Hook
+# Runs monoco issue lint on staged Issue files
+
+echo "[Monoco] Checking Issue integrity..."
+
+# Get the list of staged Issue files
+STAGED_ISSUES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '^Issues/.*\.md$' || true)
+
+if [ -z "$STAGED_ISSUES" ]; then
+    echo "[Monoco] No Issue files staged. Skipping lint."
+    exit 0
+fi
+
+# Run lint on staged Issue files
+echo "[Monoco] Running lint on staged Issue files..."
+
+# Build file list for monoco command
+FILE_ARGS=""
+for file in $STAGED_ISSUES; do
+    FILE_ARGS="$FILE_ARGS $file"
+done
+
+# Execute lint on each file
+LINT_EXIT=0
+for file in $STAGED_ISSUES; do
+    $MONOCO_CMD issue lint "$file"
+    if [ $? -ne 0 ]; then
+        LINT_EXIT=1
+    fi
+done
+
+if [ $LINT_EXIT -ne 0 ]; then
+    echo ""
+    echo "[Monoco] Issue lint failed. Please fix the errors above."
+    echo "[Monoco] You can run 'monoco issue lint --fix' to attempt automatic fixes."
+    exit $LINT_EXIT
+fi
+
+echo "[Monoco] Issue lint passed."
+exit 0

monoco/features/issue/resources/hooks/pre-push.sh

@@ -0,0 +1,35 @@
+#!/bin/sh
+# Issue Feature Pre-Push Hook
+# Checks for incomplete critical issues before pushing
+
+echo "[Monoco] Checking critical issues before push..."
+
+# Get the list of commits being pushed
+# $1 = remote name, $2 = remote url (if available)
+REMOTE="$1"
+URL="$2"
+
+# Check for high/critical issues that are not closed
+# This uses monoco issue query to find open issues with high/critical criticality
+echo "[Monoco] Scanning for incomplete critical issues..."
+
+# Run the check using monoco command
+$MONOCO_CMD issue check-critical --fail-on-warning
+CHECK_EXIT=$?
+
+if [ $CHECK_EXIT -eq 2 ]; then
+    echo ""
+    echo "[Monoco] ❌ Critical issues found! Push blocked."
+    echo "[Monoco] Please close or resolve the critical issues above before pushing."
+    exit 1
+elif [ $CHECK_EXIT -eq 1 ]; then
+    echo ""
+    echo "[Monoco] ⚠️  High priority issues found."
+    echo "[Monoco] Use --force-push to bypass this warning (not recommended)."
+    # For now, we allow the push but warn
+    # To block, change the exit code to 1
+    exit 0
+fi
+
+echo "[Monoco] ✓ No blocking critical issues found."
+exit 0

monoco/features/issue/resources/zh/AGENTS.md

@@ -20,3 +20,112 @@
      - 🛑 **禁止**直接在 `main`/`master` 分支修改代码 (Linter 会报错)。
      - **清理时机**: 环境清理仅应在 `close` 时执行。**禁止**在 `submit` 阶段清理环境。
      - 修改代码后**必须**更新 `files` 字段（通过 `sync-files` 或手动）。
+
+## Git 合并策略 (Merge Strategy)
+
+### 核心原则
+
+为确保 Feature 分支安全合并到主线，避免"旧状态污染主线"问题，必须遵循以下合并策略：
+
+#### 1. 禁止手动 Merge
+
+- **🛑 严禁** Agent 手动执行 `git merge` 合并 Feature 分支
+- **🛑 严禁** 使用 `git pull origin main` 后直接提交
+- **✅ 唯一权威途径**: 必须使用 `monoco issue close` 进行闭环
+
+#### 2. 安全合并流程 (Safe Merge Flow)
+
+正确的 Issue 关闭流程如下：
+
+```bash
+# 1. 确保当前在 main/master 分支，且代码已合并
+$ git checkout main
+$ git pull origin main
+
+# 2. 确认 Feature 分支的变更已合并到主线
+#    (通过 PR/MR 或其他代码审查流程)
+
+# 3. 使用 monoco issue close 关闭 Issue (默认执行 prune)
+$ monoco issue close FEAT-XXXX --solution implemented
+
+# 4. 如需保留分支，使用 --no-prune
+$ monoco issue close FEAT-XXXX --solution implemented --no-prune
+```
+
+#### 3. 冲突处理原则
+
+当 Feature 分支与主线产生冲突时：
+
+1. **自动合并停止**: 如果 `touched files` (Issue `files` 字段) 与主线产生冲突，自动化工具**必须立即停止合并**，并抛出明确错误。
+
+2. **手动 Cherry-Pick 模式**: 
+   - 错误信息会指示 Agent 转入手动 Cherry-Pick 模式
+   - **核心原则**: 仅挑选属于本 Feature 的有效变更，严禁覆盖主线上无关 Issue 的更新
+   - 使用 `git cherry-pick <commit>` 逐个应用有效提交
+
+3. **Fallback 策略**:
+   ```bash
+   # 1. 创建临时分支用于解决冲突
+   $ git checkout main
+   $ git checkout -b temp/FEAT-XXXX-resolve
+   
+   # 2. 逐个 Cherry-Pick 有效提交
+   $ git cherry-pick <commit-hash-1>
+   $ git cherry-pick <commit-hash-2>
+   
+   # 3. 如有冲突，仅保留本 Feature 的变更
+   #    放弃任何会覆盖主线上其他 Issue 更新的修改
+   
+   # 4. 完成后合并临时分支
+   $ git checkout main
+   $ git merge temp/FEAT-XXXX-resolve
+   
+   # 5. 关闭 Issue
+   $ monoco issue close FEAT-XXXX --solution implemented
+   ```
+
+#### 4. 基于 files 字段的智能合并 (Smart Atomic Merge)
+
+Issue 的 `files` 字段记录了 Feature 分支的真实影响范围 (Actual Impact Scope)：
+
+- **生成方式**: `monoco issue sync-files` 使用 `git diff --name-only base...target` 逻辑
+- **作用**: 作为合并白名单，仅合并列表中的文件，过滤因"旧版本基线"导致的隐性覆盖
+- **限制**: 无法防御显式的误操作修改（如无意中格式化其他 Issue 文件）
+
+**未来增强**: 基于 `files` 列表实现选择性合并逻辑：
+```bash
+# 选择性合并（规划中）
+$ git checkout main
+$ git checkout feature/FEAT-XXXX -- <files...>
+```
+
+#### 5. 清理策略
+
+- **默认清理**: `monoco issue close` 默认执行 `--prune`，删除 Feature 分支/Worktree
+- **保留分支**: 如需保留分支，显式使用 `--no-prune`
+- **强制清理**: 使用 `--force` 强制删除未完全合并的分支（谨慎使用）
+
+```bash
+# 默认清理分支
+$ monoco issue close FEAT-XXXX --solution implemented
+# ✔ Cleaned up: branch:feat/feat-XXXX-xxx
+
+# 保留分支
+$ monoco issue close FEAT-XXXX --solution implemented --no-prune
+
+# 强制清理（谨慎）
+$ monoco issue close FEAT-XXXX --solution implemented --force
+```
+
+### 总结
+
+| 操作 | 命令 | 说明 |
+|------|------|------|
+| 创建 Issue | `monoco issue create feature -t "标题"` | 先创建 Issue 再开发 |
+| 启动开发 | `monoco issue start FEAT-XXXX --branch` | 创建 Feature 分支 |
+| 同步文件 | `monoco issue sync-files` | 更新 files 字段 |
+| 提交评审 | `monoco issue submit FEAT-XXXX` | 进入 Review 阶段 |
+| 关闭 Issue | `monoco issue close FEAT-XXXX --solution implemented` | 唯一合并途径 |
+| 保留分支 | `monoco issue close ... --no-prune` | 关闭但不删除分支 |
+
+> ⚠️ **警告**: 任何绕过 `monoco issue close` 的手动合并操作都可能导致主线状态污染，违反工作流合规要求。

monoco/features/issue/resources/zh/{SKILL.md → skills/monoco_atom_issue_lifecycle/SKILL.md}

@@ -1,6 +1,8 @@
 ---
-name: monoco-issue
+name: monoco_atom_issue_lifecycle
 description: Monoco Issue System 的官方技能定义。将 Issue 视为通用原子 (Universal Atom)，管理 Epic/Feature/Chore/Fix 的生命周期。
+type: atom
+version: 1.0.0
 ---
 
 # 自我管理 (Monoco Issue System)