PITER Setup

Guide for setting up the PITER framework elements to enable AFK (Away From Keyboard) agent systems.

When to Use

• Configuring GitHub as prompt input source

• Setting up webhook or cron triggers

• Preparing a dedicated agent environment

• Designing the review process

• Moving from in-loop to out-of-loop agentic coding

PITER Overview

Element Question Common Implementation

P Where do tasks come from? GitHub Issues

I What type of work is this? LLM Classification

T When does work start? Webhooks / Cron

E Where do agents run? Dedicated VM/Sandbox

R How is work validated? Pull Requests

Setup Workflow

1. Configure Prompt Input (P)

GitHub Issues Setup

Verify GitHub CLI is authenticated

gh auth status

Test issue creation

gh issue create --title "Test Issue" --body "Testing ADW prompt input"

Test issue fetching

gh issue view 1 --json title,body,labels

Issue structure becomes the prompt:

Title: Add user authentication Body: We need OAuth with Google provider... Labels: feature, priority-high

→ Becomes: "/feature Add user authentication..."

2. Configure Classification (I)

Create /classify-issue command:

Issue Classification

Analyze the issue and respond with exactly one of:

• /chore - for maintenance, updates, cleanup
• /bug - for defects, errors, unexpected behavior
• /feature - for new functionality

Issue

$ARGUMENTS

Test classification:

claude -p "/classify-issue 'Fix login button not working'"

Expected: /bug

claude -p "/classify-issue 'Update dependencies'"

Expected: /chore

3. Configure Trigger (T)

Option A: Cron Polling

trigger_cron.py (simplified)

import time

POLL_INTERVAL = 20 # seconds

while True: issues = get_unprocessed_issues() for issue in issues: run_adw(issue.number) time.sleep(POLL_INTERVAL)

Unprocessed = no comments OR latest comment is "adw"

Option B: Webhook

trigger_webhook.py (simplified)

from flask import Flask, request

app = Flask(name)

@app.route("/gh-webhook", methods=["POST"]) def handle_webhook(): event = request.json if is_new_issue(event): run_adw(event["issue"]["number"]) return "OK"

Webhook setup:

• Set up tunnel (ngrok/cloudflare)

• Configure webhook in GitHub repo settings

• Select events: Issues, Issue comments

4. Configure Environment (E)

Environment checklist:

Verify Claude Code

claude --version

Verify API key

echo $ANTHROPIC_API_KEY | head -c 10

Verify GitHub access

gh auth status

Verify repository

git remote -v

Test templates

claude -p "/chore test" --dry-run

Create .env file (never commit):

ANTHROPIC_API_KEY=sk-ant-... GITHUB_TOKEN=ghp_... CLAUDE_CODE_PATH=claude

5. Configure Review (R)

PR-based review:

Test PR creation

gh pr create
--title "Test PR"
--body "Testing ADW review process"
--base main
--head feature-test

Branch protection (recommended):

• Require pull request reviews

• Require status checks to pass

• Require linear history

Validation Checklist

Prompt Input (P)

• GitHub CLI authenticated

• Can create issues

• Can fetch issue details

• Issue format understood

Classification (I)

• /classify-issue command works

• Correctly classifies chores

• Correctly classifies bugs

• Correctly classifies features

Trigger (T)

• Trigger method chosen (cron/webhook)

• Trigger script running

• Events detected correctly

• ADW invoked on trigger

Environment (E)

• Dedicated environment available

• API keys configured

• Claude Code accessible

• Templates tested

• Permissions configured

Review (R)

• PR creation works

• Issue linking works

• Branch protection configured

• Review process documented

Quick Test Workflow

1. Create test issue

gh issue create --title "Test: Update README" --body "Add installation section"

2. Manually run ADW

python adws/adw_plan_build.py <issue_number>

3. Verify PR created

gh pr list --state open

4. Review and close

gh pr view <pr_number>

Common Issues

Authentication Failures

Refresh GitHub auth

gh auth login

Verify API key

curl -H "x-api-key: $ANTHROPIC_API_KEY"
https://api.anthropic.com/v1/models

Webhook Not Receiving

• Check tunnel is running

• Verify webhook URL in GitHub settings

• Check webhook secret matches

• Look at GitHub webhook delivery logs

Classification Accuracy

• Improve prompt with examples

• Add edge case handling

• Consider multi-label issues

Related Memory Files

• @piter-framework.md - Full PITER reference

• @adw-anatomy.md - ADW structure

• @outloop-checklist.md - Deployment checklist

Version History

• v1.0.0 (2025-12-26): Initial release

Last Updated

Date: 2025-12-26 Model: claude-opus-4-5-20251101