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

monoco/features/agent/flow_skills.py

@@ -0,0 +1,281 @@
+"""
+Flow Skills Manager for Monoco Scheduler.
+
+This module provides management and injection of standard Agent workflow skills
+(Flow Skills) following the Kimi CLI Flow Skill format.
+
+Note: This module is now a thin wrapper around SkillManager for backward compatibility.
+New code should use SkillManager directly for multi-skill architecture support.
+
+Key Responsibilities:
+1. Discover flow skills from resources/skills/ directory
+2. Inject flow skills to target agent framework directories
+3. Handle .gitignore updates for injected skills
+"""
+
+import shutil
+from pathlib import Path
+from typing import List, Set
+from rich.console import Console
+
+console = Console()
+
+# Prefix for injected flow skills to avoid conflicts
+FLOW_SKILL_PREFIX = "monoco_flow_"
+
+# Gitignore pattern for flow skills
+GITIGNORE_PATTERN = f"{FLOW_SKILL_PREFIX}*/"
+
+
+def discover_flow_skills(resources_dir: Path) -> List[Path]:
+    """
+    Discover all flow skill directories in the resources/skills/ directory.
+
+    Flow skills are identified by either:
+    1. Directory name starting with "flow_" (legacy pattern)
+    2. SKILL.md containing "type: flow" in front matter (new pattern)
+
+    Args:
+        resources_dir: Path to the resources directory (e.g., monoco/features/scheduler/resources/)
+
+    Returns:
+        List of paths to flow skill directories
+    """
+    skills_dir = resources_dir / "skills"
+    if not skills_dir.exists():
+        return []
+
+    flow_skills = []
+    for item in skills_dir.iterdir():
+        if not item.is_dir():
+            continue
+
+        skill_file = item / "SKILL.md"
+        if not skill_file.exists():
+            continue
+
+        # Check legacy pattern: directory starts with "flow_"
+        if item.name.startswith("flow_"):
+            flow_skills.append(item)
+            continue
+
+        # Check new pattern: SKILL.md contains "type: flow" in front matter
+        try:
+            content = skill_file.read_text(encoding="utf-8")
+            # Look for type: flow in front matter (between --- markers)
+            if content.startswith("---"):
+                front_matter_end = content.find("---", 3)
+                if front_matter_end != -1:
+                    front_matter = content[3:front_matter_end]
+                    if "type: flow" in front_matter:
+                        flow_skills.append(item)
+        except Exception:
+            pass  # Skip files that can't be read
+
+    return sorted(flow_skills)
+
+
+def inject_flow_skill(
+    skill_dir: Path, target_dir: Path, prefix: str = FLOW_SKILL_PREFIX
+) -> bool:
+    """
+    Inject a single flow skill to the target directory.
+
+    Args:
+        skill_dir: Source flow skill directory (e.g., .../flow_engineer/)
+        target_dir: Target directory for skill injection (e.g., .agent/skills/)
+        prefix: Prefix to add to the skill directory name
+
+    Returns:
+        True if injection successful, False otherwise
+    """
+    try:
+        # Calculate target skill name with prefix
+        # e.g., flow_engineer -> monoco_flow_engineer
+        target_skill_name = f"{prefix}{skill_dir.name}"
+        target_skill_dir = target_dir / target_skill_name
+
+        # Remove existing skill directory if present
+        if target_skill_dir.exists():
+            shutil.rmtree(target_skill_dir)
+
+        # Copy skill directory
+        shutil.copytree(skill_dir, target_skill_dir)
+
+        console.print(f"[green]  ✓ Injected {target_skill_name}/[/green]")
+        return True
+
+    except Exception as e:
+        console.print(f"[red]  ✗ Failed to inject {skill_dir.name}: {e}[/red]")
+        return False
+
+
+def sync_flow_skills(
+    resources_dir: Path,
+    target_dir: Path,
+    prefix: str = FLOW_SKILL_PREFIX,
+    force: bool = False,
+) -> dict:
+    """
+    Synchronize all flow skills from resources to target directory.
+
+    This function:
+    1. Discovers all flow skills in resources/skills/
+    2. Injects them to target_dir with the specified prefix
+    3. Optionally removes skills that no longer exist in source
+
+    Args:
+        resources_dir: Path to the resources directory
+        target_dir: Target directory for skill injection (e.g., .agent/skills/)
+        prefix: Prefix to add to skill directory names
+        force: Force re-injection even if skills already exist
+
+    Returns:
+        Dictionary with 'injected', 'failed', 'removed' counts
+    """
+    results = {"injected": 0, "failed": 0, "removed": 0}
+
+    # Ensure target directory exists
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    # Discover flow skills
+    flow_skills = discover_flow_skills(resources_dir)
+
+    if not flow_skills:
+        console.print("[yellow]No flow skills found in resources[/yellow]")
+        return results
+
+    console.print(f"[dim]Found {len(flow_skills)} flow skill(s)[/dim]")
+
+    # Track expected skill names
+    expected_skills: Set[str] = set()
+
+    # Inject each flow skill
+    for skill_dir in flow_skills:
+        target_skill_name = f"{prefix}{skill_dir.name}"
+        expected_skills.add(target_skill_name)
+
+        # Check if already exists and not force
+        target_skill_dir = target_dir / target_skill_name
+        if target_skill_dir.exists() and not force:
+            # Check if source is newer
+            source_mtime = (skill_dir / "SKILL.md").stat().st_mtime
+            target_mtime = (target_skill_dir / "SKILL.md").stat().st_mtime
+
+            if source_mtime <= target_mtime:
+                console.print(f"[dim]  = {target_skill_name}/ is up to date[/dim]")
+                continue
+
+        if inject_flow_skill(skill_dir, target_dir, prefix):
+            results["injected"] += 1
+        else:
+            results["failed"] += 1
+
+    # Clean up orphaned skills (optional, when force=True)
+    if force:
+        for item in target_dir.iterdir():
+            if item.is_dir() and item.name.startswith(prefix):
+                if item.name not in expected_skills:
+                    shutil.rmtree(item)
+                    console.print(f"[dim]  - Removed orphaned {item.name}/[/dim]")
+                    results["removed"] += 1
+
+    return results
+
+
+def update_gitignore(project_root: Path, pattern: str = GITIGNORE_PATTERN) -> bool:
+    """
+    Add flow skill pattern to .gitignore if not present.
+
+    Args:
+        project_root: Project root directory
+        pattern: Gitignore pattern to add
+
+    Returns:
+        True if .gitignore was updated or already contains pattern
+    """
+    gitignore_path = project_root / ".gitignore"
+
+    try:
+        # Read existing content
+        if gitignore_path.exists():
+            content = gitignore_path.read_text(encoding="utf-8")
+            lines = content.splitlines()
+        else:
+            lines = []
+
+        # Check if pattern already exists
+        for line in lines:
+            if line.strip() == pattern or line.strip() == f"/{pattern}":
+                return True
+
+        # Add pattern with comment
+        comment = "# Monoco Flow Skills (auto-generated)"
+        new_lines = [comment, pattern, ""]
+
+        # Append to file
+        with open(gitignore_path, "a", encoding="utf-8") as f:
+            # Add newline if file doesn't end with one
+            if lines and not content.endswith("\n"):
+                f.write("\n")
+            f.write("\n".join(new_lines))
+
+        console.print(f"[green]  ✓ Updated .gitignore with {pattern}[/green]")
+        return True
+
+    except Exception as e:
+        console.print(f"[red]  ✗ Failed to update .gitignore: {e}[/red]")
+        return False
+
+
+def remove_flow_skills(target_dir: Path, prefix: str = FLOW_SKILL_PREFIX) -> int:
+    """
+    Remove all injected flow skills from target directory.
+
+    Args:
+        target_dir: Target directory (e.g., .agent/skills/)
+        prefix: Prefix used for flow skill directories
+
+    Returns:
+        Number of skills removed
+    """
+    if not target_dir.exists():
+        return 0
+
+    removed_count = 0
+    for item in target_dir.iterdir():
+        if item.is_dir() and item.name.startswith(prefix):
+            shutil.rmtree(item)
+            console.print(f"[green]  ✓ Removed {item.name}/[/green]")
+            removed_count += 1
+
+    return removed_count
+
+
+def get_flow_skill_commands(target_dir: Path, prefix: str = FLOW_SKILL_PREFIX) -> List[str]:
+    """
+    Get list of available flow skill commands.
+
+    In Kimi CLI, flow skills are invoked via /flow:<role> command.
+    This function extracts the role names from injected flow skills.
+
+    Args:
+        target_dir: Target directory (e.g., .agent/skills/)
+        prefix: Prefix used for flow skill directories
+
+    Returns:
+        List of available /flow:<role> commands
+    """
+    if not target_dir.exists():
+        return []
+
+    commands = []
+    for item in target_dir.iterdir():
+        if item.is_dir() and item.name.startswith(prefix):
+            # Extract role from directory name
+            # e.g., monoco_flow_engineer -> engineer
+            role = item.name[len(prefix) + 5:]  # Remove prefix + "flow_"
+            if role:
+                commands.append(f"/flow:{role}")
+
+    return sorted(commands)

