---
number: 10060
title: 'feat(claude): wire Claude Code harness (#10059)'
author: tobiu
state: MERGED
createdAt: '2026-04-18T13:06:12Z'
updatedAt: '2026-04-18T13:19:28Z'
closedAt: '2026-04-18T13:19:23Z'
mergedAt: '2026-04-18T13:19:23Z'
head: claude/goofy-tu-f83d87
base: dev
url: 'https://github.com/neomjs/neo/pull/10060'
---
## Summary

Wires Claude Code as a first-class swarm node alongside Antigravity and Gemini CLI, by auto-loading `AGENTS.md` at session start, committing the existing `.claude/skills/` symlink bundle, and preventing worktree checkouts from polluting `git status` in the main checkout.

See #10059 for the full Fat Ticket rationale, architectural reality, and rejected alternatives.

## Changes

- **`.claude/CLAUDE.md` → `../AGENTS.md`** (symlink). Claude Code auto-loads both `./CLAUDE.md` and `./.claude/CLAUDE.md` with identical precedence per the [Claude Code memory docs](https://code.claude.com/docs/en/memory.md). Placed inside `.claude/` to keep the repo root uncluttered.
- **`.claude/skills/`** — 11 symlinks to `../../.agent/skills/*` covering `create-skill`, `debugging-antigravity`, `ideation-sandbox`, `neural-link`, `pr-review`, `pull-request`, `self-repair`, `tech-debt-radar`, `ticket-intake`, `unit-test`, `whitebox-e2e`. Feature parity with Gemini CLI's `.agent/skills/` discovery.
- **`.gitignore`** — added `.claude/worktrees/` so per-agent Claude Code worktree checkouts don't appear as nested untracked files in the main checkout.

## Verification

1. Clone fresh → open Claude Code in repo root → ask *"what are your pre-commit gates?"* → expect Section 3 recital from AGENTS.md with no Glob/Grep/Read tool calls (auto-loaded from context, not discovered).
2. `git status` in the main checkout on `dev` after future Claude-Code-spawned worktrees → expect no `.claude/worktrees/<name>/` noise.
3. Windows contributors: symlinks survive `git clone` as symlinks when `core.symlinks=true`; otherwise they materialize as text files containing the target path — content is still `AGENTS.md`, acceptable fallback.

## Follow-ups (separate tickets — not in this PR)

Discovered during the commit cycle of this PR:

- Update `.agent/skills/pull-request/references/pull-request-workflow.md` §3 to explicitly document `feat` vs `fix` vs `chore` selection rules and forbid `<noreply@*>` `Co-Authored-By` footers (the Claude Code harness injects these by default).
- Add Gate 3 to `AGENTS.md` §3 Pre-Flight Check for commit-format compliance (consult pull-request skill before `git commit`).
- Accept harness-prefixed branch names (`claude/...`, `antigravity/...`, `gemini/...`) alongside `agent/<ticket>-<desc>` in the branching mandate.
- Optimize `AGENTS.md` + `AGENTS_STARTUP.md` startup-cache footprint (~47KB combined per session).

Resolves #10059

## Comments

### `@tobiu` commented on 2026-04-18T13:09:21Z

**Input from Claude Opus 4.7 (Claude Code):**

> ❋ # PR Review Summary
> 
> **Status:** Approved (self-review — awaiting human merge)
> 
> **Self-Review Opening:** Self-review of #10059. This implementation chose `.claude/CLAUDE.md → ../AGENTS.md` (symlink inside the subdirectory) over repo-root placement or content copying. Rationale: Claude Code memory docs confirm `.claude/CLAUDE.md` is auto-loaded with identical precedence to `./CLAUDE.md`, the subdirectory placement groups all Claude-Code-specific metadata under one roof (`settings.local.json`, `skills/`, `CLAUDE.md`), and symlinks guarantee single-source-of-truth against AGENTS.md drift. Key trade-offs and gaps noted below.
> 
> > **Detection note:** `query_raw_memories(#10059, sessionId=f018be49-cbf9-4f99-9119-2510fc5bb8d8)` returned 0 matches, which strictly would route to peer-review mode. This is a false negative — I authored this PR in the current session but failed to call `add_memory` during the turn cycle per AGENTS.md §4. Self-review mode applied honestly. See `[TOOLING_GAP]` below.
> 
> ---
> 
> ### 📊 Evaluation Metrics
> 
> *   **`[ARCH_ALIGNMENT]`**: 90 — Uses Claude Code's native auto-load convention (documented behavior). Symlinks preserve single-source-of-truth with AGENTS.md. Penalty: branch name `claude/goofy-tu-f83d87` does not follow the `agent/<ticket-id>-<descriptor>` mandate in pull-request-workflow.md §2 — harness-generated naming. Captured as follow-up.
> *   **`[CONTENT_COMPLETENESS]`**: 88 — Fat Ticket #10059 covers Intent, Architectural Reality, Scope, Avoided Traps, Verification, Follow-ups. PR body mirrors and extends. No JSDoc applicable (no code added). Minor gap: Claude Code memory-docs URL appears in PR body but not commit message — acceptable since commits are for change-intent, not architectural citation.
> *   **`[EXECUTION_QUALITY]`**: 85 — Symlinks use correct relative paths (verified post-creation); explicit `git add` prevented accidental staging of `.claude/settings.local.json`. No automated test exists or was added — symlinks are structurally verified by git, semantic verification ("do the gates load?") requires a fresh Claude Code session, documented in the PR verification steps. Automating this would be overkill for the change scope.
> *   **`[PRODUCTIVITY]`**: 95 — All three in-scope deliverables from #10059 delivered (CLAUDE.md symlink, skills symlinks, gitignore). Four *new* follow-up gaps were surfaced during execution and captured as explicit out-of-scope tickets rather than scope-crept into this PR.
> *   **`[IMPACT]`**: 60 — Meaningful contributor-experience improvement (Claude Code becomes a first-class swarm node), but narrow in framework terms: affects only contributors using Claude Code harness, not end-users of Neo.mjs or the core engine. Could rise to 70 once Claude Code adoption among contributors is measured.
> *   **`[COMPLEXITY]`**: 20 — 13 filesystem ops + 3 `.gitignore` lines. Cognitive load was protocol adherence (Fat Ticket + pull-request skill + Conventional Commits + Pre-Commit Gates), not the mechanics.
> *   **`[EFFORT_PROFILE]`**: Quick Win — low complexity, clear per-contributor benefit, unblocks all future Claude Code agent flows in the repo.
> 
> ---
> 
> ### 🕸️ Context & Graph Linking
> 
> *   **Target Epic / Issue ID:** Resolves #10059
> *   **Related Graph Nodes:** `.agent/skills/pull-request`, `.agent/skills/pr-review`, `.agent/skills/ticket-intake`, `AGENTS.md §3` (Pre-Commit Hard Gates), `AGENTS.md §7` (Pull Request Mandate), `AGENTS.md §9` (Swarm Fat Ticket Protocol), `AGENTS_STARTUP.md §5` (Skills discovery), `.gemini/settings.json` (parallel harness wiring for comparison). Origin Session ID: `f018be49-cbf9-4f99-9119-2510fc5bb8d8`.
> 
> ---
> 
> ### 🧠 Graph Ingestion Notes
> 
> *   **`[TOOLING_GAP]`** — Three distinct harness/workflow friction points surfaced during this PR's lifespan, all worth encoding structurally:
>     1. **First commit attempt was rejected by the user** because it used `chore(claude)` (should be `feat`), placed the ticket ID in a trailing `Refs #10059` paragraph (should be `(#10059)` appended to the subject), and included a `Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>` footer (project-forbidden). Root cause: I did not read `.agent/skills/pull-request/references/pull-request-workflow.md` §3 before running `git commit`, despite that skill's `SKILL.md` line 10 explicitly mandating it. Secondary cause: `AGENTS.md` §3 Pre-Flight Check enumerates a Ticket Gate and Contextual Completeness Gate but has no commit-format gate — making it possible to satisfy the documented gates while still violating the skill's commit protocol. Follow-up ticket will add Gate 3 and document feat/chore selection + noreply prohibition.
>     2. **`mcp__neo-mjs-memory-core__get_context_frontier` failed with a schema error** during session initialization (`data must NOT have additional properties`). Did not block this PR since no prior session state was relevant, but worth flagging — the Context Priming Engine is advertised as a mandatory Step 6 boot action in `AGENTS_STARTUP.md` and is currently a no-op due to the validator rejection.
>     3. **`mcp__neo-mjs-github-workflow__list_issues`** returned 57KB of issue bodies for a 30-issue page — exceeded the tool-result inline budget and required persisted output. Pagination default of 10 issues (with the option to expand) would match typical triage scope better and reduce context bloat.
> *   **`[KB_GAP]`** — Two documentation gaps observed:
>     1. `AGENTS_STARTUP.md` §5 lists `.agent/skills/` as the discovery directory but makes no mention of Claude Code's auto-load rules for `.claude/CLAUDE.md` vs `./CLAUDE.md`. A future Claude-Code-spawned agent will have to re-research this same question unless captured. Suggest adding a short paragraph under §5 naming the harness→memory-file mapping for each supported harness (Claude Code: `.claude/CLAUDE.md`; Gemini CLI: `.gemini/GEMINI.md`; Antigravity: ?).
>     2. Harness-vs-project commit-hygiene conflicts are not documented anywhere. The Claude Code harness system-prompt template mandates a `<noreply@anthropic.com>` co-author footer by default. Without a counter-rule in AGENTS.md, harness-following agents will violate project style. The PR's first follow-up ticket will fix this.
> *   **`[RETROSPECTIVE]`** — Two architectural takeaways worth permanent ingestion:
>     1. **Harness-specific subdirectories (`.claude/`, `.gemini/`, `.antigravity/`) should host their own metadata alongside shared-source symlinks pointing to canonical `.agent/skills/`.** This pattern scales: each new harness gets a clean discovery root while the skill library remains single-sourced. Applies any time a new CLI-driven agent harness is added to the repo.
>     2. **`.claude/CLAUDE.md` (subdirectory) beats `./CLAUDE.md` (root) when the harness supports both.** Root-level project-meta files mislead contributors into treating them as separate documents from `AGENTS.md` / `AGENTS_STARTUP.md`; the subdirectory placement makes the relationship ("this is harness-specific auto-load for AGENTS.md") obvious.
> 
> ---
> 
> ### 📋 Required Actions
> 
> No blocking actions. This PR is mergeable as-is.
> 
> Follow-up items captured as separate tickets (not in this PR — scope-creep avoidance):
> 
> - [ ] Update `.agent/skills/pull-request/references/pull-request-workflow.md` §3 — document `feat`/`fix`/`chore` selection rules and forbid `<noreply@*>` `Co-Authored-By` footers.
> - [ ] Add Gate 3 to `AGENTS.md` §3 Pre-Flight Check: commit-format compliance (consult pull-request skill before `git commit`).
> - [ ] Accept harness-prefixed branch names (`claude/...`, `antigravity/...`, `gemini/...`) alongside `agent/<ticket>-<desc>` in the branching mandate.
> - [ ] Document the harness→memory-file mapping in AGENTS_STARTUP.md §5.
> - [ ] Fix `get_context_frontier` schema validator regression (separate infrastructure ticket).
> - [ ] Optimize AGENTS.md + AGENTS_STARTUP.md startup-cache footprint (~47KB combined per session).
> 
> Ready for human merge. Handing off.

---

