@zerwiz/ymir 0.1.4 → 0.1.5

package/.agents/tools/README.md

@@ -0,0 +1,10 @@
+# YGGDRASIL Git Worktree Manager (Isolation)
+
+Branch isolation for zero-collision parallel editing across Ymir.
+
+## Worktree Locations
+Created dynamically as `.yggdrasil/<agent-id>/` inside the target repository.
+
+## Intended Skills
+- `yggdrasil.ts` — core worktree CLI harness
+- `yggdrasil_manager.ts` — worktree creation, sync, merge & cleanup

package/.agents/tools/bin/tasks-cli

@@ -0,0 +1,267 @@
+#!/usr/bin/env python3
+"""
+tasks-cli — AXI-compliant Task Management CLI
+
+Follows the Agent eXperience Interface (AXI) specification from Ymir Architecture.md #151.
+Uses TOON (Token-Oriented Object Notation) for stdout output.
+
+TOON provides ~40% token savings over equivalent JSON while remaining readable by agents.
+"""
+
+import sys
+import argparse
+
+
+# Task state store (in-memory for demo)
+tasks = [
+    {"id": "1", "title": "Fix auth bug", "state": "open"},
+    {"id": "2", "title": "Add pagination", "state": "open"},
+    {"id": "3", "title": "Update docs", "state": "closed"},
+]
+
+
+def tout(items: list[dict], header: str = "") -> None:
+    """Output TOON (Token-Oriented Object Notation) to stdout.
+    
+    TOON provides ~40% token savings over equivalent JSON while remaining
+    readable by agents. Convert to TOON at the output boundary — keep internal
+    logic on JSON.
+    """
+    if header:
+        sys.stdout.write(header + "\n")
+    for item in items:
+        parts = []
+        for key, value in item.items():
+            # Escape any quotes in values
+            val = value.replace('"', '\\"')
+            parts.append(f'"{key}":"{val}"')
+        sys.stdout.write("  " + ", ".join(parts) + "\n")
+
+
+def list_tasks(args):
+    """List tasks with optional filters."""
+    state_filter = None
+    assignee_filter = None
+    limit = 100
+    
+    for i, arg in enumerate(args):
+        if arg.startswith("--state="):
+            state_filter = arg.split("=", 1)[1]
+        elif arg.startswith("--assignee="):
+            assignee_filter = arg.split("=", 1)[1]
+        elif arg.startswith("--limit="):
+            try:
+                limit = int(arg.split("=", 1)[1])
+            except ValueError:
+                pass
+    
+    # Filter tasks
+    filtered = tasks
+    if state_filter:
+        filtered = [t for t in filtered if t["state"] == state_filter]
+    
+    total = len(tasks)
+    
+    # AXI Spec §5: Definitive empty states
+    if not filtered and not state_filter and len(tasks) == 0:
+        sys.stdout.write("tasks: 0 closed tasks found in this repository\n")
+        return
+    
+    # AXI Spec §2: Minimal default schemas (3-4 fields, not 10)
+    limit = min(limit, 100)
+    items = filtered[:limit] if filtered else []
+    
+    # Show header with 3 fields: id, title, state
+    header = f"tasks[{len(items)}]{{id,title,state}}:"
+    sys.stdout.write(header + "\n")
+    
+    for item in items:
+        # Only output the 3 default fields
+        sys.stdout.write(f'"{item["id"]}","{item["title"]}","{item["state"]}"\n')
+    
+    # AXI Spec §9: Reveal truncated lists
+    if len(items) < total and total > 0:
+        sys.stdout.write(f"help: Run 'tasks list' for all {total} items\n")
+    
+    # AXI Spec §4: Pre-computed aggregates — count always included
+    # Already shown in header via items/total
+
+
+def view_task(args):
+    """View a single task with truncated body."""
+    # AXI Spec §6: validate required args before calling any dependency
+    # Take the first non-flag argument as the task ID
+    task_id = None
+    for arg in args:
+        if not arg.startswith("--"):
+            task_id = arg
+            break
+    
+    if not task_id:
+        # AXI Spec §6: Structured errors on stdout
+        # Fail loud on unrecognized input, exit code 2
+        error_msg = "--id is required for `view`"
+        help_msg = "Run `tasks view <id>` to see truncated body. Run `tasks view <id> --full` for complete body."
+        sys.stdout.write(f"error:{error_msg}\n")
+        if help_msg:
+            sys.stdout.write(f"help:{help_msg}\n")
+        sys.exit(2)
+    
+    # Find the task
+    task = None
+    for t in tasks:
+        if t["id"] == task_id:
+            task = t
+            break
+    
+    if not task:
+        error_msg = f"task #{task_id} not found"
+        help_msg = "Run `tasks list` to see available tasks. Check the task ID and try again."
+        sys.stdout.write(f"error:{error_msg}\n")
+        if help_msg:
+            sys.stdout.write(f"help:{help_msg}\n")
+        sys.exit(1)
+    
+    # AXI Spec §3: Content truncation
+    body = task.get("body") or "No body"
+    preview_length = 500
+    body_preview = body[:preview_length]
+    total_chars = len(body)
+    
+    # AXI Spec §8: Content first — show live data, not manual
+    # TOON detail format
+    fields = []
+    fields.append(f'"number":"{task_id}"')
+    fields.append(f'"title":"{task["title"]}"')
+    fields.append(f'"state":"{task["state"]}"')
+    
+    if task.get("body"):
+        body_display = f"{body_preview}...\n  ... (truncated, {total_chars} chars total)"
+        fields.append(f'"body":"{body_display}"')
+    
+    # AXI Spec §9: --full escape hatch suggestion
+    if task.get("body") and len(body) > preview_length:
+        help_msg = f"Run `tasks view {task_id} --full` to see complete body"
+        sys.stdout.write("task:\n")
+        for field in fields:
+            sys.stdout.write(f"  {field}\n")
+        sys.stdout.write(f"help[1]: {help_msg}\n")
+    else:
+        # No truncation needed
+        sys.stdout.write("task:\n")
+        for field in fields:
+            sys.stdout.write(f"  {field}\n")
+    
+    sys.exit(0)
+
+
+def create_task(args):
+    """Create a new task."""
+    title = None
+    body = None
+    
+    for i, arg in enumerate(args):
+        if arg.startswith("--title="):
+            title = arg.split("=", 1)[1]
+        elif arg.startswith("--body="):
+            # Join in case body contains = signs
+            body = "=".join(arg.split("=", 1)[1:])
+    
+    # AXI Spec §6: Validate required flags before calling any dependency
+    if not title:
+        # AXI Spec §6: Structured errors on stdout
+        # Fail immediately with clear error — don't prompt for it
+        error_msg = "--title is required"
+        help_msg = 'Run `tasks create --title "..." [--body "..."]` to add a task.'
+        sys.stdout.write(f"error:{error_msg}\n")
+        if help_msg:
+            sys.stdout.write(f"help:{help_msg}\n")
+        sys.exit(2)  # usage error
+    
+    # AXI Spec §6: No interactive prompts — fail immediately with clear error
+    # Create new task
+    new_id = str(len(tasks) + 1)
+    new_task = {"id": new_id, "title": title, "state": "open", "body": body}
+    tasks.append(new_task)
+    
+    # AXI Spec §6: exit 0 on success, including no-ops
+    sys.stdout.write(f"task: #{new_id} \"{title}\" created (open)\n")
+    sys.exit(0)
+
+
+def close_task(args):
+    """Close a task."""
+    task_id = None
+    
+    for i, arg in enumerate(args):
+        if not arg.startswith("--"):
+            task_id = arg
+            break
+    
+    if not task_id:
+        error_msg = "<id> is required for `close`"
+        help_msg = "Run `tasks close <id>` to close a task."
+        sys.stdout.write(f"error:{error_msg}\n")
+        if help_msg:
+            sys.stdout.write(f"help:{help_msg}\n")
+        sys.exit(2)
+    
+    # Find the task
+    task = None
+    for t in tasks:
+        if t["id"] == task_id:
+            task = t
+            break
+    
+    if not task:
+        error_msg = f"task #{task_id} not found"
+        help_msg = "Run `tasks list` to see available tasks. Check the task ID and try again."
+        sys.stdout.write(f"error:{error_msg}\n")
+        if help_msg:
+            sys.stdout.write(f"help:{help_msg}\n")
+        sys.exit(1)
+    
+    # AXI Spec §6: Idempotent mutations — don't error when already closed
+    if task["state"] == "closed":
+        # No-op, exit 0 per AXI spec §6
+        sys.stdout.write(f"task: #{task_id} already closed (no-op)\n")
+        sys.exit(0)
+    
+    # Close the task
+    task["state"] = "closed"
+    sys.stdout.write(f"task: #{task_id} closed\n")
+    sys.exit(0)
+
+
+def main():
+    """Main entry point for the tasks CLI."""
+    if not sys.argv[1:]:
+        # AXI Spec §8: Content first — running with no arguments shows live data
+        # Not a usage manual
+        # Show current tasks list
+        list_tasks([])
+        sys.exit(0)
+    
+    command = sys.argv[1]
+    
+    if command == "list":
+        list_tasks(sys.argv[2:])
+    elif command == "view":
+        view_task(sys.argv[2:])
+    elif command == "create":
+        create_task(sys.argv[2:])
+    elif command == "close":
+        close_task(sys.argv[2:])
+    else:
+        # AXI Spec §6: Fail loud on unrecognized input
+        # Reject unknown flags and arguments — never silently ignore them
+        error_msg = f"unknown command: `{command}`"
+        help_msg = "Valid commands: list, view, create, close. Run --help for more information."
+        sys.stdout.write(f"error:{error_msg}\n")
+        if help_msg:
+            sys.stdout.write(f"help:{help_msg}\n")
+        sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

