kanban-framework 0.13.1__tar.gz

kanban_framework-0.13.1/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: kanban-framework
+Version: 0.13.1
+Summary: Kanban multi-agent orchestration framework for Claude Code
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"

kanban_framework-0.13.1/core/__init__.py

@@ -0,0 +1,3 @@
+"""Kanban multi-agent orchestration framework."""
+
+__version__ = "0.2.0"

kanban_framework-0.13.1/core/__main__.py

@@ -0,0 +1,18 @@
+"""Allow running kanban as: python -m core <cmd>
+
+Supports two invocation modes:
+  1. From framework root:  cd .claude/skills/kanban && python -m core status
+  2. From project root:    PYTHONPATH=.claude/skills/kanban python -m core status
+"""
+import sys
+import os
+
+# Add framework root to sys.path so core module can be imported from any cwd
+# __file__ = .../core/__main__.py -> parent = .../kanban/ (contains core/)
+_framework_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if _framework_root not in sys.path:
+    sys.path.insert(0, _framework_root)
+
+from core.cli.main import main
+
+main()

kanban_framework-0.13.1/core/cli/__init__.py

@@ -0,0 +1 @@
+from .main import main

kanban_framework-0.13.1/core/cli/evaluator.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+from pathlib import Path
+from core.infra.filesystem import Filesystem
+from core.infra.config import Config
+from core.domain.task import TaskManager
+
+
+def dispatch(args: list[str]) -> dict:
+    if not args:
+        return {"error": "subcommand required: collect-scores, record-score, collect-plan-review"}
+    sub = args[0]
+    task_id = args[1] if len(args) > 1 else "unknown"
+    root = Filesystem.find_project_root()
+    fs = Filesystem(root=root)
+    cfg = Config(fs)
+    tm = TaskManager(fs, cfg)
+
+    if sub == "collect-scores":
+        return _collect_scores(fs, tm, task_id)
+    if sub == "record-score":
+        return _record_score(fs, tm, task_id)
+    if sub == "collect-plan-review":
+        return _collect_plan_review_scores(fs, tm, task_id)
+    return {"error": f"unknown evaluator subcommand: {sub}"}
+
+
+def _collect_scores(fs: Filesystem, tm: TaskManager, task_id: str) -> dict:
+    try:
+        task = tm.show(task_id)
+    except Exception:
+        return {"task_id": task_id, "scores": [], "average": None}
+
+    scores = []
+    for it in range(1, task.iteration + 1):
+        report_dir = fs.report_dir(task_id, it)
+        if not report_dir.exists():
+            continue
+
+        for role in ["code_reviewer", "qa", "pm", "designer"]:
+            rf = report_dir / f"{role}_report.json"
+            if fs.file_exists(rf):
+                data = fs.read_json(rf)
+                scores.append({
+                    "role": role,
+                    "iteration": it,
+                    "total": data.get("total", data.get("score", data.get("overall", 0))),
+                })
+
+    avg = round(sum(s["total"] for s in scores) / len(scores), 2) if scores else None
+    return {"task_id": task_id, "scores": scores, "average": avg}
+
+
+def _record_score(fs: Filesystem, tm: TaskManager, task_id: str) -> dict:
+    scores_data = _collect_scores(fs, tm, task_id)
+    try:
+        task = tm.show(task_id)
+    except Exception:
+        return {"task_id": task_id, "error": "task not found"}
+
+    avg = scores_data["average"]
+    if avg is None:
+        return {"task_id": task_id, "recorded": False, "error": "no scores to record"}
+
+    # Build per-iteration role scores dict
+    role_scores = {s["role"]: s["total"] for s in scores_data["scores"]
+                   if s["iteration"] == task.iteration}
+
+    # Append to score_history
+    entry = {
+        "iteration": task.iteration,
+        "average": avg,
+        "roles": role_scores,
+    }
+    new_history = list(task.score_history)
+    # Replace existing entry for same iteration; otherwise append
+    replaced = False
+    for i, h in enumerate(new_history):
+        if h.get("iteration") == task.iteration:
+            new_history[i] = entry
+            replaced = True
+            break
+    if not replaced:
+        new_history.append(entry)
+
+    tm.update(task_id, scores=role_scores, score_history=new_history)
+
+    return {
+        "task_id": task_id,
+        "recorded": True,
+        "iteration": task.iteration,
+        "average": avg,
+    }
+
+
+_PLAN_REVIEW_DIMENSIONS = [
+    "requirement_clarity", "technical_feasibility",
+    "task_decomposition", "acceptance_criteria",
+    "research_completeness", "parallel_safety",
+]
+
+
+def _collect_plan_review_scores(
+    fs: Filesystem, tm: TaskManager, task_id: str
+) -> dict:
+    try:
+        task = tm.show(task_id)
+    except Exception:
+        return {"task_id": task_id, "dimensions": [], "average": None}
+
+    dimensions = []
+    for it in range(1, task.iteration + 1):
+        report_dir = fs.report_dir(task_id, it)
+        if not report_dir.exists():
+            continue
+
+        for dim in _PLAN_REVIEW_DIMENSIONS:
+            rf = report_dir / f"{dim}_report.json"
+            if fs.file_exists(rf):
+                data = fs.read_json(rf)
+                applicable = data.get("applicable", True)
+                if applicable:
+                    dimensions.append({
+                        "dimension": dim,
+                        "iteration": it,
+                        "score": data.get("score", 0),
+                        "findings": data.get("findings", []),
+                        "issues": data.get("issues", []),
+                    })
+
+    avg = round(
+        sum(d["score"] for d in dimensions) / len(dimensions), 2
+    ) if dimensions else None
+    return {"task_id": task_id, "dimensions": dimensions, "average": avg}

