Implementation Guide

This guide is the short implementation map for Claude Code Harness contributors. It complements README.md, AGENTS.md, and CLAUDE.md.

Current Architecture

Claude Code Harness v4 is Go-first.

• Runtime entrypoint: bin/harness
• Go source: go/
• Plugin manifest: .claude-plugin/plugin.json
• Hook configuration: hooks/hooks.json and .claude-plugin/hooks.json
• Primary skills: skills/
• Public mirrors: .agents/skills/, codex/.codex/skills/, opencode/skills/
• Templates: templates/
• Tests and validators: tests/, scripts/ci/

Older TypeScript core/ assumptions are not part of the current required runtime surface. Validators should check the Go runtime and shipped plugin surfaces instead.

Implementation Flow

1. Read Plans.md and identify the exact task scope.
2. Keep changes narrow and update only the owning files.
3. For skill changes, update skills/ first.
4. Run bash scripts/sync-skill-mirrors.sh after skill changes.
5. Add or update focused tests for the changed behavior.
6. Run the validation commands below before handing off.

Skill And Mirror Rules

skills/ is the source of truth for shared skills.

After editing skills, mirror them with:

bash scripts/sync-skill-mirrors.sh
bash scripts/sync-skill-mirrors.sh --check

Codex-specific behavior belongs in skills-codex/ when the Codex workflow needs a different instruction surface. Do not add Codex-only behavior to the shared skill unless it also applies to Claude Code.

Agent Frontmatter Rules

Plugin subagents do not carry Claude Code runtime-only settings such as:

• permissionMode
• top-level hooks
• mcpServers

Safety is enforced through plugin hooks, Go guardrails, settings, and the parent session permission model. See docs/agent-frontmatter-policy.md.

Template Rules

All templates/**/*.template files must be registered in templates/template-registry.json.

Tracked Markdown templates should include frontmatter:

---
_harness_template: "path/from/templates"
_harness_version: "x.y.z"
---

Locale-specific templates may share the same output path when they include a distinct locale value in the registry.

Validation Commands

Use these for broad local validation:

bash tests/validate-plugin.sh
bash tests/validate-skills.sh
bash scripts/ci/check-consistency.sh
bash scripts/ci/check-template-registry.sh
cd go && go build ./cmd/harness/ && go test ./... && go vet ./...

For a full shell-test sweep:

while IFS= read -r test_file; do
  bash "$test_file" < /dev/null
done < <(find tests -maxdepth 1 -type f \( -name 'test-*.sh' -o -name 'validate-*.sh' \) | sort)

Release Boundaries

Normal implementation work should not edit VERSION or .claude-plugin/plugin.json version fields.

Version changes belong to release work and should use the release scripts and release validation flow documented in skills/harness-release/.