@1mancompany/onemancompany 0.7.20 → 0.7.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1mancompany/onemancompany",
-  "version": "0.7.20",
+  "version": "0.7.23",
   "description": "The AI Operating System for One-Person Companies",
   "bin": {
     "onemancompany": "bin/cli.js"

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "onemancompany"
-version = "0.7.20"
+version = "0.7.23"
 description = "A one-man company simulation with pixel art visualization and LangChain AI agents"
 requires-python = ">=3.12"
 dependencies = [

package/src/onemancompany/agents/product_tools.py

@@ -297,6 +297,129 @@ async def update_kr_progress_tool(
         return f"Error: {e}"
 
 
+# ---------------------------------------------------------------------------
+# Sprint tools
+# ---------------------------------------------------------------------------
+
+
+@tool
+async def create_sprint_tool(
+    product_slug: str,
+    name: str,
+    start_date: str,
+    end_date: str,
+    goal: str = "",
+    capacity: str = "",
+) -> str:
+    """Create a new sprint for a product.
+
+    Args:
+        product_slug: The product slug
+        name: Sprint name (e.g. "Sprint 3")
+        start_date: Start date in YYYY-MM-DD format
+        end_date: End date in YYYY-MM-DD format
+        goal: Sprint goal description
+        capacity: Optional capacity in story points
+    """
+    try:
+        cap = int(capacity) if capacity else None
+        sprint = prod.create_sprint(
+            slug=product_slug,
+            name=name,
+            start_date=start_date,
+            end_date=end_date,
+            goal=goal,
+            capacity=cap,
+        )
+        logger.debug("create_sprint_tool: {} in {}", sprint["id"], product_slug)
+        return f"Created sprint '{name}' ({sprint['id']}) for {product_slug}: {start_date} → {end_date}"
+    except (ValueError, FileNotFoundError) as e:
+        return f"Error: {e}"
+
+
+@tool
+async def close_sprint_tool(
+    product_slug: str,
+    sprint_id: str = "",
+) -> str:
+    """Close the active sprint for a product. Calculates velocity, carries over unfinished issues, generates retrospective.
+
+    Args:
+        product_slug: The product slug
+        sprint_id: Sprint ID to close. If empty, closes the active sprint.
+    """
+    try:
+        if not sprint_id:
+            active = prod.get_active_sprint(product_slug)
+            if not active:
+                return f"No active sprint found for {product_slug}"
+            sprint_id = active["id"]
+        result = prod.close_sprint(product_slug, sprint_id)
+        vel = result.get("velocity", 0)
+        rate = result.get("completion_rate", 0)
+        carry = result.get("carry_over_count", 0)
+        logger.debug("close_sprint_tool: {} closed — vel={}", sprint_id, vel)
+        return (
+            f"Sprint closed: velocity={vel} pts, completion={rate}%, "
+            f"carry_over={carry} issues\n\n{result.get('retrospective', '')}"
+        )
+    except (ValueError, FileNotFoundError) as e:
+        return f"Error: {e}"
+
+
+@tool
+async def get_sprint_info_tool(
+    product_slug: str,
+    sprint_id: str = "",
+) -> str:
+    """Get sprint information. Defaults to the active sprint if no ID given.
+
+    Args:
+        product_slug: The product slug
+        sprint_id: Sprint ID. If empty, returns the active sprint.
+    """
+    try:
+        if sprint_id:
+            sprint = prod.load_sprint(product_slug, sprint_id)
+        else:
+            sprint = prod.get_active_sprint(product_slug)
+
+        if not sprint:
+            # List all sprints as fallback
+            all_sprints = prod.list_sprints(product_slug)
+            if not all_sprints:
+                return f"No sprints found for {product_slug}"
+            lines = [f"No active sprint. All sprints for {product_slug}:"]
+            for s in all_sprints:
+                lines.append(f"- [{s['status']}] {s['name']} ({s['id']}) {s['start_date']}→{s['end_date']}")
+            return "\n".join(lines)
+
+        # Show sprint details
+        issues = prod.list_issues(product_slug, sprint=sprint["id"])
+        done = [i for i in issues if i.get("status") in ("done", "released")]
+        vel = sum(i.get("story_points") or 0 for i in done)
+        total_pts = sum(i.get("story_points") or 0 for i in issues)
+
+        lines = [
+            f"**{sprint['name']}** ({sprint['id']})",
+            f"Status: {sprint['status']}",
+            f"Goal: {sprint.get('goal') or 'N/A'}",
+            f"Period: {sprint['start_date']} → {sprint['end_date']}",
+            f"Issues: {len(done)}/{len(issues)} done",
+            f"Points: {vel}/{total_pts}",
+        ]
+        if sprint.get("capacity"):
+            lines.append(f"Capacity: {sprint['capacity']} pts")
+
+        suggestion = prod.suggest_capacity(product_slug)
+        if suggestion is not None:
+            lines.append(f"Suggested capacity (avg last 3): {suggestion} pts")
+
+        return "\n".join(lines)
+    except (ValueError, FileNotFoundError) as e:
+        return f"Error: {e}"
+
+
 # ---------------------------------------------------------------------------
 # Export
 # ---------------------------------------------------------------------------
@@ -309,4 +432,7 @@ PRODUCT_TOOLS = [
     get_product_context_tool,
     list_product_issues_tool,
     update_kr_progress_tool,
+    create_sprint_tool,
+    close_sprint_tool,
+    get_sprint_info_tool,
 ]

package/src/onemancompany/api/routes.py

@@ -7331,11 +7331,19 @@ async def api_product_detail(slug: str) -> dict:
     all_projects = list_projects()
     linked_projects = [p for p in all_projects if p.get("product_id") == product.get("id")]
 
+    # Sprints
+    sprints = prod.list_sprints(slug)
+    active_sprint = prod.get_active_sprint(slug)
+    suggested_capacity = prod.suggest_capacity(slug)
+
     return {
         "product": product,
         "issues": issues,
         "versions": versions,
         "projects": linked_projects,
+        "sprints": sprints,
+        "active_sprint": active_sprint,
+        "suggested_capacity": suggested_capacity,
     }
 
 
@@ -7415,3 +7423,88 @@ async def api_start_product_planning(slug: str) -> dict:
         product_id=product["id"],
     )
     return {"conversation_id": conv.id, "existing": False}
+
+
+# ── Sprints ──────────────────────────────────────────────────────────────────
+
+
+@router.post("/api/product/{slug}/sprint")
+async def api_create_sprint(slug: str, request: Request) -> dict:
+    """Create a sprint for a product."""
+    from onemancompany.core import product as prod
+
+    body = await request.json()
+    name = body.get("name")
+    start_date = body.get("start_date")
+    end_date = body.get("end_date")
+    if not name or not start_date or not end_date:
+        raise HTTPException(status_code=400, detail="Missing required fields: name, start_date, end_date")
+    try:
+        result = prod.create_sprint(
+            slug=slug,
+            name=name,
+            start_date=start_date,
+            end_date=end_date,
+            goal=body.get("goal", ""),
+            capacity=int(body["capacity"]) if body.get("capacity") else None,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))
+    return result
+
+
+@router.get("/api/product/{slug}/sprints")
+async def api_list_sprints(slug: str, status: str = "") -> list[dict]:
+    """List sprints for a product, optionally filtered by status."""
+    from onemancompany.core import product as prod
+
+    return prod.list_sprints(slug, status=status or None)
+
+
+@router.get("/api/product/{slug}/sprint/{sprint_id}")
+async def api_get_sprint(slug: str, sprint_id: str) -> dict:
+    """Get a single sprint by ID."""
+    from onemancompany.core import product as prod
+
+    sprint = prod.load_sprint(slug, sprint_id)
+    if not sprint:
+        raise HTTPException(status_code=404, detail=f"Sprint '{sprint_id}' not found")
+    return sprint
+
+
+@router.put("/api/product/{slug}/sprint/{sprint_id}")
+async def api_update_sprint(slug: str, sprint_id: str, request: Request) -> dict:
+    """Update sprint fields (name, goal, start_date, end_date, capacity, status)."""
+    from onemancompany.core import product as prod
+
+    body = await request.json()
+    SPRINT_MUTABLE_FIELDS = {"name", "goal", "start_date", "end_date", "capacity", "status"}
+    filtered = {k: v for k, v in body.items() if k in SPRINT_MUTABLE_FIELDS}
+    if "capacity" in filtered and filtered["capacity"] is not None:
+        filtered["capacity"] = int(filtered["capacity"])
+    try:
+        result = prod.update_sprint(slug, sprint_id, **filtered)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    return result
+
+
+@router.post("/api/product/{slug}/sprint/{sprint_id}/close")
+async def api_close_sprint(slug: str, sprint_id: str) -> dict:
+    """Close a sprint: calculate velocity, carry over unfinished issues, generate retrospective."""
+    from onemancompany.core import product as prod
+
+    try:
+        result = prod.close_sprint(slug, sprint_id)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    return result
+
+
+@router.get("/api/product/{slug}/sprint/suggest-capacity")
+async def api_suggest_sprint_capacity(slug: str) -> dict:
+    """Suggest sprint capacity based on historical velocity (sliding average of last 3)."""
+    from onemancompany.core import product as prod
+
+    suggestion = prod.suggest_capacity(slug)
+    return {"suggested_capacity": suggestion}

package/src/onemancompany/core/config.py

@@ -61,6 +61,7 @@ VESSEL_YAML_FILENAME = "vessel.yaml"
 PRODUCT_YAML_FILENAME = "product.yaml"
 ISSUES_DIR_NAME = "issues"
 VERSIONS_DIR_NAME = "versions"
+SPRINTS_DIR_NAME = "sprints"
 TALENT_PERSONA_FILENAME = "talent_persona.md"
 MCP_CONFIG_FILENAME = "mcp_config.json"
 CONVERSATIONS_DIR_NAME = "conversations"

package/src/onemancompany/core/models.py

@@ -162,6 +162,8 @@ class EventType(str, Enum):
     ISSUE_ASSIGNED = "issue_assigned"
     KR_UPDATED = "kr_updated"
     VERSION_RELEASED = "version_released"
+    SPRINT_CREATED = "sprint_created"
+    SPRINT_CLOSED = "sprint_closed"
 
 
 class ProductStatus(str, Enum):
@@ -197,6 +199,13 @@ class IssueResolution(str, Enum):
     BY_DESIGN = "by_design"
 
 
+class SprintStatus(str, Enum):
+    """Sprint lifecycle status."""
+    PLANNING = "planning"
+    ACTIVE = "active"
+    CLOSED = "closed"
+
+
 # ---------------------------------------------------------------------------
 # Performance
 # ---------------------------------------------------------------------------

package/src/onemancompany/core/product.py

@@ -1,7 +1,8 @@
-"""Product management — product records, key results, and issues.
+"""Product management — product records, key results, issues, and sprints.
 
 Products stored at: PRODUCTS_DIR/{slug}/product.yaml
 Issues stored at:   PRODUCTS_DIR/{slug}/issues/{issue_id}.yaml
+Sprints stored at:  PRODUCTS_DIR/{slug}/sprints/{sprint_id}.yaml
 
 All YAML I/O through store._read_yaml / _write_yaml.
 Disk is the single source of truth — no in-memory caching.
@@ -20,6 +21,7 @@ from onemancompany.core.config import (
     ISSUES_DIR_NAME,
     PRODUCT_YAML_FILENAME,
     PRODUCTS_DIR,
+    SPRINTS_DIR_NAME,
     VERSIONS_DIR_NAME,
     DirtyCategory,
 )
@@ -28,6 +30,7 @@ from onemancompany.core.models import (
     IssuePriority,
     IssueStatus,
     ProductStatus,
+    SprintStatus,
 )
 from onemancompany.core.store import _read_yaml, _write_yaml, mark_dirty
 
@@ -330,6 +333,7 @@ def list_issues(
     status: IssueStatus | None = None,
     priority: IssuePriority | None = None,
     labels: list[str] | None = None,
+    sprint: str | None = None,
 ) -> list[dict]:
     """List issues for a product, optionally filtered."""
     issues_path = _issues_dir(slug)
@@ -351,6 +355,8 @@ def list_issues(
             issue_labels = set(data.get("labels", []))
             if not set(labels).intersection(issue_labels):
                 continue
+        if sprint is not None and data.get("sprint") != sprint:
+            continue
         results.append(data)
     return results
 
@@ -806,3 +812,237 @@ def sync_issue_statuses(slug: str) -> list[dict]:
             logger.debug("[PRODUCT] Issue {} status derived: {} → {}", issue["id"], current, derived.value)
 
     return changed
+
+
+# ---------------------------------------------------------------------------
+# Sprint management
+# ---------------------------------------------------------------------------
+
+_DONE_STATUSES = {IssueStatus.DONE.value, IssueStatus.RELEASED.value}
+
+
+def _sprints_dir(slug: str) -> Path:
+    return PRODUCTS_DIR / slug / SPRINTS_DIR_NAME
+
+
+def create_sprint(
+    *,
+    slug: str,
+    name: str,
+    start_date: str,
+    end_date: str,
+    goal: str = "",
+    capacity: int | None = None,
+) -> dict:
+    """Create a sprint for a product. Returns the sprint dict."""
+    product = load_product(slug)
+    if not product:
+        raise ValueError(f"Product '{slug}' not found")
+
+    sprint_id = _gen_id("sprint_")
+    now = datetime.now().isoformat()
+
+    data = {
+        "id": sprint_id,
+        "product_id": product["id"],
+        "name": name,
+        "goal": goal,
+        "status": SprintStatus.PLANNING.value,
+        "start_date": start_date,
+        "end_date": end_date,
+        "capacity": capacity,
+        "velocity": None,
+        "carry_over_count": 0,
+        "completion_rate": None,
+        "retrospective": None,
+        "created_at": now,
+        "closed_at": None,
+    }
+
+    sdir = _sprints_dir(slug)
+    sdir.mkdir(parents=True, exist_ok=True)
+    with _get_slug_lock(slug):
+        _write_yaml(sdir / f"{sprint_id}.yaml", data)
+    mark_dirty(DirtyCategory.PRODUCTS)
+    logger.debug("[PRODUCT] Sprint created: {} in {}", sprint_id, slug)
+    return data
+
+
+def load_sprint(slug: str, sprint_id: str) -> dict | None:
+    """Load a single sprint by ID."""
+    path = _sprints_dir(slug) / f"{sprint_id}.yaml"
+    if not path.exists():
+        return None
+    return _read_yaml(path)
+
+
+def list_sprints(slug: str, status: str | None = None) -> list[dict]:
+    """List all sprints for a product, optionally filtered by status."""
+    sdir = _sprints_dir(slug)
+    if not sdir.exists():
+        return []
+    sprints = []
+    for f in sorted(sdir.iterdir()):
+        if f.suffix == ".yaml":
+            data = _read_yaml(f)
+            if data and (status is None or data.get("status") == status):
+                sprints.append(data)
+    return sprints
+
+
+def update_sprint(slug: str, sprint_id: str, **fields) -> dict:
+    """Update sprint fields. Enforces single-active-sprint constraint."""
+    sprint = load_sprint(slug, sprint_id)
+    if not sprint:
+        raise ValueError(f"Sprint '{sprint_id}' not found in '{slug}'")
+
+    # Enforce: only one active sprint per product
+    new_status = fields.get("status")
+    if new_status == SprintStatus.ACTIVE.value:
+        existing_active = get_active_sprint(slug)
+        if existing_active and existing_active["id"] != sprint_id:
+            raise ValueError(f"Product '{slug}' already has an active sprint: {existing_active['id']}")
+
+    sprint.update(fields)
+    with _get_slug_lock(slug):
+        _write_yaml(_sprints_dir(slug) / f"{sprint_id}.yaml", sprint)
+    mark_dirty(DirtyCategory.PRODUCTS)
+    return sprint
+
+
+def get_active_sprint(slug: str) -> dict | None:
+    """Return the current active sprint for a product, or None."""
+    active = list_sprints(slug, status=SprintStatus.ACTIVE.value)
+    return active[0] if active else None
+
+
+def get_sprint_velocity(slug: str, sprint_id: str) -> int:
+    """Calculate velocity: sum of story_points for done/released issues in this sprint."""
+    issues = list_issues(slug, sprint=sprint_id)
+    total = 0
+    for issue in issues:
+        if issue.get("status") in _DONE_STATUSES:
+            total += issue.get("story_points") or 0
+    return total
+
+
+def close_sprint(slug: str, sprint_id: str) -> dict:
+    """Close a sprint: calculate velocity, carry-over, generate retrospective."""
+    sprint = load_sprint(slug, sprint_id)
+    if not sprint:
+        raise ValueError(f"Sprint '{sprint_id}' not found in '{slug}'")
+    if sprint.get("status") != SprintStatus.ACTIVE.value:
+        raise ValueError(f"Sprint '{sprint_id}' is not active")
+
+    # 1. Calculate velocity
+    velocity = get_sprint_velocity(slug, sprint_id)
+
+    # 2. Identify unfinished issues
+    all_issues = list_issues(slug, sprint=sprint_id)
+    done_count = sum(1 for i in all_issues if i.get("status") in _DONE_STATUSES)
+    total_count = len(all_issues)
+    unfinished = [i for i in all_issues if i.get("status") not in _DONE_STATUSES]
+
+    # 3. Carry-over: find next planning sprint
+    planning_sprints = list_sprints(slug, status=SprintStatus.PLANNING.value)
+    next_sprint = planning_sprints[0] if planning_sprints else None
+
+    for issue in unfinished:
+        if next_sprint:
+            update_issue(slug, issue["id"], sprint=next_sprint["id"], carried_over=True)
+        else:
+            update_issue(slug, issue["id"], sprint="", status=IssueStatus.BACKLOG.value, carried_over=True)
+
+    # 4. Completion rate
+    completion_rate = round((done_count / total_count) * 100, 2) if total_count > 0 else 0.0
+
+    # 5. Retrospective
+    retrospective = build_sprint_retrospective(slug, sprint_id)
+
+    # 6. Update sprint record
+    now = datetime.now().isoformat()
+    updated = update_sprint(
+        slug, sprint_id,
+        status=SprintStatus.CLOSED.value,
+        velocity=velocity,
+        carry_over_count=len(unfinished),
+        completion_rate=completion_rate,
+        retrospective=retrospective,
+        closed_at=now,
+    )
+
+    logger.debug(
+        "[PRODUCT] Sprint {} closed — velocity={}, completion={}%, carry_over={}",
+        sprint_id, velocity, completion_rate, len(unfinished),
+    )
+    return updated
+
+
+def suggest_capacity(slug: str) -> int | None:
+    """Suggest sprint capacity based on sliding average of last 3 closed sprints.
+
+    Returns None if fewer than 3 closed sprints exist.
+    """
+    closed = list_sprints(slug, status=SprintStatus.CLOSED.value)
+    if len(closed) < 3:
+        return None
+    # Take last 3 by closed_at
+    recent = sorted(closed, key=lambda s: s.get("closed_at") or "")[-3:]
+    velocities = [s.get("velocity") or 0 for s in recent]
+    return round(sum(velocities) / len(velocities))
+
+
+def build_sprint_retrospective(slug: str, sprint_id: str) -> str:
+    """Generate a sprint retrospective report string."""
+    sprint = load_sprint(slug, sprint_id)
+    if not sprint:
+        return ""
+
+    issues = list_issues(slug, sprint=sprint_id)
+    done = [i for i in issues if i.get("status") in _DONE_STATUSES]
+    unfinished = [i for i in issues if i.get("status") not in _DONE_STATUSES]
+    velocity = sum(i.get("story_points") or 0 for i in done)
+    total_points = sum(i.get("story_points") or 0 for i in issues)
+    total_count = len(issues)
+    done_count = len(done)
+
+    # Compare with previous sprint velocity
+    closed = list_sprints(slug, status=SprintStatus.CLOSED.value)
+    closed_sorted = sorted(closed, key=lambda s: s.get("closed_at") or "")
+    prev_velocity = None
+    for cs in closed_sorted:
+        if cs["id"] != sprint_id and cs.get("velocity") is not None:
+            prev_velocity = cs["velocity"]
+
+    lines = [
+        f"## Sprint Retrospective: {sprint['name']}",
+        f"**Goal**: {sprint.get('goal') or 'N/A'}",
+        f"**Period**: {sprint.get('start_date')} → {sprint.get('end_date')}",
+        "",
+        f"### Metrics",
+        f"- **Velocity**: {velocity} story points",
+        f"- **Completion**: {done_count}/{total_count} issues ({round(done_count / total_count * 100, 1) if total_count else 0}%)",
+        f"- **Story points completed**: {velocity}/{total_points}",
+        f"- **Carry-over**: {len(unfinished)} issues",
+    ]
+
+    if prev_velocity is not None:
+        delta = velocity - prev_velocity
+        direction = "↑" if delta > 0 else ("↓" if delta < 0 else "→")
+        lines.append(f"- **vs Previous Sprint**: {direction} {abs(delta)} points ({prev_velocity} → {velocity})")
+
+    if done:
+        lines.append("")
+        lines.append("### Completed")
+        for i in done:
+            pts = f" ({i.get('story_points') or 0}pts)" if i.get("story_points") else ""
+            lines.append(f"- ✓ {i['title']}{pts}")
+
+    if unfinished:
+        lines.append("")
+        lines.append("### Carried Over")
+        for i in unfinished:
+            pts = f" ({i.get('story_points') or 0}pts)" if i.get("story_points") else ""
+            lines.append(f"- ○ {i['title']}{pts}")
+
+    return "\n".join(lines)

package/src/onemancompany/core/product_triggers.py

@@ -469,7 +469,31 @@ async def run_product_check(product_slug: str) -> dict:
             actions_taken.append(f"Created issue for KR: {kr_title}")
             all_issues.append(issue)  # prevent duplicate creation in same cycle
 
-    # --- Step 3: Check if owner review is needed ---
+    # --- Step 3: Sprint expiry check ---
+    from datetime import date as _date
+
+    active_sprint = prod.get_active_sprint(product_slug)
+    if active_sprint:
+        end_date_str = active_sprint.get("end_date", "")
+        try:
+            end_date = _date.fromisoformat(end_date_str)
+            if _date.today() > end_date:
+                actions_taken.append(f"Sprint '{active_sprint['name']}' expired on {end_date_str}")
+        except (ValueError, TypeError):
+            logger.debug("[PRODUCT_CHECK] Invalid end_date '{}' on sprint {}", end_date_str, active_sprint.get("id"))
+
+    # --- Step 4: Backlog grooming reminder ---
+    _BACKLOG_GROOMING_THRESHOLD = 5
+    unscheduled_low = [
+        i for i in all_issues
+        if i.get("priority") in (IssuePriority.P2.value, IssuePriority.P3.value)
+        and not i.get("sprint")
+        and i.get("status") not in (IssueStatus.DONE.value, IssueStatus.RELEASED.value)
+    ]
+    if len(unscheduled_low) >= _BACKLOG_GROOMING_THRESHOLD:
+        actions_taken.append(f"{len(unscheduled_low)} P2/P3 issues unscheduled — backlog grooming needed")
+
+    # --- Step 5: Check if owner review is needed ---
     # Conditions: backlog issues with no one working, or KRs at 0% with completed projects
     needs_review = False
     review_reasons = []
@@ -491,6 +515,21 @@ async def run_product_check(product_slug: str) -> dict:
         needs_review = True
         review_reasons.append(f"{len(stale_krs)} KRs at 0% despite {len(completed_projects)} completed projects")
 
+    # Sprint expired → needs owner review
+    if active_sprint:
+        try:
+            end_date = _date.fromisoformat(active_sprint.get("end_date", ""))
+            if _date.today() > end_date:
+                needs_review = True
+                review_reasons.append(f"Sprint '{active_sprint['name']}' expired")
+        except (ValueError, TypeError):
+            logger.debug("[PRODUCT_CHECK] Invalid end_date on sprint {} for review check", active_sprint.get("id"))
+
+    # Backlog grooming threshold → needs owner review
+    if len(unscheduled_low) >= _BACKLOG_GROOMING_THRESHOLD:
+        needs_review = True
+        review_reasons.append(f"{len(unscheduled_low)} P2/P3 issues need sprint assignment")
+
     if needs_review:
         reason = "; ".join(review_reasons)
         notified = await notify_owner(product_slug, reason=reason)