kanban_framework-0.13.1/core/cli/framework.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+from pathlib import Path
+from core.infra.filesystem import Filesystem
+from core.infra.config import Config
+
+
+def dispatch(args: list[str]) -> dict:
+    sub = args[0] if args else "assess"
+    if sub == "assess":
+        task_id = args[1] if len(args) > 1 else None
+        return cmd_assess(task_id)
+    return {"subcommand": sub}
+
+
+def cmd_assess(task_id: str | None = None) -> dict:
+    root = Filesystem.find_project_root()
+    fs = Filesystem(root=root)
+    cfg = Config(fs)
+
+    results = {
+        "iron_rules": _assess_iron_rules(fs),
+        "agent_coverage": _assess_agent_coverage(cfg),
+        "artifacts": {},
+    }
+    if task_id:
+        results["artifacts"] = _assess_task_artifacts(fs, task_id)
+    results["overall_score"] = _calc_score(results)
+    return results
+
+
+def _assess_iron_rules(fs: Filesystem) -> dict:
+    rules_dir = fs.kanban_dir.parent / ".claude" / "skills" / "kanban" / "rules"
+    if not rules_dir.exists():
+        rules_dir = fs.kanban_dir.parent / ".claude" / "rules"
+    rule_files = list(rules_dir.glob("*.md")) if rules_dir.exists() else []
+    defined = len(rule_files)
+    expected = 8  # R-001 through R-008
+    return {
+        "rules_defined": defined,
+        "rules_expected": expected,
+        "coverage": min(defined / expected, 1.0) if expected else 1.0,
+    }
+
+
+def _assess_agent_coverage(cfg: Config) -> dict:
+    workflow = cfg.workflow
+    phases = workflow.get("phases", [])
+    covered_phases = 0
+    roles = set()
+    for p in phases:
+        agents = p.get("agents", [])
+        if agents:
+            covered_phases += 1
+            for a in agents:
+                roles.add(a.get("role", ""))
+    total_phases = len(phases)
+    return {
+        "phases_with_agents": covered_phases,
+        "total_phases": total_phases,
+        "coverage": covered_phases / total_phases if total_phases else 1.0,
+        "unique_roles": sorted(roles),
+    }
+
+
+def _assess_task_artifacts(fs: Filesystem, task_id: str) -> dict:
+    task_dir = fs.task_dir(task_id)
+    expected = [
+        "spec.md", "plan.md", "task_breakdown.json",
+        "execution_summary.md", "execution_pitfalls.md",
+        "execution_decisions.md", "retrospective.md", "acceptance.md",
+    ]
+    present = []
+    missing = []
+    for fname in expected:
+        if (task_dir / fname).exists():
+            present.append(fname)
+        else:
+            missing.append(fname)
+    return {
+        "present": present,
+        "missing": missing,
+        "completeness": len(present) / len(expected) if expected else 1.0,
+    }
+
+
+def _calc_score(results: dict) -> float:
+    scores = []
+    if "iron_rules" in results:
+        scores.append(results["iron_rules"].get("coverage", 0))
+    if "agent_coverage" in results:
+        scores.append(results["agent_coverage"].get("coverage", 0))
+    if results.get("artifacts"):
+        scores.append(results["artifacts"].get("completeness", 0))
+    return round(sum(scores) / len(scores) * 10, 1) if scores else 0.0

