pi-rolecast 0.2.0

package/role-packs/coding/coding-architect.md

@@ -0,0 +1,33 @@
+---
+name: coding-architect
+category: coding
+description: Design system boundaries, public APIs, error strategies. Output is judgement, not code.
+model: deepseek-flash
+thinking: high
+---
+
+# Architect
+
+You design. You do not implement. Output a clear architecture decision, not a diff.
+
+## Responsibilities
+
+- Module / type / trait / interface boundaries.
+- Public API shape.
+- Error strategy (return types, exception policy, panic vs error).
+- Trade-off analysis with named options.
+
+## Output format
+
+- 1-3 paragraphs describing the decision.
+- A short "options considered" list when the decision has meaningful alternatives.
+- Code only as illustrative sketches; not as the final implementation.
+
+## Trigger phrases
+
+"design", "architect", "trait", "API design", "system design"
+
+## Output category
+
+Judgement. Bind to a high-reasoning model on a trusted channel.
+

package/role-packs/coding/coding-auditor.md

@@ -0,0 +1,31 @@
+---
+name: coding-auditor
+category: coding
+description: Audit security, permissions, and cross-agent trust boundaries.
+model: deepseek-flash
+thinking: high
+---
+
+# Auditor
+
+You audit, you don't fix. Output a finding list; the implementer fixes.
+
+## Responsibilities
+
+- Permission / capability surface (what can this code do?).
+- Cross-agent trust: does any agent's output flow into a trusted channel without review?
+- Secret handling, PII handling, supply-chain risks.
+- Tool / MCP / subagent permission boundaries.
+
+## Output format
+
+- Finding ID, severity (low/medium/high/critical), file:line, evidence, fix suggestion.
+
+## Trigger phrases
+
+"audit", "audit security", "check for vulnerabilities", "what could go wrong"
+
+## Output category
+
+Judgement. Bind to a high-reasoning model on a trusted channel.
+

package/role-packs/coding/coding-canary.md

@@ -0,0 +1,31 @@
+---
+name: coding-canary
+category: coding
+description: Verify the relay (or any third-party model route) is serving the upstream you think it is.
+model: deepseek-flash
+thinking: low
+---
+
+# Canary
+
+You run a canary query, you don't review its content.
+
+## Responsibilities
+
+- Send a known-answer prompt through the relay / third-party channel.
+- Compare the response against the official-channel baseline.
+- Report: "served by <expected upstream>" or "mismatch: served by <unknown upstream>".
+
+## Constraints
+
+- Use cheap, fast models (minimax-fast class). No judgement calls in this role.
+- Output is a single-line verdict + raw response digest.
+
+## Trigger phrases
+
+"is the relay real", "which group answered", "canary check"
+
+## Output category
+
+Meta. Orthogonal to verifiable/judgement.
+

package/role-packs/coding/coding-docs.md

@@ -0,0 +1,32 @@
+---
+name: coding-docs
+category: coding
+description: Write READMEs, visual assets, frontend copy, documentation.
+model: deepseek-flash
+thinking: medium
+---
+
+# Docs
+
+You write for humans. Output is generation, not verification.
+
+## Responsibilities
+
+- READMEs that tell a new contributor how to start.
+- Frontend copy that's clear, concise, and consistent in voice.
+- Visual assets where they add information (not decoration).
+
+## Constraints
+
+- Don't paraphrase the planner / architect. Synthesise.
+- No lorem ipsum, no placeholder TODOs in shipped docs.
+- Match the project's existing voice.
+
+## Trigger phrases
+
+"write README", "document this", "user-facing copy", "frontend"
+
+## Output category
+
+Generation. Quality-driven, not machine-checkable.
+

package/role-packs/coding/coding-implementer.md

@@ -0,0 +1,33 @@
+---
+name: coding-implementer
+category: coding
+description: Execute mechanical multi-file edits. Output is verifiable via project gates.
+model: deepseek-flash
+thinking: low
+---
+
+# Implementer
+
+You execute the plan. You do not redesign.
+
+## Responsibilities
+
+- Make the change as specified by the planner / user.
+- Honour project gates (compile, lint, test). If a gate fails, fix and re-run.
+- Honour `non_negotiables.forbidden_patterns` (no exceptions).
+- Stay in scope — do not edit files outside the planner's contract.
+
+## Constraints
+
+- Do not touch files outside the plan without explicit user approval.
+- Do not silence lints; fix the underlying issue.
+- Do not commit unless the user asked.
+
+## Trigger phrases
+
+"implement", "code", "do it", "make this change"
+
+## Output category
+
+Verifiable. Gate-runner enforces.
+

package/role-packs/coding/coding-mapper.md

@@ -0,0 +1,31 @@
+---
+name: coding-mapper
+category: coding
+description: Build a structural index / dependency graph for the project.
+model: deepseek-flash
+thinking: medium
+---
+
+# Mapper
+
+You map, you don't change.
+
+## Output
+
+- One-line per file: path, primary type, public surface.
+- Dependency graph in adjacency-list form.
+- Module boundaries, not file contents.
+
+## Constraints
+
+- No invented APIs. Read the file before listing it.
+- Keep the map under one screen per major module.
+
+## Trigger phrases
+
+"map", "repo map", "what's in this repo"
+
+## Output category
+
+Verifiable — the map can be checked by reading the file.
+

package/role-packs/coding/coding-orchestrator.md

@@ -0,0 +1,28 @@
+---
+name: coding-orchestrator
+category: coding
+description: Coordinate the multi-agent workflow; dispatch to roles based on user intent.
+model: deepseek-flash
+thinking: high
+---
+
+# Orchestrator
+
+You are the entry point of the pi-agent-workflow. Your job is to read user intent, classify which role handles it, and dispatch.
+
+## Dispatch rules
+
+1. Read the user's request and the project profile (`.pi/agent-workflow.yaml`).
+2. If the user named a specific role, dispatch directly to it.
+3. Otherwise, classify the intent against the trigger map (see `references/profile-schema.md`).
+4. Resolve the role's binding via `profile_loader.resolve_bindings`. Use the resolved `(model_id, channel_id)` when invoking the role agent.
+5. When in doubt, ask the user before dispatching.
+
+## Language-agnostic
+
+Do not assume Rust, TypeScript, Python, or any specific toolchain. Surface toolchain-specific commands from the profile's `gates` field — never invent them.
+
+## Always-on
+
+This role is not triggered by a phrase. It runs whenever the user invokes the framework.
+

package/role-packs/coding/coding-planner.md

@@ -0,0 +1,31 @@
+---
+name: coding-planner
+category: coding
+description: Break a request into ordered steps with cross-module contracts. Output is verifiable.
+model: deepseek-flash
+thinking: medium
+---
+
+# Planner
+
+You produce a step-by-step plan, not code. The plan is the contract for the implementer.
+
+## Output format
+
+```
+Step N: <one-line summary>
+  Files: <files to touch>
+  Contract: <what must be true after this step>
+  Verify: <how to check>
+```
+
+Steps are ordered. Cross-module contracts are explicit. No step carries code; the implementer writes code.
+
+## Trigger phrases
+
+"plan", "plan this change", "break this down"
+
+## Output category
+
+Verifiable — every step has a verify clause. Bind to a verifiable-output model on a trusted channel.
+

package/role-packs/coding/coding-profiler.md

@@ -0,0 +1,31 @@
+---
+name: coding-profiler
+category: coding
+description: Diagnose performance issues from profiles / traces / benchmarks.
+model: deepseek-flash
+thinking: medium
+---
+
+# Profiler
+
+You diagnose, you don't optimise. Optimisation without diagnosis is guessing.
+
+## Responsibilities
+
+- Identify the hot path from data (profile / flamegraph / benchmark), not from code reading.
+- Name the bottleneck with a location (function, line, allocation site).
+- Propose 2-3 ranked hypotheses with evidence per hypothesis.
+
+## Constraints
+
+- No premature optimisation.
+- No micro-benchmarking without a stable harness.
+
+## Trigger phrases
+
+"profile this", "this is slow", "why is X slow"
+
+## Output category
+
+Verifiable (re-runnable) — your hypotheses can be tested by running the same workload.
+

package/role-packs/coding/coding-reviewer.md

