ai-harness

Use BEFORE any solo/low-blast creative work — designing a feature, component, behavior change, or this harness itself — to turn an idea into an approved design through a lightweight collaborative dialogue. The solo counterpart to /team-brainstorm (which owns multi-file / cross-cutting / product / architecturally-uncertain work). Harness-owned; do NOT invoke any external brainstorming skill.

6-phase verification system (+ an opt-in human comprehension quiz gate) with checkpoint support and pass@k metrics. Use in Phase 4-5 of team workflow, before creating PRs, or after completing feature implementations. Covers build, type check, lint, test, security scan, diff review, a human-understanding gate, checkpoints, and evaluation metrics.

Multi-agent team workflow orchestration with 5 phases, escalation loops, and TDD enforcement. Use when /team or /team-run commands are invoked. Coordinates Team Leader, Architects (FE/BE/Infra), UI/UX Master, Designers (TDD developers), and Testers through Planning → UI/UX → Gate → Implementation → Verification → Final Review.

Model routing (incl. per-agent Workflow / ultracode routing), effort levels, context efficiency, and compaction strategy. Use when spawning agents, authoring Workflow fan-outs, selecting models, choosing effort levels, or managing context window pressure.

Git worktree management, cascade method for multiple instances, and scaling guidelines. Use when planning parallel agent work, managing worktrees, or deciding when to scale instances.

Analyze project structure, conventions, and patterns to generate a project profile. Use when /team-init is invoked or when team agents need to understand the codebase. Scans package.json, config files, source code patterns, and test setup to produce structured profiles in .claude/project-profile/.

Worktree strategy for a submodule-monorepo where the superproject is a thin shell (doc storage + submodule pointers) and the real code lives in submodules (illustratively `fe`/`be`). TRIGGER when a worktree / parallel-implementation request lands in a repo that has git submodules (`.gitmodules`), or the project profile records a Submodule Layout. Rules: worktree ONLY the code submodules, keep the superproject as the single original checkout (the `_docs/` anchor), CARRY gitignored runtime files (`.env`/secrets/local config) into each new worktree, and defer submodule-pointer bumps. The submodule-specialized companion to `parallelization`.

Write a handoff document — a state layer over a spec/plan capturing what's done, what's left, and how to resume — when work passes to another agent or a future session. Use at session end with unfinished work, before a compaction that ends active work, or when explicitly handing a task off. Writes into `_docs/handoff/` per the docs-lifecycle convention and links (never duplicates) the spec it hands off.

Take over a handed-off work-stream — the read/resume counterpart to the `handoff` skill. A handoff is a temp carrier: locate the `_docs/handoff/` doc, hydrate its linked spec (follow `related:`), verify its state claims against the actual repo (commits, branch, tests), then GRADUATE it into its durable `_docs` home — implement-now → `complete/`, needs-planning → a `plan` in `active/`, etc. — renamed to `_docs` grammar, never a bare delete. Use when picking up handed-off work, resuming a session where a handoff exists, or when told to take over / 인계받아. Distinct from `/checkpoint` (agent session-state restore).

Manage the lifecycle of project documents (plans, specs, findings) in `_docs/` — status↔folder lockstep, date/topic foldering, reference-safe moves, and merging a task's scattered sidecar docs into ONE archive on completion. Use whenever a plan/spec is created, moves between stages, a topic is renamed, or a task finishes; and whenever `_docs/` is accumulating multiple files for the same task. Trigger at every team-workflow phase transition and before marking any work complete — scattered, status-stale, or orphaned docs are the failure this prevents.

Preferred browser-driving path for on-demand E2E / QA / smoke when the `agent-browser` CLI and its skill are installed. Use when asked to E2E-test, QA, smoke-test, or drive a web app through a real browser — OR when a headless run is blocked at login and you must authenticate without exposing the password to the LLM. Gates on two conditions (agent-browser CLI present + agent-browser skill available) checked ONCE; falls back to Playwright (`e2e-testing` / `agentic-testing`) when either is missing. The headless-login answer is agent-browser's encrypted Auth Vault (default), with credential-plugin / state-import / persistent-profile fallbacks. The LLM never sees the password.

Agentic E2E testing layer (Phase 4.5). Use AFTER deterministic E2E passes and BEFORE human final review. An agent explores a goal via the stack's UI/API driver, verifies goal achievement, and crystallizes the path into a deterministic test. Stack-agnostic via project-profile adapters (web/TS base, Spring-Kotlin, Flutter).

Playwright E2E testing patterns. Use in Phase 4 (Verification) by Tester agents. Covers Page Object Model, test structure, configuration, flaky test strategies, artifact management, and CI/CD integration.

Turn a test-scenario-doc (the manual QA checklist from `test-scenario-doc`) into runnable Playwright E2E specs. Reads the doc's structured `SCENARIOS` config (steps/expect/fail) as the source of truth, drives the live app to resolve REAL selectors, and crystallizes each scenario into a `.spec.ts` that it runs and green-gates — never fabricating selectors, never claiming pass without a green run. Falls back to a clearly-marked "unverified scaffold" when the app/driver is unavailable. Use whenever the user wants to generate Playwright e2e tests FROM a test scenario doc / QA checklist / 테스트 시나리오 문서 — "시나리오로 e2e 만들어줘", "scenario doc → playwright", "convert the QA checklist to e2e". On-demand (not phase-wired). Pairs with `test-scenario-doc` (input) and `e2e-testing` (house style).