kanban_framework-0.13.1/core/cli/inbox.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+import json
+from datetime import datetime
+from pathlib import Path
+from core.infra.filesystem import Filesystem
+from core.domain.task import TaskManager, TaskNotFoundError
+from core.infra.config import Config
+
+
+class InboxError(Exception):
+    pass
+
+
+def dispatch(args: list[str]) -> dict:
+    sub = args[0] if args else "list"
+    root = Filesystem.find_project_root()
+    fs = Filesystem(root=root)
+
+    if sub == "list":
+        return _list_inbox(fs)
+    if sub == "add":
+        return _add_to_task_inbox(fs, args[1:])
+    if sub == "archive":
+        return _archive_task_inbox(fs, args[1:])
+    if sub == "analyze":
+        return _analyze_task_inbox(fs, args[1:])
+    if sub == "process":
+        return {"subcommand": sub, "processed": []}
+    return {"subcommand": sub}
+
+
+def cmd_feedback(args: list[str]) -> dict:
+    task_id = args[0] if args else None
+    if not task_id:
+        return {"error": "task_id required"}
+    text = " ".join(args[1:]) if len(args) > 1 else ""
+
+    root = Filesystem.find_project_root()
+    fs = Filesystem(root=root)
+    inbox_file = fs.inbox_file()
+    fs.ensure_dir(inbox_file.parent)
+
+    entries = []
+    if fs.file_exists(inbox_file):
+        entries = fs.read_json(inbox_file)
+
+    entries.append({
+        "task_id": task_id,
+        "text": text,
+        "type": "feedback",
+    })
+    fs.write_json(inbox_file, entries)
+    return {"task_id": task_id, "feedback": text, "saved": True}
+
+
+def _list_inbox(fs: Filesystem) -> dict:
+    inbox_file = fs.inbox_file()
+    if not fs.file_exists(inbox_file):
+        return {"inbox": [], "count": 0}
+    entries = fs.read_json(inbox_file)
+    return {"inbox": entries, "count": len(entries)}
+
+
+def _add_to_task_inbox(fs: Filesystem, args: list[str]) -> dict:
+    """Add a feedback item to a task's inbox.md file."""
+    if not args:
+        raise InboxError("task_id required")
+    task_id = args[0]
+    text = " ".join(args[1:]) if len(args) > 1 else ""
+
+    if not text:
+        raise InboxError("feedback text required")
+
+    task_dir = fs.task_dir(task_id)
+    inbox_path = task_dir / "inbox.md"
+
+    # Ensure task directory exists
+    fs.ensure_dir(task_dir)
+
+    # Create or append to inbox.md
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M")
+    new_entry = f"- [ ] {text} <!-- {timestamp} -->\n"
+
+    if fs.file_exists(inbox_path):
+        content = inbox_path.read_text(encoding="utf-8")
+        # Add entry after header section
+        lines = content.split("\n")
+        insert_pos = 0
+        for i, line in enumerate(lines):
+            if line.startswith("#"):
+                insert_pos = i + 1
+            elif line.strip() and not line.startswith("#"):
+                # Found first non-header line, insert before it
+                break
+        lines.insert(insert_pos, "")
+        lines.insert(insert_pos + 1, new_entry)
+        inbox_path.write_text("\n".join(lines), encoding="utf-8")
+    else:
+        # Create new inbox.md with header
+        inbox_path.write_text(
+            f"# Task Inbox — {task_id}\n\n"
+            f"用户反馈和待办事项。\n\n"
+            f"{new_entry}",
+            encoding="utf-8"
+        )
+
+    return {
+        "task_id": task_id,
+        "action": "added",
+        "text": text,
+        "inbox_file": str(inbox_path)
+    }
+
+
+def _archive_task_inbox(fs: Filesystem, args: list[str]) -> dict:
+    """Archive completed items from task's inbox.md to inbox-archive.md."""
+    if not args:
+        raise InboxError("task_id required")
+    task_id = args[0]
+
+    task_dir = fs.task_dir(task_id)
+    inbox_path = task_dir / "inbox.md"
+    archive_path = task_dir / "inbox-archive.md"
+
+    if not fs.file_exists(inbox_path):
+        return {
+            "task_id": task_id,
+            "action": "archive",
+            "archived_count": 0,
+            "message": "inbox.md not found"
+        }
+
+    content = inbox_path.read_text(encoding="utf-8")
+    lines = content.split("\n")
+
+    # Separate completed (checked) and pending (unchecked) items
+    archived = []
+    remaining = []
+    in_items = False
+
+    for line in lines:
+        if line.startswith("- [x]") or line.startswith("* [x]"):
+            archived.append(line)
+        elif line.startswith("- [ ]") or line.startswith("* [ ]"):
+            remaining.append(line)
+        else:
+            remaining.append(line)
+
+    if not archived:
+        return {
+            "task_id": task_id,
+            "action": "archive",
+            "archived_count": 0,
+            "message": "no completed items to archive"
+        }
+
+    # Write archive
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    archive_header = f"\n## Archive — {timestamp}\n\n"
+    archive_content = archive_header + "\n".join(archived)
+
+    if fs.file_exists(archive_path):
+        existing = archive_path.read_text(encoding="utf-8")
+        archive_path.write_text(existing + archive_content, encoding="utf-8")
+    else:
+        archive_path.write_text(
+            f"# Inbox Archive — {task_id}\n\n"
+            f"已归档的用户反馈和待办事项。\n"
+            f"{archive_content}",
+            encoding="utf-8"
+        )
+
+    # Update inbox.md with only pending items
+    inbox_path.write_text("\n".join(remaining), encoding="utf-8")
+
+    return {
+        "task_id": task_id,
+        "action": "archived",
+        "archived_count": len(archived),
+        "pending_count": sum(1 for line in remaining if line.startswith("- [ ]") or line.startswith("* [ ]")),
+        "archive_file": str(archive_path)
+    }
+
+
+def _analyze_task_inbox(fs: Filesystem, args: list[str]) -> dict:
+    from core.domain.inbox_analyzer import InboxAnalyzer
+    if not args:
+        return {"error": "task_id required"}
+    task_id = args[0]
+    analyzer = InboxAnalyzer(fs)
+    try:
+        analysis = analyzer.generate_analysis(task_id)
+        return analysis
+    except Exception as e:
+        return {"error": str(e)}
+
+
+def archive_on_task_completion(task_id: str) -> dict:
+    """
+    Auto-archive inbox items when task is completed/archived.
+    Called by cmd_decide when action is approve_and_archive.
+    """
+    root = Filesystem.find_project_root()
+    fs = Filesystem(root=root)
+    return _archive_task_inbox(fs, [task_id])