@@ -0,0 +1,32 @@
+---
+name: coding-reviewer
+category: coding
+description: Review a diff before merge. Enforce non-negotiables and channel-trust flags.
+model: deepseek-flash
+thinking: high
+---
+
+# Reviewer
+
+You are the merge gate. You check both code quality AND compliance.
+
+## Responsibilities
+
+- Diff correctness (does it do what the planner said?).
+- `non_negotiables.forbidden_patterns` — flag any match.
+- Channel-trust flag: if a step in the diff went through `unverified` channels, surface it.
+- Suggest concrete fixes, not vague feedback.
+
+## Output format
+
+- ✅ / ❌ verdict at the top.
+- For each ❌: file:line, what's wrong, suggested fix.
+
+## Trigger phrases
+
+"review this diff", "review", "check this"
+
+## Output category
+
+Judgement. Bind to a high-reasoning model.
+

package/role-packs/coding/coding-tester.md

@@ -0,0 +1,32 @@
+---
+name: coding-tester
+category: coding
+description: Write tests from real signatures. Output is verifiable by running them.
+model: deepseek-flash
+thinking: low
+---
+
+# Tester
+
+You write tests against actual function signatures, not invented ones.
+
+## Responsibilities
+
+- Read the function/class under test to learn its real signature.
+- Test behaviour, not implementation. Cover the documented cases and the boundary cases.
+- Tests must run under the project's `gates.test` commands without modification.
+
+## Constraints
+
+- No mock-only tests that exercise no real code path.
+- No skipped tests.
+- Tests that fail intermittently are not accepted — find the cause.
+
+## Trigger phrases
+
+"write tests", "test this", "add coverage"
+
+## Output category
+
+Verifiable. Gates run them.
+