monoco/features/{scheduler → agent}/manager.py

@@ -1,8 +1,12 @@
 from typing import Dict, List, Optional
 import uuid
+from pathlib import Path
+
 from .models import RoleTemplate
 from .worker import Worker
 from .session import Session, RuntimeSession
+from monoco.core.hooks import HookRegistry, get_registry
+from monoco.core.config import find_monoco_root, MonocoConfig
 
 
 class SessionManager:
@@ -11,9 +15,37 @@ class SessionManager:
     Responsible for creating, tracking, and retrieving sessions.
     """
 
-    def __init__(self):
+    def __init__(
+        self,
+        project_root: Optional[Path] = None,
+        hook_registry: Optional[HookRegistry] = None,
+        config: Optional[MonocoConfig] = None,
+    ):
         # In-memory storage for now. In prod, this might be a DB or file-backed.
         self._sessions: Dict[str, RuntimeSession] = {}
+        self.project_root = project_root or find_monoco_root()
+        self.config = config
+        
+        # Initialize hook registry
+        self.hook_registry = hook_registry or get_registry()
+        
+        # Load hooks from config if available
+        self._load_hooks_from_config()
+
+    def _load_hooks_from_config(self) -> None:
+        """Load and register hooks from configuration."""
+        if self.config is None:
+            try:
+                from monoco.core.config import get_config
+                self.config = get_config(str(self.project_root))
+            except Exception:
+                return
+        
+        # Load hooks from config
+        if self.config and hasattr(self.config, "session_hooks"):
+            hooks_config = self.config.session_hooks
+            if hooks_config:
+                self.hook_registry.load_from_config(hooks_config, self.project_root)
 
     def create_session(self, issue_id: str, role: RoleTemplate) -> RuntimeSession:
         session_id = str(uuid.uuid4())
@@ -29,7 +61,12 @@ class SessionManager:
         )
 
         worker = Worker(role, issue_id)
-        runtime = RuntimeSession(session_model, worker)
+        runtime = RuntimeSession(
+            session_model, 
+            worker,
+            hook_registry=self.hook_registry,
+            project_root=self.project_root,
+        )
         self._sessions[session_id] = runtime
         return runtime
 

monoco/features/{scheduler → agent}/models.py

@@ -4,14 +4,13 @@ from pydantic import BaseModel, Field
 
 class RoleTemplate(BaseModel):
     name: str = Field(
-        ..., description="Unique identifier for the role (e.g., 'crafter')"
+        ..., description="Unique identifier for the role (e.g., 'Planner')"
     )
     description: str = Field(..., description="Human-readable description of the role")
     trigger: str = Field(
         ..., description="Event that triggers this agent (e.g., 'issue.created')"
     )
     goal: str = Field(..., description="The primary goal/output of this agent")
-    tools: List[str] = Field(default_factory=list, description="List of allowed tools")
     system_prompt: str = Field(
         ..., description="The system prompt template for this agent"
     )
@@ -20,5 +19,9 @@ class RoleTemplate(BaseModel):
     )
 
 
-class SchedulerConfig(BaseModel):
+class AgentConfig(BaseModel):
     roles: List[RoleTemplate] = Field(default_factory=list)
+
+
+# Backward compatibility alias
+SchedulerConfig = AgentConfig

monoco/features/{scheduler → agent}/reliability.py

@@ -20,7 +20,7 @@ class ApoptosisManager:
         roles = load_scheduler_config(project_root)
 
         # Find coroner role
-        self.coroner_role = roles.get("coroner")
+        self.coroner_role = roles.get("Coroner")
 
         if not self.coroner_role:
             raise ValueError("Coroner role not defined!")

monoco/features/agent/resources/skills/flow_engineer/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: flow-engineer
+description: Engineer 角色的标准化工作流 (Flow Skill)。定义从需求调研到代码提交的标准操作流程，确保测试覆盖和代码质量。
+type: flow
+role: engineer
+version: 1.0.0
+---
+
+# Engineer Flow
+
+Engineer 角色的标准化工作流，确保代码开发遵循 "Investigate → Code → Test → Report → Submit" 流程。
+
+## 工作流状态机
+
+```mermaid
+stateDiagram-v2
+    [*] --> Investigate: 接收任务
+    
+    Investigate --> Code: 需求清晰
+    Investigate --> Investigate: 需求模糊<br/>(请求澄清)
+    
+    Code --> Test: 编码完成
+    
+    Test --> Test: 测试失败<br/>(修复代码)
+    Test --> Report: 测试通过
+    
+    Report --> Submit: 报告完成
+    
+    Submit --> [*]: 提交成功
+```
+
+## 执行步骤
+
+### 1. Investigate (调研)
+
+- **目标**: 充分理解需求，识别技术风险和依赖
+- **输入**: Issue 描述、相关代码、依赖 Issue
+- **输出**: 技术方案草稿、风险清单
+- **检查点**:
+  - [ ] 阅读并理解 Issue 描述
+  - [ ] 识别相关代码文件
+  - [ ] 检查依赖 Issue 状态
+  - [ ] 评估技术可行性
+
+### 2. Code (编码)
+
+- **目标**: 实现功能或修复缺陷
+- **前置条件**: 需求已清晰，分支已创建 (`monoco issue start <ID> --branch`)
+- **检查点**:
+  - [ ] 遵循项目代码规范
+  - [ ] 编写/更新必要的文档
+  - [ ] 处理边界情况
+
+### 3. Test (测试)
+
+- **目标**: 确保代码质量和功能正确性
+- **策略**: 循环测试直到通过
+- **检查点**:
+  - [ ] 编写/更新单元测试
+  - [ ] 运行测试套件 (`pytest`, `cargo test`, etc.)
+  - [ ] 修复失败的测试
+  - [ ] 检查测试覆盖率
+
+### 4. Report (报告)
+
+- **目标**: 记录变更内容，更新 Issue 状态
+- **检查点**:
+  - [ ] 更新 Issue 文件追踪 (`monoco issue sync-files`)
+  - [ ] 编写变更摘要
+  - [ ] 更新任务清单 (Checkboxes)
+
+### 5. Submit (提交)
+
+- **目标**: 完成代码提交，进入评审流程
+- **检查点**:
+  - [ ] 运行 `monoco issue lint` 检查合规性
+  - [ ] 运行 `monoco issue submit <ID>`
+  - [ ] 等待评审结果
+
+## 决策分支
+
+| 条件 | 动作 |
+|------|------|
+| 需求不清晰 | 返回 Investigate，请求澄清 |
+| 测试失败 | 返回 Code，修复问题 |
+| Lint 失败 | 修复合规性问题，重新 Submit |
+| 评审拒绝 | 返回 Code，按反馈修改 |
+
+## 合规要求
+
+- **禁止**: 跳过测试直接提交
+- **禁止**: 在 main/master 分支直接修改代码
+- **必须**: 使用 `monoco issue start --branch` 创建功能分支
+- **必须**: 所有单元测试通过后才能 Submit

monoco/features/agent/resources/skills/flow_manager/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: flow-manager
+description: Manager 角色的标准化工作流 (Flow Skill)。定义从 Inbox 整理到任务指派的标准操作流程，确保需求清晰和任务合理拆解。
+type: flow
+role: manager
+version: 1.0.0
+---
+
+# Manager Flow
+
+Manager 角色的标准化工作流，确保 "Inbox → Clarify → Decompose → Assign" 流程。
+
+## 工作流状态机
+
+```mermaid
+stateDiagram-v2
+    [*] --> Inbox: 新需求/想法
+    
+    Inbox --> Clarify: 开始处理
+    Inbox --> Inbox: 暂存<br/>(低优先级)
+    
+    Clarify --> Decompose: 需求清晰
+    Clarify --> Clarify: 需更多信息<br/>(等待反馈)
+    
+    Decompose --> Assign: 拆解完成
+    Decompose --> Decompose: 过于复杂<br/>(拆分为 Epic)
+    
+    Assign --> [*]: 指派完成
+```
+
+## 执行步骤
+
+### 1. Inbox (收件箱)
+
+- **目标**: 收集和暂存所有 incoming 需求、想法和任务
+- **输入**: Memo、用户反馈、系统告警、技术债务
+- **检查点**:
+  - [ ] 记录需求来源和背景
+  - [ ] 初步分类 (Feature/Chore/Fix)
+  - [ ] 评估紧急程度
+
+### 2. Clarify (需求澄清)
+
+- **目标**: 将模糊的需求转化为清晰的描述
+- **策略**: 5W2H 分析法
+- **检查点**:
+  - [ ] **What**: 要解决什么问题？
+  - [ ] **Why**: 为什么重要？
+  - [ ] **Who**: 谁是利益相关者？
+  - [ ] **When**: 期望的完成时间？
+  - [ ] **Where**: 影响范围？
+  - [ ] **How**: 建议的实现方式？
+  - [ ] **How Much**: 工作量预估？
+
+### 3. Decompose (任务拆解)
+
+- **目标**: 将大任务拆分为可独立交付的子任务
+- **策略**: 垂直切片 (Vertical Slicing)
+- **检查点**:
+  - [ ] 识别核心价值和依赖关系
+  - [ ] 拆分为可独立交付的 Feature/Chore/Fix
+  - [ ] 设置合理的优先级
+  - [ ] 为复杂任务创建 Epic
+
+### 4. Assign (任务指派)
+
+- **目标**: 将任务分配给合适的执行者
+- **检查点**:
+  - [ ] 评估团队能力和负载
+  - [ ] 明确验收标准 (Acceptance Criteria)
+  - [ ] 设置合理的截止日期
+  - [ ] 通知相关成员
+
+## 决策分支
+
+| 条件 | 动作 |
+|------|------|
+| 需求过于模糊 | 返回 Inbox，等待更多信息 |
+| 任务过于复杂 | 创建 Epic，拆分为多个 Feature |
+| 依赖其他任务 | 设置依赖关系，调整优先级 |
+| 资源不足 | 调整范围或延期 |
+
+## 合规要求
+
+- **必须**: 每个任务都有清晰的验收标准
+- **必须**: 复杂任务必须拆分为 Epic + Features
+- **禁止**: 指派没有澄清需求给 Engineer
+- **建议**: 使用 `monoco memo` 管理临时想法

monoco/features/agent/resources/skills/flow_reviewer/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: flow-reviewer
+description: Reviewer 角色的标准化工作流 (Flow Skill)。定义从代码检出到评审完成的标准操作流程，确保代码质量和流程合规。
+type: flow
+role: reviewer
+version: 1.0.0
+---
+
+# Reviewer Flow
+
+Reviewer 角色的标准化工作流，确保 "Checkout → Test → Review → Decide → Cleanup" 流程。
+
+## 工作流状态机
+
+```mermaid
+stateDiagram-v2
+    [*] --> Checkout: 收到评审请求
+    
+    Checkout --> Test: 检出完成
+    Checkout --> Checkout: 检出失败<br/>(环境检查)
+    
+    Test --> Review: 测试通过
+    Test --> Test: 测试失败<br/>(记录问题)
+    
+    Review --> Approve: 代码 OK
+    Review --> Reject: 发现问题
+    
+    Reject --> Checkout: 修复后重审
+    
+    Approve --> Cleanup: 批准
+    
+    Cleanup --> [*]: 清理完成
+```
+
+## 执行步骤
+
+### 1. Checkout (检出)
+
+- **目标**: 获取待评审的代码
+- **检查点**:
+  - [ ] 检出 PR/Branch
+  - [ ] 确认与 Base 分支的差异
+  - [ ] 检查环境配置
+
+### 2. Test (测试)
+
+- **目标**: 验证功能正确性和测试覆盖
+- **检查点**:
+  - [ ] 运行单元测试
+  - [ ] 运行集成测试 (如适用)
+  - [ ] 验证手动测试场景
+  - [ ] 检查测试覆盖率报告
+
+### 3. Review (代码审查)
+
+- **目标**: 检查代码质量和设计合理性
+- **检查清单**:
+  - [ ] **功能**: 代码是否实现了需求？
+  - [ ] **设计**: 架构是否合理？
+  - [ ] **可读性**: 代码是否易于理解？
+  - [ ] **测试**: 测试是否充分？
+  - [ ] **文档**: 文档是否同步更新？
+  - [ ] **合规**: 是否遵循项目规范？
+
+### 4. Decide (决策)
+
+- **目标**: 做出批准或拒绝的决定
+- **选项**:
+  - **Approve**: 代码可以合并
+  - **Reject**: 需要修改，提供具体反馈
+  - **Request Changes**: 小问题，可快速修复
+
+### 5. Cleanup (清理)
+
+- **目标**: 完成评审后的环境清理
+- **检查点**:
+  - [ ] 删除本地分支 (如适用)
+  - [ ] 更新 Issue 状态
+  - [ ] 记录评审意见到 Review Comments
+
+## 决策分支
+
+| 条件 | 动作 |
+|------|------|
+| 测试失败 | Reject，要求修复测试 |
+| 代码风格问题 | Request Changes 或提供建议 |
+| 设计问题 | Reject，要求重新设计 |
+| 文档缺失 | Request Changes，要求补充 |
+| 修复后重审 | 返回 Checkout，重新执行流程 |
+
+## 评审意见模板
+
+```markdown
+## Review Comments
+
+### ✅ 优点
+- 
+
+### ⚠️ 建议
+- 
+
+### ❌ 必须修改
+- 
+
+### 📝 其他
+- 
+```
+
+## 合规要求
+
+- **必须**: 所有测试通过才能 Approve
+- **必须**: 拒绝时必须提供具体反馈
+- **禁止**: 未经测试直接 Approve
+- **建议**: 使用 `monoco issue close --prune` 合并后清理