junjak-ai-harness

AI Harness — Multi-Agent Team Workflow

A reusable Claude Code harness for Claude Opus: a 5-phase multi-agent team workflow (TDD, escalation loops, worktree parallelization) plus a full testing stack, a document-storage system, code-minimalism discipline, and instinct-based learning.

Overview

Specialized AI agents collaborate through defined phases to implement features, fix bugs, or refactor code. Beyond the core team workflow, the harness adds:

• Testing stack — unit (Vitest) → deterministic E2E (Playwright) → agentic E2E (Phase 4.5: an agent verifies goals and crystallizes deterministic tests) → human QA (/test-scenario-doc, an interactive checklist).
• Document storage (3 buckets) — _docs/ (project, lifecycle-managed) · _note/ (human-owned, agent read-only) · .claude/wiki/ (an agent-maintained LLM wiki that compounds knowledge), classified by a portable ownership discriminator.
• Code minimalism — the ponytail YAGNI decision ladder, applied at design time and reviewed in Phase 4.
• Instinct-based learning — continuous-learning captures atomic, confidence-scored, project-scoped instincts that evolve into skills / commands / agents.
• Ultracode orchestration — when enabled, fan-out phases run via the Workflow tool.

Team Roles

Role	Agent	Model	When Called
Team Leader	team-leader	opus	Always (Phase 1, Gate, Escalation)
Architect A (Frontend)	team-architect-fe	opus	Phase 1 (parallel with B)
Architect B (Backend)	team-architect-be	opus	Phase 1 (parallel with A)
Architect C (Infra/Security)	team-architect-infra	opus	Phase 1 (on-demand) + Phase 5 (always)
UI/UX Master	team-uiux-master	sonnet	Phase 2 (conditional)
Designer x N	team-designer	opus	Phase 3 (parallel, worktree isolated)
Tester x N	team-tester	sonnet	Phase 4 (parallel)
Agentic Tester	team-agentic-tester	opus	Phase 4.5 (conditional, after Tester PASS)
Web Architect	web-architect	opus	Web architecture (standalone or complements FE)
Web Reviewer	web-reviewer	sonnet	Web quality audit (a11y, CWV, SEO, AI-slop)

Workflow Phases

Phase 1: Planning
  Leader drafts plan → Arch A + B detail (parallel) → Cross-review → File assignment

Phase 2: UI/UX (conditional)
  UI/UX Master reviews and proposes changes

Leader Approval Gate
  Approve → Phase 3 | Reject → Phase 1

Phase 3: Implementation (TDD)
  Designer x N in parallel worktrees (Red-Green-Refactor)

Phase 4: Verification
  Tester x N (unit + E2E, loop until pass)

Phase 4.5: Agentic Testing (conditional)
  Agent explores goals → verifies → crystallizes deterministic tests
  (then human QA via /test-scenario-doc, before final sign-off)

Phase 5: Final Security Review
  Arch C security & infra audit → SHIP or escalate

Escalation

• Each agent self-judges: simple fix (retry, max 3) vs fundamental issue (escalate up)
• Global re-plan limit: 3 cycles to prevent infinite loops
• Both /team and /team-run report escalation events to user

Commands

Command	Description
/team-init	Analyze project → generate profile (run first!)
/team	Interactive mode — user participates in planning phase
/team-run	Autonomous mode — full auto-execution
/team-brainstorm	Planning only — Leader + Architects discuss, no implementation
/test-scenario-doc	On-demand human QA checklist HTML (human acceptance layer)

Installation (Plugin)

This harness is distributed as a Claude Code plugin.

# 1. Add the marketplace
/plugin marketplace add JunjaK/ai-harness

# 2. Install the plugin
/plugin install junjak-ai-harness@ai-harness

Required User Configuration

The plugin manifest cannot set environment variables or permissions. Add to your user or project settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "60"
  },
  "permissions": {
    "allow": [
      "Edit",
      "Write",
      "LSP",
      "Bash(git *)",
      "Bash(ls *)",
      "Bash(mkdir *)",
      "Bash(bun *)",
      "Bash(bunx *)",
      "Bash(pnpm *)",
      "Bash(npx *)"
    ]
  }
}

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is required — /team, /team-run, /team-brainstorm depend on TeamCreate for cross-review.

CLAUDE_HARNESS_ULTRACODE=1 is optional — an explicit override that forces ultracode orchestration (Workflow-tool fan-outs) in headless / non-Claude-Code contexts where the runtime ultracode signal is absent. See CLAUDE.md "Ultracode Orchestration".

Dependencies