java-harness-agent

Enforces format rules + Pre-Creation Protocol for Skill, Sub-agent, Rule files. TRIGGER: create any of them. NOT FOR: WHETHER to create (use skill-author), registration (use skill-graph-manager).

Governs WAL fragment writes (domain/api/rules/data/architecture) at Archive. TRIGGER: STANDARD Archive, dimensions elected via h-archive. NOT FOR: PATCH; wiki authoring (use documentation-curator).

Runs one-round adversarial critique. TRIGGER: HIGH-risk STANDARD — Explorer (Cat A), Propose/Review (Cat B/C). NOT FOR: code review (use code-reviewer); PATCH; >1 round per category.

Orchestrate the repo-aligned AI engineering pipeline (plan → decisions → eval → improve → cleanup → verify → archive) with explicit approval gates. TRIGGER when user asks to run the full pipeline or go from idea to delivery; DO NOT TRIGGER for small tasks or when user invokes a specific phase.

Decides whether to author a SKILL.md. TRIGGER: 'create a skill', recurring workflow without one, broken trigger. NOT FOR: one-offs, rules, non-skill artifacts (use authoring-standards).

Skill navigator. List active skills, locate archived ones, choose the right sequence per scenario.

Verifies each AC against implementation in a single pass before Archive. TRIGGER: Phase 5 QA with AC ≤ 3 AND risk ≠ HIGH. NOT FOR: AC ≥ 4 or HIGH risk (use ultraqa); writing tests (use lead-engineer).

Cleans AI code slop via deletion-first workflow. TRIGGER: 'deslop' / 'AI slop' / bloated code; AI pipeline Phase 5. NOT FOR: bug fixes (use root-cause-debug); behavior-changing refactors.

Captures architectural decisions as ADRs. TRIGGER: 'ADR this' / 'record decision'; HIGH-risk Propose with irreversible choice (transport/persistence/framework). NOT FOR: MEDIUM risk; mechanical CRUD.

Turns an idea into a design with alternatives + constraints. TRIGGER: Propose opener for STANDARD. NOT FOR: PATCH; AC transcription (requirement-engineer); ADR capture (architecture-decision-records).

Runs inline self-review checklist after writing TRIVIAL/LOW (PATCH) code. TRIGGER: PATCH, after Implement, before finalize. NOT FOR: STANDARD MEDIUM/HIGH (use code-reviewer); never run both.

Scans reasoning for hallucination, overconfidence, anchoring. TRIGGER: Propose/Review AFTER decision-frameworks produces options (Zone G). NOT FOR: building options (use decision-frameworks first).

Builds options via SWOT / 5-Why / First Principles. TRIGGER: Explorer/Propose with ambiguous problem or unknown root cause. NOT FOR: bias-scanning output (use cognitive-bias-checklist after).

Decomposes a spec into a checkpoint plan before coding. TRIGGER: Propose, after brainstorming picks a design. NOT FOR: PRD decomposition (use task-decomposition-guide); design (use brainstorming).

Classifies raw input as PRD/Idea/Bug/Signal/Perf/Security/Compliance/Feedback → [Intake] routing block. TRIGGER: input has no @shortcut, >1 line. NOT FOR: AC transcription (requirement-engineer).

Defines Java test standards: isolation, mocks, 3-scenario coverage (Happy/Exception/Edge). TRIGGER: writing or reviewing Java tests. NOT FOR: choosing QA flow (use ac-verify or ultraqa per Zone C).

Gathers zero-cost context via BM25 wiki search + Java symbol index + failure memory. TRIGGER: Explorer phase, before reading source or writing Allowed Scope. NOT FOR: semantic / LLM-based retrieval.

Handles PRDs: Mode A ingests → ACs+deps; Mode B generates a draft. TRIGGER: input-classifier tags PRD, or user asks for one. NOT FOR: non-PRD (use requirement-engineer); Bug/Signal (root-cause-debug).

Classifies session knowledge into project memory / notepad / docs. TRIGGER: Archive, after uncovering a non-obvious constraint or decision. NOT FOR: WAL fragments (use wal-documentation-rules).

Investigates root cause before any fix via Hierarchical Localization. TRIGGER: bug / test failure / runtime exception. NOT FOR: build failures (use java-build-resolver); fixes before Phase 1.

Reviews Java backend for secrets, input validation, authZ, IDOR, data exposure, dependency safety. TRIGGER: HIGH-risk delivery or auth/data changes. NOT FOR: secret scanning (use security-sentinel).

Manages the Skill Knowledge Graph + central index. TRIGGER: a skill's purpose/trigger/phase changes. NOT FOR: minor wording tweaks; first-time creation (use skill-author + authoring-standards).

Verifies AI-generated docs (task_brief, specs, WAL) for clarity + actionability. TRIGGER: manually after drafting, before submit/gate. NOT FOR: code review (use code-reviewer / code-review-checklist).

Resolves cross-stakeholder requirement conflicts → map + decision. TRIGGER: parties in conflict; adversarial-review Cat A CRITICAL; PRD contradictions. NOT FOR: solo ambiguity (ambiguity-gatekeeper).

Decomposes PRDs / EPICs into INVEST subtasks via Vertical Slicing. TRIGGER: Explorer/Propose with EPIC/PRD or multi-task scope. NOT FOR: single-task spec (use impl-plan); design (use brainstorming).

Cycles QA test → verify → fix until all ACs pass, with an Evidence Mapping Table (AC ↔ Test ↔ Result). TRIGGER: Phase 5 with AC ≥ 4 OR HIGH risk. NOT FOR: AC ≤ 3 AND risk ≠ HIGH (use ac-verify).

Deep codebase initialization. Two outputs: (1) hierarchical CLAUDE.md files for human navigation; (2) a machine-readable context_brief.md that other skills (brainstorming, greenfield-scaffold, input-classifier) can load directly as structured context. TRIGGER when initializing a new repo, onboarding an agent to an unfamiliar codebase, or when input-classifier needs codebase context and no context_brief.md exists.

Large-scale external research across four trigger modes: (1) Pipeline plateau — breaking optimization bottlenecks when self-improve stalls; (2) Security/CVE — researching known vulnerabilities, CVE advisories, and security mitigations; (3) Compliance — researching regulatory requirements (GDPR, PCI-DSS, SOC2, etc.) and their technical implications; (4) Competitor/benchmark — researching industry-standard patterns, reference implementations, and design alternatives. TRIGGER for any of these four modes. DO NOT TRIGGER when the pipeline is making steady progress or the user just wants a quick web search.

Starting-from-scratch protocol for projects with no existing codebase. Replaces the standard Explorer phase's 'infer from existing code' logic with a forward-design sequence: domain model → API contract → DB schema → package structure → scaffold. TRIGGER when input-classifier emits Scenario=Greenfield or when there is no src/ directory.

Production emergency triage and post-mortem protocol. Phase 1: rapid triage (classify severity, identify blast radius, issue immediate mitigation). Phase 2: root cause investigation using Hypothesis Falsification. Phase 3: post-mortem with structured Action Items and 5-Why chain. TRIGGER when input-classifier emits Input-Type: Incident (A9) or user reports a production outage, data corruption, security breach, or SLA violation.

Shared OK/WARN/FAIL severity contract for every gate script under .claude/scripts/gates/. TRIGGER whenever a gate is invoked — agent MUST surface WARN/FAIL inline using the reporting protocol below. New gates MUST pass `_severity_audit.py`.

A→B system migration protocol where the core requirement is behavioral equivalence, not new features. Generates an equivalence test suite BEFORE migration begins. Migration is done when equivalence tests pass. TRIGGER when input-classifier emits Scenario=Migration or when the request is 'migrate from X to Y'.

Layer 1 (Architecture) for Java backend. Daily decisions you can make WITHOUT opening SKILL.md: - Red Lines: NO @PathVariable (use query string / request body); NO hard delete (is_deleted=1); NO `I` prefix on interfaces; every list query filters by tenant_id. - Service writes: throw DomainException + AbstractErrorCode (never RuntimeException) — guarantees @Transactional rollback. - Cross-domain reads: Anti-JOIN — query main table, extract FK ids, query related table, assemble in memory. - DI: @RequiredArgsConstructor on the class, NEVER @Autowired on fields. Lombok: @Getter+@Setter, NOT @Data. - Null checks: Objects.isNull() / Objects.nonNull(), not == null. Open SKILL.md when deciding: POJO directory layout, audit field set, endpoint naming verbs, @ResourceLock usage.

