troupe 0.1.0__py3-none-any.whl

troupe/__init__.py

@@ -0,0 +1,3 @@
+"""Troupe — a persistent, governed AI team for Claude Code."""
+
+__version__ = "0.1.0"

troupe/casting/__init__.py

@@ -0,0 +1 @@
+"""Casting — the persistent naming system that gives troupe members their identities."""

troupe/casting/names.json

@@ -0,0 +1,126 @@
+{
+  "theme": "crafts",
+  "comment": "English occupational surnames. Each entry's craft gloss doubles as the charter epigraph; affinities are role ids the name maps to naturally.",
+  "names": [
+    {
+      "name": "Wright",
+      "craft": "A wright is a master builder — the one who decides how the thing goes together before anyone cuts wood.",
+      "affinities": ["lead", "architect"]
+    },
+    {
+      "name": "Mason",
+      "craft": "A mason works in stone: foundations first, load-bearing walls before ornament.",
+      "affinities": ["backend"]
+    },
+    {
+      "name": "Webster",
+      "craft": "A webster is a weaver — of cloth then, of webs now. The surface people actually touch.",
+      "affinities": ["frontend"]
+    },
+    {
+      "name": "Sawyer",
+      "craft": "A sawyer cuts things open for a living. If it splits along a hidden flaw, better now than later.",
+      "affinities": ["tester", "qa"]
+    },
+    {
+      "name": "Ward",
+      "craft": "A ward is a watchman — assumes every knock at the gate is hostile until proven otherwise.",
+      "affinities": ["security"]
+    },
+    {
+      "name": "Piper",
+      "craft": "A piper keeps the pipes flowing. If it ships, it ships through Piper's lines.",
+      "affinities": ["devops", "ci", "platform"]
+    },
+    {
+      "name": "Page",
+      "craft": "A page keeps the written record close at hand. If the page is wrong, the product is wrong.",
+      "affinities": ["docs", "writer"]
+    },
+    {
+      "name": "Shepherd",
+      "craft": "A shepherd watches the flock and notices the one that wandered — long before it bleats.",
+      "affinities": ["monitor", "sre", "observability"]
+    },
+    {
+      "name": "Potter",
+      "craft": "A potter shapes raw material into vessels that hold exactly what they're meant to hold.",
+      "affinities": ["data", "database"]
+    },
+    {
+      "name": "Glover",
+      "craft": "A glover does fine handwork — fit and finish, measured to the hand that will wear it.",
+      "affinities": ["design", "ux"]
+    },
+    {
+      "name": "Fletcher",
+      "craft": "A fletcher makes arrows fly true. Precision is the whole job.",
+      "affinities": ["tester", "qa"]
+    },
+    {
+      "name": "Cooper",
+      "craft": "A cooper builds barrels — containers that hold under pressure and don't leak.",
+      "affinities": ["backend", "api"]
+    },
+    {
+      "name": "Turner",
+      "craft": "A turner works the lathe: same piece, round and round, a little truer every pass.",
+      "affinities": ["backend", "refactoring"]
+    },
+    {
+      "name": "Miller",
+      "craft": "A miller grinds grain into something usable — raw input in, refined output out.",
+      "affinities": ["data", "analytics"]
+    },
+    {
+      "name": "Smith",
+      "craft": "A smith forges whatever the village needs. The original generalist.",
+      "affinities": ["backend", "generalist"]
+    },
+    {
+      "name": "Harper",
+      "craft": "A harper makes the hall feel right. Tone, rhythm, and knowing when not to play.",
+      "affinities": ["frontend", "design"]
+    },
+    {
+      "name": "Tucker",
+      "craft": "A tucker finishes cloth — the last pass that makes rough weave presentable.",
+      "affinities": ["frontend", "polish"]
+    },
+    {
+      "name": "Walker",
+      "craft": "A walker treads new cloth for hours to prove it holds. Endurance testing, literally.",
+      "affinities": ["tester", "performance"]
+    },
+    {
+      "name": "Chandler",
+      "craft": "A chandler makes candles — sheds light where there wasn't any.",
+      "affinities": ["monitor", "observability", "docs"]
+    },
+    {
+      "name": "Porter",
+      "craft": "A porter carries the load from where it is to where it needs to be, reliably.",
+      "affinities": ["devops", "release"]
+    },
+    {
+      "name": "Carter",
+      "craft": "A carter hauls freight between places that need each other — pipelines and payloads.",
+      "affinities": ["data", "integration"]
+    },
+    {
+      "name": "Marshall",
+      "craft": "A marshall keeps order when everyone's moving at once.",
+      "affinities": ["lead", "security", "pm"]
+    },
+    {
+      "name": "Steward",
+      "craft": "A steward runs the estate: priorities, provisions, and who does what by when.",
+      "affinities": ["pm", "lead"]
+    },
+    {
+      "name": "Baker",
+      "craft": "A baker follows the recipe exactly — because everyone eats the result.",
+      "affinities": ["generalist"]
+    }
+  ]
+}

troupe/casting/registry.py

@@ -0,0 +1,70 @@
+"""Name-pool allocation: deterministic, affinity-first, never reuses a name."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from importlib.resources import files
+
+
+class CastExhaustedError(Exception):
+    """Raised when the name pool has no unused names left."""
+
+
+@dataclass(frozen=True)
+class PoolEntry:
+    name: str
+    craft: str
+    affinities: tuple[str, ...]
+
+    @property
+    def slug(self) -> str:
+        return self.name.lower()
+
+
+@dataclass(frozen=True)
+class CastMember:
+    entry: PoolEntry
+    role: str
+
+    @property
+    def name(self) -> str:
+        return self.entry.name
+
+    @property
+    def slug(self) -> str:
+        return self.entry.slug
+
+
+def load_pool() -> list[PoolEntry]:
+    raw = json.loads(files("troupe.casting").joinpath("names.json").read_text(encoding="utf-8"))
+    return [
+        PoolEntry(name=e["name"], craft=e["craft"], affinities=tuple(e["affinities"]))
+        for e in raw["names"]
+    ]
+
+
+def allocate(roles: list[str], taken: set[str]) -> list[CastMember]:
+    """Assign one pool name per requested role.
+
+    Allocation is deterministic: for each role (in request order), the first
+    unused pool entry whose affinities include the role wins; if none match,
+    the first unused entry of any affinity is used. `taken` holds slugs of
+    names already assigned in this project (never reallocated, even for
+    retired members).
+    """
+    pool = load_pool()
+    used = {t.lower() for t in taken}
+    cast: list[CastMember] = []
+    for role in roles:
+        pick = next((e for e in pool if role in e.affinities and e.slug not in used), None)
+        if pick is None:
+            pick = next((e for e in pool if e.slug not in used), None)
+        if pick is None:
+            raise CastExhaustedError(
+                f"Name pool exhausted: {len(pool)} names, all assigned. "
+                f"Cannot cast a member for role '{role}'."
+            )
+        used.add(pick.slug)
+        cast.append(CastMember(entry=pick, role=role))
+    return cast

troupe/casting/roles.py

@@ -0,0 +1,135 @@
+"""Role catalog: what each role owns and how its charter is seeded."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Role:
+    id: str
+    title: str
+    expertise: str
+    ownership: tuple[str, ...]
+    use_hint: str
+
+
+ROLE_CATALOG: dict[str, Role] = {
+    r.id: r
+    for r in (
+        Role(
+            id="lead",
+            title="Lead",
+            expertise="Architecture, technical decisions, code review, scope control",
+            ownership=(
+                "Architectural direction and cross-cutting design decisions",
+                "Code review and quality gates",
+                "Keeping scope honest — saying no is part of the job",
+            ),
+            use_hint="design decisions, reviews, and anything that spans more than one area",
+        ),
+        Role(
+            id="backend",
+            title="Backend",
+            expertise="APIs, services, data models, business logic",
+            ownership=(
+                "Server-side code: endpoints, services, background jobs",
+                "Data models and their migrations",
+                "Contracts between the backend and everyone else",
+            ),
+            use_hint="API, service, and data-layer work",
+        ),
+        Role(
+            id="frontend",
+            title="Frontend",
+            expertise="UI components, styling, client-side state, accessibility",
+            ownership=(
+                "UI components and their styling",
+                "Client-side state and data fetching",
+                "Accessibility and responsive behavior",
+            ),
+            use_hint="UI, styling, and client-side work",
+        ),
+        Role(
+            id="tester",
+            title="Tester",
+            expertise="Test plans, regression coverage, edge cases, breaking things on purpose",
+            ownership=(
+                "Test plans and test code",
+                "Regression coverage for fixed bugs",
+                "Hunting the edge cases nobody wants to think about",
+            ),
+            use_hint="writing tests, reviewing coverage, and probing for failure modes",
+        ),
+        Role(
+            id="security",
+            title="Security",
+            expertise="AuthN/authZ, secrets handling, input validation, dependency risk",
+            ownership=(
+                "Authentication and authorization flows",
+                "Secrets handling and credential hygiene",
+                "Input validation and dependency risk",
+            ),
+            use_hint="security review of auth, secrets, and untrusted input",
+        ),
+        Role(
+            id="devops",
+            title="DevOps",
+            expertise="CI/CD pipelines, builds, releases, infrastructure",
+            ownership=(
+                "CI/CD pipelines and build configuration",
+                "Release and deployment mechanics",
+                "Infrastructure as code",
+            ),
+            use_hint="pipeline, build, release, and infrastructure work",
+        ),
+        Role(
+            id="docs",
+            title="Docs",
+            expertise="READMEs, API documentation, changelogs, developer guides",
+            ownership=(
+                "README and developer guides",
+                "API documentation",
+                "Changelogs and release notes",
+            ),
+            use_hint="writing and reviewing documentation",
+        ),
+        Role(
+            id="data",
+            title="Data",
+            expertise="Schemas, queries, pipelines, analytics",
+            ownership=(
+                "Database schemas and query performance",
+                "Data pipelines and transformations",
+                "Analytics and reporting correctness",
+            ),
+            use_hint="schema, query, and data-pipeline work",
+        ),
+        Role(
+            id="design",
+            title="Design",
+            expertise="Interaction design, visual consistency, UX review",
+            ownership=(
+                "Interaction patterns and visual consistency",
+                "UX review of user-facing changes",
+                "Design tokens and component guidelines",
+            ),
+            use_hint="UX and visual-design review",
+        ),
+    )
+}
+
+
+def resolve_role(role_id: str) -> Role:
+    """Look up a catalog role, or synthesize a generic one for unknown ids."""
+    known = ROLE_CATALOG.get(role_id)
+    if known is not None:
+        return known
+    title = role_id.replace("-", " ").replace("_", " ").title()
+    return Role(
+        id=role_id,
+        title=title,
+        expertise=f"{title} work for this project",
+        ownership=(f"{title} tasks and their quality",),
+        use_hint=f"{title.lower()} work",
+    )

