Junhanliu-dev/espalier-engineering / skills/espalier-init
espalier-init
VerifiedAnalyze 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/).
templates/scout-prompts.md
View on GitHub# Espalier Discovery Scout Prompts (shipped)
Canonical, target-side copies of the Phase 1 discovery scouts. `/espalier-prune`
and `/espalier-doctor` both read THIS file (they ship into the target project and
cannot read the plugin's `references/discovery-checklist.md`) — the single source
of truth for re-scouting an artifact.
> Sync note: this file mirrors the scout blocks in the plugin's
> `references/discovery-checklist.md`. When a scout's JSON shape changes, edit
> BOTH. Bootstrap copies this file to `espalier/.scout-prompts.md` in the target.
## Writing Contract — rule files (espalier/rules/*.md)
A rule file is read on every turn by every agent. It carries what a coder
must DO and a reviewer must CHECK, nothing else. Every scout that renders a
rule file, and every refresh `/espalier-prune` proposes, writes under it:
- One bullet per rule, present tense; a rubric table row is one rule.
- Exactly one citation per bullet: `path:line` of the shape to copy.
- No counts, dates, commit SHAs, PR numbers, or shell commands. A number
that matters is re-derived by the doctor's scout, never stored.
- No history ("was deleted", "used to", "no longer", "pre-v0.x"). A
surface that must not be copied is one line in `## Not Precedent`.
- No walkthroughs: a flow that needs more than two lines lives in
`espalier/wiki/critical-paths.md` or the workspace CLAUDE.md; the rule
keeps one bullet and a pointer.
- Universal seed text (severity tiers, required controls, taxonomy,
maintenance-commits anchor) is fixed and never rewritten by a scout.
No budget enforces this: the prune gate shows the rules a refresh would
remove (Removed rules ledger) and the doctor reports lines that drift from
the contract; the human decides.
## Scout 1.2 — Architecture
```
You are a codebase architect. Run `tldr tree . --depth 3`, `tldr arch .`, and
`tldr structure . --lang <lang>`, then identify the project's architectural
layers.
Return JSON ONLY:
{
"scout_id": "1.2",
"status": "ok" | "no_evidence",
"summary": "<=200 word prose summary",
"structured": {
"layers": [{"name": "<layer>", "dir": "<path>", "deps": ["<other layer>"]}],
"boundary_table": [{"from": "<layer>", "may_call": [...], "must_not_call": [...]}],
"not_precedent": [{"path": "<file or dir>", "kind": "dead|legacy|transitional|generated", "clause": "<one clause: why it must not be copied>", "evidence": "file:line"}]
},
"evidence_files": ["<paths examined>"]
}
not_precedent lists surfaces a coder must NOT copy — each re-proved from the
code NOW (an entry you cannot evidence is omitted, never carried forward).
```
## Scout 1.3 — Coding Patterns
```
Read 5-8 representative source files from different parts of the codebase.
Extract: naming conventions (files/functions/types/constants), error-handling
pattern, async style, type discipline, logging library + format, validation,
comment conventions (density / docstring style / what earns a comment).
Every pattern's example is one `file:line`, present tense — no history, no
counts, no commands (rule-file Writing Contract).
Return JSON ONLY:
{
"scout_id": "1.3",
"status": "ok",
"summary": "...",
"structured": {
"naming": {"files": "...", "fns": "...", "types": "...", "consts": "..."},
"error_handling": "...",
"async_pattern": "...",
"type_usage": "...",
"logging": {"library": "...", "format": "..."},
"validation": "...",
"comments": {"density": "...", "docstrings": "...", "what_gets_commented": "..."}
},
"evidence_files": [...]
}
```
## Scout 1.5 — Git + CI + deploy
```
Read git log + CI configs (.github/workflows/, Jenkinsfile, Makefile, justfile).
Also look for deploy configuration: deploy workflows/jobs, Procfile, Dockerfile +
compose/k8s manifests, fly.toml, vercel.json, serverless.yml — and any health/
readiness endpoint the app exposes (grep routes for /health, /healthz, /ready,
/ping). Deploy discovery is OPTIONAL — when the repo has no deploy config, set
"deploy": null (do NOT invent one).
ci_checks values must be commands that exist TODAY (a manifest script, Makefile
target, or CI step). A kind with no command — no lint configured, no build
step, no test runner — is null, never guessed: an invented command lands in
the pre-push gate and blocks every push.
Return JSON ONLY:
{
"scout_id": "1.5",
"status": "ok",
"structured": {
"branch_strategy": "...",
"commit_conventions": "<conventional-commits | imperative | other>",
"ci_checks": {
"build": "<exact command, e.g. 'npm run build'> | null",
"lint": "<exact command> | null",
"test": "<exact command> | null"
},
"deploy": {
"mechanism": "<e.g. 'GitHub Actions deploy.yml on main' | 'fly deploy'>",
"command": "<exact command, or 'automatic on merge'>",
"health_check": "<URL path or command, e.g. 'GET /healthz'>",
"environment": "<staging|production|both>"
}
},
"evidence_files": [...]
}
```
## Scout 1.6 — Unwritten Rules
```
Compare 3+ files of the same "type" in each detected layer. Find patterns that
are CONSISTENT across all of them — these are unwritten invariants. Also find
patterns NEVER violated. Each entry is present tense with one `file:line`
citation, no history (rule-file Writing Contract).
Return JSON ONLY:
{
"scout_id": "1.6",
"status": "ok" | "no_evidence",
"structured": {
"invariants": ["<observed-consistent rule>", ...],
"anti_patterns": ["<never-done in codebase>", ...]
},
"evidence_files": [...]
}
```
## Scout 1.8 — Data Models
```
Find schema/model files: prisma/schema.prisma, **/models/, **/entities/,
SQLAlchemy, Mongoose, Gorm structs, ActiveRecord migrations, JPA @Entity.
Return JSON ONLY:
{
"scout_id": "1.8",
"status": "ok" | "no_evidence",
"structured": {
"entities": [{"name": "...", "file": "...", "fields_sample": [...]}],
"schema_location": "...",
"migration_pattern": "...",
"relationships": [{"from": "...", "to": "...", "kind": "<has_many|belongs_to|...>"}]
},
"evidence_files": [...]
}
```
## Scout 1.9 — Critical Paths
```
Identify entry points (HTTP handlers, CLI commands, cron jobs, message
consumers, main functions). For each, trace which 3-5 files are touched
downstream. Identify hotspots that get modified frequently.
Return JSON ONLY:
{
"scout_id": "1.9",
"status": "ok" | "no_evidence",
"structured": {
"entry_points": [{"name": "...", "file": "..."}],
"primary_flows": [{"name": "...", "files_touched": [...], "layers": [...]}],
"modification_hotspots": [...]
},
"evidence_files": [...]
}
```
## Scout 1.10 — External Services
```
Grep for external-service SDK imports (stripe, aws-sdk, redis, kafka, postgres,
elasticsearch, openai, twilio, sendgrid, etc.). Read env var config
(.env.example, config/). Look for timeout / retry / circuit-breaker patterns in
calling code.
Return JSON ONLY:
{
"scout_id": "1.10",
"status": "ok" | "no_evidence",
"structured": {
"services": [{"name": "...", "purpose": "...", "config_location": "..."}],
"env_vars": [...],
"timeout_retry_patterns": [{"service": "...", "pattern": "..."}]
},
"evidence_files": [...]
}
```
## Scout 1.11 — Security Surface
Used to refresh the three DISCOVERED sections of `rules/security-standards.md`
(trust-boundary bullets, per-axis `{discovered}` taxonomy cells,
Project-Specific Security Conventions). The universal taxonomy, required
controls, mass-assignment ban, and abuse-test requirement are fixed text — a
refresh never rewrites them.
```
Find the trust boundary and sensitive fields for security-standards.md.
Identify: (a) entry points where client data enters (controllers / routes /
resolvers / RPC / server actions / queue consumers); (b) how caller identity is
established (session / JWT / auth middleware — pattern + file:line); (c) how object
ownership is enforced before a load or mutate (pattern + file:line, or "NONE
FOUND"); (d) where request validation happens (library + layer); (e) existing
security conventions the codebase already follows (e.g. "all controllers call
requireOwner(ctx, id) before load", "prices come from PriceService.quote()"), each
with a file:line. Then list fields on the money / identity / permission / owner /
state axes, project-specific names included. Each project_conventions entry is
present tense with one `file:line`, no history (rule-file Writing Contract).
Return JSON ONLY:
{
"scout_id": "1.11",
"status": "ok" | "no_evidence",
"structured": {
"entry_points": [{"kind": "...", "example": "file:line"}],
"identity_pattern": "...",
"ownership_pattern": "... | NONE FOUND",
"validation": {"library": "...", "layer": "..."},
"sensitive_fields": [{"name": "...", "axis": "money|identity|permission|owner|state"}],
"project_conventions": [{"pattern": "...", "example": "file:line"}]
},
"evidence_files": [...]
}
```
## Per-Layer Spec Scout
```
Read 2-3 representative files in <layer.dir> (the layer whose spec is stale).
Return JSON ONLY:
{
"layer_name": "...",
"template_skeleton": "<10-15 line code skeleton>",
"allowed_imports": [...],
"forbidden_imports": [...],
"example_file_path": "..."
}
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |