convez.ai
MCP Server
lebobo88

pair-programmer

lebobo88/pair-programmer

Ver no GitHub
InicialPluginScore · de 0 a 100

Multi-agent coding harness: Claude Code drives Codex and Gemini sub-agents with taxonomy-driven artifacts, cross-vendor judging, and a TypeScript MCP daemon.

Instalação

$npx convez-ai lebobo88/pair-programmer

1 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

Estrelas
8
Forks
1
Acompanhando
0
Saúde
28%
Último commit
há 1 semana
Versão
—
Issues abertas
36
Contribuidores
3

README

A tradução para o português deste README ainda está na fila.

pair-programmer

Multi-agent coding harness with tiered model validation, taxonomy enforcement, and best-of-N generation.

A TypeScript daemon that orchestrates code generation across Claude, OpenAI Codex (GPT), and Google Gemini with tiered validation:

  • Critical gates (spec, design, security, contracts) → judged by a different vendor from the generator
  • Lower-stakes gates (code style, docs, lint) → judged by a different model from the same vendor (Codex same-vendor upgrades to cross-vendor when the generator used GPT-5.4; Gemini may fall back to same-model when no alternative exists)

Supports Claude Code and GitHub Copilot CLI as entrypoints. Enforces a 16-section software development taxonomy on every task.

Architecture diagrams (C1 system context, C2 containers, run lifecycle, C3 subsystems, and the judging concepts) live in ARCHITECTURE.md as native Mermaid blocks with ASCII fallbacks.

%%{init: {'theme':'dark'}}%%
graph LR
    CC["Claude Code / Copilot CLI"] --> H["pp-daemon"]
    H --> HARNESS["pp_harness (75 tools)"]
    H --> CODEX["pp_codex → Codex CLI"]
    H --> GEMINI["pp_gemini → Gemini CLI"]
    H --> HTTP["HTTP control plane<br/>127.0.0.1:7878"]
    H --> DB[("SQLite ~/.pp-harness")]

How It Works

pair-programmer wraps a structured lifecycle around every coding task — from a one-line bug fix to a multi-stage feature build. The daemon manages state, routes generation to sub-agents, and gates artifacts through tiered judging (cross-vendor for critical gates, same-vendor-different-model for code/docs) before they ship.

The full nine-phase run lifecycle (triage → profile → taxonomy → stage loop → missability → master-plan patch → finalize) is diagrammed as a stateDiagram-v2 in ARCHITECTURE.md §3.

Key Concepts

ConceptWhat it does
16-Section TaxonomyEvery task maps to sections of taxonomy_blueprint.md — discovery, spec, architecture, contracts, code, security, tests, docs, and more. The harness ensures no section is skipped when the profile requires it.
Tiered JudgingSpec/design/security/contract gates require a different vendor from the generator (Claude generates → Codex or Gemini judges). Code/docs/lint gates use a different model from the same vendor (Codex same-vendor is conditional — upgrades to cross-vendor when the generator used GPT-5.4). A degenerate same-model fallback exists for Gemini when no alternative is available.
Reflexion ×1On judge failure, the critique is fed back to the generator for exactly one retry. If it fails again, the stage surfaces for human review. Maximum 6 validator calls per run.
Best-of-N + Borda CountFor major-scope requests, fan out to N parallel candidates (different model/seed mix in isolated git worktrees). A tournament judge picks the winner via Borda count + diff-entropy analysis.
Missability GatesBefore finalization, 56 checks verify non-functional requirements: authorization models, data retention, rollout reversibility, accessibility, console cert compliance, and more.
PROJECT_MASTER.mdA 20-section living document auto-scaffolded per project and patched by every finalized run — accumulates architecture decisions, API contracts, threat models, and operational runbooks over time.
sequenceDiagram
    participant U as User
    participant H as Harness
    participant G as Generator (Claude/Codex/Gemini)
    participant J as Cross-Vendor Judge
    U->>H: /pp:run "request"
    H->>H: Triage → Profile Detect → Taxonomy Map
    loop Stage Loop (spec → arch → code → tests → docs)
        H->>G: Generate artifact
        H->>J: Validate (tiered: cross-vendor or same-vendor)
        alt Pass
            H->>H: Archive artifact
        else Fail
            H->>G: Reflexion retry (critique fed back)
            H->>J: Re-judge (1 retry max)
        end
    end
    H->>H: Missability gates (56 checks)
    H->>H: Patch PROJECT_MASTER.md
    H->>U: Finalize (complete | surfaced)