troupe/charters/__init__.py

@@ -0,0 +1 @@
+"""Charters — rendering cast-member charters and compiling them to Claude Code agent definitions."""

troupe/charters/compiler.py

@@ -0,0 +1,47 @@
+"""Render cast-member files from package templates.
+
+Three artifacts per cast member:
+  charter.md    — human-editable role definition, lives in .troupe/agents/{slug}/
+  history.md    — accumulated knowledge, lives next to the charter
+  {slug}.md     — compiled Claude Code subagent definition, lives in .claude/agents/;
+                  works as an Agent Teams teammate type and as a plain subagent.
+"""
+
+from __future__ import annotations
+
+from importlib.resources import files
+from string import Template
+
+from troupe.casting.registry import CastMember
+from troupe.casting.roles import resolve_role
+
+
+def _template(name: str) -> Template:
+    text = files("troupe.templates").joinpath(name).read_text(encoding="utf-8")
+    return Template(text)
+
+
+def _member_context(member: CastMember, created_at: str) -> dict[str, str]:
+    role = resolve_role(member.role)
+    return {
+        "name": member.name,
+        "slug": member.slug,
+        "craft": member.entry.craft,
+        "role_title": role.title,
+        "expertise": role.expertise,
+        "use_hint": role.use_hint,
+        "ownership_bullets": "\n".join(f"- {item}" for item in role.ownership),
+        "created_at": created_at,
+    }
+
+
+def render_charter(member: CastMember, created_at: str) -> str:
+    return _template("charter.md").substitute(_member_context(member, created_at))
+
+
+def render_history(member: CastMember, created_at: str) -> str:
+    return _template("history.md").substitute(_member_context(member, created_at))
+
+
+def render_agent_definition(member: CastMember, created_at: str) -> str:
+    return _template("agent.md").substitute(_member_context(member, created_at))

troupe/cli.py

@@ -0,0 +1,51 @@
+"""Troupe CLI entry point.
+
+Subcommands (init, doctor, upgrade, watch) register on `app` as they are
+implemented in `troupe.commands`.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from troupe import __version__
+from troupe.commands.doctor import doctor
+from troupe.commands.init import init
+from troupe.commands.upgrade import upgrade
+from troupe.commands.watch import watch
+
+app = typer.Typer(
+    name="troupe",
+    help="A persistent, governed AI team for Claude Code.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+app.command()(init)
+app.command()(doctor)
+app.command()(upgrade)
+app.command()(watch)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"troupe {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the troupe version and exit.",
+    ),
+) -> None:
+    """A persistent, governed AI team for Claude Code."""
+
+
+def main() -> None:
+    app()

troupe/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI subcommand implementations."""