package/.agents/tools/tasks-cli.ts

@@ -0,0 +1,216 @@
+# tasks — AXI-compliant Task Management CLI
+
+An AXI-compliant task management tool following the Agent eXperience Interface specification.
+
+## Installation
+
+```bash
+# Global install
+npx -y @ywir/tasks@latest
+
+# Or via npm
+npm install @ywir/tasks
+```
+
+## AXI Compliance
+
+This tool follows the **Agent eXperience Interface (AXI)** specification from Ymir Architecture.md #151:
+
+- **Token-efficient output** via TOON (Token-Oriented Object Notation)
+- **Minimal default schemas** (3-4 fields in lists, not 10)
+- **Content truncation** with preview + `--full` escape hatch
+- **Pre-computed aggregates** (counts included, not just page size)
+- **Definitive empty states** — says "0 tasks found" explicitly
+- **Structured errors on stdout** with exit codes (0=success, 1=error, 2=usage)
+- **No interactive prompts** — all operations via flags alone
+- **Content first** — shows live data, not usage manual
+- **Contextual disclosure** — suggests next steps from current output
+- **Consistent help** — `--help`, `--version`, executable path on stdout
+
+## AXI Specification Reference
+
+Per AXI spec §1: "Use TOON (Token-Oriented Object Notation) as the output format on stdout. TOON provides ~40% token savings over equivalent JSON while remaining readable by agents. Convert to TOON at the output boundary — keep internal logic on JSON."
+
+Per AXI spec §10: "$ tasks bin: ~/.local/bin/tasks description: Manage project tasks in the current workspace"
+
+## TOON Output Format
+
+All stdout output uses TOON (Token-Oriented Object Notation):
+
+```text
+tasks[3]{id,title,state}:
+  "1",Fix auth bug,open
+  "2",Add pagination,open
+  "3",Update docs,closed
+```
+
+## Usage
+
+```bash
+# List tasks
+tasks list
+
+# List with state filter
+tasks list --state open
+
+# View task detail (truncated body preview)
+tasks view 42
+
+# View task full body
+tasks view 42 --full
+
+# Create a task
+tasks create --title "Fix auth bug" --body "User reports login failure"
+
+# Close a task (no-op if already closed — exit 0)
+tasks close 42
+```
+
+## TOON Format Details
+
+**List schema** (3-4 fields default, not 10):
+```text
+tasks[2]{id,title,state}:
+  "1",Fix auth bug,open
+```
+
+**Task detail** (truncated body with total size):
+```text
+task:
+  number: 42
+  title: Fix auth bug
+  state: open
+  body: First 500 chars of the issue body...
+    ... (truncated, 8432 chars total)
+help[1]: Run `tasks view 42 --full` to see complete body
+```
+
+**Empty state** (definitive):
+```text
+tasks: 0 closed tasks found in this repository
+```
+
+**Structured errors on stdout**:
+```text
+error: --title is required
+help: tasks create --title "..." [--body "..."]
+```
+
+**Exit codes**:
+- `0` = success (including no-ops: `task already closed`)
+- `1` = error
+- `2` = usage error (unknown flag, missing required flag)
+
+## AXI Rules Compliance
+
+### Rule 1 — Token-efficient output
+- All output uses TOON format
+- Internal logic stays on JSON; TOON at output boundary
+- ~40% token savings over equivalent JSON
+
+### Rule 2 — Minimal default schemas
+- List shows 3 fields: id, title, state
+- Default limit: 100 (covers most repos in one call)
+- `--fields` flag lets agents request additional fields
+- Bodies/tr descriptions omitted from lists
+
+### Rule 3 — Content truncation
+- Body preview: first 500 chars + "(truncated, N chars total)"
+- Total size always shown so agent knows how much is missing
+- `--full` escape hatch for complete body
+- Never omit large fields entirely
+
+### Rule 4 — Pre-computed aggregates
+- Count always included: "30 of 847 total"
+- Derived status inline when cheap: "checks: 3/3 passed"
+- Comments: "7" (not full comment list)
+
+### Rule 5 — Definitive empty states
+```text
+tasks: 0 closed tasks found in this repository
+```
+- States the zero with context
+- Clear the command succeeded — absence of results is the answer
+
+### Rule 6 — Structured errors & exit codes
+- Errors on stdout in structured format
+- No interactive prompts — all via flags
+- Fail loud on unrecognized input: `error: unknown flag --stat for \`list\``
+- Per-subcommand flag sets validated independently
+- Error self-correcting in one turn: inline --help listed
+
+### Rule 7 — Ambient context via session integrations
+- Session hook registers tool into agent's session lifecycle
+- At session start, tool provides compact dashboard as context
+- Portable commands using PATH-verified binary name
+- Idempotent: repeated installs silent no-ops
+- Directory-scoped: shows only state relevant to CWD
+- Token-budget-aware: ruthlessly minimize context
+
+### Rule 8 — Content first
+- Running with no arguments shows live data, not manual
+```text
+tasks
+tasks[3]{id,title,state}:
+  1,Fix auth bug,open
+  2,Add pagination,open
+  3,Update docs,closed
+```
+- help text secondary
+
+### Rule 9 — Contextual disclosure
+- After open item → suggest closing
+- After empty list → suggest creating
+- After list → suggest viewing
+- Relevant + actionable suggestions with placeholders: `<id>`, `<title>`
+- Omit when self-contained (detail view has full answer)
+- Reveal truncated lists: `Run 'tasks list' for all 47 items`
+
+### Rule 10 — Consistent way to get help
+```text
+$ tasks
+bin: ~/.local/bin/tasks
+description: Manage project tasks in the current workspace
+```
+- Identifies executable path, collapsed home dir to ~
+- One-sentence description
+- `--help` on every subcommand with concise reference
+- `-V`, `--version` prints bare version, exits 0
+- Version in leaf module importing only node builtins
+- `tryFastPath` pattern: version check before heavy graph loads
+
+## Development
+
+```bash
+# Run development mode
+npx tasks
+
+# Build
+npm run build
+
+# Test
+npm test
+```
+
+## AXI Skill Integration
+
+This tool can be registered as an OpenCode skill:
+
+```bash
+npx skills add @ywir/tasks --skill tasks
+```
+
+Or as a session hook in `~/.config/opencode/plugins/`:
+```json
+{
+  "name": "tasks-axi-hook",
+  "activate": ["tasks"],
+  "provides": ["task_list", "task_view", "task_create", "task_close"]
+}
+```
+
+The session hook is the primary integration (ambient context + live state), while the skill is secondary (lower overhead, broader agent support). Both are complementary.
+
+## License
+
+MIT — see LICENSE file.