Generate a self-contained, interactive HTML test-scenario / QA checklist document — grouped scenarios with checkable steps, pass/fail/hold verdicts, a sticky progress bar, localStorage auto-save, a copyable markdown summary, an image-embedded HTML result report, and per-scenario screenshot attachment (file picker + clipboard paste). Use this whenever the user wants a manual test plan, QA checklist, regression-test doc, acceptance/smoke test scenarios, a "테스트 시나리오 문서", release verification steps, or any structured way to track manual verification of a feature, bug fix, or merge — even if they only say "track what to test", "make a QA checklist", or "write test scenarios" without naming this format. Prefer this over hand-writing a one-off HTML each time.

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes. Harness-owned general debugging methodology (root cause → pattern → hypothesis → fix); the TS/LSP-specific `debug` skill builds on this.

LSP-driven debugging patterns for TypeScript codebases. Complements the general debugging methodology in the harness `systematic-debugging` skill. Use in Phase 3-4 escalation scenarios or when investigating unexpected behavior.

Use when facing 2+ independent tasks (different test files, subsystems, bugs) that can be worked on without shared state or sequential dependencies. Decide when to split work into parallel agents vs keep it sequential.

Use when completing tasks, implementing major features, or before merging to verify work meets requirements. Dispatches a code-reviewer subagent with crafted context.

Wire an optional personal 'brain' SSOT (a separate repo holding your cross-machine persona + harness auto-memory) into the Claude Code environment on a machine — persona @import, per-project memory junction, and opt-in auto-sync hooks. Use when setting up the harness on a new machine (work/home), when a user provides a path to their brain repo and wants it connected/referenced, or when relocating an existing brain to a new folder/remote. Dependency-free: the harness ships the generic connector scripts as a copyable template and defines the brain contract; it does NOT import or depend on any specific brain repo. The reference conforming brain is the private claude-brain SSOT.

Critical plan review for evaluating implementation plans, feature proposals, and architectural decisions. Focuses on worst-case analysis, risks, performance bottlenecks, UI/UX concerns, and edge cases. Also drives open plan decisions to resolution via structured one-question-at-a-time elicitation. Use during Phase 1 cross-review or before any code is written.

Bootstrap a brand-new project from zero — research the stack, scaffold it, and generate the project profile — when there is no code yet. Use when /team-new is invoked, or when the user wants to start a new project from an idea. Ends by handing off to /team-run for the first feature. Distinct from project-analyzer/team-init (which assume an existing codebase).

Generate interactive HTML visualization of team plans. Use after plan is finalized in /team, /team-run, or /team-brainstorm. Creates a visual diagram showing team composition, phase flow, file assignments, and dependency graph. Saves HTML alongside the plan .md file.

Extract reusable patterns from sessions, manage session state, and evolve learnings into skills. Use at session end, after completing features, or when patterns emerge during work.

Universal coding standards and best practices. Use in Phase 3 (Implementation) as the baseline for Designer agents. Covers readability, KISS, DRY, YAGNI, TypeScript patterns, error handling, and code smell detection.

Build and maintain the agent wiki (.claude/wiki/) — a persistent, compounding knowledge base. Use when ingesting a source into the wiki, querying it, or linting it for drift. The wiki links to the SSOT (code / _docs/ / _note/); it routes and synthesizes, it does NOT duplicate facts.

Regenerate and re-verify a code-generated API client after any backend/server contract change, BEFORE writing or verifying client code against it. Use whenever a task changes a backend DB schema, request/response DTO, enum, or endpoint shape in a project where the frontend consumes a generated client/types (OpenAPI, GraphQL codegen, gRPC, tRPC, etc.). Trigger this even if the user only says 'I changed the API' or 'update the frontend to match' — the regenerate→typecheck gate is what prevents silent type/runtime desync. Run it at the BE→FE handoff in team workflows, before verification-loop Phase 2, and any time someone reports 'I changed the backend but the frontend doesn't match.'

Save and restore work state across sessions, branches, and compactions. Use when saving progress before stopping, switching branches, or when the /checkpoint command is invoked.

Security vulnerability detection and remediation. Use in Phase 5 (Final Review) by Architect C, when handling user input, authentication, API endpoints, or sensitive data. Covers OWASP Top 10, secrets management, and pre-deployment checklist.

Iterative retrieval pattern, context negotiation, and sequential phase architecture for subagent coordination. Use when spawning agents, designing multi-agent workflows, or debugging subagent quality issues.

Test-Driven Development workflow using Vitest 4.x. Use in Phase 3 (Implementation) when Designers write code. Enforces Red-Green-Refactor cycle with 80%+ coverage. Covers unit, integration, and E2E test patterns.