v1.1.0 to v2.0.1

701 added, 362 removed. Audit B to B.

---

name: create-agent-harness

license: MIT

- description: Bootstrap a complete production-ready agent harness in a repository — AGENTS.md/CLAUDE.md, .claude/, .devin/, .opencode/, .cursor/, .gemini/, skills/, rules/, ignore files, and sub-agents. Use when initializing AI agent support in a new repo, restructuring existing agent files into modern File-based Context conventions, or generating harness artifacts following Agent = Model + Harness principles. Supports Claude Code, Devin CLI/Desktop, OpenCode, Cursor, Gemini CLI, Antigravity IDE/CLI, and OpenClaw. Do NOT use for building MCP servers (use building-mcp-servers). Part of the afonsoft/skills collection.

+ description: Bootstrap or migrate a complete production-ready agent harness in a repository — CLAUDE.md, AGENTS.md (symlink/reference), .claude/ (settings.json, rules, agents review/plan/test, skills, commands, hooks, memory, knowledge, CONTEXT.md, RULES.md, MEMORY.md, TOOLS.md, WORKFLOWS.md, README.md), .devin/config.json, .opencode/, .cursor/, .gemini/, context engineering and memory protocol. Use when initializing AI agent support in a new repo, migrating legacy harness (AGENTS.md, .agents/, .devin/, .cursorrules, .windsurf) to .claude/, configuring permissions and hooks, or when the agent loses context every session. Supports Claude Code, Devin CLI/Desktop, OpenCode, Cursor, Gemini CLI, Antigravity IDE/CLI, and OpenClaw. Do NOT use for building MCP servers (use building-mcp-servers).

metadata:

- version: "1.1.0"

+ version: "2.0.1"

visibility: public

author: afonsoft

url: https://github.com/afonsoft/skills

user-invokable: "true"

argument-hint: "[repo-path]"

+ execution-mode: sequential

+ confirmation-required: true

+ phase-count: 5

+ critical-constraints:

+ - 'Start Phase 0 immediately on invocation — never ask what to do'

+ - 'Never write on main, master or develop — create a dedicated feature branch first'

+ - 'The discovery gate is the only mandatory pause — nothing is written before it'

+ - 'Every generated statement must cite repository evidence — otherwise write TODO and ask'

+ - 'Migrate and remove: no legacy harness structure may survive alongside .claude/'

+ - 'Re-running on a migrated repo must complete, never duplicate'

+ - 'Always generate .claude/memory/ — the memory protocol is not optional'

---

# Create Agent Harness

- Generate a production-ready harness for AI agents in a target repository. The harness is everything the model can't do alone. Supports all major agent platforms:

+ Generate — or migrate — the agent harness of a repository into the modern **Claude Code + Agent Skills** structure. A harness is everything the model cannot do alone: orientation before acting, state that survives context resets, and computational guardrails that cannot be ignored. The skill discovers the repository, migrates any legacy harness, generates the missing artifacts and validates the result with deterministic commands.

- |----------|-------------|------------|-----------|

+ > Scope: primary `CLAUDE.md` plus `.claude/`. The same source also serves Devin CLI (which reads `.claude/` natively when `read_config_from.claude` is set). For Cursor, OpenCode, Gemini and Antigravity generate thin platform-specific directories that reference `.claude/` where possible. Legacy structures are migrated into `.claude/` and the originals removed.

- > **Strategy:** Generate `CLAUDE.md` as the Single Source of Truth, then create `AGENTS.md` as a thin symlink/reference for non-Claude platforms. All platforms read `AGENTS.md` natively except Claude Code which reads `CLAUDE.md`. This avoids duplication while ensuring every platform gets the same instructions.

+ ## Supported Platforms

+ |----------|-------------|------------|-----------|-------|

+ > **Strategy:** Generate `CLAUDE.md` as the Single Source of Truth, then create `AGENTS.md` as a thin symlink/reference for non-Claude platforms. Claude Code reads `CLAUDE.md` natively; the others read `AGENTS.md`.

+ ## When to Use

+ - "prepare this repo for AI agents" / "configure the harness for this repo"

+ - "create the CLAUDE.md" / "improve the CLAUDE.md"

+ - "migrate AGENTS.md / .agents/ / .cursorrules to .claude/"

+ - "configure permissions, hooks or subagents"

+ - "the agent forgets everything between sessions" / "configure memory"

+ ## Do NOT Use For

+ | Request | Use instead |

+ | --- | --- |

+ | Build an MCP server | `building-mcp-servers` |

+ | GitHub Actions agentic workflows (gh-aw) | `github-agentic-workflows` |

+ | A harness for JetBrains/Copilot only | Out of scope — refuse and explain why |

+ | Keeping `AGENTS.md` as the source of truth | Out of scope — this skill migrates it into `CLAUDE.md` |

+ ## Immediate Execution

+ On invocation, start **Phase 0** right away. Do not ask what to do — invoking the skill is the request.

+ **The discovery gate at the end of Phase 1 is the only mandatory pause.** Nothing is created, moved or deleted before it; everything after it runs autonomously.

## Core Principle

`Agent = Model + Harness`

- Every harness component exists because the model can't do something on its own. Design for obsolescence — components become unnecessary as models improve. Two reliability loops guide the design:

+ Every component exists because the model cannot do something on its own. Design for obsolescence. Two reliability loops guide the design:

- - **Feedforward** — orient BEFORE acting (CLAUDE.md, rules, skills)

- - **Feedback** — validate AFTER action (lint, tests, CI)

+ - **Feedforward** — orient BEFORE acting (`CLAUDE.md`, rules, skills, memory read)

+ - **Feedback** — validate AFTER acting (lint, tests, CI, hooks, memory write)

- ## Workflow

+ Prefer **computational controls over prompts**: `settings.json` and hooks cannot be ignored; a prompt can.

+ > ❗ **Forbidden:** invent context. Every statement in a generated artifact must be evidenced by the target repository. Where evidence is missing, write `TODO:` and ask.

+ ## Process

```mermaid

graph LR

- D[1. Discovery<br/>evidence-based] --> P[2. Plan<br/>artifacts to generate]

- P --> G[3. Generate<br/>files in repo]

- G --> V[4. Validate<br/>checklist + lint]

+ P[0. Pre-flight] --> D[1. Discovery]

+ D --> G{Gate}

+ G --> M[2. Migration]

+ M --> A[3. Artifacts]

+ A --> V[4. Validation]

```

- > ❗ **Forbidden:** invent context. Everything must be evidenced by the target repository.

+ | Phase | Goal |

+ | --- | --- |

+ | 0. Pre-flight | Execution rules, git state, dedicated branch |

+ | 1. Discovery | Evidence-based report plus legacy harness inventory, then **pause** |

+ | 2. Migration | Consolidate every legacy artifact into `.claude/` and remove the originals |

+ | 3. Artifacts | Generate or complete `CLAUDE.md` and `.claude/` |

+ | 4. Validation | Deterministic checks, final report, commit and PR proposal |

- ## Step 1 — Discovery

+ ## Execution Rules

- Explore the target repo and document what exists:

+ Breaking any of these invalidates the run.

- | Discovery item | What to capture |

- |---|---|

- | Directory structure | Root + main subdirectories |

- | Tech stack | Languages, frameworks, runtimes with versions |

- | Architectural patterns | Clean Architecture, MVVM, microservices, etc. |

- | External integrations | APIs, cloud services, auth providers |

- | CI/CD pipelines | GitHub Actions, Jenkins, etc. |

- | Code conventions | Naming, formatting, testing patterns |

- | Existing agent infra | `CLAUDE.md`, `.claude/`, `.devin/`, `skills/`, `rules/`, `.instructions.md` |

- | Ignore files | `.gitignore`, `.aiignore`, `.claudeignore`, etc. |

+ 1. **Never invent context.** Every generated statement must be evidenced by the repository — code, configs, docs. Where evidence is missing, write `TODO:` and ask. Never fill a gap with a plausible guess.

+ 2. **Plan before acting.** Present the Discovery Summary and the Migration Plan and wait for human confirmation before creating, moving or deleting any file.

+ 3. **Dedicated branch.** Never work on `main`, `master` or `develop`. Create `feature/{AgentLLM}-{YYYYMMDD}-{short-description}` before the first write.

+ 4. **Single source.** The final harness lives primarily in `CLAUDE.md` plus `.claude/`. No parallel structures survive. A minimal `AGENTS.md` / `.devin/config.json` / `.cursor/` / `.gemini/` may exist only as thin references.

+ 5. **Migrate and remove.** Move or convert the content, then delete the original. Prefer `git mv` and `git rm` to preserve history.

