junhanliu-dev/espalier-engineering/espalier-init

Claude Code and agent skill by junhanliu-dev/espalier-engineering

Trust tier 2
  • community
LLM review pending
Source check pending

Checking that the SKILL.md file is still in the repository.

Analyze any existing codebase, discover its patterns and best practices, and generate an Espalier structure (rules, skills, wiki, pipeline) so AI coders produce code matching that project's language and conventions. Greenfield repos take the two-pass Decide-Then-Bind path (/espalier-map charts the conventions, init binds them); boilerplate repos run init normally, then map the product. Wires into Claude Code, Codex, and/or GitHub Copilot (.claude/, .agents/skills/ + .codex/, .github/).

Install

npx vskill@latest install junhanliu-dev/espalier-engineering/espalier-init

SKILL.md

Espalier Init

Discover the actual patterns, conventions, and architecture of an existing codebase, then generate a structured constraint system that ensures AI agents produce code matching those standards.

When to Use

  • "Set up Espalier for this project"
  • "Create Espalier structure for my codebase"
  • "Make AI code production-ready for this repo"
  • "Build agent constraints for this project"
  • "/espalier-init"
  • "/espalier-init --outside" — install with the espalier/ tree OUTSIDE the repo (nothing espalier-related committed)

Flags

FlagEffect
--outside[=<dir>]Outside mode (v0.30). The espalier/ tree lives at <dir>/<name>/espalier/ — default <dir> is the project's PARENT directory + /espalier-main, created if missing — with its own local git repo (no remote). The project root gets a RELATIVE symlink espalier -> ../espalier-main/<name>/espalier, excluded via .git/info/exclude. Hooks go to .claude/settings.local.json, the instruction section to CLAUDE.local.md, every wiring path to the exclude file: the project repo never tracks anything espalier-related, and Stage 7 commits records into the outside repo instead of opening an espalier PR. Fresh installs only — an existing inside install moves with /espalier-repot.
--outside-name=<n>Outside mode: the folder name under <dir> (default: the project's basename). Pass it when two projects share a basename — init refuses to adopt a root whose .espalier-origin names another project.

Outside mode has ONE extra step, and it comes FIRST. Phase 2 writes espalier/rules/…, espalier/agents/… and the rest by path, so the symlink must exist before any of those writes — otherwise they create a real directory inside the repo. Immediately after Phase 0's questions, before Phase 1:

bash
# ${CLAUDE_SKILL_DIR} = this skill's directory. Append --main=<dir> when
# --outside=<dir> was given, --name=<n> when --outside-name=<n> was given.
bash "${CLAUDE_SKILL_DIR}/hook-templates/espalier-outside.sh" prepare .

It prints the outside root. Exit 3 means the default root already belongs to another project or holds foreign content: surface the message and ask the user for --outside-name=<other>; do not proceed. Pass the same flags to bootstrap in Phase 3 (--outside[=<dir>], --outside-name=<n>) — bootstrap re-runs prepare (idempotent) and writes every wiring file in its outside-mode form. Re-runs auto-detect the mode from the symlink.

Philosophy

When an agent makes an error, engineer its elimination — not with prompt tweaks, but with files, rules, automated checks, and system structure.

Core insight: The problem isn't model intelligence. It's that models don't know the unwritten rules — patterns every experienced developer on the team knows but nobody documented.

This skill discovers those rules from the code itself, then encodes them as machine-enforceable constraints. Like an espalier trains a fruit tree to grow along a wall, this skill trains your AI coder to grow along the patterns already in your codebase.

File Layout of This Skill

espalier-init/
├── SKILL.md                       # this file — overview + phase index
├── templates/                     # markdown templates emitted into target project
│   ├── rules/                     # → espalier/rules/ in target
│   ├── skills/                    # → espalier/skills/<name>/SKILL.md
│   ├── agents/                    # → espalier/agents/ in target
│   ├── agent.md                   # → espalier/agent.md (orchestrator)
│   └── pipeline.md                # → espalier/pipeline.md
├── hook-templates/                # shell scripts emitted into espalier/hooks/
└── references/                    # deep-dive content read on demand
    ├── discovery-checklist.md     # Phase 1 detail
    ├── wiring.md                  # Phase 10 detail
    ├── validation.md              # Phase 11 detail
    └── wiki-templates.md          # Phase 6 wiki stubs

Rule: Every phase below tells you which template/reference to read. Open them with the Read tool when the phase fires — do NOT invent template content from memory.

Output Structure in Target Project (after full setup)

project-root/
├── .claude/                        # [claude platform]
│   ├── rules/                     # symlinks to espalier/rules/*.md
│   ├── skills/                    # symlinks to espalier/skills/*
│   ├── agents/                    # symlinks to espalier/agents/*.md
│   └── settings.json              # hooks for quality gates
├── .agents/                        # [codex platform]
│   └── skills/                    # symlinks to espalier/skills/* (Codex repo-skill discovery)
├── .codex/                         # [codex platform]
│   ├── config.toml                # PreToolUse/PostToolUse hook block (marker-guarded)
│   └── agents/                    # harness-{coder,reviewer,security}.toml sub-agents
├── .github/                        # [copilot platform]
│   ├── skills/                    # symlinks to espalier/skills/* (Copilot Agent Skills — VS Code/CLI/cloud agent)
│   ├── agents/                    # harness-*.agent.md custom agents (@harness-coder …)
│   ├── hooks/espalier-gates.json  # preToolUse/postToolUse gates via copilot-hook-adapter.sh
│   └── copilot-instructions.md    # Espalier section + platform mapping (bootstrap-appended)
├── AGENTS.md                       # [codex] Espalier section + platform mapping (bootstrap-appended)
├── CLAUDE.md                       # [claude] references espalier/agent.md
├── espalier/
│   ├── agent.md                    # orchestrator definition
│   ├── rules/                      # engineering-structure, coding-standards, development-process, security-standards, production-standards
│   ├── skills/                     # folder name MUST equal SKILL.md `name:` frontmatter
│   │   ├── espalier-coding/
│   │   │   ├── SKILL.md
│   │   │   ├── specs/{layer}.md
│   │   │   └── references/platform-native.md   # ladder rung-4 lookup (v0.28; pure copy)
│   │   ├── espalier-review/SKILL.md
│   │   ├── espalier-security/SKILL.md            # trust-boundary audit checklist (harness-security)
│   │   ├── espalier-testing/SKILL.md
│   │   ├── espalier-requirements/SKILL.md
│   │   ├── espalier-grill/SKILL.md             # Stage 1 interrogation (invoked by espalier + espalier-fix)
│   │   ├── espalier/SKILL.md                   # main pipeline orchestrator — the ROUTER (slash: /espalier)
│   │   ├── espalier/stages/*.md                # per-stage procedure files, read at stage entry (v0.25; pure copies)
│   │   ├── espalier-fix/SKILL.md               # bug-fix lane, 7 stages (0–7, no Stage 2); slash: /espalier-fix
│   │   ├── espalier-prune/SKILL.md             # stale-artifact refresh (slash: /espalier-prune)
│   │   ├── espalier-doctor/SKILL.md            # periodic drift scan (slash: /espalier-doctor)
│   │   ├── espalier-ask/SKILL.md               # read-only Q&A lane (slash: /espalier-ask)
│   │   ├── espalier-audit/SKILL.md             # repo-wide security audit (slash: /espalier-audit)
│   │   ├── espalier-map/SKILL.md               # multi-session planning lane (slash: /espalier-map)
│   │   ├── espalier-maprun/SKILL.md               # map batch executor (slash: /espalier-maprun)
│   │   ├── espalier-simplify/SKILL.md             # simplification survey lane (slash: /espalier-simplify)
│   │   └── espalier-repot/SKILL.md                # move the install inside <-> outside the repo (slash: /espalier-repot; v0.30)
│   ├── agents/                     # harness-coder.md, harness-reviewer.md, harness-security.md (agent names kept for stability)
│   │   └── modes/                  # fix-round, simplification, re-review, repo-audit, stage6-abuse-coverage, wiki-sweep — mode text read when a prompt names it (v0.25; pure copies)
│   ├── wiki/                       # architecture, data-models, critical-paths, external-services
│   ├── hooks/                      # check-layer-boundaries.sh, pre-push-gate.sh, map-guard.sh, espalier-stats.sh, espalier-pr.sh (Stage 7 code PR / espalier PR), espalier-outside.sh (outside mode: prepare/discover/commit/repot), maprun.py + maprun-*.sh (run-lane engine)
│   ├── pipeline.md
│   ├── maps/                       # decision maps ({slug}/map.md + tickets/ + assets/) — /espalier-map
│   └── changes/                    # typed: feat/, fix/, refactor/, …
│       ├── _template/              # requirements.md, task-breakdown.md, coding-report.md, review-record.md, pipeline-state.md, ci-result.md
│       ├── feat/{slug}/            # full pipeline outputs   ({slug} = YYYY-MM-DD-<name>, sorts chronologically)
│       ├── fix/{slug}/             # fix-lane outputs (with caused_by frontmatter)
│       └── refactor/{slug}/        # refactor outputs (simplify-filed cuts carry simplify_from frontmatter)
└── src/  (existing code)

Outside mode (`--outside`) changes WHERE, not WHAT: project-root/espalier is a relative symlink to <parent>/espalier-main/<project-basename>/espalier/ (that root also holds .espalier-origin — the project's absolute path — and a .git/ of its own, no remote). The .claude/ wiring is identical but excluded via .git/info/exclude; CLAUDE.md → CLAUDE.local.md; .claude/settings.json → .claude/settings.local.json; no .gitignore, .gitattributes or CODEOWNERS edits. espalier/.espalier-config carries outside-root: <abs path>.

Skill Naming Invariant (CRITICAL — read before creating any skill)

Claude Code's skill loader compares the folder name against the SKILL.md name: frontmatter. If they differ, the skill emits a warning and may fail to register.

Rule: every skill folder MUST be named identically to its name: frontmatter value.

✅ CORRECT
espalier/skills/espalier-coding/SKILL.md         (name: espalier-coding)
espalier/skills/espalier-review/SKILL.md         (name: espalier-review)
espalier/skills/espalier/SKILL.md                (name: espalier)            ← main pipeline
 
❌ WRONG (will warn / break)
espalier/skills/coding/SKILL.md                  (name: espalier-coding)
espalier/skills/review/SKILL.md                  (name: espalier-review)

When you generate a skill:

  1. Choose the name: value first (must be globally unique, kebab-case, descriptive — prefix with espalier- for child skills inside this install; the main pipeline owns the bare name espalier).
  2. Use the SAME string as the folder name.
  3. Symlinks in .claude/skills/<name> then resolve to a same-named source folder — no mismatch possible.

This applies to all skill folders generated by this skill: espalier-coding, espalier-review, espalier-security, espalier-testing, espalier-requirements, espalier-grill, espalier (main), espalier-fix, espalier-prune, espalier-doctor, espalier-ask, espalier-audit, espalier-map, espalier-maprun, espalier-simplify, espalier-repot, and any additional ones added later.

Phase Dependency Note (parallel execution)

Phases 0-2 are sequential by necessity (Phase 0 prompt blocks; Phase 1 produces DISCOVERY blob consumed by Phase 2). Within Phase 1 and Phase 2, work is parallel. Phases 3+ are bundled into a single bootstrap-espalier.sh invocation.

Rule: run Phases 0 → 1 → 2 → 3 in order. Each step batches parallel work to minimize sequential tool calls (~5-7 batched turns total).

Phase 0: Setup Decisions (front-loaded)

Issue ONE AskUserQuestion with FOUR questions in the multi-question form (under Codex there is no AskUserQuestion tool — ask the same questions in chat and wait for answers; see "Running under Codex" below):

Q1 — Squash-merge strategy

ONE question, EXACTLY these 4 options (AskUserQuestion caps options at 4; the two overflow values are reachable by typing them into Other):

This is the start of the file. Read the full SKILL.md on GitHub.

Security

  • Security scanPassed, 100 of 100Pattern checks on the skill's files.
  • Model reviewNot runA model review is scheduled for the next rescan.

See the full security report

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

Popularity

Repository stars
72
Repository forks
9
7-day trend score
21

Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/junhanliu-dev/espalier-engineering/espalier-init/badge)](https://verified-skill.com/skills/junhanliu-dev/espalier-engineering/espalier-init)

Something wrong with this skill or its page? Tell us.