Layer 2 (Coding style) for Java. Daily decisions without opening SKILL.md: - 4 spaces (never tabs); K&R braces; always braces for if/for/while (no single-line). - NO wildcard imports (`import x.*;`). NO `// comment` for structural blocks — use `/** */`. - Every public class/method has Javadoc with @author/@date/@param/@return. - Custom utility class: `public final class` + `private` ctor + all methods `static`. NO business imports. - Discovery-first: prefer cn.hutool / commons / existing *Util before writing a new helper. Open SKILL.md when deciding: In-Memory JOIN generic helper signature, Cursor Batching skeleton for large datasets, Javadoc template details.

Layer 3 (Persistence). TRIGGER when touching mapper XML, SQL fragment, or table schema. Daily decisions without opening SKILL.md: - NO JOIN to fetch dictionary/redundant fields — single-table query + in-memory assembly (95% of queries are single-table). - NO `${}` parameter substitution (SQL injection); use `#{}` or a whitelisted enum. - NO `SELECT *` — list columns; skip large TEXT/JSON unless explicitly needed. - NO physical foreign keys; store ids logically and rely on application-level boundaries. - Every business table has the 8 standard audit columns (id, tenant_id, create_time, update_time, create_by, update_by, is_deleted, version). - Prefer LambdaQueryWrapper over hardcoded XML for single-table queries. - Don't add `tenant_id = #{}` manually — the global TenantLineInnerInterceptor injects it. - Type-match params to columns (VARCHAR↔String, BIGINT↔Long); type mismatch disables the index. Open SKILL.md when deciding: composite index leftmost-prefix design, IN-clause partitioning threshold, `<choose>`/`

TDD discipline for STANDARD-profile Implement phase. Daily protocol without opening SKILL.md: - RED first: write the test from an AC, RUN it, confirm it fails. No implementation yet. - GREEN second: write the minimum code to pass. Resist adding "while I'm here" code. - REFACTOR third: clean up only after green. Tests stay green throughout. - One test = one AC. If a test asserts multiple behaviors, split it. - Never modify a test to make a failing implementation pass — fix the implementation. - Skipping RED (writing test+impl together) violates the discipline; you do not know the test actually tests anything. Open SKILL.md when deciding: how to test code without obvious seams, when to stub vs mock vs use a real dependency, refactor patterns that preserve green.

Turn a one-line objective into a step-by-step construction plan for multi-session, multi-agent engineering projects. Each step has a self-contained context brief so a fresh agent can execute it cold. Includes adversarial review gate, dependency graph, parallel step detection, anti-pattern catalog, and plan mutation protocol. TRIGGER when: user requests a plan, blueprint, or roadmap for a complex multi-PR task, or describes work that needs multiple sessions, or invokes the AI engineering pipeline. DO NOT TRIGGER when: task is completable in a single PR or fewer than 3 tool calls, or user says "just do it".

Dispatch specialized sub-agents for 2+ independent task domains that have no shared state or sequential blocking dependencies. TRIGGER during Propose/Implement phase when task-decomposition identifies parallel workstreams (e.g., multi-domain EPIC, 3+ failing test files with unrelated root causes). Each agent gets an isolated context and a scoped contract.

Formal evaluation framework with two operating modes: (A) Early-phase AC Definition — usable at Explorer phase to translate requirements into executable pass/fail criteria before any code is written; (B) Pipeline Evaluation — Phase 3 of the AI engineering pipeline (after blueprint and ADR, before self-improve) to set up benchmarks and measure reliability with pass@k metrics. TRIGGER for either mode: when requirements need to be translated to testable assertions, or when setting up evaluation benchmarks.

Release workflow executor — reads repo release rules, validates pre-release gates (tests, changelog, version bump), then guides step-by-step release execution. TRIGGER when user requests a release, version tag, or deployment.