+ 6. **No content loss.** Before deleting a legacy artifact, confirm its useful content already exists at the destination.

+ 7. **Idempotency.** Re-running on an already migrated repository must not duplicate or corrupt anything. Detect what exists and complete only what is missing.

+ 8. **Tooling.** With a shell, run the `bash` commands below. Without a shell, perform the equivalent action with file tools — the commands are the canonical specification of what must happen.

- **Output discovery summary** (mandatory before generating anything):

+ ### Placeholder glossary

+ | Placeholder | Meaning | Example |

+ | --- | --- | --- |

+ | `{AgentLLM}` | The executing agent | `claude`, `devin` |

+ | `{YYYYMMDD}` | UTC date of the run, read from the system | `20260908` |

+ | `{slug}` | kebab-case, ASCII, no spaces or accents | `dotnet-backend` |

+ | `{stack}` | Stack detected in Phase 1 | `Angular 20`, `.NET 8` |

+ | `{ProjectName}` | Real repository name | `my-project` |

+ Never guess `{YYYYMMDD}`. Read it from the system: `date -u +%Y%m%d`, or `(Get-Date).ToUniversalTime().ToString('yyyyMMdd')` on PowerShell.

+ ### Tooling fallback

+ | Shell command | File-tool equivalent |

+ | --- | --- |

+ | `ls -la` | List the directory |

+ | `find`, `grep -r` | Search by pattern |

+ | `git mv` | Create at the destination, then delete the origin |

+ | `git rm` | Delete the file |

+ | `chmod +x` | Report to the user as a manual step |

+ When the fallback is used, state it in the final report — permissions and git history will differ.

+ ## Phase 0 — Pre-flight

+ No writes are allowed in this phase.

+ ```bash

+ # 0.1 — Confirm this is a git repository and nothing is at risk

+ git rev-parse --is-inside-work-tree

+ git status --short

+ # 0.2 — Check the current branch (must NOT be main/master/develop)

+ git rev-parse --abbrev-ref HEAD

+ # 0.3 — Create the dedicated branch

+ git checkout -b feature/{AgentLLM}-{YYYYMMDD}-bootstrap-claude-harness

+ ```

+ Decision points:

+ - `git status` shows unrelated changes → **stop** and ask. Never mix work.

+ - Already on an appropriate `feature/*` branch from the same session → reuse it instead of creating another.

+ - Not a git repository → report it and ask whether to continue. Migration without `git mv` and `git rm` loses history.

+ ## Phase 1 — Discovery

+ No writes are allowed in this phase. Every item must cite the **source file** that proves it. Where no evidence exists, write `NOT FOUND` and turn it into a question for the human.

+ ### 1.1 Repository analysis

+ Capture, with sources:

+ - Directory structure, root and main subdirectories

+ - Tech stack with versions — languages, frameworks, runtimes

+ - Architectural patterns — Clean Architecture, MVVM, microservices

+ - External integrations — APIs, cloud, authentication, message brokers

+ - CI/CD pipelines and the commands a merge requires

+ - Code conventions — naming, formatting, testing — and minimum coverage

+ - Protected branches and the branching strategy already practised

+ - Formatter and linter actually configured in the repo

+ - **Context sources already present** — documentation, knowledge bases, MCP servers (`.mcp.json`), state or memory files. Map them against the context sources inventory in Phase 3.

+ ```bash

+ # Root overview, including hidden entries

+ ls -la

+ # Most common stack manifests

+ ls package.json pnpm-lock.yaml requirements.txt pyproject.toml go.mod pom.xml \

+ build.gradle *.csproj *.sln Cargo.toml composer.json 2>/dev/null

+ # CI/CD

+ ls -la .github/workflows .gitlab-ci.yml Jenkinsfile azure-pipelines.yml 2>/dev/null

+ # Directory map, two levels, ignoring noise

+ find . -maxdepth 2 -type d \

+ -not -path '*/node_modules/*' -not -path '*/.git/*' \

+ -not -path '*/dist/*' -not -path '*/bin/*' -not -path '*/obj/*' | sort

+ ```

+ Inspect `runs-on:` in the CI workflows. Never assume `ubuntu-latest` — corporate repositories often use self-hosted runners, and the wrong assumption makes workflows fail silently.

+ ### 1.2 Legacy harness inventory

+ Mandatory. Detect every harness artifact already present, in any format.

+ ```bash

+ # Legacy harness artifacts at the root and in dedicated directories

+ ls -la CLAUDE.md AGENTS.md DEVIN.md GEMINI.md copilot-instructions.md \

+ .cursorrules .cursorignore .aiignore .claudeignore .devinignore \

+ .windsurfignore 2>/dev/null

+ ls -la .claude .agents .devin .windsurf 2>/dev/null

+ # Harness directories LOOSE at the root (must move into .claude/)

+ ls -la skills rules knowledge memory 2>/dev/null

+ # Legacy frontmatter that requires conversion

+ grep -rl "applyTo" --include="*.md" . 2>/dev/null # convert to paths:

+ grep -rl "allowed-tools" --include="*.md" . 2>/dev/null # convert to tools:

+ ```

+ Record every hit as one line: **origin → destination in `.claude/` → action (move / convert / merge / remove)**.

+ Idempotency check: when `.claude/` already exists and no legacy artifact is found, the run is a **completion**, not a migration. Generate only what is missing.

+ ### 1.3 Gap classification

+ | Bucket | Meaning | Action |

+ | --- | --- | --- |

+ | **Generate** | Artifact missing and owned by this skill | Add to the generation plan |

+ | **Complete** | Artifact exists but is partial | Extend without overwriting |

+ | **Migrate** | Legacy artifact holding useful content | Move, convert, then remove the origin |

+ | **Ask** | Requires a human decision — missing test command, coverage target, license | Raise as a `TODO:` at the gate |

+ A missing command becomes the literal placeholder `TODO: define test command` plus an Ask item. Never hallucinate a plausible command.

+ ### 1.4 Discovery gate

+ Present exactly this summary and **stop** until the human confirms.

```text

## Discovery Summary

- - Stack: [languages and frameworks found]

+ - Stack: [languages, frameworks, versions]

- Architecture: [patterns identified]

- - CI/CD: [pipelines found]

- - Existing harness: [files already present]

- - Conventions: [naming, testing, branching]

- - Gaps: [what's missing for a complete harness]

+ - CI/CD: [pipelines found + runner]

+ - Conventions: [naming, testing, coverage, branching]

+ - Existing harness: [files and directories found, any format]

+ - Context sources: [instructions, state/memory, knowledge, MCP — present or missing]

+ ## Migration Plan (origin → destination → action)

+ | Origin | Destination | Action |

+ |--------|-------------|--------|

+ | ... | ... | move / convert / merge / remove |

+ ## Artifacts to GENERATE (do not exist)

+ - [list]

+ ## Gaps and TODOs (no evidence in the repo)

+ - [questions for the human]

```

- Wait for confirmation before Step 2.

+ This is the **only mandatory pause**. Nothing is created, moved or deleted until this output is confirmed. After confirmation, Phases 2 to 4 run autonomously.

- ## Step 2 — Artifacts to Generate

+ ## Phase 2 — Migration

- Generate only what is missing or needs restructuring. Adapt structure to discovery findings.

+ ### 2.1 Prepare the destination

- ### A. `CLAUDE.md` — Single Source of Truth (root)

+ ```bash

+ mkdir -p .claude/agents .claude/skills .claude/commands \

+ .claude/hooks .claude/memory .claude/knowledge .claude/rules \

+ .specs

+ ```

- **Limit:** max 500 lines. Single point of truth for Claude Code (and Devin CLI, which reads it natively).

+ ### 2.2 Migration reference

+ Canonical mappings, naming/collision rules, frontmatter conversions and removal commands are in [`references/migration-map.md`](references/migration-map.md).

+ Execute the commands from that reference only for the artifacts actually migrated, and only after confirming their useful content exists at the destination. Removal is verified in Phase 4.

+ ## Phase 3 — Artifacts

+ Generate what is missing; complete what is partial; never duplicate what is already correct.

+ ### 3.1 Target structure

