Skip to content

Junhanliu-dev/espalier-engineering / skills/espalier-init

espalier-init

Verified

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/).

FileKindSize
SKILL.mdskill md43.5 KB
hook-templates/check-layer-boundaries-go.shscript665 B
hook-templates/check-layer-boundaries-python.shscript821 B
hook-templates/check-layer-boundaries-typescript.shscript1.6 KB
hook-templates/copilot-hook-adapter.shscript2.4 KB
hook-templates/drift-detect.shscript5.7 KB
hook-templates/drift-helpers.shscript56.4 KB
hook-templates/espalier-outside.shexecutablescript28.8 KB
hook-templates/espalier-pr.shexecutablescript43.2 KB
hook-templates/espalier-stats.shexecutablescript27.3 KB
hook-templates/lookup-helpers.shscript9.5 KB
hook-templates/map-guard.shexecutablescript3.9 KB
hook-templates/maprun-dispatch.shexecutablescript21.0 KB
hook-templates/maprun-integration.shexecutablescript3.4 KB
hook-templates/maprun-merge.shexecutablescript2.9 KB
hook-templates/maprun-pr.shexecutablescript12.8 KB
hook-templates/maprun-verify.shexecutablescript5.0 KB
hook-templates/maprun.pyscript65.6 KB
hook-templates/parse-drift-blocks.pyscript1.1 KB
hook-templates/post-edit-wrapper.shscript2.0 KB
hook-templates/post-merge-backlink.shscript2.2 KB
hook-templates/pre-push-gate-wrapper.shscript3.0 KB
hook-templates/pre-push-gate.shscript18.1 KB
hook-templates/rebuild-commit-index.shscript2.6 KB
references/discovery-checklist.mdmarkdown18.5 KB
references/validation.mdmarkdown16.7 KB
references/wiki-templates.mdmarkdown710 B
references/wiring.mdmarkdown13.5 KB
templates/agent.mdmarkdown3.7 KB
templates/agents/harness-coder.mdmarkdown33.9 KB
templates/agents/harness-reviewer.mdmarkdown25.1 KB
templates/agents/harness-security.mdmarkdown14.0 KB
templates/agents/modes/fix-round.mdmarkdown3.0 KB
templates/agents/modes/re-review.mdmarkdown5.3 KB
templates/agents/modes/repo-audit.mdmarkdown2.8 KB
templates/agents/modes/simplification.mdmarkdown7.0 KB
templates/agents/modes/stage6-abuse-coverage.mdmarkdown1.3 KB
templates/agents/modes/wiki-sweep.mdmarkdown5.6 KB
templates/pipeline.mdmarkdown18.9 KB
templates/rules/coding-standards.mdmarkdown3.2 KB
templates/rules/development-process.mdmarkdown3.2 KB
templates/rules/engineering-structure.mdmarkdown1008 B
templates/rules/production-standards.mdmarkdown5.8 KB
templates/rules/security-standards.mdmarkdown5.6 KB
templates/scout-prompts.mdmarkdown9.0 KB
templates/skills/espalier-ask.mdmarkdown6.4 KB
templates/skills/espalier-audit.mdmarkdown10.0 KB
templates/skills/espalier-coding-references/platform-native.mdmarkdown9.4 KB
templates/skills/espalier-coding-spec.mdmarkdown496 B
templates/skills/espalier-coding.mdmarkdown4.0 KB
templates/skills/espalier-doctor.mdmarkdown8.0 KB
templates/skills/espalier-fix.mdmarkdown77.5 KB
templates/skills/espalier-grill.mdmarkdown21.5 KB
templates/skills/espalier-map.mdmarkdown20.0 KB
templates/skills/espalier-maprun.mdmarkdown31.1 KB
templates/skills/espalier-prune.mdmarkdown13.0 KB
templates/skills/espalier-repot.mdmarkdown7.6 KB
templates/skills/espalier-requirements.mdmarkdown4.7 KB
templates/skills/espalier-review.mdmarkdown4.5 KB
templates/skills/espalier-security.mdmarkdown5.6 KB
templates/skills/espalier-simplify.mdmarkdown25.0 KB
templates/skills/espalier-stages/1-2-requirements.mdmarkdown7.6 KB
templates/skills/espalier-stages/3-coding.mdmarkdown15.0 KB
templates/skills/espalier-stages/4-panel.mdmarkdown14.3 KB
templates/skills/espalier-stages/5-6-contract.mdmarkdown10.3 KB
templates/skills/espalier-stages/7-10-delivery.mdmarkdown16.8 KB
templates/skills/espalier-stages/simple.mdmarkdown14.0 KB
templates/skills/espalier-testing.mdmarkdown2.9 KB
templates/skills/espalier.mdmarkdown27.7 KB

templates/skills/espalier-prune.md

View on GitHub
---
name: espalier-prune
description: Refresh stale Espalier artifacts (rules, wiki, layer specs, hooks) by re-running discovery scouts and applying a gated, per-file diff
---

# Espalier Prune

The ONLY component that edits an Espalier doc. Interactive, per-file, always
gated — it never overwrites a doc without an explicit user accept.

## When to Use

- "/espalier-prune <path>" — refresh one flagged artifact
- "/espalier-prune --all-stale" — refresh every file in the drift sidecar
- Surfaced by the Stage 0 pre-flight when a doc is flagged stale

## Trigger

```
/espalier-prune <path>        # refresh a single artifact
/espalier-prune --all-stale   # refresh every flagged artifact
```

With `--all-stale`, the file list comes from the drift sidecar:

```bash
. espalier/hooks/drift-helpers.sh
stale_files          # one repo-relative path per line (empty if no drift)
```

## Per-File Refresh Protocol

Each step is a real tool action (scout spawn, Read, diff, AskUserQuestion) —
NOT a bash script. For each file:

1. **Look up the scout(s)** for the file (Scout Mapping below).
2. **Spawn the scout(s)** — read the prompts from `espalier/.scout-prompts.md`
   (Scout Prompts (shipped file) below). The scout runs against the CURRENT codebase. For a file with
   two scouts (`coding-standards.md` ← 1.3 + 1.6), spawn both and merge their
   outputs into ONE proposed file before diffing.
3. **Two-way diff:** current file vs the proposed scout output. Two-way, not
   three-way — the init template is full of `{placeholders}` and is useless as
   a diff base.
4. **If the diff is empty or immaterial** (a teammate already refreshed the
   file): `clear_stale <file>`, report "already current", move on — no prompt.
   Under the per-clone sidecar a teammate's fix leaves a phantom row on your
   clone; this retires it instead of nagging forever.
5. **Else render the unified diff** and gate by file class with
   `AskUserQuestion`. Classify with `classify_file <path>` from
   `drift-helpers.sh`. For a rule file, render the **Removed rules** ledger
   ABOVE the diff so a refresh can never silently drop a rule:

   ```bash
   . espalier/hooks/drift-helpers.sh
   comm -23 <(rule_bullets "$CURRENT" | sort) <(rule_bullets "$PROPOSED" | sort)
   ```

   Show it as `Removed rules (N)` — one line per bullet or table row the
   proposed render no longer carries — and the gate line as
   `size: {current} KB → {proposed} KB` (information). A rule file is
   rendered under the Writing Contract in `espalier/.scout-prompts.md`; the
   ledger is what makes a refresh shrink instead of ratchet. Nothing refuses
   on size or on count — `keep-old` / `edit` are the human's answer.

   | File class | Options | Default |
   |------------|---------|---------|
   | Wiki  | apply / review / skip | apply |
   | Rules | apply / keep-old / show-full-diff / edit | (none) |
   | Specs (layer_spec) | apply / keep-old / edit | (none) |
   | Hooks | apply / keep-old / edit + dry-run validate | (none) |

6. **On apply:** overwrite the file, then `clear_stale <file>`.
7. **On skip / keep-old:** leave the sidecar row — it re-surfaces at the next
   Stage 0 pre-flight.

After all files, report a summary: applied / already-current / kept-old /
skipped. Then suggest a commit:

> docs: refresh stale espalier artifacts

Commit it BEFORE resuming any pipeline, so the refresh is its own commit and is
never bundled into a feature commit.

## Unattended Invocation

```bash
. espalier/hooks/drift-helpers.sh
[ "$(interactivity_mode)" = "unattended" ] && echo unattended
```

Only an EXPLICIT unattended signal counts (`CI`, `ESPALIER_UNATTENDED`,
`ESPALIER_LOOP`, `ESPALIER_HEADLESS`) — never a bash TTY test, which reads
"no TTY" inside every interactive Claude Code session and would demote every
attended `--all-stale` run to report-only. If you (the orchestrator) can call
`AskUserQuestion`, you are interactive: gate each file normally.

If genuinely unattended with `--all-stale`: do NOT prompt. Write the proposed
diffs to `espalier/.drift-report.md` and exit, leaving every sidecar row in
place. Refresh is never silent.

