squads 0.1.0__py3-none-any.whl

squads/__init__.py

@@ -0,0 +1,3 @@
+"""squads — manage a team of AI agents working on a code project."""
+
+__version__ = "0.1.0"

squads/__main__.py

@@ -0,0 +1,4 @@
+from squads._cli import app
+
+if __name__ == "__main__":
+    app()

squads/_backends/__init__.py

@@ -0,0 +1 @@
+"""Private subpackage — import members from its underscore modules."""

squads/_backends/_base.py

@@ -0,0 +1,75 @@
+"""Pluggable agent-backend interface. Claude Code is the first implementation."""
+
+import os
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+
+from squads._models._item import Item
+from squads._paths import SquadPaths
+from squads._roles._catalog import RoleDef
+
+
+@dataclass(frozen=True)
+class Artifact:
+    """A tool-owned file the backend generated (path is project-root-relative)."""
+
+    path: str
+    kind: str  # agent | skill | settings | claude_md
+    backend: str
+
+
+@dataclass(frozen=True)
+class RoleView:
+    """The roster entry passed to backends (decoupled from RoleDef internals)."""
+
+    slug: str
+    full_name: str
+    title: str
+    is_default: bool
+
+
+@dataclass
+class BackendContext:
+    paths: SquadPaths
+    version: str
+
+    @property
+    def root(self) -> Path:
+        return self.paths.root
+
+    @property
+    def squad_dir(self) -> Path:
+        return self.paths.squad_dir
+
+    def rel(self, path: Path) -> str:
+        """Project-root-relative, forward-slash path (for pointers and Artifact paths)."""
+        return os.path.relpath(path, self.root).replace(os.sep, "/")
+
+    def root_relative(self, item: Item) -> str:
+        """Root-relative path to an item's markdown file (for pointer references)."""
+        return self.rel(self.paths.abspath(item.path))
+
+
+class AgentBackend(ABC):
+    name: str
+
+    @abstractmethod
+    def ensure_scaffold(self, ctx: BackendContext) -> list[Artifact]:
+        """Create backend dirs and base config (idempotent; never clobber user content)."""
+
+    @abstractmethod
+    def write_managed(self, ctx: BackendContext, roster: list[RoleView]) -> list[Artifact]:
+        """(Re)write roster/version-dependent tool files: the skill + CLAUDE.md section."""
+
+    @abstractmethod
+    def generate_role_pointer(self, ctx: BackendContext, item: Item, role: RoleDef) -> Artifact:
+        """Write the thin pointer file that loads a role's real definition."""
+
+    @abstractmethod
+    def generate_skill_pointer(self, ctx: BackendContext, item: Item) -> Artifact:
+        """Write the thin pointer file that loads a skill's real definition."""
+
+    @abstractmethod
+    def remove_artifacts(self, ctx: BackendContext, item: Item) -> None:
+        """Delete the pointer file(s) for an item."""

squads/_backends/_claude_code/__init__.py

@@ -0,0 +1,6 @@
+from squads._backends._claude_code._backend import ClaudeCodeBackend
+from squads._backends._registry import register
+
+register(ClaudeCodeBackend)
+
+__all__ = ["ClaudeCodeBackend"]

squads/_backends/_claude_code/_backend.py

@@ -0,0 +1,184 @@
+"""Claude Code backend: writes thin pointer files into ``.claude/`` plus managed skill & CLAUDE.md.
+
+The real definitions live under the squad folder; these files only route the agent there.
+"""
+
+import json
+import shutil
+from pathlib import Path
+from typing import Any
+
+from squads import _interactions as interactions
+from squads._backends._base import AgentBackend, Artifact, BackendContext, RoleView
+from squads._backends._claude_code import _claude_md as claude_md
+from squads._backends._claude_code._frontmatter import normalize_model, oneline
+from squads._models._enums import ItemType
+from squads._models._extras import ExtraKey as X
+from squads._models._item import Item
+from squads._rendering._engine import render
+from squads._roles._catalog import RoleDef
+
+_AGENTS = "agents"
+_SKILLS = "skills"
+_SKILL_FILE = "SKILL.md"
+
+
+class ClaudeCodeBackend(AgentBackend):
+    name = "claude_code"
+
+    # ------------------------------------------------------------------ scaffold
+    def ensure_scaffold(self, ctx: BackendContext) -> list[Artifact]:
+        cdir = ctx.paths.claude_dir
+        (cdir / _AGENTS).mkdir(parents=True, exist_ok=True)
+        (cdir / _SKILLS / "squads").mkdir(parents=True, exist_ok=True)
+        settings = cdir / "settings.json"
+        self._merge_settings(settings)
+        return [Artifact(ctx.rel(settings), "settings", self.name)]
+
+    def _merge_settings(self, settings: Path) -> None:
+        default: dict[str, Any] = json.loads(render("claude/settings.json.j2"))
+        if settings.exists():
+            current: dict[str, Any]
+            try:
+                current = json.loads(settings.read_text(encoding="utf-8"))
+            except json.JSONDecodeError:
+                current = {}
+            perms: dict[str, Any] = current.setdefault("permissions", {})
+            allow: list[str] = perms.setdefault("allow", [])
+            for rule in default["permissions"]["allow"]:
+                if rule not in allow:
+                    allow.append(rule)
+            perms.setdefault("deny", [])
+            settings.write_text(json.dumps(current, indent=2) + "\n", encoding="utf-8")
+        else:
+            settings.write_text(json.dumps(default, indent=2) + "\n", encoding="utf-8")
+
+    # ------------------------------------------------------------------ managed files
+    def write_managed(self, ctx: BackendContext, roster: list[RoleView]) -> list[Artifact]:
+        squad_dir = ctx.paths.config.squad_dir
+        artifacts: list[Artifact] = []
+        # squads skill (real body under squads/agents/skills/, thin pointer in .claude/)
+        artifacts += self._write_managed_skill(
+            ctx,
+            name="squads",
+            description=(
+                "How to track work on this project with the squads (`sq`) CLI: create/transition "
+                "items, comment, link context. Use whenever you start, hand off, or update work."
+            ),
+            body=render("agents/squads_skill.md.j2", version=ctx.version, squad_dir=squad_dir),
+        )
+        # CLAUDE.md managed section
+        default = next((r for r in roster if r.is_default), None)
+        section = render(
+            "claude/claude_section.md.j2",
+            squad_dir=squad_dir,
+            roles=[{"full_name": r.full_name, "title": r.title, "slug": r.slug} for r in roster],
+            default_role_full_name=default.full_name if default else "the manager",
+            default_role_slug=default.slug if default else "manager",
+        )
+        claude_md.inject(ctx.paths.claude_md, section)
+        artifacts.append(Artifact(ctx.rel(ctx.paths.claude_md), "claude_md", self.name))
+        artifacts.extend(self._write_item_skills(ctx, roster))
+        return artifacts
+
+    def _write_managed_skill(
+        self, ctx: BackendContext, *, name: str, description: str, body: str
+    ) -> list[Artifact]:
+        """Write a managed skill's real body under squads/ and a thin pointer in .claude/."""
+        body_path = ctx.squad_dir / _AGENTS / _SKILLS / f"{name}.md"
+        body_path.parent.mkdir(parents=True, exist_ok=True)
+        body_path.write_text(body, encoding="utf-8")
+        pointer = ctx.paths.claude_dir / _SKILLS / name / _SKILL_FILE
+        pointer.parent.mkdir(parents=True, exist_ok=True)
+        pointer.write_text(
+            render(
+                "claude/pointer_skill.md.j2",
+                slug=name,
+                description=oneline(description),
+                squad_path=ctx.rel(body_path),
+            ),
+            encoding="utf-8",
+        )
+        return [
+            Artifact(ctx.rel(body_path), "skill_body", self.name),
+            Artifact(ctx.rel(pointer), "skill_pointer", self.name),
+        ]
+
+    def _write_item_skills(self, ctx: BackendContext, roster: list[RoleView]) -> list[Artifact]:
+        """One managed skill per item type, with a section per *active* interacting role."""
+        by_slug = {r.slug: r for r in roster}
+        out: list[Artifact] = []
+        for item_type in interactions.managed_item_types():
+            pb = interactions.PLAYBOOK[item_type]
+            sections: list[dict[str, str]] = []
+            for guide in pb.roles:
+                if guide.slug == interactions.DEV:
+                    sections.append({"title": "developers", "text": guide.text})
+                elif guide.slug in by_slug:
+                    r = by_slug[guide.slug]
+                    sections.append({"title": f"{r.full_name} (`{r.slug}`)", "text": guide.text})
+            name = interactions.item_skill_name(item_type)
+            body = render(
+                "agents/item_skill.md.j2",
+                title=item_type.value.capitalize(),
+                version=ctx.version,
+                overview=pb.overview,
+                lifecycle=pb.lifecycle,
+                commands=list(pb.commands),
+                sections=sections,
+            )
+            out += self._write_managed_skill(
+                ctx,
+                name=name,
+                description=(
+                    f"Working with {item_type.value} items in this squad: "
+                    "lifecycle, commands, and role-specific guidance."
+                ),
+                body=body,
+            )
+        return out
+
+    # ------------------------------------------------------------------ pointers
+    def generate_role_pointer(self, ctx: BackendContext, item: Item, role: RoleDef) -> Artifact:
+        pointer = ctx.paths.claude_dir / _AGENTS / f"{role.slug}.md"
+        pointer.parent.mkdir(parents=True, exist_ok=True)
+        pointer.write_text(
+            render(
+                "claude/pointer_agent.md.j2",
+                slug=role.slug,
+                full_name=role.full_name,
+                role_title=role.title,
+                description=oneline(role.description),
+                model=normalize_model(role.model),
+                color=role.color,
+                squad_path=ctx.root_relative(item),
+                skills=interactions.skills_for_role(role.slug),
+            ),
+            encoding="utf-8",
+        )
+        return Artifact(ctx.rel(pointer), "agent", self.name)
+
+    def generate_skill_pointer(self, ctx: BackendContext, item: Item) -> Artifact:
+        slug = item.extra.get(X.SLUG, item.slug)
+        pointer = ctx.paths.claude_dir / _SKILLS / slug / _SKILL_FILE
+        pointer.parent.mkdir(parents=True, exist_ok=True)
+        description = item.extra.get(X.DESCRIPTION) or item.description or item.title
+        pointer.write_text(
+            render(
+                "claude/pointer_skill.md.j2",
+                slug=slug,
+                description=oneline(description),
+                squad_path=ctx.root_relative(item),
+            ),
+            encoding="utf-8",
+        )
+        return Artifact(ctx.rel(pointer), "skill_pointer", self.name)
+
+    def remove_artifacts(self, ctx: BackendContext, item: Item) -> None:
+        slug = item.extra.get(X.SLUG, item.slug)
+        if item.type is ItemType.SKILL:
+            skill_dir = ctx.paths.claude_dir / _SKILLS / slug
+            if skill_dir.is_dir():
+                shutil.rmtree(skill_dir)
+        else:
+            (ctx.paths.claude_dir / _AGENTS / f"{slug}.md").unlink(missing_ok=True)

squads/_backends/_claude_code/_claude_md.py

@@ -0,0 +1,26 @@
+"""Manage the squads-owned section of CLAUDE.md, delimited by stable markers."""
+
+from pathlib import Path
+
+START = "<!-- squads:start -->"
+END = "<!-- squads:end -->"
+
+
+def wrap(section_body: str) -> str:
+    return f"{START}\n{section_body.rstrip()}\n{END}\n"
+
+
+def inject(claude_md: Path, section_body: str) -> None:
+    """Insert or replace the managed section, preserving everything else in the file."""
+    block = wrap(section_body)
+    if not claude_md.exists():
+        claude_md.write_text(f"# Project guidance\n\n{block}", encoding="utf-8")
+        return
+    text = claude_md.read_text(encoding="utf-8")
+    si, ei = text.find(START), text.find(END)
+    if si != -1 and ei != -1:
+        new = text[:si] + block.rstrip("\n") + text[ei + len(END) :]
+        claude_md.write_text(new, encoding="utf-8")
+    else:
+        sep = "" if text.endswith("\n") else "\n"
+        claude_md.write_text(f"{text}{sep}\n{block}", encoding="utf-8")

squads/_backends/_claude_code/_frontmatter.py

@@ -0,0 +1,14 @@
+"""Helpers for emitting valid Claude Code config."""
+
+_VALID_MODELS = {"sonnet", "opus", "haiku", "inherit"}
+
+
+def normalize_model(model: str | None) -> str | None:
+    if model is None:
+        return None
+    return model if model in _VALID_MODELS else None
+
+
+def oneline(text: str) -> str:
+    """Collapse to a single line so it is safe inside double-quoted YAML."""
+    return " ".join(text.split()).replace('"', "'")

