init
Set up a fresh repository, or adopt an existing one, to Lyngon conventions. Interviews the owner relentlessly about purpose, failure modes, audiences, stack and constraints, then writes INTENT.md, .claude/CLAUDE.md, README.md, CONCEPTS.md, decision records, devenv, git hooks, CI and every package in the kind-first Lyngon layout. User-invoked only.
- License 许可
- Apache-2.0
- 所属仓库
- lyngon/devkit
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- init
- description
- Set up a fresh repository, or adopt an existing one, to Lyngon conventions. Interviews the owner relentlessly about purpose, failure modes, audiences, stack and constraints, then writes INTENT.md, .claude/CLAUDE.md, README.md, CONCEPTS.md, decision records, devenv, git hooks, CI and every package in the kind-first Lyngon layout. User-invoked only.
- argument-hint
- [fresh|adopt]
- disable-model-invocation
- true
02 资源文件 4
- 参考文档references/devenv.md20.8 KB
- 参考文档references/interview.md6.5 KB
- 参考文档references/repo-files.md10.5 KB
- 参考文档STRUCTURE.md31 B
03 SKILL.md 正文
Initialize a repository
Overview
One session that takes a repository from "empty" or "grown organically" to the Lyngon baseline. The interview is the core. The files are its output, written only after the owner confirms a shared understanding.
Every repository this skill sets up has the Lyngon documents, the baseline and the workflow.
The one choice is the structure: the interview asks whether the repository adopts the layout defined in STRUCTURE.md, and the structure files below are written only when it does.
The workflow comes with the settings, which enable all and each of its members: the standing instructions of build commit, push and open pull requests without asking.
When to use
- The user asks to initialize, bootstrap, scaffold or set up a repository.
- The user asks to adopt or bring an existing repository "up to standard".
When not to use
- Adding a single file (a decision record, a hook) to a repository that already follows the baseline. Edit it directly.
- Anything unrelated to repository structure. The skill does not write application code.
Workflow
Work through the steps in order. Do not write files before step 3 is confirmed.
1. Inventory
Facts are your job, never the user's. Before asking anything, look up:
git remote -v,git log --oneline | head, tracked files. No tracked files means fresh mode, otherwise adopt mode.- Existing
README.md,INTENT.md,CONCEPTS.md,CONTEXT.md,docs/decisions/,docs/TODO.md, and what an older setup left: aCLAUDE.mdat the root or in a package, a line of.claude/CLAUDE.mdthat is not an import,AGENTS.md,docs/adr/. - Existing
devenv.nix,devenv.yaml,.envrc,flake.nix,.gitignore,.pre-commit-config.yaml,.claude/settings.json,.mcp.json, CI workflows. - Stack markers:
pyproject.toml,uv.lock,package.json,pnpm-lock.yaml,Cargo.toml,go.mod,*.tf,*.cabal,stack.yaml,*.nix, shell scripts. - Existing package layout (
apps/,libs/, a flatpackages/,services/, per-language roots) and root workspace files (pyproject.toml,pnpm-workspace.yaml,Cargo.toml,go.work). - Existing tests and how they run.
Summarize the inventory in at most ten lines, then start the interview. Whatever the inventory settled is not asked again.
2. Interview
Invoke two skills from the discover plugin: discover:interview for the rounds-and-frontier method, and discover:domain-model for settling terms into CONCEPTS.md and recording decisions.
Then follow references/interview.md for the question catalog, the first question ("what would make this repository a failure in a year?"), the rules specific to repository setup, and where each answer lands.
Every question carries a recommended answer. Skipped questions take the recommendation, and you say so at the start of the next round.
Do not turn a "don't know" or "later" into a docs/TODO.md item on your own.
Only what the user explicitly defers goes there.
The interview ends when the frontier is empty.
3. Shared understanding
Present one table: every decision, its answer, and which file it lands in. List the decision records and the rule files you intend to write, by name. Wait for the user to confirm. If they change something, update the table and wait again.
4. Plan the file set
List every file you will create.
In adopt mode, show a diff for every file that already exists and never overwrite silently.
For README.md in adopt mode, merge into the existing structure rather than replacing it.
If an existing README.md states the problem, audience or non-goals, move that content into INTENT.md and leave a link behind.
An existing CLAUDE.md outside .claude/, at the root or in a package, an AGENTS.md, a docs/adr/ and every line of an agent file that is not an import are sorted and then deleted, never kept.
Sort each line and each record by the admission test in discover:domain-model: drop what a check carries, what the tree shows and what holds for every Lyngon repository; a principle that passes becomes a rule file under .claude/rules/, with paths: when it concerns one package, and a decision that passes becomes a record under docs/decisions/, named after the decision.
Show the owner the sorting before deleting anything.
What the owner wants kept as it is goes into a rule file under .claude/rules/, never into an agent file: an agent file holds only imports.
5. Write
In adopt mode, when the repository is on its default branch, create the branch first: git switch -c chore/adopt-lyngon-conventions.
Use the templates and rules in references/repo-files.md and references/devenv.md. The full set:
The documents:
INTENT.mdfrom the round 1 answers: product, for whom, done, failure, non-goals, horizon..claude/CLAUDE.mdholding only the line that importsINTENT.md.<package>/.claude/CLAUDE.mdholding only the line@../INTENT.md, for each existing package with anINTENT.mdof its own..claude/rules/<name>.mdfor each repository principle from step 3, one per file. Most repositories start with none.README.md,CONCEPTS.md,docs/decisions/<name>.mdfor each decision record from step 3,docs/TODO.mdonly if the user deferred something,docs/conventions/<topic>.mdonly for a repository-specific convention too long for a rule file..gitignorewith the baseline patterns,/tmp/,/sandbox/, and the stack patterns..claude/settings.jsonhiding the agent's commit attribution, registering thelyngonmarketplace and enablingall@lyngonand each of its members by name. The README installs the bundle..github/workflows/ci.ymland.github/workflows/pull-request.yml(or the equivalents for the chosen host).
The baseline:
devenv.yaml,devenv.nix,.envrc,.vscode/extensions.json.ruff.tomland[tool.basedpyright]in the rootpyproject.tomlwhen Python is in the stack.tsconfig.base.json,eslint.config.js, and their dev dependencies in the rootpackage.json, when TypeScript is in the stack.secretspec.tomland thesecretspecsection indevenv.yamlwhen the repository needs secrets.- Services (
services.*in devenv) only when the user confirmed each one by name.
The structure, only when the repository adopts it:
lyngon.structure.enable = true;on a line of its own in the rootdevenv.nix; the session hook andadd-packagelook for that line.- The root workspace file for every language in use, with explicit members (see
add-package'sworkspaces.mdreference), andlanguages.*in the rootdevenv.nix. - Every package named in the interview, created through the
add-packageskill of this plugin, which puts it in the directory its kind decides, writes its files and registers it in its workspace and the rootdevenv.yaml.
6. Verify
Run, and fix what fails without disabling hooks:
devenv test
Also confirm that git status shows exactly the planned files.
Report the result faithfully, including hooks that could not run.
7. Commit and hand off
add-package does not commit when this skill invokes it; the commits below include its packages.
In fresh mode the repository has no commits, so there is no base for a pull request: everything lands in one root commit on main.
git symbolic-ref HEAD refs/heads/main
git add -A
git commit -m "chore: initialize repository"
The first command names the unborn branch main when git's default named it otherwise.
Ask before pushing: the commit is on the default branch.
In adopt mode the work is on the branch step 5 created, or on the feature branch init started on. Commit by concern, in an order in which each commit passes the hooks, and put two concerns in one commit when neither passes alone:
docs: adopt the Lyngon documents:INTENT.md, the agent files, the rule files,README.md,CONCEPTS.md, the decision records,docs/,.gitignoreand.claude/settings.json, together with the removal of an oldCLAUDE.md,AGENTS.mdanddocs/adr/.build: import the Lyngon baseline: the devenv files, the linter configurations andsecretspec.toml.ci: run the full check and the pull request check in CI: both workflows.build: adopt the Lyngon structure, only when the repository adopts it: the root workspace files; then onefeat(<name>): add <kind> <name>per package.
Then hand the branch over with build:pull-request.
Print the next steps for the owner:
devenv allowin the repository.- Either
direnv allow, oreval "$(devenv hook zsh)"(or the equivalent for their shell) in their shell configuration. - Install the VS Code extension
mkhl.direnvso the Claude Code extension sees the devenv tools. - In fresh mode without a remote: add one and push
main.
04 同仓库更多 Skills
unslop
Remove AI writing patterns from prose and give it a voice. Use whenever writing or editing non-code text (docs, READMEs, decision records, posts, commit messages, PR descriptions), before handing it over, and on request: "unslop", "humanize", "make this sound human", "clean up this writing", "edit for voice", "de-AI this text".
technical
Layered technical-writing standard: Diátaxis structure, Google developer style sentences, STE instruction rules, Global English syntax. Use before writing or reviewing docs, RFCs, readmes, PR descriptions, or commit messages, every time, however small the document.
simpler
Restate the last message in plain human language, with no jargon. Use when the reader did not follow the last message and says so: "bro", "say that simpler", "in plain words", "no jargon".
add-package
Create a package in a Lyngon repository in the directory its kind decides (apps/, libs/, contracts/, tools/, infra/), with README.md, devenv.nix and the layer lint, and register it in its workspace and devenv. Use whenever a new app, service, CLI, library, adapter, contract, schema, tool, infra module or environment is needed, including when one feature needs several packages. Never create a package by hand.
index
The index of Lyngon's principles, one line per principle saying when it applies and what it demands, each with a file under references/. Invoke before work that takes judgment, such as a design choice, a refactor, a bug fix, a test, a measurement, a script, a document or a question to the owner; then read the file of each principle that applies.
why
Investigate why code, a design or a decision is the way it is, and return a cited answer that separates what was found from what is inferred and what is unknown. Reads the decision records, git history, pull request bodies and reviews, and issues, and any other evidence source the session offers. Use for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed thresholds, and before changing code whose reason is not visible. For how the code behaves at runtime, use discover:how.