Ecosystem Integration

pair-programmer operates as the engineering squad within a larger multi-agent ecosystem. It works fully standalone, but gains cross-squad coordination, persistent memory, and governance enforcement when connected to sibling services. See the C1 system-context diagram in ARCHITECTURE.md §1.

SystemRoleIntegration
HydraMulti-squad LangGraph supervisorDispatches DevTask envelopes to pair-programmer; receives DECISION_RECORD replies. Bidirectional via TheEights envelope store.
TheEightsMemory fabric + evolution daemonStores episodic memory (runs, verdicts, artifacts), serves prior critiques for cross-run Reflexion, manages evolution proposals, and provides the audit chain.
AgentSmithMeta-governance + invariant enforcementValidates pair-programmer's .claude/ artifacts against 10 immutable invariants. Schema inspection, quarantine on drift, constitutional attestation.
ExecutiveSuiteC-Suite decision supportReceives CSuiteDecisionPacket envelopes for strategic framing on major-tier enterprise/AI requests. Advisory, not blocking.
RLM-CreativeBrand & visual workflowsReceives CreativeBrief envelopes for visual-direction-advisory on UX surfaces. Advisory.
MarketBlissMarketing strategy & brand voiceReceives CreativeBrief envelopes for brand-voice-check on customer-facing copy. Advisory.
SenatePhD-level legal wing — "the Curia"A sibling Hydra squad (legal-compliance): 12 jurists (9 primary + 3 consilium) under the Twelve Tables, resolving conflict by the Law of Citations (Papinian breaks ties; dissents preserved) gatekept by the Tribune's Veto (HITL). Coordinates with pair-programmer through Hydra, not directly. Active.
XeniaCustomer-support — "the Hearth"A sibling Hydra squad (customer-support): an 11-agent crew for ticket triage, recommendation, VoC, and approval-gated execution with WS-AUTH capability enforcement. Coordinates with pair-programmer through Hydra, not directly. Active.
AgentMeshBinding control plane (the tenth layer)The thin, governed control plane that unifies all nine sibling systems behind ONE registry (~/.agentmesh/state.db; sole writer of ~/.hydra/backends.json), ONE lifecycle supervisor (Win32 Job Objects + crash-loop breaker + health probes), ONE audit timeline, ONE protocol edge (A2A / REST / MCP-over-HTTP), and ONE operator console. pair-programmer enrolls by shipping mesh-manifest.yaml (fail-closed: JSON-Schema + constitution attestation + AgentSmith inspection). AgentMesh routes and observes but enforces no governance of its own — authority stays TheEights → AgentSmith → Hydra.

Graceful degradation: pair-programmer operates fully standalone when ecosystem services are offline — cross-run memory, advisory envelopes, and evolution proposals degrade to no-ops, but the core generation/judging/missability lifecycle is unaffected. All external calls are null-tolerant with circuit breakers; the daemon never blocks on a peer that isn't responding.


Quick Start

Prerequisites

  • Node.js 20+ and npm
  • Git (worktrees used for best-of-N isolation)
  • At least one external CLI for cross-vendor judging:
    • Codex CLI: npm i -g @openai/codex + OPENAI_API_KEY
    • Gemini CLI: npm i -g @google/gemini-cli + GEMINI_API_KEY

Build

cd daemon
npm install
npm run build

First Run (Claude Code)

# Health check — confirms CLIs, DB, vendor matrix
/pp:doctor

# Single-agent run with cross-vendor judge
/pp:run "add input validation to the signup handler"

