Installs the 4th Layer Engineering harness into a repository. Claude Code and Codex hooks, run tracking, multi-agent council protocol, subagent guides, handoff templates with memory promotion, and CLAUDE.md/AGENTS.md workflow sections. Use when setting up a new repo for agent-driven development, or when adding structured run tracking and multi-agent workflow support to an existing project.
Installation
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Installs the 4th Layer Engineering harness into a repository. Claude Code and Codex hooks, run tracking, multi-agent council protocol, subagent guides, handoff templates with memory promotion, and CLAUDE.md/AGENTS.md workflow sections. Use when setting up a new repo for agent-driven development, or when adding structured run tracking and multi-agent workflow support to an existing project.
4th Layer Agent Harness — Engineering Workflow
This skill installs the 4th Layer Engineering workflow infrastructure into the current
repository. It takes ~10 minutes and leaves you with a complete agent operating environment:
run tracking, subagent protocol, hooks, templates, and Claude/Codex workflow sections.
Prerequisites
Before proceeding, confirm:
You are in the root directory of the target repository
Git is initialized (git init if not)
Python 3 is available (for hooks — they use stdlib only)
~/bin/agent is set up if you plan to use Cursor as a subagent (see SETUP.md)
Skill package location:
This SKILL.md and all accompanying files are in 4th-layer-scaffold/ at the
Code Projects root. All files/ paths below are relative to that directory.
Template stays tracked as the blank canonical form; ARCHIVE.md is the per-developer working log (gitignored so multi-dev archive histories don't conflict).
skills/README.md
Optional project-local skills/ or .agents/skills/
Scaffold for domain skills when the user explicitly requests repo-specific skills
SPEC quality checklist on write (for council-style repos)
Install skills globally by default: ~/.claude/skills/<name>/ for Claude Code
and ~/.agents/skills/<name>/ for Codex. Only copy skills into the target repo
when the user explicitly asks for project-specific skills. The same
files/skills/<name>/ payload is used for both Claude and Codex.
Installation
Work through these steps in order. Do not skip steps.
Step 1: Create directories
Create all required directories in the target repo:
Read files/.claude/settings-hooks-template.json from the skill package and write it
to .claude/settings-hooks-template.json in the target repo.
This contains only the "hooks" section. The user will merge it into their
settings.local.json (Step 10).
Step 3b: Copy Codex hook scripts and templates
If the target repo will be used with Codex, copy these files:
Source (in skill package)
Destination (in target repo)
files/.codex/hooks/block-destructive-git.py
.codex/hooks/block-destructive-git.py
files/.codex/hooks/session-run-prompt.py
.codex/hooks/session-run-prompt.py
files/.codex/hooks/task-log-reminder.py
.codex/hooks/task-log-reminder.py
files/.codex/hooks.json
.codex/hooks.json
files/.codex/config-hooks-template.toml
.codex/config-hooks-template.toml
Codex hooks are behind a feature flag. In the target repo, merge the template's
contents into .codex/config.toml or another active Codex config layer:
[features]codex_hooks = true
If .codex/config.toml already exists, do not overwrite it. Merge only the
[features] value.
Codex hooks are guardrails, not a security boundary. Keep Codex sandboxing and
approval settings in place.
Project-local Codex hooks load only when the project .codex/ config layer is
trusted by Codex. If Codex prompts about trusting project config, trust it only
after reviewing the hook scripts and config.
Step 4: Copy run infrastructure
Source
Destination
files/runs/.gitkeep
runs/.gitkeep (empty file)
files/runs/CLAUDE-RUNS/.gitkeep
runs/CLAUDE-RUNS/.gitkeep (empty file)
files/runs/CLAUDE-RUNS/ARCHIVE.template.md
runs/CLAUDE-RUNS/ARCHIVE.template.md (tracked)
files/runs/CLAUDE-RUNS/ARCHIVE.template.md
runs/CLAUDE-RUNS/ARCHIVE.md (copy of template; becomes the dev's local working log — gitignored)
Why the split:ARCHIVE.template.md is the scaffold-canonical blank form — tracked, shared, rarely changes. ARCHIVE.md is the per-developer archive history — gitignored so each dev can archive runs on their machine without creating merge conflicts or leaking private run history into the shared repo.
Note:init-run.sh and all run templates (TASK_LOG, SPEC, HANDOFF, FINDINGS)
now live inside the task-tracking skill and are installed in Step 7. The skill's
scripts/init-run.sh resolves templates from ../templates/ relative to itself.
Step 5: Copy local runtime state template
CLAUDE.local.md is per-machine runtime state. It belongs in the target repo root,
but it must stay gitignored and should not be committed.
Source
Destination
Runtime
files/CLAUDE.local.md
CLAUDE.local.md
Claude Code
files/AGENTS.local.md
AGENTS.local.md
Codex
If CLAUDE.local.md does not already exist in the target repo, copy the template
from files/CLAUDE.local.md.
If CLAUDE.local.md already exists, do not overwrite it. Verify it has the
Active Tasks table, and merge only the missing table/template pieces if needed while
preserving any existing Agent Voice or per-machine notes.
For Codex, do the same with AGENTS.local.md: copy files/AGENTS.local.md only if
the target repo does not already have one. Codex does not auto-load this file; the
4th Layer Codex SessionStart hook reads it when hooks are enabled.
Step 6: Documentation now lives in skills
Do not copy duplicate docs/coding_agents/ versions of agent workflow guides.
The harness keeps those protocols in skills so Claude Code and Codex can load
them on demand:
context-loading replaces MEMORY_OPTIMIZATION.md
docstring-guide replaces DOCSTRING_GUIDE.md
subagent-management replaces SUBAGENT_GUIDE.md
gemini-subagent replaces GEMINI_CLI_SUBAGENT.md
adversarial-review replaces ADVERSARIAL_REVIEW.md
council-guide replaces COUNCIL_GUIDE.md
Note:docstring_validation_template.md also lives inside the task-tracking
skill at templates/docstring_validation_template.md and is installed in Step 7.
Step 7: Install skills
This harness ships 10 skills. Install all skills globally by default for the
agent runtime(s) being configured. Project-local copies are only for users who
explicitly ask for repo-specific skills.
Core skills:
task-tracking — run tracking protocol, templates, init-run.sh, docstring validation
council-guide — quad-model council deliberation protocol
Default: install skills globally for the agent runtime(s) being configured.
Do not add project-local skills/ or .agents/skills/ directories unless the
user explicitly asks for repo-specific skills.
Ask the user before proceeding:
"I'll install the harness skills globally by default.
A) Global - copied to the relevant global skills directory:
~/.claude/skills/<name>/ for Claude Code and/or
~/.agents/skills/<name>/ for Codex.
B) Project-local too - also copy to the active agent's project-local skills
directory (skills/<name>/ for Claude Code, .agents/skills/<name>/ for
Codex). Choose this only if you want repo-specific skill copies."
Then execute the chosen option:
For Claude Code, use ~/.claude/skills/ for global install. Use skills/
only if the user explicitly requests project-local Claude skills.
For Codex, use ~/.agents/skills/ for global install. Use .agents/skills/
only if the user explicitly requests project-local Codex skills. Codex does not
use ~/.claude/skills/, CLAUDE.md, or CLAUDE.local.md automatically.
Codex compatibility note: The skill format is shared. The existing
files/skills/<name>/SKILL.md files are valid Codex skills because they use the
standard name and description frontmatter plus Markdown instructions.
Step 7b: Configure archive metrics
Ask the user:
"What metrics should be collected when archiving a run?
I'll create .claude/archive-run.config with the collectors you want.
The git collector (files changed, lines +/-, commits) is always included.
Code duplication (jscpd) — run manually with repo-specific ignore patterns
None of the above — git metrics only"
Based on the answer, create .claude/archive-run.config with the appropriate collectors
uncommented. Use files/skills/archive-run/scripts/archive-run.config.example as the base.
If the user isn't sure yet, copy the example file as-is (git-only default) and note they
can uncomment collectors later.
Step 8: Copy snippets
Source
Destination
files/../snippets/CLAUDE_MD_WORKFLOW.md
snippets/CLAUDE_MD_WORKFLOW.md
files/../snippets/AGENTS_MD_WORKFLOW.md
snippets/AGENTS_MD_WORKFLOW.md
(The snippets directory is at 4th-layer-scaffold/snippets/, not inside files/.)
Step 9: Update .gitignore
Append the following to .gitignore (create the file if it doesn't exist):
# Claude agent run directories (local only — contents never committed)
runs/
!runs/.gitkeep
!runs/CLAUDE-RUNS/.gitkeep
!runs/CLAUDE-RUNS/ARCHIVE.template.md
# Per-machine Claude runtime state
/CLAUDE.local.md
# Per-machine Codex runtime state
/AGENTS.local.md
# Log files
*.log
Do NOT replace an existing .gitignore — append only. Do NOT force-add
CLAUDE.local.md. If the target repo already tracks CLAUDE.local.md, ask the user
before running git rm --cached CLAUDE.local.md so the file remains locally but is
removed from version control.
Do the same for AGENTS.local.md if it already exists and is tracked.
Step 10: Force-add tracked files
git add -f runs/.gitkeep
git add -f runs/CLAUDE-RUNS/.gitkeep
git add -f runs/CLAUDE-RUNS/ARCHIVE.template.md
# NOTE: Do NOT force-add runs/CLAUDE-RUNS/ARCHIVE.md — it is intentionally# gitignored as a per-developer archive log.
Note:init-run.sh is no longer at runs/CLAUDE-RUNS/ — it lives inside the
task-tracking skill directory (installed in Step 7). The skill's scripts/init-run.sh
was already made executable in Step 7.
Step 11: Test run infrastructure
Run init-run.sh from the global skill install by default:
# Claude Code global default:
~/.claude/skills/task-tracking/scripts/init-run.sh test-tent
# Codex global default:
~/.agents/skills/task-tracking/scripts/init-run.sh test-tent
If the user explicitly requested project-local skills, use the project-local path
for that runtime instead:
Expected output: ✅ Created: runs/CLAUDE-RUNS/RUN-YYYYMMDD-HHMM-test-tent/ with
TASK_LOG.md, SPEC_v1.md, and HANDOFF.md present with timestamps substituted
(not {{RUN_ID}} literals).
If template variables aren't substituted, check that the templates/ directory
inside the task-tracking skill is populated correctly from Step 7.
Customization Pass
The infrastructure is now installed. The former docs/coding_agents/ workflow
guides now live in skills, so this pass focuses on repo instruction files and
any project-specific notes the user wants to add.
Customize: CLAUDE.md workflow section
The former context-loading checklist now lives in the context-loading skill,
the former docstring guide now lives in the docstring-guide skill, and the
former subagent guide now lives in the subagent-management skill.
The file snippets/CLAUDE_MD_WORKFLOW.md contains a slim workflow pointer section
ready to paste into CLAUDE.md. The full task-tracking protocol now lives in the
task-tracking skill (installed in Step 7), so CLAUDE.md only needs a pointer.
Ask the user: "Do you have an existing CLAUDE.md, or should I create a new one?"
If creating new: Copy snippets/CLAUDE_MD_WORKFLOW.md to CLAUDE.md. Then add
a project-specific header section above the workflow section covering:
Project name and purpose
Documentation map (what docs exist and when to use them)
If merging with existing: Paste the workflow sections from
snippets/CLAUDE_MD_WORKFLOW.md into the appropriate place in the existing CLAUDE.md.
At minimum, ensure these sections are present:
Task Execution Protocol (pointer to task-tracking skill)
Subagent Usage + Codex + Cursor sections
Background Process Guidelines
Timestamp reminder
Then ensure CLAUDE.local.md exists with the Active Tasks table (and optionally
the Agent Voice section). If missing, copy files/CLAUDE.local.md to CLAUDE.local.md.
This file is gitignored — it holds per-machine runtime state.
After merging, fill in all [TODO: project-specific] markers in CLAUDE.md.
Customize: AGENTS.md workflow section
If the repo will be used with Codex, use snippets/AGENTS_MD_WORKFLOW.md.
If no AGENTS.md exists: Copy snippets/AGENTS_MD_WORKFLOW.md to AGENTS.md.
Then add project-specific repository guidance above the workflow section.
If AGENTS.md already exists: Merge the workflow sections from
snippets/AGENTS_MD_WORKFLOW.md into the existing file.
Then ensure AGENTS.local.md exists with the Active Tasks table. If missing, copy
files/AGENTS.local.md to AGENTS.local.md. This file is gitignored.
Finalize: Configure settings.local.json
Merge .claude/settings-hooks-template.json into .claude/settings.local.json:
If no settings.local.json exists: rename the template to settings.local.json
If it exists: merge the "hooks" key into the existing file without overwriting
other keys (permissions, enabledMcpjsonServers, additionalDirectories, etc.)
After merging, delete .claude/settings-hooks-template.json.
Finalize: Configure Codex hooks
If using Codex, ensure .codex/hooks.json exists and .codex/config.toml enables hooks:
[features]codex_hooks = true
If .codex/config.toml already exists, merge the feature flag without overwriting
other Codex settings.
Completion Checklist
Verify everything before starting work:
task-tracking, context-loading, docstring-guide, archive-run, and subagent-management skills installed globally, unless the user explicitly requested project-local skill copies
init-run.sh test-tent generates TASK_LOG.md, SPEC_v1.md, and HANDOFF.md with substituted timestamps
.agent-harness/hooks/ exists with shared hook logic
.claude/settings.local.json has "hooks" key with 7 core hooks + SessionStart
.codex/hooks.json has SessionStart, UserPromptSubmit, and PreToolUse hook wiring (if using Codex)
.codex/config.toml or another active Codex config layer has [features] codex_hooks = true (if using Codex)
.claude/archive-run.config created with appropriate metric collectors
context-loading skill installed and referenced by CLAUDE.md/AGENTS.md workflow section
docstring-guide skill installed and referenced by CLAUDE.md/AGENTS.md workflow section
subagent-management skill installed and referenced by CLAUDE.md/AGENTS.md workflow section
CLAUDE.md has the workflow pointer section (skill references, subagent section)
AGENTS.md has the workflow pointer section (if using Codex)
CLAUDE.local.md has the Active Tasks table (and Agent Voice if used)
AGENTS.local.md has the Active Tasks table (if using Codex)
.gitignore has runs/, !runs/.gitkeep, /CLAUDE.local.md, and /AGENTS.local.md appended
CLAUDE.local.md exists locally but is not tracked by git
AGENTS.local.md exists locally but is not tracked by git (if using Codex)
runs/.gitkeep, runs/CLAUDE-RUNS/.gitkeep, ARCHIVE.template.md force-added to git
runs/CLAUDE-RUNS/ARCHIVE.md exists locally and is not tracked
What's NOT installed (by design)
The following were intentionally excluded. Add them yourself if needed:
