PIS: Claude Code CLI-First Architecture

Brainstorming session — transforming PIS from user-driven to AI-agent-driven platform

The Paradigm Shift

Current: User-Driven
User
→
PIS UI
→
Chat Claude (API)
↓ separate, disconnected
User
→
PIS UI
→
Terminal Claude (CLI)
Problem: Two Claudes that don't talk. Terminal is a dumb pipe. User manually orchestrates everything. PIS can't see what CLI does.
Proposed: CLI-First
Claude Code CLI
↔
MCP (full access)
↔
PIS Platform
↓ pulls in at key moments
PIS
→
User (approve / guide)
Shift: CLI is the primary operator. PIS becomes its workspace API. User is the decision-maker, not the driver.

Decision #1: Orchestration Model

Chosen: B — PIS as Orchestrator

Architecture
PIS (container)
→
Host Agent
→
claude CLI (host)
PIS decides what to build Spawns & monitors Full VPS access: git, docker, fs, plugins, hooks
Key insight: CLI runs on the host, not inside Docker. Gets full access to the VPS ecosystem — git repos, Docker socket, file system, Claude plugins, skills, MCP servers, worktrees. PIS manages the lifecycle via a lightweight host agent.

PIS Container

  • Holds project state (canvas, docs, tickets)
  • Exposes rich MCP server
  • Decides build order & assigns work
  • Sends commands to Host Agent
  • Shows user dashboards & approval gates

Host Agent new

  • Lightweight daemon on VPS host
  • Spawns claude CLI processes
  • Streams output back to PIS
  • Monitors process health
  • Manages CLAUDE.md + .mcp.json per session

Claude CLI Sessions

  • Run as real host processes
  • Full system access
  • Connect to PIS MCP for project state
  • Report progress via MCP tools
  • Can spawn worktrees for isolation

Decision #2: Autonomy Model

Chosen: D — Maximum Autonomy

AI Self-Governs, User Reviews Async

AI Handles Autonomously

  • Plan execution & task ordering
  • Code generation & testing
  • Spawning parallel sessions
  • Git operations (commit, branch, worktree)
  • Docker builds & deployments
  • Bug fixing & iteration
  • Phase transitions (Define → Ship)
  • Resource creation & deletion
boundary

User Pulled In When...

  • AI is stuck (3+ failed attempts)
  • Critical design fork (2+ valid paths)
  • Spec ambiguity (can't infer intent)
  • External dependency needed (API keys, DNS, etc.)
User reviews progress async via PIS dashboard. No blocking gates.
Live document — this page updates as the brainstorm progresses. Refresh to see new sections.