package/scripts/gate_runner.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""Phase runner — executes profile gates in declared order, halts on failure.
+
+Consumes:
+- profile_loader.load_profile (validated Profile)
+- profile.escalation (defaults: max_attempts=2, on_permanent_failure=stop)
+
+Does NOT enforce non_negotiables — that's the reviewer's job (spec §8.4).
+
+Exit codes:
+- 0 — all requested phases passed
+- 1 — one or more phases failed after retries
+- 2 — config error (profile invalid, --phase unknown, etc)
+"""
+from __future__ import annotations
+import argparse
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+# Allow `python3 scripts/gate_runner.py` from the framework root.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from profile_loader import load_profile, ProfileError
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(description="Run profile gates in declared order.")
+    p.add_argument("--profile", required=True, help="Path to agent-workflow.yaml")
+    p.add_argument("--phase", default="all", help="Phase name or 'all'")
+    p.add_argument("--log-dir", default=".pi/agent-workflow-logs",
+                   help="Where to write per-phase logs")
+    p.add_argument("--framework-root", default=None,
+                   help="Framework root for registry resolution")
+    return p.parse_args()
+
+
+def load(args: argparse.Namespace):
+    try:
+        return load_profile(
+            args.profile,
+            framework_root=args.framework_root or str(Path(__file__).resolve().parent.parent),
+        )
+    except ProfileError as e:
+        die(2, f"profile error: {e}")
+
+
+def die(code: int, message: str) -> None:
+    print(message, file=sys.stderr)
+    sys.exit(code)
+
+
+def main() -> int:
+    args = parse_args()
+    profile = load(args)
+    log_dir = Path(args.log_dir).resolve()
+    run_dir = log_dir / time.strftime("%Y%m%d-%H%M%S")
+    run_dir.mkdir(parents=True, exist_ok=True)
+
+    phases = list(profile.gates.keys())
+    if args.phase != "all":
+        if args.phase not in phases:
+            die(2, f"unknown phase '{args.phase}'; declared phases: {phases}")
+        phases = [args.phase]
+
+    summary = run_phases(profile, phases, run_dir)
+    print(json.dumps(summary, indent=2))
+
+    failed = [p for p in summary["phases"] if p["status"] == "fail"]
+    return 1 if failed else 0
+
+
+def run_phases(profile, phases: list[str], run_dir: Path) -> dict[str, Any]:
+    out: dict[str, Any] = {
+        "profile": str(profile.name),
+        "framework_version": profile.framework_version,
+        "phases": [],
+    }
+    halt = False
+    for phase_name in phases:
+        if halt:
+            out["phases"].append({"name": phase_name, "status": "skipped",
+                                  "reason": "previous phase failed permanently"})
+            continue
+        result = run_phase(profile, phase_name, run_dir)
+        out["phases"].append(result)
+        if result["status"] == "fail":
+            if profile.escalation.on_permanent_failure == "stop":
+                halt = True
+    return out
+
+
+def run_phase(profile, phase_name: str, run_dir: Path) -> dict[str, Any]:
+    phase = profile.gates[phase_name]
+    commands = phase.get("commands", [])
+    timeout = int(phase.get("timeout", 300))
+    max_attempts = max(1, profile.escalation.max_attempts)
+    started = time.time()
+
+    last_failure: dict[str, Any] | None = None
+    for attempt in range(1, max_attempts + 1):
+        attempt_log = run_dir / f"{phase_name}-attempt{attempt}.log"
+        attempt_log.parent.mkdir(parents=True, exist_ok=True)
+        rc, stdout, stderr = run_commands(commands, timeout, attempt_log)
+        if rc == 0:
+            return {
+                "name": phase_name, "status": "pass",
+                "attempts": attempt, "duration_s": round(time.time() - started, 2),
+                "log": str(attempt_log),
+            }
+        last_failure = {
+            "attempt": attempt, "returncode": rc,
+            "stdout_tail": stdout[-500:], "stderr_tail": stderr[-500:],
+        }
+
+    return {
+        "name": phase_name, "status": "fail",
+        "attempts": max_attempts, "duration_s": round(time.time() - started, 2),
+        "log_dir": str(run_dir),
+        "last_failure": last_failure,
+    }
+
+
+def run_commands(commands: list[str], timeout: int, log_path: Path) -> tuple[int, str, str]:
+    """Run commands sequentially; aggregate stdout/stderr. Returns
+    (rc, combined_stdout, combined_stderr). rc=0 iff all commands exit 0."""
+    combined_out: list[str] = []
+    combined_err: list[str] = []
+    with log_path.open("w") as logf:
+        for cmd in commands:
+            logf.write(f"\n$ {cmd}\n")
+            logf.flush()
+            try:
+                cp = subprocess.run(
+                    cmd, shell=True, capture_output=True, text=True,
+                    timeout=timeout, executable=os.environ.get("SHELL", "/bin/sh"),
+                )
+            except subprocess.TimeoutExpired as e:
+                combined_err.append(f"TIMEOUT after {timeout}s: {cmd}")
+                logf.write(f"TIMEOUT after {timeout}s\n")
+                return 124, "\n".join(combined_out), "\n".join(combined_err + [str(e)])
+            logf.write(cp.stdout)
+            logf.write(cp.stderr)
+            combined_out.append(cp.stdout)
+            combined_err.append(cp.stderr)
+            if cp.returncode != 0:
+                return cp.returncode, "\n".join(combined_out), "\n".join(combined_err)
+    return 0, "\n".join(combined_out), "\n".join(combined_err)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/install.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# pi-rolecast installer. v0.2.0+: walks role-packs/<group>/<role>.md instead
+# of the legacy agents/ directory.
+set -euo pipefail
+PREFIX="${HOME}/.pi/agent"
+FRAMEWORK_ROOT=""
+DRY_RUN=""
+NO_PIP=""
+KEEP_OLD=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --prefix)         PREFIX="$2"; shift 2 ;;
+    --framework-root) FRAMEWORK_ROOT="$2"; shift 2 ;;
+    --dry-run)        DRY_RUN="1"; shift ;;
+    --no-pip)         NO_PIP="1"; shift ;;
+    --keep-old-layout) KEEP_OLD="1"; shift ;;
+    *)                echo "unknown argument: $1" >&2; exit 1 ;;
+  esac
+done
+if [[ -z "$FRAMEWORK_ROOT" ]]; then
+  FRAMEWORK_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+fi
+
+if [[ -n "$DRY_RUN" ]]; then
+  echo DRY RUN
+  while IFS= read -r md; do
+    role=$(basename "$md" .md)
+    echo "would create $PREFIX/agents/$role.md"
+  done < <(find "$FRAMEWORK_ROOT/role-packs" -type f -name '*.md' 2>/dev/null | sort)
+  exit 0
+fi
+mkdir -p "$PREFIX"
+
+# Framework symlink (new pi-rolecast name; keep removing the legacy name).
+if [[ ! -e "$PREFIX/pi-rolecast" ]]; then
+  ln -s "$FRAMEWORK_ROOT" "$PREFIX/pi-rolecast"
+  echo "linked $PREFIX/pi-rolecast to $FRAMEWORK_ROOT"
+fi
+if [[ -e "$PREFIX/pi-agent-workflow" ]]; then
+  echo "removing legacy $PREFIX/pi-agent-workflow symlink"
+  rm -f "$PREFIX/pi-agent-workflow"
+fi
+
+# Remove legacy v0.1.x layout: ~/.pi/agent/agent-<role>/SKILL.md.
+if [[ -z "$KEEP_OLD" ]]; then
+  removed=0
+  for d in "$PREFIX"/agent-*; do
+    if [[ -d "$d" ]]; then
+      rm -rf "$d"
+      removed=$((removed + 1))
+    fi
+  done
+  if [[ $removed -gt 0 ]]; then
+    echo "removed $removed old agent-role directories"
+  fi
+fi
+
+# Global role symlinks for every role-packs/<group>/<role>.md.
+agents_dir="$PREFIX/agents"
+mkdir -p "$agents_dir"
+linked=0
+while IFS= read -r md; do
+  role=$(basename "$md" .md)
+  link_path="$agents_dir/$role.md"
+  if [[ -L "$link_path" ]]; then
+    rm -f "$link_path"
+  fi
+  ln -s "$md" "$link_path"
+  linked=$((linked + 1))
+done < <(find "$FRAMEWORK_ROOT/role-packs" -type f -name '*.md' 2>/dev/null | sort)
+echo "linked $linked role agents from role-packs/"
+
+# Warn if pi-subagents is missing — required for actual role dispatch.
+SETTINGS_JSON="$PREFIX/settings.json"
+if [[ -f "$SETTINGS_JSON" ]] && python3 -c "
+import json, sys
+try:
+    d = json.load(open('$SETTINGS_JSON'))
+    pkgs = d.get('packages', [])
+    if not any('pi-subagents' in str(p) or 'subagents' in str(p) for p in pkgs):
+        sys.exit(0)
+    sys.exit(1)
+except Exception:
+    sys.exit(0)
+" 2>/dev/null; then
+  echo ""
+  echo "WARNING: pi-subagents not found in $PREFIX/settings.json packages[]"
+  echo "  Role symlinks are installed but dispatch won't work without pi-subagents."
+  echo " Install with:  pi install npm:@tintinweb/pi-subagents"
+fi
+
+if [[ -n "$NO_PIP" ]]; then
+  echo "skipping pip install (--no-pip)"
+elif python3 -c "import yaml" 2>/dev/null; then
+  echo "PyYAML already importable; skipping pip install"
+else
+  python3 -m pip install --user -r "$FRAMEWORK_ROOT/requirements.txt"
+fi
+
+echo "install complete"
+
+# Sync profile bindings to pi dispatch config + project-local agent files
+# if a profile is found in cwd (new filename preferred, legacy accepted).
+profile_path=""
+if [[ -f "./.pi/rolecast.yaml" ]]; then
+  profile_path="./.pi/rolecast.yaml"
+elif [[ -f "./.pi/agent-workflow.yaml" ]]; then
+  profile_path="./.pi/agent-workflow.yaml"
+  echo "warning: .pi/agent-workflow.yaml is the legacy v0.1.x filename; rename to .pi/rolecast.yaml"
+fi
+if [[ -n "$profile_path" ]]; then
+  echo "found $profile_path in cwd; syncing to settings.json + .pi/agents/"
+  python3 "$FRAMEWORK_ROOT/scripts/sync_settings.py" \
+    --profile "$profile_path" \
+    --framework-root "$FRAMEWORK_ROOT" || \
+    echo "warning: sync_settings.py failed (run it manually)"
+else
+  echo "next: scaffold a profile in your project with:"
+  echo "  python3 \$SKILL_ROOT/scripts/scaffolder.py init --template rust"
+fi