# Best-of-3 with Borda count winner selection
/pp:best-of 3 "refactor the payment module for testability"

# Specialized team pipeline
/pp:team feature-team "implement dark mode toggle"

The MCP servers register automatically via .mcp.json. Restart Claude Code after cloning so the new servers load.

Environment Variables

VariablePurpose
OPENAI_API_KEYCodex CLI authentication (or use codex login)
GEMINI_API_KEYGemini CLI authentication (or use gemini auth)

Cross-vendor gates require two configured vendors. The SessionStart.vendor-matrix hook warns if only one is available.


Capabilities

CategoryCountHighlights
MCP Tools7975 on pp_harness (orchestration, taxonomy, gates, best-of-N, replay, janitor) + 2 on pp_codex + 2 on pp_gemini
Sub-Agents75engineer, architect, judge-cross-vendor, security-reviewer, designer, game-ai-programmer, live-ops-manager, and 68 more
Slash Commands19/pp:run, /pp:best-of, /pp:team, /pp:review, /pp:constitution, /pp:evolution, and 13 more
Teams25feature, bug-fix, refactor, security-review, ux, design-system, deep-reasoning (Fable-5), game-cert, game-live-ops, and 16 more
Profiles16web-ui, api-platform, enterprise, ai-agentic, mobile, game-dev-unity, game-dev-unreal, and 9 more
Rubrics25WCAG 2.2 AA, OWASP ASVS L1/L2, C4, OpenAPI 3.1, SLSA L2/L3, NIST AI RMF, Game Accessibility Guidelines, and 17 more
Hooks29across 5 events (SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, Stop): block-destructive-shell, cost tallying, vendor-matrix check, +3 TheEights recall hooks, and 23 more (26 wired in settings.json, all 29 in hooks.json)
Missability Checks5623 generic (NFRs, authz, data retention) + 33 game-dev (console TRC, netcode, live-service, accessibility)
Skills8pair-programmer master skill, taxonomy-adherence, master-plan-patching, game-design, frontend-design, and 3 more

Commands

CommandDescription
/pp:run "<request>"Single-agent generation + tiered cross-vendor judge
/pp:best-of N "<request>"N-way parallel fan-out with Borda count winner
/pp:team <name> "<request>"Run through a specialized team pipeline
/pp:review <forum>Run one of 10 governance review forums
/pp:retry <run_id>Reflexion ×1 retry on a surfaced stage
/pp:gate <stage_id>Re-run only the judge step (no regeneration)
/pp:status [run_id]List runs or show full run tree
/pp:budget [scope]Token + dollar totals by run / day / model
/pp:doctorFull health-check (daemon, CLIs, vendors, DB)
/pp:taxonomy [run_id]Show 16-section coverage for a run
/pp:masterView or scaffold PROJECT_MASTER.md
/pp:checklist15-item completion check (Section 10)
/pp:profile [show|list|template]View active profile or render a built-in template
/pp:rubrics [list|show <id>]List rubrics or show rubric body
/pp:teamsList available specialized teams
/pp:replay <run_id>Reproduce-bundle for a past run
/pp:claudemdShow/scaffold AGENTS.md + CLAUDE.md
/pp:constitutionView or amend CONSTITUTION.md
/pp:evolutionList/review autogenesis evolution proposals

Full reference: docs/USER_GUIDE.md covers every command, agent, team, profile, rubric, forum, hook, MCP tool, and the security/trust model.


Installation Options

Option A: System-wide (recommended)

Register once at user scope so /pp:* commands, MCP servers, hooks, agents, and skills are available in every Claude Code session:

.\scripts\install-user.ps1

Updates with git pull — no reinstall needed (uses NTFS junctions).

Option B: Per-project

Copy or symlink .claude/ into your project, or run Claude Code from this repo directly.

Option C: GitHub Copilot CLI

.\scripts\install-user-copilot.ps1
copilot --agent pair-programmer-orchestrator

Installs as a Copilot CLI plugin for the current user. Re-run after git pull (Copilot caches plugin contents). See docs/INSTALL.md for details.