## Multi-Developer Discipline (Maintenance Lanes)

With several developers on one repo, each maintenance mechanism has its own
lane — the failure mode each lane prevents is different:

| Mechanism | Lane | Why |
|---|---|---|
| Doctor scan | Weekly maintenance PR on the canonical branch (the gardener's run) | The scan result is team visibility; a scan stranded on a feature branch helps nobody until merge. |
| Prune refresh | Weekly maintenance PR by default; **feature-branch escape hatch** when YOUR OWN flag is critical/expired — as its own isolated `docs:` commit, covered by the conflict recipe below | One prune sweep per interval makes cross-branch prune conflicts ~impossible by scheduling; the escape hatch keeps a blocked dev unblocked, and the recipe makes the residual recoverable. |
| Convention promotion | Feature branch is fine — own isolated commit; CODEOWNERS routes the rules-touching PR to the rule owner at merge either way | The deciding dev has the context; the ownership gate binds at merge regardless of source branch. |

The canonical branch is `canonical-branch` in `espalier/.espalier-config`
(remote: `canonical-remote`) — detected at init, edit if wrong.

**The weekly gardener rota (social, documented — what makes the lanes
sufficient).** One rotating dev per cadence interval is the gardener; the
rota names WHO, which is what kills "someone else surely ran it". The
gardener's loop, ~15 minutes:

1. Open a temporary worktree of the canonical branch (flow below).
2. `/espalier-doctor` — the weekly scan.
3. `/espalier-prune` over the flagged files (normal per-file gates).
4. **If the prune cleared every finding, re-run `/espalier-doctor`** so the
   shared stamp says `clean` (the doctor skill's end-of-session rule — a
   dirty stamp whose findings were fixed in the same PR would nag the whole
   team forever).
5. One maintenance PR — `docs: weekly espalier maintenance` — containing the
   stamp commit plus the refresh commits. CODEOWNERS routes any
   rules-touching part to the rule owner automatically. On a protected
   integration branch (assume protected at team scale) the PR IS the lane —
   any teammate approves the routine parts (~1 min of someone's week); with
   direct-push rights the worktree flow pushes straight.

A skipped gardener week self-corrects: the shared stamp ages out,
`doctor_due()` starts nagging everyone again — the pre-rota behavior is the
fallback, not a new failure.

**Worktree flow — do the discipline FOR the user, not BY the user.** When a
maintenance-lane action should land on the canonical branch while the user
sits on a feature branch, offer: *"run this in a temporary worktree of the
canonical branch and push the maintenance commit?"* Mechanically:

```bash
R=$(grep '^canonical-remote:' espalier/.espalier-config | awk '{print $2}')
B=$(grep '^canonical-branch:' espalier/.espalier-config | awk '{print $2}')
WT=$(mktemp -d) && git worktree add "$WT" "$B"
# run the doctor/prune flow inside $WT (normal gates apply), commit there:
#   docs: weekly espalier maintenance
# push directly with push rights, or push a PR branch when the canonical
# branch is protected (at team scale assume it is) — the maintenance PR IS
# the lane. Then:
git worktree remove "$WT"
```

No stash, no branch switch — the feature checkout is untouched; suggest
`git rebase` afterwards when the user wants the fresh doc on their branch.
Contributors without push access use the same flow with a fork/PR branch —
the weekly maintenance PR is still the destination.

## Conflict Recipes (moved here from pipeline.md in v0.25)

Three residual-conflict recipes; the lane table above says which lane each
mechanism rides. Never hand-merge scout prose.

### Maintenance-commit conflicts (prune vs prune)

1. Inspect both sides — diff the conflicting doc against each merge parent.
2. Take the newer refresh wholesale: `git checkout --theirs -- <doc>` (or
   `--ours` when yours is newer), commit the merge.
3. Re-run `/espalier-prune <doc>` on the merged tree — an empty scout diff
   confirms the kept side; a non-empty one shows what the union of both
   branches' code changed.

A modify/delete conflict on an espalier doc resolves as DELETION (the other
side retired the doc).

### Per-key convention conflicts (`espalier/conventions/k-*.tsv`)

A same-key conflict is the promotion race DETECTION, not a breakage. Two
decisions (both sides flipped statuses) → pick the winning decision like any
5-line conflict. An observation append against another append or against a
status flip → **keep both lines** — every decided row AND every fresh
observation row survive; `conv_fold` dedupes repeated observations at read time,
so nothing double-counts. The shared `espalier/.doctor-stamp` is one line:
keep the newer line (or either `clean`).

### Slug collisions across branches

Two branches can mint the same `espalier/changes/{type}/{slug}/` folder on
the same day; the merge shows add/add conflicts inside it. All in ONE commit:

1. Rename the later-merging change's dir to the next free suffix:
   `git mv espalier/changes/{type}/{slug} espalier/changes/{type}/{slug}-2`.
2. Rebuild the reverse-lookup cache:
   `bash espalier/hooks/rebuild-commit-index.sh`.
3. Rewrite the old slug in every back-link that points at the renamed change:
   `grep -l "{type}/{slug}" espalier/changes/*/*/pipeline-state.md`, then fix
   each `## Follow-up Fixes` row from `{type}/{slug}` to `{type}/{slug}-2` —
   otherwise those back-links point at the other branch's change.

## Scout Mapping

| Artifact | Scout(s) |
|----------|----------|
| `rules/engineering-structure.md` | 1.2 (+ `## Not Precedent` from its `not_precedent` array, see below) |
| `rules/coding-standards.md` | 1.3 + 1.6 (merge before diff) |
| `rules/development-process.md` | 1.5 |
| `rules/security-standards.md` | 1.11 → discovered sections ONLY (see below) |
| `rules/production-standards.md` | 1.3 + 1.10 + 1.8 → `{discovered}` cells ONLY (merge before diff) |
| `wiki/architecture.md` | 1.2 |
| `wiki/data-models.md` | 1.8 |
| `wiki/critical-paths.md` | 1.9 |
| `wiki/external-services.md` | 1.10 |
| `skills/espalier-coding/specs/{layer}.md` | per-layer spec scout |
| `hooks/check-layer-boundaries.sh` | 1.2 → regenerate the `case` block |
| `hooks/pre-push-gate.sh` | 1.5 → re-substitute build/lint/test commands |

`development-process.md` is a mixed file too: its `## Maintenance Commits`
section (the `ESPALIER MAINTENANCE COMMITS v2` marker) is fixed policy text —
scout 1.5 regenerates the discovered sections ONLY, and the two-way diff must
show the marker section unchanged.

`engineering-structure.md`'s `## Not Precedent` section (the
`ESPALIER NOT PRECEDENT v1` managed anchor — every reader matches that token
only) is refreshed from scout 1.2's `not_precedent` array and from nothing
else: an entry the scout cannot re-prove is dropped, one it newly proves is
added, one line per entry (`path — kind — clause — evidence file:line`).
Negative knowledge is re-proved instead of decaying in prose; the anchor
comment line is kept verbatim.

The two always-loaded standards rules are MIXED files — universal seed text
plus discovered cells. A refresh regenerates ONLY the discovered parts:
`security-standards.md` = the Trust Boundary bullets, the per-axis
`{discovered}` taxonomy column, and Project-Specific Security Conventions
(from scout 1.11); `production-standards.md` = the `{discovered}` mechanism
cells and Project-Specific Production Conventions (from 1.3's
logging/error-handling/validation, 1.10's timeout_retry_patterns, 1.8's
migration_pattern). The universal taxonomy, required controls, seeds, and
severity tiers are fixed text — never rewritten by a scout; the two-way diff
must show them unchanged.

A hook is not a prose doc. For `check-layer-boundaries.sh` regenerate the layer
`case` block from scout 1.2's `layers`; for `pre-push-gate.sh` re-substitute the
`{build_command}` / `{lint_command}` / `{test_command}` placeholders from scout
1.5's `ci_checks`. Always dry-run a refreshed hook (`bash -n <hook>`) before the
apply gate.

## Scout Prompts (shipped file)

Read the prompts from `espalier/.scout-prompts.md` — they are NOT embedded here. The file is copied into this project at init. Spawn the scout(s)
mapped to the artifact under refresh (Scout Mapping above); run each as an
Agent/Task scout against the current codebase. Keeping the prompts in a single
shipped file means `/espalier-prune` and `/espalier-doctor` can never drift apart.

## What This Skill Does NOT Do

- Does not re-run a full `/espalier-init`. It refreshes only flagged files.
- Does not promote conventions. Promotion is a deliberate rule edit handled at
  the Stage 0 pre-flight (see the `espalier` skill's Convention Promotion
  section). A scout re-derives a rule from a code base that is now a MIX of old
  and new patterns; it reports the mix, it cannot make the promote/reject call.
- Never edits a doc without an explicit user accept (attended), or at all
  (unattended — it only writes a report).
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall