@smilintux/skcapstone 0.1.0 → 0.2.4

package/src/skcapstone/cli/context_cmd.py

@@ -0,0 +1,142 @@
+"""Context loader commands: show, generate."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from ._common import AGENT_HOME, console
+
+
+def register_context_commands(main: click.Group) -> None:
+    """Register the context command group."""
+
+    @main.group()
+    def context():
+        """Universal AI agent context loader.
+
+        Outputs agent identity, pillar status, board state, and recent
+        memories in formats consumable by any AI tool. Tool-agnostic:
+        works with Claude Code, Cursor, Windsurf, Aider, or any terminal.
+        """
+
+    @context.command("show")
+    @click.option("--home", default=AGENT_HOME, type=click.Path())
+    @click.option(
+        "--format",
+        "fmt",
+        type=click.Choice(["text", "json", "claude-md", "cursor-rules"]),
+        default="text",
+        help="Output format (default: text).",
+    )
+    @click.option("--memories", "-n", default=10, help="Max recent memories to include.")
+    def context_show(home: str, fmt: str, memories: int):
+        """Show the agent's full context.
+
+        Pipe into any AI tool or redirect to a file:
+
+            skcapstone context show                        # terminal
+            skcapstone context show --format json          # machine-readable
+            skcapstone context show --format claude-md     # for Claude Code
+            skcapstone context show | claude               # pipe to Claude Code CLI
+
+        Examples:
+            skcapstone context show --format claude-md > CLAUDE.md
+            skcapstone context show --format cursor-rules > .cursor/rules/agent.mdc
+        """
+        home_path = Path(home).expanduser()
+        if fmt == "claude-md":
+            from ..claude_md import generate_claude_md
+            click.echo(generate_claude_md(home_path, memory_limit=memories))
+        else:
+            from ..context_loader import FORMATTERS, gather_context
+            ctx = gather_context(home_path, memory_limit=memories)
+            click.echo(FORMATTERS[fmt](ctx))
+
+    @context.command("generate")
+    @click.option("--home", default=AGENT_HOME, type=click.Path())
+    @click.option("--memories", "-n", default=10, help="Max recent memories to include.")
+    @click.option(
+        "--target",
+        type=click.Choice(["claude-md", "cursor-rules", "both"]),
+        default="both",
+        help="Which config file(s) to generate.",
+    )
+    def context_generate(home: str, memories: int, target: str):
+        """Auto-generate AI tool config files from agent context.
+
+        Writes CLAUDE.md (for Claude Code CLI) and/or
+        .cursor/rules/agent.mdc (for Cursor) in the current directory.
+
+        Examples:
+            skcapstone context generate                   # both files
+            skcapstone context generate --target claude-md # CLAUDE.md only
+        """
+        from ..context_loader import FORMATTERS, gather_context
+
+        home_path = Path(home).expanduser()
+        ctx = gather_context(home_path, memory_limit=memories)
+
+        cwd = Path.cwd()
+
+        if target in ("claude-md", "both"):
+            claude_path = cwd / "CLAUDE.md"
+            claude_path.write_text(FORMATTERS["claude-md"](ctx), encoding="utf-8")
+            console.print(f"  [green]Written:[/] {claude_path}")
+
+        if target in ("cursor-rules", "both"):
+            rules_dir = cwd / ".cursor" / "rules"
+            rules_dir.mkdir(parents=True, exist_ok=True)
+            rules_path = rules_dir / "agent.mdc"
+            rules_path.write_text(FORMATTERS["cursor-rules"](ctx), encoding="utf-8")
+            console.print(f"  [green]Written:[/] {rules_path}")
+
+        console.print()
+
+    @main.command("refresh-context")
+    @click.option("--home", default=AGENT_HOME, type=click.Path())
+    @click.option("--memories", "-n", default=10, help="Max recent memories to embed.")
+    @click.option(
+        "--dest",
+        default=None,
+        type=click.Path(),
+        help="Destination path for CLAUDE.md (default: repo root or cwd).",
+    )
+    @click.option("--backup", is_flag=True, default=False, help="Rename existing CLAUDE.md to .bak before writing.")
+    def refresh_context(home: str, memories: int, dest: str | None, backup: bool):
+        """Regenerate CLAUDE.md from current agent state.
+
+        Writes CLAUDE.md to the git repository root (or cwd if not in a
+        git repository). Useful as a pre-commit hook or alias.
+
+        Examples:
+            skcapstone refresh-context
+            skcapstone refresh-context --dest /path/to/project/CLAUDE.md
+            skcapstone refresh-context --backup
+        """
+        import subprocess
+
+        from ..claude_md import write_claude_md
+
+        home_path = Path(home).expanduser()
+
+        if dest:
+            target = Path(dest).expanduser().resolve()
+            if target.is_dir():
+                target = target / "CLAUDE.md"
+        else:
+            # Walk up from cwd to find git root; fall back to cwd.
+            try:
+                result = subprocess.run(
+                    ["git", "rev-parse", "--show-toplevel"],
+                    capture_output=True,
+                    text=True,
+                    check=True,
+                )
+                target = Path(result.stdout.strip()) / "CLAUDE.md"
+            except (subprocess.CalledProcessError, FileNotFoundError):
+                target = Path.cwd() / "CLAUDE.md"
+
+        write_claude_md(home_path, target, memory_limit=memories, backup=backup)
+        console.print(f"  [green]Written:[/] {target}")

package/src/skcapstone/cli/coord.py

@@ -0,0 +1,194 @@
+"""Coordination board commands: status, create, claim, complete, board, changelog, briefing."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from ._common import AGENT_HOME, console
+from ._validators import validate_agent_name, validate_task_id
+
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+
+def register_coord_commands(main: click.Group) -> None:
+    """Register the coord command group."""
+
+    @main.group()
+    def coord():
+        """Multi-agent coordination board.
+
+        Create tasks, claim work, and track progress across
+        agents. All data lives in ~/.skcapstone/coordination/
+        and syncs via Syncthing. Conflict-free by design.
+        """
+
+    @coord.command("status")
+    @click.option("--home", default=AGENT_HOME, type=click.Path())
+    def coord_status(home):
+        """Show the coordination board overview."""
+        from ..coordination import Board
+
+        home_path = Path(home).expanduser()
+        board = Board(home_path)
+        views = board.get_task_views()
+        agents = board.load_agents()
+
+        if not views and not agents:
+            console.print("\n  [dim]Board is empty. Create tasks with:[/]")
+            console.print("  [cyan]skcapstone coord create --title 'My Task'[/]\n")
+            return
+
+        open_count = sum(1 for v in views if v.status.value == "open")
+        progress_count = sum(1 for v in views if v.status.value == "in_progress")
+        claimed_count = sum(1 for v in views if v.status.value == "claimed")
+        done_count = sum(1 for v in views if v.status.value == "done")
+
+        console.print()
+        console.print(Panel(
+            f"[bold]Tasks:[/] {len(views)} total  "
+            f"[green]{open_count} open[/]  "
+            f"[cyan]{claimed_count} claimed[/]  "
+            f"[yellow]{progress_count} in progress[/]  "
+            f"[dim]{done_count} done[/]",
+            title="Coordination Board", border_style="bright_blue",
+        ))
+
+        table = Table(show_header=True, header_style="bold", box=None, padding=(0, 2))
+        table.add_column("ID", style="cyan", max_width=10)
+        table.add_column("Title", style="bold")
+        table.add_column("Priority")
+        table.add_column("Status")
+        table.add_column("Assignee", style="dim")
+        table.add_column("Tags", style="dim")
+
+        priority_colors = {"critical": "bold red", "high": "red", "medium": "yellow", "low": "dim"}
+        status_colors = {"open": "green", "claimed": "cyan", "in_progress": "yellow", "done": "dim", "blocked": "red"}
+
+        for v in views:
+            if v.status.value == "done":
+                continue
+            t = v.task
+            p_style = priority_colors.get(t.priority.value, "dim")
+            s_style = status_colors.get(v.status.value, "dim")
+            table.add_row(t.id, t.title, Text(t.priority.value.upper(), style=p_style),
+                          Text(v.status.value.upper(), style=s_style), v.claimed_by or "", ", ".join(t.tags))
+
+        console.print(table)
+
+        if agents:
+            console.print()
+            for ag in agents:
+                icon = {"active": "[green]ACTIVE[/]", "idle": "[yellow]IDLE[/]"}.get(ag.state.value, "[dim]OFFLINE[/]")
+                current = f" -> [cyan]{ag.current_task}[/]" if ag.current_task else ""
+                console.print(f"  {icon} [bold]{ag.agent}[/]{current}")
+        console.print()
+
+    @coord.command("create")
+    @click.option("--home", default=AGENT_HOME, type=click.Path())
+    @click.option("--title", required=True, help="Task title.")
+    @click.option("--desc", default="", help="Task description.")
+    @click.option("--priority", type=click.Choice(["critical", "high", "medium", "low"]), default="medium")
+    @click.option("--tag", multiple=True, help="Tags (repeatable).")
+    @click.option("--by", default="human", help="Creator name.")
+    @click.option("--criteria", multiple=True, help="Acceptance criteria (repeatable).")
+    @click.option("--dep", multiple=True, help="Dependency task IDs (repeatable).")
+    def coord_create(home, title, desc, priority, tag, by, criteria, dep):
+        """Create a new task on the board."""
+        from ..coordination import Board, Task, TaskPriority
+
+        validate_agent_name(by)
+        for d in dep:
+            validate_task_id(d)
+
+        home_path = Path(home).expanduser()
+        board = Board(home_path)
+        task = Task(title=title, description=desc, priority=TaskPriority(priority),
+                    tags=list(tag), created_by=by, acceptance_criteria=list(criteria), dependencies=list(dep))
+        path = board.create_task(task)
+        console.print(f"\n  [green]Created:[/] [{task.id}] {task.title}")
+        console.print(f"  [dim]{path}[/]\n")
+
+    @coord.command("claim")
+    @click.argument("task_id")
+    @click.option("--home", default=AGENT_HOME, type=click.Path())
+    @click.option("--agent", required=True, help="Agent name claiming the task.")
+    def coord_claim(task_id, home, agent):
+        """Claim a task for an agent."""
+        from ..coordination import Board
+
+        validate_task_id(task_id)
+        validate_agent_name(agent)
+
+        home_path = Path(home).expanduser()
+        board = Board(home_path)
+        try:
+            ag = board.claim_task(agent, task_id)
+            console.print(f"\n  [green]Claimed:[/] [{task_id}] by [bold]{ag.agent}[/]\n")
+        except ValueError as e:
+            console.print(f"\n  [red]Error:[/] {e}\n")
+            sys.exit(1)
+
+    @coord.command("complete")
+    @click.argument("task_id")
+    @click.option("--home", default=AGENT_HOME, type=click.Path())
+    @click.option("--agent", required=True, help="Agent name completing the task.")
+    def coord_complete(task_id, home, agent):
+        """Mark a task as completed."""
+        from ..coordination import Board
+
+        validate_task_id(task_id)
+        validate_agent_name(agent)
+
+        home_path = Path(home).expanduser()
+        board = Board(home_path)
+        ag = board.complete_task(agent, task_id)
+        # board.complete_task() automatically mints Joules via _mint_joules_for_task
+        console.print(f"\n  [green]Completed:[/] [{task_id}] by [bold]{ag.agent}[/]\n")
+
+    @coord.command("board")
+    @click.option("--home", default=AGENT_HOME, type=click.Path())
+    def coord_board(home):
+        """Generate and display the BOARD.md overview."""
+        from ..coordination import Board
+
+        home_path = Path(home).expanduser()
+        board = Board(home_path)
+        path = board.write_board_md()
+        md = board.generate_board_md()
+        console.print(md)
+        console.print(f"\n  [dim]Written to {path}[/]\n")
+
+    @coord.command("changelog")
+    @click.option("--home", default=AGENT_HOME, type=click.Path())
+    @click.option("--output", "-o", default=None, type=click.Path(), help="Output file path.")
+    def coord_changelog(home, output):
+        """Generate CHANGELOG.md from completed board tasks."""
+        from ..changelog import generate_changelog, write_changelog
+
+        home_path = Path(home).expanduser()
+        out_path = Path(output) if output else None
+        path = write_changelog(home_path, out_path)
+
+        content = generate_changelog(home_path)
+        console.print(content[:3000])
+        if len(content) > 3000:
+            console.print(f"\n  [dim]... ({len(content)} chars total)[/]")
+        console.print(f"\n  [green]Written to {path}[/]\n")
+
+    @coord.command("briefing")
+    @click.option("--home", default=AGENT_HOME, type=click.Path())
+    @click.option("--format", "fmt", type=click.Choice(["text", "json"]), default="text")
+    def coord_briefing(home, fmt):
+        """Print the full coordination protocol for any AI agent."""
+        from ..coordination import get_briefing_text, get_briefing_json
+
+        home_path = Path(home).expanduser()
+        if fmt == "json":
+            click.echo(get_briefing_json(home_path))
+        else:
+            click.echo(get_briefing_text(home_path))

