Skip to content

mtrenker/pi-clean

v0.1.0

pi-clean workflow skills: GitHub issues and pull requests, interactive agent sessions, prose, experience design, React composition, and Proton Pass.

GitHub

pi-clean

Custom pi package collection.

Install

pi install git:git@github.com:mtrenker/pi-clean.git

Extensions

🛡 Agent Guard

Adds focused guardrails for catastrophic shell commands, sensitive file paths, and secret-like tool output while preserving normal agent autonomy.

◩ Visual Design Relay

Prototypes repo-native, Plate-compatible visual artifacts: select a stable design node in the browser, discuss it with Pi, and watch validated agent mutations or external file edits appear live. Start the included artifact with /design designs/example.design.json.

Interactive delegation with Herdr

Pi-clean intentionally does not ship a subprocess delegation tool or duplicate Herdr command reference. Its interactive-agent-sessions skill maps short requests to predictable Claude and Codex launch profiles and placement; it reads Herdr's own skill from herdr --skill as the canonical guide to current pane, workspace, output, focus, and intervention commands.

Choose the delegation boundary by risk:

  • Assign any product, UX, interaction, visual, architecture, API, or data-model design exclusively to Claude Opus 5.5. Fable may coordinate but must not implement code or delegate coding to another Fable unless Martin explicitly requests Fable implementation for that specific task. Use Opus or Codex as coding workers. Pi and Codex may investigate constraints, implement the durable Opus direction, and validate it, but must not originate or materially revise unresolved design.
  • For bounded read-only investigation, split a pane in the current Herdr workspace only when sharing the checkout is safe.
  • When delegating from inside an issue worktree, keep the delegate in that worktree's existing workspace as a sibling pane or a named tab. One worktree has one semantic workspace, so never open a second one for the same checkout.
  • Keep one writer at a time in a shared worktree. Read-only delegates may run alongside the writer; a writing delegate takes that role exclusively while the coordinator holds still.
  • For a new issue's implementation, or any mutation of another checkout, use scripts/github-work.mjs start-issue so the agent receives an isolated linked worktree and workspace.
  • For independent pull-request review, use scripts/github-work.mjs review-pr so the reviewer receives a detached review worktree in a named tab of a workspace this repository already has.

Keep delegated agents visible. First observe the pane reach working; a pane that never does may not have launched correctly. After that, treat either done or idle as settled, read the pane output, and surface blocked for operator attention. Viewing a completed pane acknowledges Herdr's ephemeral unread done state and may change it to idle, so never wait only for done. The operator can focus the pane at any time to guide, interrupt, or resume the agent.

The interactive-agent-sessions skill defines the current version-verified non-prompting profiles: Claude bypasses permission prompts, while Codex suppresses approvals but retains an explicit read-only or workspace-write sandbox. These local profiles do not authorize publishing reviews, approving, merging, deleting remote branches, or any other protected remote mutation without explicit operator approval. Claude's bypass mode is not a host sandbox; the isolated worktree protects Git state, not the host, pending separate sandbox hardening.

GitHub issue and pull request workflow

GitHub issues are the durable mental model for work. Each implementation uses one bounded issue, one managed worktree, one semantic Herdr workspace, and independent or human review. A review keeps its own detached checkout but lives in a tab of that workspace, so one issue stays in one place on screen. That worktree delivers one pull request, or a stack of layer pull requests when the change is worth reading in several units.

Agents stop for Martin's judgment at consequential UI/UX decisions and bring a running preview to the question, rather than presenting a finished surface at the end. Accepting a design lets the agent keep implementing; committing, publishing, and merging stay separate authorizations. See Reviewable delivery.

The package includes reusable skills. Pi loads them through the package manifest, and Claude Code loads the same directory as a plugin named pi-clean when CLAUDE_CODE_PLUGIN_DIRS in the personal settings names the checkout, so a skill shows up as pi-clean:<name> in every Claude session:

  • experience-design-quality for emotionally fitting, distinctive, accessible experience design across product contexts.
  • interactive-agent-sessions for visible, focusable Claude, Codex, and Fable sessions with deterministic models, effort, permissions, prompts, and Herdr placement.
  • github-issues for Projects, issue hierarchy, dependencies, milestones, grooming, and human/agent readiness.
  • github-pull-requests for opening PRs, independent reviews, checks, merge preparation, and cleanup.
  • prose-quality for direct, natural human-facing prose that keeps technical meaning exact.
  • proton for Proton Pass CLI (pass-cli) work that keeps secrets out of agent context: session isolation, run and inject secret delivery, items, sharing, agent tokens, and the SSH agent. It covers pass-cli only.
  • react-composition-quality for maintainable React composition, render-ready data, and simple UI contracts.

The package also provides deterministic, read-only cross-repository issue grooming. User portfolio configuration lives in ~/.pi/agent/github-workflow.json (override with PI_GITHUB_WORKFLOW_CONFIG); the package never creates it during inspection. Use /github-add, /github-groom, or /github-daily, or run:

node scripts/github-planning.mjs snapshot <portfolio> --format json
node scripts/github-planning.mjs groom <portfolio>
node scripts/github-planning.mjs daily <portfolio>

See the deterministic issue-grooming guide and its placeholder-only configuration example.

Issue implementation and independent reviews run in isolated worktrees. Inside Herdr, issue author worktrees use Herdr's native linked-worktree lifecycle:

node scripts/github-work.mjs start-issue 123
node scripts/github-work.mjs review-pr 456 --reviewer codex
node scripts/github-work.mjs status
node scripts/github-work.mjs cleanup-pr 456
node scripts/github-work.mjs finish-issue 123 --delete-branch
node scripts/github-work.mjs profiles
node scripts/github-work.mjs launch-command --profile codex-sol-read --prompt 'Investigate the parser.'

Issue authors and reviewers default to the claude-opus profile. scripts/agent-profiles.mjs holds every model, effort, permission, and delegation setting; launch-command prints the exact command so skills and recipes do not retype flags. See Agent launch profiles for how a launch is rendered and Model selection for which model each profile pins.

Worktrees are stored outside project folders under ~/.local/share/agent-worktrees/github.com/<owner>/<repo>/. Outside Herdr, start-issue --agent none retains a direct-Git fallback; Herdr-managed issue work requires native worktree support in Herdr 0.7.3 or newer.

Set FLIGHTDECK_TELEMETRY_FILE to emit compatible worktree and agent-start events to Flightdeck's JSONL telemetry input. Repository-specific policy remains in each project's AGENTS.md. See the GitHub workflow guide for Project-based work admission, issue hierarchy, cognitive-budget limits, lifecycle, safety, Herdr, and Flightdeck details.

Structure

pi-clean/
├── extensions/agent-guard/ # Shell, path, and output safety guardrails
├── extensions/visual-design/ # PlateJS visual artifact relay
├── designs/                # Example repo-native visual artifacts
├── skills/                 # GitHub workflow, code-quality, and Proton Pass skills
├── .claude-plugin/         # Marks the checkout as a Claude Code plugin exposing skills/
├── scripts/                # GitHub issue/worktree helpers
└── prompts/                # GitHub issue-grooming shortcuts

License

MIT