PocketPal Dev Team
a-ghorbani/pocketpal-dev-team
Agentes Claude com pipeline estruturado para dev colaborativo e revisão em loop
Ver no GitHubFramework de agentes Claude para desenvolvimento colaborativo com pipeline de 4 estágios (Intent → WHAT → HOW → Implementation). Implementa revisão independente, crítica em loop e checkpoint humano, tudo em worktrees git isoladas. Ideal para times que precisam de governança estruturada em projetos de código.
Instalação
npx convez-ai a-ghorbani/pocketpal-dev-team1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automatizar ciclo de design → planejamento → implementação com crítica integrada
- Executar revisão independente de PRs sem intervenção manual intermediária
- Gerenciar complexidade de tarefas com exploração de múltiplas candidatas
Veredito

Solução madura e bem arquitetada para times que precisam de rigor em CI/CD de código. Pipeline explícito com crítica em loop (max 2 rounds) é robusto, mas exige investimento em configuração e compreensão profunda do fluxo para extrair máximo valor.
README
A tradução para o português deste README ainda está na fila.
PocketPal Dev Team
Starter Claude Code setup for PocketPal AI development. Includes agents, workflows, and templates - extend as needed.
How It Works
A four-stage pipeline — Intent → WHAT → HOW → Implementation — followed by an independent review loop and a human merge gate.
Issue / description
│
▼
┌──────────────┐ builds a self-contained intent-brief.md, classifies complexity
│ intake │ (trivial / quick / standard / complex), and stops with
└──────┬───────┘ NEEDS_INPUT if required answers are missing
│
│ complexity decides which design stages run:
│ • trivial → straight to implementer
│ • quick → planner only
│ • standard/complex → architect + planner
▼
┌──────────────┐ revise ┌───────────────────┐ WHAT (standard/complex): explore 2–3
│ architect │ ◄───────► │ architect-critic │ design candidates, then distill one
└──────┬───────┘ max 2 └───────────────────┘ what.md (exploration required for complex)
▼ rounds
┌──────────────┐ revise ┌───────────────────┐ HOW (quick/standard/complex): explore 2–3
│ planner │ ◄───────► │ plan-critic │ plan candidates, then distill one
└──────┬───────┘ max 2 └───────────────────┘ how.md (exploration required for complex)
▼ rounds
┌──────────────┐ code + commits + architecture-doc update
│ implementer │
└──────┬───────┘
▼
┌──────────────┐ tests + coverage
│ tester │
└──────┬───────┘
▼
┌──────────────┐ opens a DRAFT PR (REQUEST_CHANGES → back to implementer)
│ pipeline- │
│ reviewer │
└──────┬───────┘
▼
┌──────────────┐ /review-pr → workflows/reviews/PR-<n>/round-<N>/final.md
│ independent │ BLOCKER / CONCERN findings → PR-fix loop → back to implementer
│ review │ (max 2 external rounds, then escalate)
└──────┬───────┘
▼
HUMAN REVIEW & MERGE
Key Points:
- All work happens in isolated git worktrees — never touches the main branch directly
- Explore-then-distill: for complex work (and risky standard work), the architect and planner first sketch 2–3 candidate designs/plans, then synthesize a single
what.md/how.md; critics review only the distilled result - The pipeline keeps WHAT (design) and HOW (plan) separate, each gated by its own critic loop (max 2 rounds, then escalate)
- Independent review stays separate from the implementation agents; a human only steps in when the loops can't converge or a reviewer escalates
- Human checkpoint: PR review before merge
- Headless-safe invocation: every agent call is self-contained; missing information returns
NEEDS_INPUT - Each agent verifies its environment (worktree, branch, story context) before starting work
Getting Started
1. Clone with Submodules
git clone --recursive https://github.com/a-ghorbani/pocketpal-dev-team.git
cd pocketpal-dev-team
If you already cloned without --recursive:
git submodule update --init --recursive
2. (Optional) Use Your Own Fork
If you want to work with your own fork of pocketpal-ai:
cd repos/pocketpal-ai
git remote add myfork git@github.com:YOUR_USERNAME/pocketpal-ai.git
git fetch myfork
3. (Optional) Set Up Secrets for Native Builds
If you plan to run iOS/Android builds, copy your env and config files to the submodule. The worktree tooling will automatically copy these (via the allowlisted sync) into each worktree:
# Copy your secrets to repos/pocketpal-ai/
cp /path/to/your/.env repos/pocketpal-ai/
cp /path/to/your/e2e/.env repos/pocketpal-ai/e2e/
# iOS
cp /path/to/your/ios/.xcode.env.local repos/pocketpal-ai/ios/
cp /path/to/your/ios/GoogleService-Info.plist repos/pocketpal-ai/ios/
cp /path/to/your/ios/Config/Env.xcconfig repos/pocketpal-ai/ios/Config/
# Android
cp /path/to/your/android/local.properties repos/pocketpal-ai/android/
cp /path/to/your/android/app/google-services.json repos/pocketpal-ai/android/app/
These files are gitignored by pocketpal-ai, so they won't be committed.
4. Start a Task
/start-task #123 # Start from a GitHub issue
/start-task "Add feature X" # Start from a description
/start-task is the top-level delivery controller: it creates the worktree, runs the pipeline through a draft PR, then drives the independent review and any review-fix rounds.
When another agent or control plane drives this workflow, pass a self-contained brief in the prompt. Do not pass internal tracker IDs and expect the dev team to look them up. If required information is missing, intake stops with NEEDS_INPUT: instead of guessing.
Safety Guarantees
The dev team has built-in safeguards to prevent common mistakes:
| Protection | How It Works |
|---|---|
| Worktree Isolation | All work happens in worktrees/TASK-xxx/, never in pocketpal-ai directly |
| Branch Protection | Agents refuse to work on main/master - only feature branches |
| Native Build Verification | For native changes, agents MUST run pod install and actual builds |
| Pre-Flight Checks | Every agent verifies environment before starting work |
Workflow
Each stage produces a durable artifact and hands off to the next:
| Stage | Agent | Output |
|---|---|---|
| Intent | pocketpal-intake | workflows/stories/<TASK-ID>/intent-brief.md (or NEEDS_INPUT stop) |
| WHAT | pocketpal-architect | what.md (delta on context/architecture/<flow>.md) |
| WHAT review | pocketpal-architect-critic | LGTM / HAS_CONCERNS / HAS_BLOCKERS |
| HOW | pocketpal-planner | how.md |
| HOW review | pocketpal-plan-critic | LGTM / HAS_CONCERNS / HAS_BLOCKERS / ARCHITECTURE_DRIFT |
| Implementation | pocketpal-implementer | code + commits + architecture-doc update |
| Test | pocketpal-tester | tests + coverage |
| Final review | pocketpal-pipeline-reviewer | draft PR or REQUEST_CHANGES |
| Independent review | /review-pr + role reviewers | workflows/reviews/<TARGET-ID>/round-<N>/final.md |
Before drafting the final WHAT/HOW, the architect and planner can run a lightweight exploration pass — design-candidate-{A,B,C}.md / plan-candidate-{A,B,C}.md (the third only when a materially different option exists) — then distill exactly one contract artifact. Exploration is required for complex tasks and optional for risky standard tasks (competing architecture shapes, migrations, native/security changes, tricky sequencing). Critics review only the synthesized what.md/how.md, not the candidates.
Complexity, picked by intake, decides which stages run:
| Level | When | Pipeline applied |
|---|---|---|
| trivial | Single-file copy / config / typo / version bump (< 20 lines, no new contract) | Intent → Implementer |
| quick | 1–3 files, no contract change, existing flow doc covers the area | Intent → Planner → Plan-critic → Implementer |
| standard | Touches a contract (data model, persistence, wire format, rendering), multi-file | Full pipeline |
| complex | Cross-flow, new flow, architecture-changing | Full pipeline (both critic loops expected to use the full budget) |
See AGENTS.md for the full pipeline contract, critic-loop semantics, and non-negotiables.
Example Tasks
# Feature
/start-task "Add haptic feedback when sending messages"
# Bug fix
/start-task "Fix crash when loading large models on low-memory devices"
# From a GitHub issue
/start-task #123
# Self-contained brief (native - will run pod install + builds)
/start-task "Upgrade llama.rn from 0.12.0 to 0.12.1 to pick up the upstream structured-output fix. Keep the change limited to the dependency bump and required lockfile/native refresh. Verify with typecheck, the structured-output regression path, pod install, and iOS/Android native builds."
Agents
Pipeline agents (run in order by /start-task):
| Agent | Purpose |
|---|---|
pocketpal-intake | Entry point — builds the intent brief, classifies complexity, routes downstream |
pocketpal-architect | Produces what.md — the WHAT (design delta on the architecture library) |
pocketpal-architect-critic | Reviews what.md for design gaps; triggers revision if needed |
pocketpal-planner | Produces how.md — the HOW (step-by-step implementation plan) |
pocketpal-plan-critic | Reviews how.md; flags ARCHITECTURE_DRIFT back to the architect |
pocketpal-implementer | Writes code IN WORKTREE, runs platform builds for native changes |
pocketpal-tester | Writes and runs tests IN WORKTREE using PocketPal's testing patterns |
pocketpal-pipeline-reviewer | Quality gate — verifies builds + tests, opens the draft PR |
Review & support agents:
| Agent | Purpose |
|---|---|
pocketpal-code-reviewer | Independent review of a branch or PR (/review-pr), separate from the pipeline |
| Role reviewers | architect-reviewer, qa-reviewer, security-reviewer, performance-reviewer, mobile-reviewer, data-reviewer, ux-reviewer, local-invariants-reviewer, design-parity-reviewer — dimension-specific review lenses |
pocketpal-proposer / pocketpal-challenger | Propose / challenge technical solutions (used in /deliberate) |
Native Changes
When a task involves native dependencies (llama.rn, react-native-*, etc.):
- Intake flags
NATIVE_CHANGES: YES - Implementer runs
pod installand verifies iOS/Android builds - The pipeline reviewer independently verifies builds succeed before opening the PR
The dev team will NOT claim "build ready" without actually running builds.
Invoke Agents Directly
Normally you run the whole thing with /start-task. To drive a single stage yourself, pass the worktree, branch, and story context in the prompt:
# Just create a plan (no implementation)
claude "Use pocketpal-planner to create how.md for: Add dark mode support
WORKTREE: ./worktrees/TASK-20250115-1200
BRANCH: feature/TASK-20250115-1200"
# Implement an existing story
claude "Use pocketpal-implementer to implement story TASK-20250115-1200
WORKTREE: ./worktrees/TASK-20250115-1200
BRANCH: feature/TASK-20250115-1200
STORY: ./workflows/stories/TASK-20250115-1200/"
# Review a branch or PR independently
/review-pr 490
Note: When invoking pipeline agents directly (not through /start-task), you MUST provide the WORKTREE and BRANCH parameters. Agents will refuse to work without them.
Parallel Development
Since each task runs in its own git worktree, you can safely run multiple workstreams in parallel from the same directory. No need to clone the repo multiple times or set up separate folders - just open separate terminals:
# Terminal 1
/start-task "Add feature A"
# Terminal 2
/start-task "Fix bug B"
# Terminal 3
/start-task "Refactor component C"
Each task automatically creates an isolated worktree:
worktrees/
├── TASK-20250115-1430/ # Feature A
├── TASK-20250115-1431/ # Bug B
└── TASK-20250115-1432/ # Refactor C
No conflicts, no setup overhead - worktrees handle the isolation.
Autonomous Mode
Skip permission prompts for faster execution:
claude --dangerously-skip-permissions "/start-task <task>"
Safe commands are pre-allowed in .claude/settings.json. Dangerous commands (rm -rf, curl, .env access) are blocked.
Project Structure
pocketpal-dev-team/
├── repos/
│ └── pocketpal-ai/ # Git submodule - the target codebase
├── .claude/
│ ├── agents/ # Agent definitions with pre-flight checks
│ ├── skills/ # Slash command skills (/start-task, /review-pr, etc.)
│ └── settings.json # Permission rules
├── context/
│ ├── architecture/ # Cumulative architecture library (one doc per flow)
│ └── patterns.md # Coding & testing patterns
├── workflows/
│ ├── stories/ # Per-task artifacts (intent-brief / what / how)
│ └── reviews/ # Independent review output (final.md per round)
├── worktrees/ # Git worktrees for isolated development
├── templates/ # Artifact templates (intent / what / how / review)
├── tools/ # Utility scripts (create/remove-worktree.sh, etc.)
└── AGENTS.md # The full pipeline contract & non-negotiables
Key Files
context/patterns.md- Coding patterns (especially testing - read this!)workflows/stories/- Story files created by planner.claude/settings.json- Auto-approved commands
Tips
- Be specific — More detail in your task = better results
- Check the PR — The critic loops handle WHAT/HOW review; focus your attention on the final PR
- Check tests — PocketPal has specific testing patterns (centralized mocks)
- Trust the guards — Agents will refuse to work in wrong environments
- Native = slow — Tasks with native changes take longer (builds required)
When Reviews Find Issues
During PR review, you may find problems with the implementation:
| Issue Size | Action |
|---|---|
| Minor (typos, small tweaks) | Ask the agent to fix directly |
| Significant (wrong approach, missing requirements) | Update the story file, discard the PR, and re-run the workflow |
Why? The story file is the source of truth. For significant issues, patching the code leads to drift between the plan and implementation. It's cleaner to:
- Update the story with the correct approach
- Close/discard the current PR (or
git resetto before implementation) - Re-run from implementer with the updated story
This keeps the story accurate and ensures the implementation follows a proper plan.
Cleanup
After a task is merged, clean up the worktree with the allowlisted tool (never raw git worktree remove or rm -r):
./tools/remove-worktree.sh TASK-xxx --yes
Optional Features
| Feature | Requirement | Without It |
|---|---|---|
| Native iOS builds | Xcode + CocoaPods | Set NATIVE_CHANGES=NO or skip native tasks |
| Native Android builds | Android SDK + Gradle | Set NATIVE_CHANGES=NO or skip native tasks |
Requirements
- Claude Code CLI installed
- Git 2.20+ (for worktree support)
- Node.js 18+ (for PocketPal development)
- (Optional) Xcode 15+ for iOS builds
- (Optional) Android SDK for Android builds