AGENT SKILL

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

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: a CLAUDE.md at the root or in a package, a line of .claude/CLAUDE.md that 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 flat packages/, 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.md from the round 1 answers: product, for whom, done, failure, non-goals, horizon.
  • .claude/CLAUDE.md holding only the line that imports INTENT.md.
  • <package>/.claude/CLAUDE.md holding only the line @../INTENT.md, for each existing package with an INTENT.md of its own.
  • .claude/rules/<name>.md for each repository principle from step 3, one per file. Most repositories start with none.
  • README.md, CONCEPTS.md, docs/decisions/<name>.md for each decision record from step 3, docs/TODO.md only if the user deferred something, docs/conventions/<topic>.md only for a repository-specific convention too long for a rule file.
  • .gitignore with the baseline patterns, /tmp/, /sandbox/, and the stack patterns.
  • .claude/settings.json hiding the agent's commit attribution, registering the lyngon marketplace and enabling all@lyngon and each of its members by name. The README installs the bundle.
  • .github/workflows/ci.yml and .github/workflows/pull-request.yml (or the equivalents for the chosen host).

The baseline:

  • devenv.yaml, devenv.nix, .envrc, .vscode/extensions.json.
  • ruff.toml and [tool.basedpyright] in the root pyproject.toml when Python is in the stack.
  • tsconfig.base.json, eslint.config.js, and their dev dependencies in the root package.json, when TypeScript is in the stack.
  • secretspec.toml and the secretspec section in devenv.yaml when 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 root devenv.nix; the session hook and add-package look for that line.
  • The root workspace file for every language in use, with explicit members (see add-package's workspaces.md reference), and languages.* in the root devenv.nix.
  • Every package named in the interview, created through the add-package skill of this plugin, which puts it in the directory its kind decides, writes its files and registers it in its workspace and the root devenv.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:

  1. docs: adopt the Lyngon documents: INTENT.md, the agent files, the rule files, README.md, CONCEPTS.md, the decision records, docs/, .gitignore and .claude/settings.json, together with the removal of an old CLAUDE.md, AGENTS.md and docs/adr/.
  2. build: import the Lyngon baseline: the devenv files, the linter configurations and secretspec.toml.
  3. ci: run the full check and the pull request check in CI: both workflows.
  4. build: adopt the Lyngon structure, only when the repository adopts it: the root workspace files; then one feat(<name>): add <kind> <name> per package.

Then hand the branch over with build:pull-request.

Print the next steps for the owner:

  1. devenv allow in the repository.
  2. Either direnv allow, or eval "$(devenv hook zsh)" (or the equivalent for their shell) in their shell configuration.
  3. Install the VS Code extension mkhl.direnv so the Claude Code extension sees the devenv tools.
  4. In fresh mode without a remote: add one and push main.

04 同仓库更多 Skills

lyngon
lyngon/devkit

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".

★ 0
lyngon
lyngon/devkit

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.

★ 0
lyngon
lyngon/devkit

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".

★ 0
lyngon
lyngon/devkit

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.

★ 0
lyngon
lyngon/devkit

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.

★ 0
lyngon
lyngon/devkit

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.

★ 0