squads/_backends/_registry.py

@@ -0,0 +1,25 @@
+"""Name → backend lookup. New backends register here."""
+
+from squads._backends._base import AgentBackend
+from squads._errors import SquadsError
+
+_REGISTRY: dict[str, type[AgentBackend]] = {}
+
+
+def register(cls: type[AgentBackend]) -> type[AgentBackend]:
+    _REGISTRY[cls.name] = cls
+    return cls
+
+
+def get_backend(name: str) -> AgentBackend:
+    # Import for side-effect registration of the built-in backend.
+    import importlib
+
+    importlib.import_module("squads._backends._claude_code")
+
+    try:
+        return _REGISTRY[name]()
+    except KeyError:
+        raise SquadsError(
+            f"unknown backend {name!r} (available: {', '.join(_REGISTRY) or 'none'})"
+        ) from None

squads/_cli/__init__.py

@@ -0,0 +1,67 @@
+"""The Typer application, exposed as both `squads` and `sq`."""
+
+import typer
+
+from squads import __version__
+from squads._cli import _common as common
+
+app = typer.Typer(
+    name="sq",
+    help=(
+        "Manage a team of AI agents: bootstrap roles & skills, track work with stable IDs.\n\n"
+        "New here? Run `sq workflow` for how the team works, or `sq <command> --help` for details."
+    ),
+    epilog="Team workflow: `sq workflow`  ·  per-command help: `sq <command> --help`",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _version_cb(value: bool):
+    if value:
+        common.console.print(f"squads {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main_callback(
+    dir: str | None = typer.Option(
+        None,
+        "--dir",
+        help="Operate on the squad folder at PATH (overrides config/walk-up).",
+        metavar="PATH",
+    ),
+    at: str | None = typer.Option(
+        None,
+        "--at",
+        help="Forge timestamps for this command (ISO 8601, UTC) — for migrating history.",
+        metavar="WHEN",
+    ),
+    version: bool = typer.Option(
+        False, "--version", callback=_version_cb, is_eager=True, help="Show version and exit."
+    ),
+):
+    common.set_active_dir(dir)
+    common.apply_timestamp(at)
+    common.version_notice()
+
+
+# Register commands (imported after `app` is defined; they decorate it).
+from squads._cli import (  # noqa: E402
+    _comment,
+    _create,
+    _dev,
+    _main,
+    _refs,
+    _role,
+    _skill,
+)
+
+app.add_typer(_create.create_app, name="create", help="Create a tracked item.")
+app.add_typer(_role.role_app, name="role", help="Manage agent roles.")
+app.add_typer(_comment.story_app, name="story", help="Manage a feature's user stories.")
+app.add_typer(_comment.subtask_app, name="subtask", help="Manage a task's subtasks.")
+app.add_typer(_refs.ref_app, name="ref", help="Manage reference edges.")
+app.add_typer(_dev.dev_app, name="dev", help="Manage developer roles.")
+app.add_typer(_skill.skill_app, name="skill", help="Manage agent skills.")
+app.add_typer(_main.guide_app, name="guide", help="Manage project guides.")

squads/_cli/_comment.py

@@ -0,0 +1,128 @@
+"""`sq comment`, `sq story`, `sq subtask` — collaboration on item files."""
+
+import json
+
+import typer
+from rich.table import Table
+
+from squads._cli import app
+from squads._cli._common import console, e, get_service, handle_errors
+from squads._service import BlockResult
+
+story_app = typer.Typer(no_args_is_help=True, help="Manage a feature's user stories.")
+subtask_app = typer.Typer(no_args_is_help=True, help="Manage a task's subtasks.")
+
+
+@app.command()
+@handle_errors
+def comment(
+    item_id: str = typer.Argument(...),
+    message: list[str] = typer.Option(..., "-m", "--message", help="A talking point (repeatable)."),
+    as_: str = typer.Option("operator", "--as", help="Author: a role slug or 'operator'."),
+    story: str | None = typer.Option(None, "--story", help="Target a user story (e.g. US1)."),
+    subtask: str | None = typer.Option(None, "--subtask", help="Target a subtask (e.g. ST1)."),
+):
+    """Append a timestamped comment to an item's discussion."""
+    svc = get_service()
+    svc.comment(item_id, list(message), as_slug=as_, story=story, subtask=subtask)
+    where = f" ({story or subtask})" if (story or subtask) else ""
+    console.print(f"commented on {item_id}{where} as [bold]{svc.author(as_)}[/bold]")
+
+
+def _print_block(parent_id: str, res: BlockResult, json_out: bool) -> None:
+    if json_out:
+        console.print_json(
+            json.dumps(
+                {
+                    "local_id": res.local_id,
+                    "file": str(res.path),
+                    "region": res.body_tag,
+                    "start_line": res.start_line,
+                    "end_line": res.end_line,
+                }
+            )
+        )
+        return
+    console.print(f"added [bold]{res.local_id}[/bold] to {parent_id}")
+    console.print(
+        f"  write in [cyan]{res.path}[/cyan] between "
+        f"[dim]<!-- sq:{res.body_tag} -->[/dim] (line {res.start_line}) "
+        f"and its [dim]:end[/dim] (line {res.end_line})"
+    )
+    console.print("  [dim]free-form paragraphs or bullets; leave the marker lines untouched.[/dim]")
+
+
+@story_app.command("add")
+@handle_errors
+def story_add(
+    feature_id: str = typer.Argument(...),
+    title: str = typer.Argument("", help="Optional short label; write the full story in the body."),
+    json_out: bool = typer.Option(False, "--json"),
+):
+    """Scaffold a user story (free-form body + its own discussion) on a feature."""
+    svc = get_service()
+    _print_block(feature_id, svc.add_story(feature_id, title), json_out)
+
+
+@story_app.command("list")
+@handle_errors
+def story_list(feature_id: str = typer.Argument(...)):
+    """List a feature's user stories."""
+    svc = get_service()
+    stories = svc.list_stories(feature_id)
+    if not stories:
+        console.print("[dim]no user stories[/dim]")
+        return
+    table = Table(box=None, pad_edge=False)
+    table.add_column("ID")
+    table.add_column("Story")
+    for sid, text in stories:
+        table.add_row(sid, e(text))
+    console.print(table)
+
+
+@subtask_app.command("add")
+@handle_errors
+def subtask_add(
+    task_id: str = typer.Argument(...),
+    title: str = typer.Argument("", help="Optional checklist label; write detail in the body."),
+    story: str | None = typer.Option(
+        None,
+        "--story",
+        help="User story this subtask implements (e.g. US2; must exist in the parent feature).",
+    ),
+    json_out: bool = typer.Option(False, "--json"),
+):
+    """Scaffold a subtask (free-form body + its own discussion) on a task."""
+    svc = get_service()
+    _print_block(task_id, svc.add_subtask(task_id, title, story=story), json_out)
+
+
+@subtask_app.command("list")
+@handle_errors
+def subtask_list(task_id: str = typer.Argument(...)):
+    """List a task's subtasks (with their checkbox and user-story map)."""
+    svc = get_service()
+    subs = svc.list_subtasks(task_id)
+    if not subs:
+        console.print("[dim]no subtasks[/dim]")
+        return
+    table = Table(box=None, pad_edge=False)
+    table.add_column("ID")
+    table.add_column("Subtask")
+    for sid, text in subs:
+        table.add_row(sid, e(text))
+    console.print(table)
+
+
+@subtask_app.command("done")
+@handle_errors
+def subtask_done(
+    task_id: str = typer.Argument(...),
+    local_id: str = typer.Argument(..., metavar="STn"),
+    undo: bool = typer.Option(False, "--undo", help="Re-open the subtask."),
+):
+    """Mark a subtask done (or re-open it with --undo)."""
+    svc = get_service()
+    svc.set_subtask_done(task_id, local_id, done=not undo)
+    console.print(f"{task_id} {local_id} → {'open' if undo else 'done'}")

squads/_cli/_common.py

@@ -0,0 +1,101 @@
+"""Shared CLI helpers: console, error handling, service resolution, value parsing."""
+
+import functools
+from collections.abc import Callable
+
+import typer
+from rich.console import Console
+from rich.markup import escape
+
+from squads import __version__, _clock
+from squads._errors import SquadsError
+from squads._models._enums import ItemType, Status
+from squads._paths import resolve
+from squads._service import Service, open_service
+
+console = Console()
+err_console = Console(stderr=True)
+
+# The active squad folder from the global --dir option, set once by the root callback.
+_active_dir: str | None = None
+
+
+def set_active_dir(value: str | None) -> None:
+    global _active_dir
+    _active_dir = value
+
+
+def apply_timestamp(at: str | None) -> None:
+    """Honour the global ``--at`` option: forge `clock.now()` for this invocation (or clear it)."""
+    if at is None:
+        _clock.set_now(None)
+        return
+    try:
+        _clock.set_now(_clock.parse_iso(at))
+    except ValueError:
+        err_console.print(
+            f"[red]error:[/red] invalid --at timestamp {at!r} "
+            "(use ISO 8601, e.g. 2024-01-15 or 2024-01-15T09:30:00Z)"
+        )
+        raise typer.Exit(2) from None
+
+
+def e(value: object) -> str:
+    """Escape a dynamic string so Rich does not interpret ``[...]`` as markup."""
+    return escape(str(value))
+
+
+def get_service() -> Service:
+    return open_service(_active_dir)
+
+
+def handle_errors[**P, R](fn: Callable[P, R]) -> Callable[P, R]:
+    @functools.wraps(fn)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        try:
+            return fn(*args, **kwargs)
+        except SquadsError as exc:
+            err_console.print(f"[red]error:[/red] {exc}")
+            raise typer.Exit(1) from exc
+
+    return wrapper
+
+
+def _vtuple(version: str) -> tuple[int, ...]:
+    parts: list[int] = []
+    for p in version.split("."):
+        num = "".join(c for c in p if c.isdigit())
+        parts.append(int(num) if num else 0)
+    return tuple(parts)
+
+
+def version_notice() -> None:
+    """Print a non-fatal notice if the installed squads is newer than the managed files."""
+    try:
+        sp = resolve(_active_dir)
+    except SquadsError:
+        return  # not initialized yet (e.g. before `sq init`)
+    recorded = sp.config.squads_version
+    if recorded and _vtuple(__version__) > _vtuple(recorded):
+        err_console.print(
+            f"[yellow]squads {__version__} detected (managed files at {recorded}). "
+            f"Run `sq sync` to refresh them.[/yellow]"
+        )
+
+
+def parse_type(value: str) -> ItemType:
+    try:
+        return ItemType(value)
+    except ValueError:
+        choices = ", ".join(t.value for t in ItemType)
+        raise SquadsError(f"unknown type {value!r} (one of: {choices})") from None
+
+
+def parse_status(value: str) -> Status:
+    # accept either the canonical value ("InProgress") or a loose form ("in_progress", "inprogress")
+    norm = value.replace("_", "").replace("-", "").lower()
+    for s in Status:
+        if s.value.lower() == norm or s.value == value:
+            return s
+    choices = ", ".join(s.value for s in Status)
+    raise SquadsError(f"unknown status {value!r} (one of: {choices})") from None