package/src/skcapstone/cli/crush_cmd.py

@@ -0,0 +1,170 @@
+"""Crush (charmbracelet/crush) integration commands.
+
+Subcommands:
+    skcapstone crush setup   — install config + soul instructions
+    skcapstone crush config  — print the generated crush.json
+    skcapstone crush status  — show installation status
+"""
+
+from __future__ import annotations
+
+import json
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+console = Console()
+
+
+def register_crush_commands(main: click.Group) -> None:
+    """Register the crush command group."""
+
+    @main.group()
+    def crush():
+        """Crush terminal AI client integration.
+
+        Wire the charmbracelet/crush TUI to skcapstone MCP and
+        load your soul blueprint as its system instructions.
+
+        https://github.com/charmbracelet/crush
+        """
+
+    @crush.command("setup")
+    @click.option(
+        "--overwrite",
+        is_flag=True,
+        default=False,
+        help="Overwrite existing crush config files.",
+    )
+    def crush_setup(overwrite: bool) -> None:
+        """Set up Crush: write crush.json + instructions.md.
+
+        Writes:
+          ~/.config/crush/crush.json     — MCP wiring + permissions
+          ~/.config/crush/instructions.md — soul blueprint as system prompt
+        """
+        from ..crush_integration import setup_crush
+
+        console.print()
+        with console.status("  Configuring Crush…", spinner="dots"):
+            result = setup_crush(overwrite=overwrite)
+
+        t = Table.grid(padding=(0, 2))
+        t.add_column(style="dim", width=20)
+        t.add_column()
+
+        if result["installed"]:
+            t.add_row("Binary", f"[green]{result['binary_path']}[/]")
+        else:
+            t.add_row("Binary", "[yellow]not found[/]")
+            if result.get("install_hint"):
+                t.add_row("Install with", f"[cyan]{result['install_hint']}[/]")
+
+        t.add_row("Config", f"[dim]{result['config_path']}[/]")
+        t.add_row("Instructions", f"[dim]{result['instructions_path']}[/]")
+
+        console.print(
+            Panel(
+                t,
+                title="[bold]Crush Setup Complete[/]",
+                border_style="bright_blue",
+            )
+        )
+
+        console.print()
+        console.print(
+            "  [dim]Run crush in your project directory to start coding with your sovereign agent.[/]"
+        )
+        if not result["installed"]:
+            console.print()
+            hint = result.get("install_hint", "go install github.com/charmbracelet/crush@latest")
+            console.print(f"  [bold]Install crush:[/]  [cyan]{hint}[/]")
+        console.print()
+
+    @crush.command("config")
+    @click.option(
+        "--json-only",
+        "json_only",
+        is_flag=True,
+        default=False,
+        help="Print raw JSON without formatting.",
+    )
+    def crush_config(json_only: bool) -> None:
+        """Print the crush.json config that will be written."""
+        from ..crush_integration import generate_crush_config
+
+        config = generate_crush_config()
+        if json_only:
+            click.echo(json.dumps(config, indent=2))
+        else:
+            console.print()
+            console.print_json(json.dumps(config, indent=2))
+            console.print()
+            console.print(
+                f"  [dim]Write this to [cyan]~/.config/crush/crush.json[/] "
+                f"with:  skcapstone crush setup[/]"
+            )
+            console.print()
+
+    @crush.command("status")
+    def crush_status() -> None:
+        """Show Crush installation and config status."""
+        from ..crush_integration import (
+            find_crush_binary,
+            get_install_hint,
+            is_crush_installed,
+        )
+        from pathlib import Path
+
+        crush_config_dir = Path("~/.config/crush").expanduser()
+        crush_json = crush_config_dir / "crush.json"
+        instructions_md = crush_config_dir / "instructions.md"
+
+        console.print()
+        t = Table(
+            title="Crush Status",
+            border_style="bright_blue",
+            show_header=True,
+        )
+        t.add_column("Item", style="bold", width=22)
+        t.add_column("Status")
+        t.add_column("Detail", style="dim")
+
+        # Binary
+        binary = find_crush_binary()
+        if binary:
+            t.add_row("Binary", "[green]FOUND[/]", str(binary))
+        else:
+            hint = get_install_hint()
+            t.add_row("Binary", "[yellow]MISSING[/]", hint)
+
+        # crush.json
+        if crush_json.exists():
+            try:
+                data = json.loads(crush_json.read_text(encoding="utf-8"))
+                mcp_count = len(data.get("mcp", {}))
+                t.add_row(
+                    "crush.json",
+                    "[green]OK[/]",
+                    f"{mcp_count} MCP server(s) — {str(crush_json)}",
+                )
+            except Exception:
+                t.add_row("crush.json", "[red]CORRUPT[/]", str(crush_json))
+        else:
+            t.add_row("crush.json", "[yellow]MISSING[/]", "run: skcapstone crush setup")
+
+        # instructions.md
+        if instructions_md.exists():
+            size = instructions_md.stat().st_size
+            t.add_row("instructions.md", "[green]OK[/]", f"{size} bytes — {str(instructions_md)}")
+        else:
+            t.add_row(
+                "instructions.md",
+                "[yellow]MISSING[/]",
+                "run: skcapstone crush setup",
+            )
+
+        console.print(t)
+        console.print()