Project Layout

pair-programmer/
  daemon/                         # TypeScript daemon (MCP + SQLite + orchestration)
    src/
      mcp/                        # 3 MCP servers: harness (75 tools), codex (2), gemini (2)
      orchestrator/               # runs, gates, taxonomy, missability, best-of-n, profiles, teams, forums
      ecosystem/                  # TheEights client, Hydra envelopes
      rubrics/                    # 25 standard-aligned rubric definitions
      hooks/                      # hook dispatcher + bash-safety (29 hooks / 5 events)
      security/                   # untrusted-envelope wrapping, secret-scan
      http/                       # read-only control plane (127.0.0.1:7878)
      db/                         # SQLite schema + WAL connection pool
    test/                         # smoke tests (MCP roundtrip)
    package.json
  .claude/
    agents/                       # 75 sub-agent definitions
    commands/pp/                  # 19 slash commands
    teams/                        # 25 specialized team pipelines (incl. deep-reasoning-team)
    profiles/                     # 16 project profile templates
    rubrics/                      # rubric markdown mirrors
    skills/                       # 8 domain skills
    settings.json                 # permissions + 26 hook commands (hooks.json adds 3 eights-recall → 29)
  .github/                        # generated Copilot CLI assets
  docs/
    USER_GUIDE.md                 # full reference guide
    INSTALL.md                    # installation details
  ARCHITECTURE.md                 # C1-C3 + lifecycle Mermaid/ASCII diagrams
  taxonomy_blueprint.md           # 16-section taxonomy (the blueprint)
  .mcp.json                       # MCP server registration (stdio)
  plugin.json                     # Copilot CLI plugin manifest
  hooks.json                      # Copilot CLI hook file

State: ~/.pair-programmer/state.db (SQLite WAL) | Logs: ~/.pair-programmer/logs/ | Artifacts: <project>/.harness/<run_id>/


Hardening & Configuration

Env varEffect
PP_ENFORCE_ACTIVE_RUN=1PreToolUse hook hard-blocks Edit/Write outside an active run
PP_ALLOW_DANGER=1Allows --sandbox=danger-full-access on Codex calls (off by default)
PP_LOG_LEVEL=debugVerbose pino logs
PP_DEBUG=1Include stack traces in MCP error responses
PP_STRICT_AGENT_TYPE=1Reject record_attempt calls with agent_type='general-purpose'

Testing

cd daemon
npm run typecheck          # TypeScript strict mode
npm run build
node test/smoke.mjs        # end-to-end MCP roundtrip checks

Related Projects

ProjectDescriptionLink
HydraMulti-squad LangGraph supervisor — routes work across engineering, executive, creative squadsgithub.com/lebobo88/Hydra
TheEightsMemory fabric + evolution daemon — episodic store, governance plane, artifact evolutiongithub.com/lebobo88/TheEights
AgentSmithMeta-governance — 10 immutable invariants, factory/inspector/sentinel/archivistgithub.com/lebobo88/AgentSmith
ExecutiveSuiteC-Suite decision support — boardroom orchestrator, 20 executive personasgithub.com/lebobo88/ExecutiveSuite
RLM-CreativeBrand & visual creative workflows — visual-direction-advisory for UX surfacesgithub.com/lebobo88/RLM-Creative
MarketBlissMarketing strategy & brand voice — brand-voice-check for customer-facing copygithub.com/lebobo88/MarketBliss

Documentation

  • ARCHITECTURE.md — Architecture diagrams (C1 context, C2 containers, run lifecycle, C3 subsystems) + judging concepts, as Mermaid with ASCII fallbacks
  • docs/USER_GUIDE.md — Canonical reference (commands, agents, teams, profiles, rubrics, forums, hooks, MCP tools, security model)
  • docs/INSTALL.md — Installation options and prerequisites
  • docs/troubleshooting.md — Common issues and solutions
  • taxonomy_blueprint.md — The 16-section software development taxonomy

License

MIT

Ver o original no GitHub

Bom para

Relacionados