+ ```text

+ |.

+ ├── AGENTS.md # Thin symlink/reference to CLAUDE.md for non-Claude platforms

+ ├── CLAUDE.md # Single source of truth, max 1000 lines

+ ├── .specs/

+ │ └── SPEC-{YYYYMMDD}-{feature}.md # Spec-Driven Development specs

+ └── .claude/

+ ├── agents/{name}.md # Sub-agents — review, plan, test are mandatory

+ ├── skills/{slug}/SKILL.md # Modular skills

+ ├── commands/{slug}.md # Custom slash commands

+ ├── hooks/{slug}.sh # Hook scripts wired in settings.json

+ ├── memory/ # Short-term and long-term memory

+ ├── knowledge/{slug}.md # On-demand knowledge sources

+ ├── rules/global-rules.md # Always-on rule

+ ├── rules/{domain}.md # Path-scoped rules

+ ├── CONTEXT.md # Context engineering strategy

+ ├── RULES.md # Guardrails summary

+ ├── MEMORY.md # Memory protocol documentation — no state/history

+ ├── TOOLS.md # Tools and MCP inventory

+ ├── WORKFLOWS.md # Automation workflows

+ ├── README.md # Harness infrastructure documentation

+ └── settings.json # Permissions, hooks, env — versioned

+ ```

+ | --- | --- | --- | --- |

+ | `.claude/memory/{YYYYMMDD}-memory.md` | **Yes** | On-demand (last 3) | Always — today's file |

+ | `.specs/SPEC-{YYYYMMDD}-{feature}.md` | Conditional | Written by `plan` sub-agent | One per feature before implementation |

+ | `.claude/rules/{domain}.md` | Conditional | Path-scoped (with `paths:`) | One per relevant stack |

+ | `.claude/skills/{slug}/SKILL.md` | Conditional | On-demand by relevance | One per recurring domain or flow |

+ | `.claude/knowledge/{slug}.md` | Conditional | On-demand when referenced | If dense reusable knowledge exists |

+ | `.claude/commands/{slug}.md` | Conditional | Slash command | If a clear repetitive flow exists |

+ | `.claude/hooks/{slug}.sh` | Conditional | Event wired in `settings.json` | Only for real automation — never speculative |

+ | `docs/*.md` | Recommended | On-demand reference | If no system documentation exists |

+ > **Loading notes**

+ > - **Native always-on** — loaded automatically by Claude Code: `CLAUDE.md` (root) and `.claude/rules/global-rules.md` (no `paths:`).

+ > - **Always-on via `CLAUDE.md` reference** — the Agent Loop in `CLAUDE.md` must explicitly instruct the agent to read these files at the start of every session.

+ > - **On-demand** — loaded only when the current task or a rule/skill explicitly references them.

+ > ⚠️ **Must not remain in the repository:** `.agents/`, `AGENTS.md` as source of truth, `DEVIN.md`, `GEMINI.md`, `.cursorrules`, `.cursorignore`, `.windsurf/`, `.windsurfignore`, `.aiignore`, `copilot-instructions.md`, `.claudeignore`, `.devinignore`, or `skills/`, `rules/`, `knowledge/`, `memory/` directories outside `.claude/`. Admissible artifacts outside `.claude/` are: a thin `AGENTS.md` (reference to `CLAUDE.md`), a minimal `.devin/config.json`, and thin platform-specific directories (`.opencode/`, `.cursor/`, `.gemini/`) only when required.

+ > `.claudeignore` is **not read** by the Claude Code CLI. Exclusions go to `permissions.deny` as `Read(...)` patterns. Branch protection is server-side plus `global-rules.md` — never a local hook.

+ ### 3.2 CLAUDE.md

+ Root file, **max 1000 lines**. A context router: it references other files instead of duplicating them. Repository-specific, nothing generic.

+ > **Always-on contract:** any instruction that must be loaded every session must live in `CLAUDE.md` or in `.claude/rules/global-rules.md` (no `paths:`). All other `.claude/*.md` files are on-demand unless the Agent Loop in `CLAUDE.md` explicitly reads them.

```markdown

# CLAUDE.md

## Mission

- [Project description + agent persona]

+ Project description and agent persona.

## Tech Stack

- [Languages, frameworks, versions]

+ Languages, frameworks and exact versions.

## Paths per Platform

|---|---|---|---|---|

+ ## Harness Structure

+ | Component | Location | Loading |

+ |---|---|---|

+ | Root instructions | `CLAUDE.md` | Native always-on |

+ | Global rules | `.claude/rules/global-rules.md` | Native always-on (no `paths:`) |

+ | Domain rules | `.claude/rules/{domain}.md` | Path-scoped (with `paths:`) |

+ | Skills | `.claude/skills/{name}/SKILL.md` | On-demand by relevance |

+ | Sub-agents | `.claude/agents/{name}.md` | By `description` or via the Task tool |

+ | Commands | `.claude/commands/{name}.md` | Slash commands |

+ | Hooks | `.claude/hooks/{name}.sh` | Events wired in `settings.json` |

+ | Knowledge | `.claude/knowledge/*.md` | On-demand when referenced |

+ | Context Engineering | `.claude/CONTEXT.md` | Always-on — read at session start (see Agent Loop) |

+ | Guardrails | `.claude/RULES.md` | Always-on — read at session start (see Agent Loop) |

+ | Memory state | `.claude/memory/memory.md` | Short-term always-on via read ritual |

+ | Memory history | `.claude/memory/{YYYYMMDD}-memory.md` | Long-term, on-demand (last 3 files) |

+ | Memory docs | `.claude/MEMORY.md` | On-demand protocol reference — no state or history |

+ | Tools and MCP | `.claude/TOOLS.md` | On-demand reference |

+ | Workflows | `.claude/WORKFLOWS.md` | On-demand reference |

+ | Harness README | `.claude/README.md` | On-demand reference |

+ ## Context Engineering

+ Loading priority, token budget with a 20% output reserve, chunking for files

+ over 500 lines, and the compaction ladder.

+ ## Memory Protocol

+ - **State** (short-term): `.claude/memory/memory.md` — overwritten every session, max 100 lines.

+ - **History** (long-term): `.claude/memory/{YYYYMMDD}-memory.md` — append-only, single source of truth for decisions, technical debt and lessons learned.

+ - **Protocol docs** (on-demand): `.claude/MEMORY.md` — reference only, no state or history.

+ Read `memory.md` and the 3 most recent long-term files at session start. Write on every verified checkpoint, decision, mistake or promotion.

## Code Standards

- - DO / DON'T / Principles (discovered from repo)

+ DO / DON'T / principles discovered in the repository.

## Hard Rules

- [Blocking restrictions — protected branches, immutable files, forbidden secrets]

+ Immediate-block restrictions: protected branches, immutable files, secrets.

## Soft Rules

- [Warning + confirmation — modify Dockerfile, delete files, prod deploy]

+ Warning plus confirmation.

## Agent Loop

- [Choose pattern — ReAct / Plan-and-Execute / Reasoning Sandwich]

+ Plan-and-Execute:

+ 1. Receive the task.

+ 2. Confirm `CLAUDE.md` is loaded (native always-on).

+ 3. Confirm `.claude/rules/global-rules.md` is loaded (native always-on, no `paths:`).

+ 4. Read `.claude/memory/memory.md` and the 3 most recent long-term files.

+ 5. Read `.claude/CONTEXT.md` and `.claude/RULES.md` (always-on references).

+ 6. Load pattern-matched skills and rules.

+ 7. If the task is a feature/change, invoke the `plan` sub-agent to produce `.specs/SPEC-{YYYYMMDD}-{feature}.md`; read the SPEC and wait for approval before implementing.

+ 8. Verify guardrails in `settings.json` and hooks.

+ 9. Execute within permissions.

+ 10. Verification loop: lint → test → CI.

+ 11. Adjust — at most 2 iterations before escalating to a human.

+ 12. Update memory and commit the checkpoint.

+ ## Always-on Connection

+ Claude Code natively loads only `CLAUDE.md` and `.claude/rules/*.md` (rules without `paths:` are always-on). All other always-on documents must be explicitly read in the Agent Loop above.

+ **Native always-on:**

+ - `CLAUDE.md` (root)

+ - `.claude/rules/global-rules.md` (no `paths:`)

+ **Always-on via CLAUDE.md read ritual:**

+ - `.claude/memory/memory.md`

+ - `.claude/CONTEXT.md`

+ - `.claude/RULES.md`

+ **On-demand:**

+ - `.claude/TOOLS.md`, `.claude/WORKFLOWS.md`, `.claude/README.md`

+ - `.claude/knowledge/*.md`

+ - `.claude/MEMORY.md` — protocol reference only

+ - `.claude/memory/{YYYYMMDD}-memory.md` (last 3 only)

## Response Style

- [Format, language, verbosity]

+ Format, language, verbosity.

## References

- - [docs/](../docs/) — System documentation (technologies, packages, plugins, features)

- - [.claude/rules/](.claude/rules/) — Guardrails and permissions

- - [.claude/skills/](.claude/skills/) — Agent skills

+ - [.claude/rules/](.claude/rules/) — native rules

+ - [.claude/skills/](.claude/skills/) — agent skills

+ - [.claude/knowledge/](.claude/knowledge/) — knowledge sources

+ - [.claude/memory/](.claude/memory/) — cross-session memory

+ - [.claude/CONTEXT.md](.claude/CONTEXT.md) — context engineering

+ - [.claude/RULES.md](.claude/RULES.md) — guardrails

+ - [.claude/MEMORY.md](.claude/MEMORY.md) — memory protocol documentation

+ - [.claude/TOOLS.md](.claude/TOOLS.md) — tools and MCP

+ - [.claude/WORKFLOWS.md](.claude/WORKFLOWS.md) — automation

+ - [.specs/](.specs/) — SPEC SDD files

```

- **Principles:**

- - Context router — reference other files, don't duplicate

- - Repo-specific — nothing generic

- - Hard rules must be computationally verifiable (not just prompts)

+ > Never create `AGENTS.md`, `DEVIN.md`, `GEMINI.md`, `.cursorrules` or `copilot-instructions.md` as a source of truth. Only `CLAUDE.md` plus a thin `AGENTS.md` reference.

- ### B. Platform Files (root)

+ ### 3.3 AGENTS.md (thin reference or symlink)

- | File | Platforms | Content |

- |---|---|---|

- | `CLAUDE.md` | Claude Code | Single Source of Truth (base instructions) |

- | `AGENTS.md` | Devin CLI/Desktop, OpenCode, Cursor, Gemini CLI, Antigravity IDE/CLI | Thin reference to `CLAUDE.md` content (or symlink) |

+ For non-Claude platforms (Devin, OpenCode, Cursor, Gemini, Antigravity), create `AGENTS.md` as either a symlink to `CLAUDE.md` or a thin reference:

- **Rule:** `CLAUDE.md` is the main file for Claude Code. `AGENTS.md` is the main file for all other platforms. To avoid duplication, write the full content in `CLAUDE.md` and create `AGENTS.md` as either:

- 1. A symlink: `ln -s CLAUDE.md AGENTS.md` (preferred on Linux/macOS)

- 2. A thin reference file that includes the same content

+ ```bash

+ # Preferred on Linux/macOS

+ ln -s CLAUDE.md AGENTS.md

+ ```

- **`AGENTS.md` template (thin reference):**

+ Or, if a separate file is required:

```markdown

# AGENTS.md

-

-

+

+

[Same content as CLAUDE.md — mission, tech stack, paths, rules, agent loop, etc.]

```

- > ⚠️ **Keep `CLAUDE.md` and `AGENTS.md` in sync.** If symlinked, changes propagate automatically. If separate files, update both.

- > ⚠️ **Do NOT create** `.cursorrules` (legacy, replaced by `AGENTS.md`), `GEMINI.md` (replaced by `AGENTS.md`), `copilot-instructions.md` (replaced by `AGENTS.md`), or `.geminiignore`/`.cursorignore`/`.aiignore` — these are legacy formats superseded by the Agent Skills specification.

+ > ⚠️ Keep `CLAUDE.md` and `AGENTS.md` in sync. If symlinked, changes propagate automatically. If separate files, update both. Do NOT create `.cursorrules`, `GEMINI.md`, `copilot-instructions.md`, `.geminiignore`, `.cursorignore`, `.aiignore` or `.opencodeignore` — these are legacy formats.

- ### C. `.claude/CONTEXT.md` — Context Engineering

+ ### 3.4 .claude/CONTEXT.md

Defines how context is delivered to the agent.

| Strategy | When | Examples |

- |---|---|---|

- | **Always-on** | Always loaded | CLAUDE.md, hard rules |

- | **Pattern-matched** | By file type | `applyTo: '**/*.cs'` → C# rules |

- | **On-demand** | When requested | Knowledge, design docs |

- | **Progressive disclosure** | Large codebases | Dir map → headers → content |

+ | --- | --- | --- |

+ | **Native always-on** | Loaded by Claude Code | `CLAUDE.md`, `.claude/rules/global-rules.md` |

+ | **Always-on via read ritual** | Read in Agent Loop step 5 | `.claude/memory/memory.md`, `.claude/CONTEXT.md`, `.claude/RULES.md` |

+ | **Pattern-matched** | By file type | `paths: '**/*.cs'` → C# rules |

+ | **On-demand** | When referenced | `.claude/knowledge/*.md`, `.claude/TOOLS.md`, `.claude/WORKFLOWS.md`, `.claude/README.md`, `docs/`, long-term memory |

+ | **Progressive disclosure** | Large codebases | Directory map → headers → content |

- **Must include:**

+ Must include:

- Loading priority hierarchy

- Token budget (reserve 20% for output)

- Chunking strategy (files >500 lines)

- Context compaction: budget reduction → snip → microcompact → collapse → auto-compact

- ### D. `.claude/RULES.md` — Guardrails

+ ### 3.5 .claude/RULES.md

> Principle: prefer computational controls over prompts. Lint and CI cannot be ignored; prompts can.

```markdown

# RULES.md

## Hard Rules (immediate block)

[Protected branches, immutable workflows, etc.]

## Soft Rules (warning + confirmation)

[Modify Dockerfile, prod deploy, delete files]

## Per-Environment Permissions

[dev/staging/prod — adapted to what exists]

## Tool Permissions

- Read-only by default

- Write via approval gates

- Execute in sandbox with logging

```

- ### E. `.claude/MEMORY.md` — State Management

+ ### 3.6 .claude/MEMORY.md

- > ❗ Never store PII, secrets, or credentials.

- > ❗ Verify just-in-time against current code before using cross-session memory.

+ > **On-demand protocol documentation.** `MEMORY.md` documents the `.claude/memory/` protocol. It must not store state or history — those live exclusively in `.claude/memory/`.

+ > Never store PII, secrets, or credentials.

+ > Verify just-in-time against current code before using cross-session memory.

```markdown

# MEMORY.md

- ## Technical Decisions

+ ## Purpose

+ Reference documentation for the `.claude/memory/` protocol.

- ## Technical Debt

- | Item | Impact | Priority |

+ ## Short-term memory

+ - File: `.claude/memory/memory.md`

+ - Lifetime: current session, **overwritten**

+ - Max: 100 lines

+ - Content: working state only (branch, baseline, blockers, next action)

- ## Lessons Learned

- | Context | Mistake | How to Avoid |

+ ## Long-term memory

+ - File: `.claude/memory/{YYYYMMDD}-memory.md`

+ - Lifetime: permanent, **append-only**, one file per day

+ - Content: decisions, lessons, technical debt, discoveries, checkpoints

+ - **Single source of truth for durable records**

- ## Cleanup Policies

- - Memories from deleted branches must be discarded

- - Outdated facts must be removed

+ ## Read protocol

+ At session start: read `memory.md`, then the 3 most recent dated files descending by filename. Never read the whole folder. Treat long-term memory as a hint, not truth.

+ ## Write triggers

+ | Trigger | Write to | What |

+ |---|---|---|

+ | Verified checkpoint or commit | Both | Update `memory.md`; append to `## Checkpoints` |

+ | Decision taken | Long-term | Append to `## Decisions` with rationale and alternatives discarded |

+ | Mistake corrected | Long-term | Append to `## Lessons learned` |

+ | Out-of-scope problem found | Short-term | Add to `memory.md` blockers; do not fix now |

+ | Promotion (`memory.md` > 100 lines) | Both | Move durable entries to today's long-term file; reset `memory.md` |

+ ## Security

+ - Zero secrets, tokens, passwords, connection strings or private keys

+ - Zero PII: no customer names, documents, account numbers or identifiers

+ - Reference identifiers, never values

+ ## Cleanup policies

+ - Memories from deleted branches must be superseded

+ - Outdated facts must be corrected by appending a `SUPERSEDED:` entry

```

**Three memory tiers:**

- |---|---|---|---|

+ | --- | --- | --- | --- |

+ | **Episodic** | Cross-session | Experiences, decisions, debt, lessons | `.claude/memory/{YYYYMMDD}-memory.md` |

- ### F. `.claude/TOOLS.md` — Tools and MCP

+ ### 3.7 .claude/TOOLS.md

**Tool design principles:** named for what they do (not how), minimal schemas, JSON errors, idempotent operations.

| Category | Risk | Policy |

- |---|---|---|

+ | --- | --- | --- |

| **Read-only** (search, list) | Low | Free |

| **Write** (edit, create, delete) | Medium | Confirmation |

| **Execute** (run, build, deploy) | High | Sandboxed + logged |

| **External** (APIs, webhooks) | Variable | Rate-limited |

Include: available tools, MCP servers, external APIs (required headers, timeouts, rate limits).

- ### G. `.claude/WORKFLOWS.md` — Automation

+ ### 3.8 .claude/WORKFLOWS.md

Document discovered or recommended workflows:

- Preconditions and success criteria per workflow

- Trigger conditions (issue opened, PR created, schedule)

- Verification loop: `Agent Output → Lint → Tests → CI → LLM Judge → Human`

- Rollback strategy

- If repo uses GitHub Actions, consider **gh-aw** (Agentic Workflows) with safe-outputs, sanitized context expressions, and bash narrowlist tool allow-listing. See [GitHub Agentic Workflows](https://github.com/github/gh-aw).

- ### H. Ignore Files

- > ❗ **`.claudeignore`, `.devinignore`, `.cursorignore`, `.geminiignore`, `.opencodeignore`, `.aiignore` are NOT read by most CLIs.** Exclude files via **`permissions.deny`** (where supported) and rely on `.gitignore` for discovery. Do not generate dedicated ignore files.

+ If the repo uses GitHub Actions, consider **gh-aw** (Agentic Workflows) with safe-outputs, sanitized context expressions, and bash narrowlist tool allow-listing. See [GitHub Agentic Workflows](https://github.com/github/gh-aw).

- **Correct mechanism by platform:**

+ ### 3.9 .claude/README.md

- | Platform | Where | How |

- |---|---|---|

- | **Claude Code** | `.claude/settings.json` | `permissions.deny` with `Read(...)` patterns |

- | **Devin CLI** | `.devin/config.json` | `permissions.deny` (`Read(...)`/`Exec(...)`) |

- | **OpenCode** | `.opencode/config.json` | `permissions.deny` (if supported) or `.gitignore` |

- | **Cursor** | `.cursor/settings.json` | `permissions.deny` (if supported) or `.gitignore` |

- | **Gemini CLI / Antigravity** | `.gemini/settings.json` | `.gitignore` (no native deny support) |

+ - File structure diagram

+ - How skills are loaded (tripartite description)

+ - How to add a new skill (step by step)

+ - Platform compatibility table

+ - How to run the verification loop locally

- > Files matching `deny` patterns are excluded from discovery, search, and reading. `.gitignore` is respected for file discovery on all platforms.

+ ### 3.10 .claude/settings.json

- **Base content** (adapt to discovered stack):

+ Computational guardrails. `settings.json` cannot be ignored; a prompt can.

- ```gitignore

- # Build outputs

- bin/ obj/ dist/ build/ out/

+ ```json

+ {

+ "permissions": {

+ "allow": ["Read", "Grep", "Glob"],

+ "ask": ["Edit", "Write", "Bash(git commit:*)", "Bash(git push:*)"],

+ "deny": []

+ },

+ "hooks": {}

+ }

+ ```

- # Dependencies

- node_modules/ .venv/ __pycache__/

+ - `deny` starts **empty**. Populate it only when the project really needs to exclude files from discovery, for example `Read(./.env)` or `Read(**/*.key)`. No speculative restrictions.

+ - **Branch protection** for `main`, `master`, `develop` and protection of `/.github/workflows` are handled **server-side** by repository branch protection plus the prompt level in `global-rules.md`. A glob in `permissions.deny` cannot scope the branch of a `git push`.

+ - File exclusion goes through `permissions.deny`, never `.claudeignore`. `.gitignore` is respected for discovery, so already-ignored build outputs need no explicit `deny`.

+ - `settings.local.json` holds local overrides and is **not** versioned — add it to `.gitignore`.

- # Version control

- .git/

+ ```bash

+ python3 -c "import json; json.load(open('.claude/settings.json')); print('settings.json OK')"

+ ```

- # Secrets

- .env .env.* *.key *.pem secrets.*

+ **Tools and MCP.** Classify by risk when defining permissions and documenting tools.

- # IDE

- .vs/ .idea/

+ | Category | Risk | Policy |

+ | --- | --- | --- |

+ | Read-only (search, list) | Low | Free — `allow` |

+ | Write (edit, create, delete) | Medium | Confirmation — `ask` |

+ | Execute (run, build, deploy) | High | Sandboxed and logged |

+ | External (APIs, webhooks, MCP) | Variable | Rate-limited |

- # Test artifacts

- TestResults/ coverage/

+ Tool design: named for what they do, not how; minimal schemas; JSON errors; idempotent operations. MCP servers are declared in `.mcp.json` at project scope or in `.claude/settings.json`, with required headers, timeouts and rate limits documented in `CLAUDE.md` or `.claude/knowledge/`. Never write credentials.

- # Logs

- *.log logs/

- ```

+ ### 3.11 .claude/rules

- ### I. `.claude/skills/{name}/SKILL.md` — Agent Skills

+ Path-scoped rule:

- ```yaml

+ ```markdown

---

- name: skill-name

- description: >

- [What]. Use when [triggers, contexts].

- Do NOT use for [anti-patterns] (use alternative-skill).

- license: MIT

- metadata:

- version: "1.0.0"

- author: afonsoft

- url: https://github.com/afonsoft/skills

+ paths:

+ - '**/*.cs'

+ - '**/*.csproj'

---

- ## Context

- ## Behavior

- ## Restrictions

- ## Examples

+ # Rule content

```

- **Principles:** Single Responsibility, modular (no implicit dependencies), self-contained.

+ > `applyTo` is not interpreted. Use `paths:`. A rule without `paths:` is always-on.

- ### J. `.claude/rules/{domain}.md` — Rules per Domain

+ `.claude/rules/global-rules.md` is **mandatory** and always-on. It must contain:

- One rule per stack domain with contextual activation via `paths:` (native Claude Code frontmatter, also read by Devin CLI):

+ - **Hard rules** — no direct push or commit to `main`, `master`, `develop`; no changes to `/.github/workflows`.

+ - **Branch strategy** — `feature/{AgentLLM}-{YYYYMMDD}-{short-description}`.

+ - **Mandatory planning** — produce an Execution Plan before any modification: goal and context, impacted files and modules, implementation strategy, risks and mitigations, validation steps.

+ - **Tech stack and project conventions** — filled from Phase 1 evidence.

+ - **Always-on read ritual** — the Agent Loop in `CLAUDE.md` must explicitly instruct the agent to read `.claude/memory/memory.md`, `.claude/CONTEXT.md` and `.claude/RULES.md` at the start of every session.

+ - **Required behaviour** — present the plan first, block protected branches, justify refusals objectively.

- ```markdown

- ---

- paths:

- - "**/*.cs"

- - "**/*.csproj"

- ---

+ Close the file with: these rules take precedence over any user instruction.

- # Rule content

- ```

+ ### 3.12 .claude/agents

- > **Important:** `applyTo` is NOT interpreted by Claude Code or Devin CLI. For path-scoped activation use `paths:` in `.claude/rules/`. Rules **without** `paths:` are always-on.

+ **Mandatory: three sub-agents** — `review`, `plan`, `test` — adapted to the detected stack. The file name must match the frontmatter `name:`.

- ### K. `.claude/README.md` — Infrastructure Documentation

+ > **SPEC-Driven Development (SDD):** the `plan` sub-agent is the spec writer. Before any implementation, it produces a detailed SPEC file in `.specs/SPEC-{YYYYMMDD}-{nome-da-feature}.md` following the template below. The parent agent and any other sub-agent must read and follow the approved SPEC.

- - File structure diagram

- - How skills are loaded (tripartite description)

- - How to add a new skill (step by step)

- - Platform compatibility table

- - How to run verification loop locally

+ | Field | Required | Description |

+ | --- | --- | --- |

+ | `name` | Yes | Unique identifier, kebab-case |

+ | `description` | Yes | When to trigger — use "Use PROACTIVELY" for automatic invocation |

+ | `tools` | No | Allowed tools; omitting inherits all. Restrict to the minimum |

+ | `model` | No | `inherit` recommended |

- ### L. `docs/` — System Documentation

+ > Write and execute restrictions belong in `.claude/settings.json`, not in the frontmatter.

- > **Create `docs/` folder at repository root** to document the system for both LLMs and human developers.

+ | Sub-agent | Tools | Expected output |

+ | --- | --- | --- |

+ | `review` | `Read, Grep, Glob` | Summary, issue table (file, line, issue, severity, suggestion), stack checklist, verdict APPROVED / REQUEST CHANGES / NEEDS REVISION |

+ | `plan` | `Read, Grep, Glob, WebFetch, Write` | SPEC SDD in `.specs/SPEC-{YYYYMMDD}-{feature}.md` (sections 0-9) plus a concise Execution Plan summary. Do not implement — only write the spec. |

+ | `test` | `Read, Grep, Glob, Bash` | Test files created, cases, execution results, coverage against the project minimum with PASS/FAIL |

- **Purpose:** Provide comprehensive system documentation to help LLMs understand the system architecture, technologies, and functionality.

+ Each sub-agent declares a **verification loop** the parent agent must run. For `review`: confirm every modified file was covered, confirm each suggestion is actionable, confirm severity matches the final verdict.

- **Required documentation files:**

+ Keep only the stack specializations relevant to the repository. Design principles: single responsibility, context isolation, structured I/O, tool minimization, bounded execution.

+ #### `plan` sub-agent

+ Frontmatter for the spec-writer agent. It must **not** implement — only produce and, if requested, revise the SPEC.

```markdown

- docs/

- ├── README.md # System overview and architecture

- ├── technologies.md # Technologies, frameworks, versions

- ├── packages.md # NPM packages, NuGet packages, dependencies

- ├── plugins.md # Plugins, extensions, integrations

- ├── features.md # System features and functionality

- └── api.md # API documentation (if applicable)

- ```

+ ---

+ name: plan

+ description: >

+ Use PROACTIVELY when the user asks for a new feature, change, bugfix or refactor.

+ Reads repository context, asks clarifying questions, then writes a SPEC SDD to

+ `.specs/SPEC-{YYYYMMDD}-{feature}.md` and returns a concise Execution Plan.

+ tools:

+ - Read

+ - Grep

+ - Glob

+ - WebFetch

+ - Write

+ ---

- **Content guidelines:**

+ # plan — SPEC-Driven Development writer

- - **Neutral language** — suitable for both LLMs and human developers

- - **Evidence-based** — document what actually exists in the repository

- - **Structured format** — use tables, lists, and code blocks for clarity

- - **Always updated** — LLMs must consult and update this documentation when making changes

+ ## Purpose

+ Write a complete, implementation-ready SPEC before any code is produced. The SPEC is the single source of truth for the feature.

- **`docs/README.md` template:**

+ ## Workflow

+ 1. Receive the feature request.

+ 2. Read `CLAUDE.md`, `.claude/rules/global-rules.md`, relevant `.claude/rules/{domain}.md`, the target source files and existing specs.

+ 3. Ask clarifying questions until the scope is unambiguous. Use `[A DEFINIR]` only when the user explicitly declines to answer.

+ 4. Write `.specs/SPEC-{YYYYMMDD}-{feature}.md` using the template below.

+ 5. Return a short `Execution Plan` summary: goal, impacted files, key tasks, risks and validation steps.

+ 6. Do NOT implement. Stop after the SPEC `Status` in section 0 is set to `Approved` or when explicitly asked to proceed.

+ ## Verification loop

+ - The file name matches `SPEC-{YYYYMMDD}-{feature}.md`.

+ - All sections 0-9 are present (use `[A DEFINIR]` when required).

+ - Requirements are numbered, verifiable and include input/output.

+ - Acceptance criteria use BDD "Dado...quando...então" or "Given...when...then" format.

+ - Corporate / organization guardrails (section 8) are included when provided by the repo owner.

+ - The parent agent confirms the spec before implementation starts.

+ ```

+ ### 3.13 .claude/skills

+ One skill per recurring domain or flow. Skills enter the context only when relevant.

```markdown

- # System Documentation

+ ---

+ name: skill-name

+ description: >

+ What: what it does.

+ When: triggers and contexts.

+ Do NOT: when not to use it.

+ metadata:

+ version: '1.0.0'

+ ---

- ## Overview

- [System description, purpose, and scope]

+ ## Context

+ ## Behavior

+ ## Restrictions

+ ## Examples

+ ```

- ## Architecture

- [High-level architecture, modules, components]

+ Principles: single responsibility, modular with no implicit dependencies, self-contained.

- ## Directory Structure

- [Key directories and their purposes]

+ ### 3.14 .claude/commands

- ## Quick Start

- [How to set up and run the system]

+ Custom slash commands for repetitive flows, for example `/review`, `/changelog`, `/dod`. Markdown holding the command prompt; use `$ARGUMENTS` for parameters.

- ## References

- - [technologies.md](./technologies.md) — Technologies and versions

- - [packages.md](./packages.md) — Dependencies and packages

- - [plugins.md](./plugins.md) — Plugins and integrations

- - [features.md](./features.md) — System features

- ```

+ Recommended when the repository has an executable verification chain: `.claude/commands/dod.md` runs the real lint, test and build commands and reports the output as evidence. "It looks fine" is never accepted, and memory is updated before reporting done.

- **Rule:** When an LLM makes changes to the codebase, it must:

- 1. Consult the relevant `docs/` files before implementing changes

- 2. Update the `docs/` files after implementing changes to keep documentation current

+ ### 3.15 .claude/hooks

- ### M. `.claude/agents/` — Sub-Agents (REQUIRED)

+ Event-driven scripts registered in `settings.json`. Use them for automation that does **not** depend on the model: format or lint after an edit, fast tests, file normalization. Generate hooks **only when there is real, evident need** — no speculative hooks.

- > **REQUIRED.** Always create three specialized sub-agents: **Review**, **Plan**, and **Test**, in `.claude/agents/{name}.md`. Each sub-agent must be specialized according to the analyzed repository's stack and conventions.

+ > Never create branch-protection hooks or hooks blocking `/.github/workflows`. Those protections are server-side plus prompt level; a local hook is fragile.

- > **Unified structure:** Claude Code **and** Devin CLI share the **same folder and the same sub-agent format** (`.claude/agents/`). There is no per-platform translation or duplication — a single file per sub-agent serves both.

+ ```bash

+ #!/usr/bin/env bash

+ # PostToolUse(Edit|Write): run the project formatter when it exists

+ input=$(cat)

+ if command -v prettier >/dev/null 2>&1; then

+ prettier --write . >/dev/null 2>&1 || true

+ fi

+ exit 0

+ ```

- Sub-agents apply `Agent = Model + Harness` at finer granularity — reduced scope, isolated context, restricted permissions.

+ ```json

+ {

+ "hooks": {

+ "PostToolUse": [

+ { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": ".claude/hooks/format-on-edit.sh" }] }

+ ]

+ }

+ ```

- **Required sub-agents:**

+ ```bash

+ chmod +x .claude/hooks/*.sh

+ ```

- | Sub-agent | Purpose | When to use |

- |---|---|---|

- | `review.md` | Review code, PRs, changes with focus on quality, patterns, security, performance | Proactively after changes, before commit |

- | `plan.md` | Create detailed execution plans for complex tasks | Before multi-file changes, complex refactors, migrations |

- | `test.md` | Generate and run tests, validate coverage | When implementing features or refactors |

+ Hooks must be idempotent and emit JSON when the event requires a decision.

- **Frontmatter template:**

+ ### 3.16 .claude/knowledge

- ```yaml

- ---

- name: review

- description: >

- author: afonsoft

- url: https://github.com/afonsoft/skills

- Use PROACTIVELY to review code and PRs. Trigger after changes land,

- validate adherence to standards, and detect quality, security,

- and performance problems. Specialized in the repository's stack.

- tools: Read, Grep, Glob

- model: inherit

- ---

+ Self-contained knowledge sources per domain: code examples, architecture references and detailed patterns of the detected stack. Loaded on demand when referenced from `CLAUDE.md` or a rule. Every entry cites the source path it came from.

- ## Mission

- [Review mission specific to the repo's stack]

+ ### 3.17 docs/

+ ```text

+ docs/

+ ├── README.md # Overview and architecture

+ ├── technologies.md # Technologies, frameworks, versions

+ ├── packages.md # Dependencies

+ ├── plugins.md # Plugins, extensions, integrations

+ ├── features.md # Functionality

+ └── api.md # API, if applicable

```

- **Design principles:** Single Responsibility, Context Isolation, Structured I/O, Tool Minimization, Bounded Execution, internal Feedforward/Feedback loops.

+ **Rule:** when changing code, the agent must consult `docs/` before and update it after. State this rule in `CLAUDE.md`.

- ### N. `.devin/config.json` — Devin CLI Configuration (REQUIRED)

+ ### 3.18 .devin/config.json

- > **REQUIRED.** Always create the `.devin/config.json` file to enable Devin CLI to read the Claude Code configuration.

+ Only with Devin CLI integration. Devin reuses `.claude/` natively; this file just makes the import explicit.

- ```jsonc

+ ```json

{

- // Import Claude Code configs (REQUIRED)

- "read_config_from": {

- "claude": true

- },

+ "read_config_from": { "claude": true },

"permissions": {

"deny": [

"Read(./.env)",

"Read(**/*.key)",

"Read(**/*.pem)",

"Read(./.github/workflows/**)"

]

"hooks": {

- // block push to protected branches (glob does not parse branch)

"PreToolUse": [

{ "matcher": "Exec", "command": "bash .devin/hooks/block-protected-push.sh" }

]

}

```

- > ⚠️ **`read_config_from: { claude: true }` is REQUIRED** — without it, Devin CLI will not import Claude Code's rules, skills, and subagents.

- ### O. Platform-specific directories (for non-Claude targets)

+ > Do not duplicate `permissions` or `hooks` here — the source of truth is `.claude/settings.json`. Do not create `AGENTS.md`, `DEVIN.md` or `.devin/agents/`.

- Generate these only for platforms the repo targets. Each mirrors `.claude/` structure:

+ > ⚠️ `read_config_from: { claude: true }` is REQUIRED — without it, Devin CLI will not import Claude Code's rules, skills, and subagents.

- | Platform | Directory | Key files |

- |---|---|---|

- | OpenCode | `.opencode/` | `skills/`, `hooks/`, `config.json` (MCP under `mcp` key, not `mcpServers`) |

- | Cursor | `.cursor/` | `skills/`, `hooks/`, `mcp.json` (MCP under `mcpServers` key) |

- | Gemini CLI | `.gemini/` | `skills/`, `hooks/`, `settings.json`, `config/mcp_config.json` |

- | Antigravity IDE | `.gemini/` | Same as Gemini CLI (shared directory) |

- | Antigravity CLI (agy) | `.gemini/antigravity-cli/` | `skills/`, `hooks/` (separate from IDE) |

+ ### 3.19 Platform-specific directories

- > **MCP config gotchas per platform** — see `composio-mcp` or `notebooklm-mcp` skills for the full platform-quirks matrix (e.g. Devin Desktop uses `serverUrl` not `url`, OpenCode uses `environment` not `env`).

+ Generate platform-specific directories only when explicitly targeted. Directory layouts, MCP gotchas and Devin import details are in [`references/platform-quirks.md`](references/platform-quirks.md).

- ## Step 3 — Agent Loop

+ ### 3.20 Agent loop

- Define in CLAUDE.md. Choose pattern adapted to the repo:

+ Define **one** pattern in `CLAUDE.md`. Never leave the agent choosing between equivalent patterns.

- | Pattern | When to Use |

- |---|---|

+ | Pattern | Use when |

+ | --- | --- |

| **ReAct** (`Observe → Think → Act → Verify`) | Simple step-by-step tasks |

- | **Plan-and-Execute** | Long-horizon, multi-file tasks |

+ | **Plan-and-Execute** | Long-horizon, multi-file tasks — **default** |

| **Reasoning Sandwich** (`Deep Think → Execute → Deep Think → Verify`) | Complex tasks with critical verification |

- **Plan-and-Execute expanded:**

+ Plan-and-Execute, expanded:

- ```text

- 1. Receive task

- 2. Load CLAUDE.md + rules (always-on)

- 3. Load pattern-matched skills/rules

- 4. Present Execution Plan — wait for approval

- 5. Verify guardrails

- 6. Execute (sandbox + permissions)

- 7. Verification loop: lint → test → CI

- 8. Validate result

- 9. Adjust (max 2 iterations before escalating to human)

- 10. Update MEMORY.md

- ```

+ 1. Receive the task.

+ 2. Confirm `CLAUDE.md` is loaded (native always-on).

+ 3. Confirm `.claude/rules/global-rules.md` is loaded (native always-on, no `paths:`).

+ 4. Read `.claude/memory/memory.md` and the 3 most recent long-term files.

+ 5. Read `.claude/CONTEXT.md` and `.claude/RULES.md` (always-on references).

+ 6. Load pattern-matched skills and rules.

+ 7. If the task is a feature/change, invoke the `plan` sub-agent to produce `.specs/SPEC-{YYYYMMDD}-{feature}.md`; read the SPEC and wait for approval before implementing.

+ 8. Verify guardrails in `settings.json` and hooks.

+ 9. Execute within permissions.

+ 10. Verification loop: `lint → test → CI`.

+ 11. Adjust — at most 2 iterations before escalating to a human.

+ 12. Update memory and commit the checkpoint.

- ## Step 4 — Validation

+ ### 3.21 Context engineering

- ### Anti-Patterns

+ The complete context-engineering guide — context sources inventory, loading strategies, token budget, chunking, compaction ladder, memory tiers and governance controls — is in [`references/context-engineering.md`](references/context-engineering.md).

- | Anti-Pattern | Fix |

- |---|---|

- | Guardrails only in prompts | Add computational controls (permissions.deny, hooks) |

- | Unlimited context | Compact and curate with budget |

- | No verification loop | Mandatory lint/test/CI |

- | Monolithic agent | Split into sub-agents if needed |

- | Stateless sessions | MEMORY.md with checkpoints |

- | Verbose feedback | Filter to summary lines |

- | Duplicated info across files | Reference, don't copy |

- | `AGENTS.md` created separately from `CLAUDE.md` with duplicated content | Symlink `AGENTS.md` → `CLAUDE.md`, or maintain a thin reference to avoid duplication |

- | `GEMINI.md` / `.cursorrules` / `copilot-instructions.md` created | Remove — these are legacy formats superseded by `AGENTS.md` (Agent Skills specification) |

- | `.geminiignore` / `.cursorignore` / `.aiignore` / `.opencodeignore` created | Remove — not read by most CLIs; use `permissions.deny` or `.gitignore` instead |

+ ### 3.22 Memory protocol

- ### Quality Checklist

+ Mandatory in every harness. Two memory tiers inside `.claude/memory/` plus `.claude/MEMORY.md` as on-demand protocol documentation.

- - [ ] `CLAUDE.md` ≤ 500 lines, no generic content

- - [ ] `AGENTS.md` created (symlink or thin reference to `CLAUDE.md`) for non-Claude platforms

- - [ ] `permissions.deny` covers secrets and `/.github/workflows` (`.claude/settings.json` + `.devin/config.json`)

- - [ ] Hook de branch protection (main/master/develop) configured

- - [ ] Skills with tripartite description (What / Use when / Do NOT use)

- - [ ] Rules in `.claude/rules/` with `paths:` for activation (NOT `applyTo`)

- - [ ] Knowledge files are self-contained

- - [ ] Verification loop documented and executable

- - [ ] Interoperable across all target platforms (Claude Code, Devin, OpenCode, Cursor, Gemini, Antigravity)

- - [ ] All artifacts consistent with each other

- - [ ] No invented context — everything backed by repo evidence

+ | --- | --- | --- | --- |

+ | **Long-term** | `.claude/memory/{YYYYMMDD}-memory.md` | Permanent, **append-only** | Decisions, lessons, technical debt, discoveries, checkpoints |

- ## Output

+ The complete protocol — templates, read/write triggers, promotion, retention, security and migration — is in [`references/memory-protocol.md`](references/memory-protocol.md).

- When complete, list all generated artifacts grouped by location:

+ ### 3.23 .specs/ — SPEC SDD template

- ```text

- ## Generated Artifacts

+ > **Base:** Spec-Driven Development. The `plan` sub-agent copies the template from [`references/spec-sdd-template.md`](references/spec-sdd-template.md) to `.specs/SPEC-{YYYYMMDD}-{feature-name}.md` and fills it before any implementation.

- ### Root

- - [ ] CLAUDE.md (SSoT, ≤500 lines) — read natively by Claude Code

- - [ ] AGENTS.md (symlink to CLAUDE.md or thin reference) — read by Devin, OpenCode, Cursor, Gemini, Antigravity

- - [ ] .claude/settings.json (permissions, hooks)

- - [ ] .devin/config.json (read_config_from: { claude: true })

+ After `plan` writes the SPEC, the parent agent must:

- ### docs/

- - [ ] README.md — System overview and architecture

- - [ ] technologies.md — Technologies, frameworks, versions

- - [ ] packages.md — NPM packages, NuGet packages, dependencies

- - [ ] plugins.md — Plugins, extensions, integrations

- - [ ] features.md — System features and functionality

- - [ ] api.md — API documentation (if applicable)

+ 1. Read the SPEC and confirm every section is filled and coherent.

+ 2. Ask the user for approval or revision.

+ 3. When approved, set `Status` to `Approved` in section 0. Only after **Status = Approved** may implementation begin.

+ 4. When implementation begins, set `Status` to `In implementation` and keep it updated as a living document.

+ 5. During implementation, fill the DoD checklist (section 9). The DoD is complete when **all items are checked**.

+ 6. When the DoD is complete, set `Status` to `Done` in section 0 and immediately open the PR on branch `feature/...`.

+ 7. Any change during implementation must update the SPEC first.

- ### .claude/

- - [ ] settings.json (permissions, hooks)

- - [ ] rules/global-rules.md (always-on)

- - [ ] rules/{domain}.md (path-scoped with `paths:`)

- - [ ] agents/review.md (review sub-agent)

- - [ ] agents/plan.md (planning sub-agent)

- - [ ] agents/test.md (test sub-agent)

- - [ ] skills/{domain}/SKILL.md

- - [ ] knowledge/{domain}.md (optional)

+ ## Phase 4 — Validation

- ### .devin/

- - [ ] config.json (read_config_from: { claude: true })

- - [ ] hooks/block-protected-push.sh (optional, for branch protection)

+ ### 4.1–4.3 Validation

- ### Platform-specific (generate only for target platforms)

- - [ ] .opencode/ (skills, hooks, config — for OpenCode)

- - [ ] .cursor/ (skills, hooks, config — for Cursor)

- - [ ] .gemini/ (skills, hooks, config — for Gemini CLI / Antigravity IDE)

- - [ ] .gemini/antigravity-cli/ (skills, hooks — for Antigravity CLI / agy)

+ Run the validation script:

+ ```bash

+ bash .claude/skills/create-agent-harness/scripts/validate-harness.sh

```

- ## Additional Requirements

+ If the skill is being invoked from this repo, run it from the target repo after copying the script, or copy the commands manually from [`scripts/validate-harness.sh`](scripts/validate-harness.sh).

- ### Hard Rules (Immediate Block)

+ ### 4.4–4.7 Validation artifacts

- **Protected branches** — direct push/commit forbidden:

- - `main`

- - `master`

- - `develop`

+ Anti-patterns, quality checklist, final report template and handoff steps are in [`references/validation-artifacts.md`](references/validation-artifacts.md).

- **Protected workflows** — modification forbidden:

- - `/.github/workflows`

+ ## Examples

- ### Branch Strategy (Required)

+ **Input:** "prepare this Node repo for AI agents" — repository has no harness

- Every change must occur on a dedicated branch.

+ **Output:**

- **Naming convention:**

- ```

- feature/{AgentLLM}-{date}-{short-description}

- ```

+ 1. Pre-flight: clean tree confirmed, branch `feature/claude-{YYYYMMDD}-bootstrap-claude-harness` created.

+ 2. Discovery Summary citing `package.json` (Node, Jest, ESLint) and `.github/workflows/ci.yml` (`npm ci && npm test && npm run lint`); no legacy harness found. **Pause for confirmation.**

+ 3. After confirmation: `.claude/` created with `settings.json`, `rules/global-rules.md`, the three sub-agents, memory files, and `CLAUDE.md` written at the root.

+ 4. Validation 4.1 returns empty, 4.2 and 4.3 all pass.

+ 5. Commit on the feature branch and a pull request proposed to `main`.

- **Rules:**

- - `date` = YYYYMMDD

- - `short-description` → `short-description` in English, kebab-case

- - `AgentLLM` = agent/LLM name (devin, copilot, cursor)

- - Branch based on `main` or `master`

+ **Input:** "migrate the harness of this repo to Claude" — repository has `AGENTS.md` and `.agents/`

- ### Execution Plan (Required)

+ **Output:** discovery inventories every legacy artifact and prints the Migration Plan as `origin → destination → action`. After confirmation, `AGENTS.md` is merged into `CLAUDE.md`, `.agents/rules/*` become `.claude/rules/*` with `applyTo` converted to `paths:`, `.agents/subagents/*` become `.claude/agents/*` with `allowed-tools` converted to `tools`, and the originals are removed with `git rm`. Validation 4.1 proves nothing legacy survived.

- Before any modification, present a plan:

+ **Input:** "create a GEMINI.md for this repo"

- **Claude Code:** Use `/plan` before executing (activates Plan Mode for multi-file changes).

- **Devin CLI:** Use the `.claude/agents/plan.md` sub-agent for planning.

+ **Output:** refuse — Gemini-only harness is out of scope. Explain that the skill keeps a single source in `CLAUDE.md` plus a thin `AGENTS.md` reference; platform-specific directories are generated only when explicitly targeted and never as the source of truth.

- ```

- Execution Plan:

- 1. Goal and context

- 2. Impacted files and modules

- 3. Implementation strategy

- 4. Risks and mitigations

- 5. Validation steps (tests, build, lint)

- ```

+ **Input:** "the agent forgets what it did yesterday"

- ### Multi-Agent

+ **Output:** run the full flow, report that only the memory artifacts are missing, and generate `.claude/memory/memory.md`, `.claude/memory/{YYYYMMDD}-memory.md` and the wiring in `CLAUDE.md`, `global-rules.md` and the agent loop.

- **Use multi-agent whenever possible:**

- - Independent tasks → dispatch parallel agents (one per domain)

- - Code review → isolated-context reviewer sub-agent

- - Complex planning → planner sub-agent before execution

- - Testing → testing-specialized sub-agent

+ ## Troubleshooting

+ | Problem | Fix |

+ | --- | --- |

+ | Skill asks what to do instead of starting | Re-read "Immediate Execution" — Phase 0 starts on invocation |

+ | Current branch is `main`, `master` or `develop` | Stop and create the dedicated feature branch before any write |

+ | Working tree has unrelated changes | Stop and ask — never mix work |

+ | A command was not found during discovery | Write `TODO: define {command}` and raise it at the gate; never invent one |

+ | Legacy artifact still present after migration | Validation 4.1 returned non-empty — go back to Phase 2 |

+ | Rule is never applied | It uses `applyTo`; Claude Code only interprets `paths:` |

+ | Sub-agent is never triggered | `name:` does not match the file name, or `description` lacks "Use PROACTIVELY" |

+ | Files still readable despite `.claudeignore` | The CLI does not read that file — move the patterns to `permissions.deny` |

+ | Push to `main` was not blocked | Branch protection is server-side; a local hook cannot scope the branch of a `git push` |

+ | CI workflow fails silently | Inspect `runs-on:` — never assume `ubuntu-latest` in corporate repos |

+ | Re-running duplicated artifacts | Idempotency broken — detect what exists before generating |

+ | Memory folder grows and pollutes context | Read only the 3 most recent dated files; promotion keeps `memory.md` under 100 lines |

+ | Agent trusts a stale memory entry | Verify just-in-time against the code, then append a `SUPERSEDED:` entry |

## When to use related skills

| Need | Skill |

- |---|---|

+ | --- | --- |

| Build an MCP server for the agent | `building-mcp-servers` |

- | GitHub Actions agentic workflows (gh-aw) | [gh-aw](https://github.com/github/gh-aw) (external) |

+ | GitHub Actions agentic workflows (gh-aw) | `github-agentic-workflows` |

| Full Devin operational playbook with confirmation gates | `devin/playbooks/create-agents` |

+ | Composio MCP setup and auth | `composio-mcp` |

+ | NotebookLM MCP setup and auth | `notebooklm-mcp` |

## References

- [agents.md specification](https://agents.md/#examples)

- [OpenAI — Harness Engineering](https://openai.com/index/harness-engineering/)

- [Anthropic — Building Effective Agents](https://www.anthropic.com/research/building-effective-agents)

- [Claude Code — Memory & Imports](https://code.claude.com/docs/en/memory)

- [Claude Code — Subagents](https://code.claude.com/docs/en/sub-agents)

- [Claude Code — Settings & Permissions](https://code.claude.com/docs/en/settings)

+ - [Claude Code — Hooks](https://code.claude.com/docs/en/hooks)

+ - [Claude Code — Slash Commands](https://code.claude.com/docs/en/slash-commands)

- [Devin CLI — Extensibilidade](https://docs.devin.ai/pt-BR/cli/extensibility)

- [Martin Fowler — Harness Engineering](https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html)

- [LangChain — Anatomy of an Agent Harness](https://blog.langchain.com/the-anatomy-of-an-agent-harness/)

- [awesome-ai-conventions](https://github.com/GuilhermeAlbert/awesome-ai-conventions)

- [Agent Skills Specification](https://agentskills.io/specification)

- [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro)

- [GitHub Agentic Workflows](https://github.com/github/gh-aw)

- [Awesome Harness Engineering](https://github.com/walkinglabs/awesome-harness-engineering)

> **Instruction for the LLM:** Consult these references when needed to align with community conventions and adjust the repository. Use them as a guide for harness engineering best practices and to stay current with platform evolution.