# TrufflePit P.I.G. Farm - Vision Document

## Overview

P.I.G. Farm (Programmatic Intelligence Gateway Farm) is a Textual TUI screen that integrates the Claude Agent SDK with the Cleave task decomposition skill. It provides a visual interface for creating, managing, and executing complex directives through an interrogative workflow.

## Core Concept

The screen serves as a "farm" where directives (`.calf` files) are:
1. **Raised** - Created through interrogative dialogue with Claude
2. **Fattened** - Refined with Cleave parameters via UI controls
3. **Processed** - Executed through the Cleave skill for task decomposition

## Architecture

### SDK Integration

- Uses `claude-agent-sdk` Python API directly via `ClaudeSDKClient`
- Single shared chat session handles both interrogation and execution modes
- Session runs with `cwd` set to project directory for skill discovery
- Skills loaded via symlink or direct path injection if user-level skills not auto-discovered
- Authentication: Assumes `claude` CLI installed and authenticated; login flow triggered if needed

### File Format

`.calf` files are plaintext directive documents:
```
Implement user authentication with JWT tokens, ensuring backwards
compatibility with existing session-based auth. Include migration
path and tests.
```

No metadata, no structure. Just the raw instruction. Cleave parameters are configured via UI elements, not stored in the file.

## Screen Layout

```
┌─────────────────────────────────────────────────────────────────────┐
│  ████████╗██████╗ ██╗   ██╗███████╗███████╗██╗     ███████╗        │
│  ╚══██╔══╝██╔══██╗██║   ██║██╔════╝██╔════╝██║     ██╔════╝        │
│     ██║   ██████╔╝██║   ██║█████╗  █████╗  ██║     █████╗          │
│     ██║   ██╔══██╗██║   ██║██╔══╝  ██╔══╝  ██║     ██╔══╝          │
│     ██║   ██║  ██║╚██████╔╝██║     ██║     ███████╗███████╗        │
│     ╚═╝   ╚═╝  ╚═╝ ╚═════╝ ╚═╝     ╚═╝     ╚══════╝╚══════╝        │
│                     P.I.G. Farm                                     │
│            Programmatic Intelligence Gateway                        │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌─ sL̶aughter House ─────────────┐  ┌─ Slop Trough ──────────────┐ │
│  │                               │  │                             │ │
│  │  ┌─ Cleaver ───────────────┐  │  │  .calf files:               │ │
│  │  │                         │  │  │  ┌─────────────────────────┐│ │
│  │  │  Load: [dropdown    ▼]  │  │  │  │ ○ auth-migration.calf   ││ │
│  │  │                         │  │  │  │ ● api-refactor.calf     ││ │
│  │  │  ☐ Parallel execution   │  │  │  │ ○ test-coverage.calf    ││ │
│  │  │  ☐ Dry run              │  │  │  └─────────────────────────┘│ │
│  │  │  Max depth: [3      ]   │  │  │                             │ │
│  │  │  Model: ○ Sonnet        │  │  │  Preview:                   │ │
│  │  │         ● Opus          │  │  │  ┌─────────────────────────┐│ │
│  │  │         ○ Haiku         │  │  │  │ Refactor the API layer  ││ │
│  │  │                         │  │  │  │ to use async handlers...││ │
│  │  └─────────────────────────┘  │  │  └─────────────────────────┘│ │
│  │                               │  │                             │ │
│  │  ┌─────────────────────────┐  │  │  ┌─────────────────────────┐│ │
│  │  │  🔪 CLEAVE              │  │  │  │  Perform Calf Raises    ││ │
│  │  └─────────────────────────┘  │  │  └─────────────────────────┘│ │
│  └───────────────────────────────┘  └─────────────────────────────┘ │
│                                                                     │
│  ┌─ Chat ───────────────────────────────────────────────────────┐  │
│  │ Claude: I'll help you define this directive. What system or  │  │
│  │ feature are you looking to work on?                          │  │
│  │                                                               │  │
│  │ You: I need to refactor the authentication layer to support  │  │
│  │ both JWT and session-based auth simultaneously.              │  │
│  │                                                               │  │
│  │ Claude: Good. Let me clarify a few things:                   │  │
│  │ 1. Should existing sessions remain valid during migration?   │  │
│  │ 2. What's the target timeline for deprecating sessions?      │  │
│  │ ...                                                          │  │
│  ├──────────────────────────────────────────────────────────────┤  │
│  │ > _                                                          │  │
│  └──────────────────────────────────────────────────────────────┘  │
│                                                                     │
│  ┌─ Progress ───────────────────────────────────────────────────┐  │
│  │ ████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  3/12 subtasks     │  │
│  │ Current: Implementing JWT token validation middleware        │  │
│  └──────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘
```

## Components

### 1. Banner
- TrufflePit P.I.G. Farm ASCII art header
- Generated during implementation (box-drawing chars, phosphex-themed)

### 2. sLaughterHouse Panel
Title rendered with strikethrough on 'S' to emphasize "Laughter House"

**Cleaver Sub-panel:**
- File picker dropdown for `.calf` files
- Checkbox: Parallel execution
- Checkbox: Dry run
- Number input: Max depth
- Radio group: Model selection (Sonnet/Opus/Haiku)
- "CLEAVE" button with butcher knife emoji/motif

### 3. Slop Trough Panel
- List widget showing `.calf` files in working directory
- Preview pane showing selected file contents
- "Perform Calf Raises" button - initiates interrogative flow

### 4. Chat Panel
- Shared session for both modes
- Scrollable message history with Claude/User differentiation
- Input field at bottom
- Mode indicated by context (interrogation vs execution output)

### 5. Progress Panel
- Progress bar showing rough completion estimate
- Current subtask text display
- Polls TodoWrite state or streams Cleave output

## Workflow

### Creating a Directive (Calf Raises)

1. Operator clicks "Perform Calf Raises" in Slop Trough
2. Chat panel enters interrogation mode
3. Claude asks clarifying questions about the desired work
4. Operator responds iteratively
5. Claude synthesizes responses into a clear directive
6. Directive saved as `.calf` file
7. File appears in Slop Trough list

### Executing a Directive (Cleave)

1. Operator selects `.calf` file in sLaughterHouse dropdown
2. Operator configures Cleave parameters via UI widgets
3. Operator clicks "CLEAVE" button
4. Chat panel shows Cleave skill output
5. Progress bar updates based on subtask completion
6. On completion, results displayed in chat

## Technical Decisions

### SDK vs CLI Subprocess
**Decision:** Use `ClaudeSDKClient` directly

**Rationale:**
- Cleaner integration, no output parsing
- Direct access to message streams
- Better error handling
- Avoids process management complexity

### Skill Discovery
**Decision:** Spike during implementation

**Options to explore:**
1. SDK auto-discovers `~/.claude/skills/`
2. Symlink Cleave skill into project `.claude/skills/`
3. Inject skill instructions via `system_prompt`

Document findings and chosen approach.

### Session Management
**Decision:** Single shared session

**Rationale:**
- Simpler state management
- Context preserved across interrogation and execution
- Mode switching is implicit (user intent drives behavior)

### Progress Tracking
**Decision:** Stream Cleave output + TodoWrite polling

**Implementation:**
- Capture assistant messages containing progress updates
- Optionally poll `~/.claude/todos/` for structured state
- Render as simple progress bar + current task text

## Theming

Inherit existing styrene-tui theming system:
- Use phosphex color cascade
- HighlightedPanel for sectioned content
- Semantic symbols for status indication
- CSS variables, no hardcoded colors

## File Structure

```
styrene-tui/src/styrene/
├── screens/
│   └── pigfarm.py           # Main screen
├── widgets/
│   ├── cleaver_panel.py     # sLaughterHouse + Cleaver
│   ├── slop_trough.py       # .calf file management
│   ├── chat_panel.py        # SDK chat interface
│   └── progress_panel.py    # Execution progress
└── services/
    └── sdk_session.py       # ClaudeSDKClient wrapper
```

## Dependencies

Add to styrene-tui:
```toml
dependencies = [
    # ... existing ...
    "claude-agent-sdk>=0.1.0",
]
```

## Open Questions (Resolve During Implementation)

1. Does SDK discover user-level skills automatically?
2. Optimal progress polling interval?
3. ASCII art style for banner?
4. Keyboard shortcuts for common actions?

## MVP Acceptance Criteria

- [ ] Screen loads with banner and all panels visible
- [ ] Can list and preview existing `.calf` files
- [ ] "Perform Calf Raises" starts interrogation in chat
- [ ] Chat interaction works bidirectionally with Claude
- [ ] Can save interrogation result as new `.calf` file
- [ ] Can load `.calf` file in sLaughterHouse
- [ ] Cleave parameter widgets functional
- [ ] "CLEAVE" button executes directive through Cleave skill
- [ ] Progress bar shows execution status
- [ ] Theming consistent with styrene-tui
