grund-init
Use when bootstrapping or adopting grund in a repository, especially when the user wants an interactive guided setup for grund init, grund.toml, AGENTS.md, docs scaffolding, citation format, scan scope, output format, or Markdown link settings.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 4
- Forks
- 1
01 前言 Front Matter
- name
- grund-init
- description
- Use when bootstrapping or adopting grund in a repository, especially when the user wants an interactive guided setup for grund init, grund.toml, AGENTS.md, docs scaffolding, citation format, scan scope, output format, or Markdown link settings.
02 资源文件 10
- 参考文档references/citations.md12.4 KB
- 参考文档references/config.md14.2 KB
- 参考文档references/editor.md1.9 KB
- 参考文档references/integrations.md3.6 KB
- 参考文档references/languages.md9.8 KB
- 参考文档references/members.md3.9 KB
- 参考文档references/queries.md1.9 KB
- 参考文档references/rules.md23.7 KB
- 参考文档references/schema.md950 B
- 参考文档references/scoped-guidance.md1.9 KB
03 SKILL.md 正文
grund init
Guide the user through grund adoption. grund init itself is non-interactive, so this skill acts as the interactive wrapper: inspect the repository, recommend suitable settings, ask the user to confirm or override every option, write grund.toml, run grund init, then validate.
Fresh repository
A repository is fresh when it has no grund.toml, at its root or under .agents/, and no specs, decision records or tests to adopt. Say you are taking the defaults, and once the user agrees, run these three commands in order:
grund init --scaffold --name <name> --agents-md # add --claude, --gemini, … for each agent in use
grund init --check
grund check
Success is all three exiting 0. On a fresh scaffold the last one also warns nothing recognized until the first declaration exists: that is expected, and nothing to fix. A fresh repository takes every default after that one confirmation, so that is the whole setup. Any repository that is not fresh is an adoption, and its per-option interview is the workflow grund guide setup prints.
Contents
This core, the section setup, holds Fresh repository, Contents, Workflow, Repo Analysis First, Asking Style, Init Questions, Existing Specs Adoption, Validation and Maintaining Declarations. The rest of the guide is ten reference sections, each printed on request by grund guide <name>; where this skill is installed as a directory, the same text is references/<name>.md.
grund guide config(references/config.md): how to recommend each setting, then the config questions.grund guide citations(references/citations.md): the citation-directions question, version 1's[citations]and version 2's[rules.citations], and its reference.grund guide languages(references/languages.md): language and repo-shape examples, version-2 sources, and moving from version 1.grund guide members(references/members.md): splitting off a member.grund guide scoped-guidance(references/scoped-guidance.md): where a version-2 config writes each row's guidance.grund guide schema(references/schema.md): seeing the schema withgrund schema.grund guide queries(references/queries.md): querying the structure.grund guide editor(references/editor.md): wiring an editor togrund-lsp.grund guide integrations(references/integrations.md): clickable-citation integrations.grund guide rules(references/rules.md): writing chapter rules.
grund guide --full prints this core and then every section, in this order.
Workflow
- Inspect the target repo before asking questions. Find existing specs, artifact types, roadmaps, changelogs, decisions, plans, tests, and agent instruction files before recommending anything.
- Present a short "detected repo shape" summary and recommended setup.
- If existing specs or spec-like artifacts are present, show the canonical
grundartifact types beside the detected project-specific sections/tags/document classes, then ask which artifact model to adopt before writing config or refactoring docs. - Fetch
grund guide configfor recommendations and questions except citation directions, andgrund guide citationsfor those (version 1's[citations], version 2's[rules.citations]). Directory copies:references/config.mdandreferences/citations.md. Ask each remaining question with a recommendation, repo evidence, pros, cons and when to choose otherwise. - Write
grund.tomlfrom the analysis beforegrund init, so guidance reflects its grammar, marker, strict mode, kinds, artifact folders and scan scope. Without a config, rungrund initfirst: its v2 starter writes only non-defaults — project name, kind rows, places and titles. Add only user-chosen overrides. Showgrund config show: it prints effective settings with defaults in the config's version; copy a line intogrund.tomlto override it. Usegrund config explainfor that version's keys and each check code's fix. To adopt,grund init --template=nonewrites v2 config with no kinds. Before adding a kind, run check's offline help,grund config explain '[schema.kinds.<NAME>]', orgrund config explain schema.kindsfor the same child key rows. Add[schema.kinds.<KIND>]tables with declarationfoldersorfiles, then rerungrund initto teach entrypoints. - Run
grund init [path] [--name NAME] [--force], adding--scaffoldonly when the repo is fresh or the user selected a canonical-layout migration needing starter files.--nameoverrides the target config'sproject_nameor, without one, its directory name.--dry-runpreviews;--checkgates pre-commit/CI without writes.grund checkreports stale managed blocks;init --checkalso covers unjudged files, such as a member's workspace sections. A target needs a.git,.hg,.jjor.svnmarker in itself or an ancestor; initialize its VCS first or pass--no-vcs. The home directory and machine-global agent files (~/.claude/CLAUDE.md,~/.codex/AGENTS.md, etc.) are refused regardless of flags: correct the target path. Follownext:, which names a configured kind and its home. For non-FSkinds, create a missing home manually:--scaffoldlays the whole software-development starter, not that home alone, placing homes at its fixed places (aREQrow's folder), so it can miss one. Without--scaffold, no block means only that the home exists. - Run
grund config validate [path]andgrund check [path]. At a workspace root,config validatenames the config findingschecknames;config show, only its own config's. - Summarize generated files, validation results, existing specs/artifacts found, and any follow-up cleanup.
- Optionally offer to wire the user's editor to the
grund-lspserver (see Editor Setup:grund guide editor). Editor configuration is the user's one-time work, not somethinggrund initwrites — so only offer it, and prefer editor user settings over a per-repo config to make the configuration available across projects. User settings do not grant Workspace Trust; Editor Setup (grund guide editor) gives the VSCode / VSCodium prerequisite.
Repo Analysis First
Use rg and rg --files first. Prefer evidence from existing files over generic defaults.
Analyze:
- Existing
AGENTS.md, agrund.tomlin either discovery location (root or.agents/), and grund-style citations. - Documentation layout:
docs/,e2e/,spec/,rfcs/,adr/,decisions/,roadmap,changelog. - Existing artifact types and their homes: specifications, requirements, RFCs, ADRs/decisions, roadmaps, changelogs, plans, end-to-end fixtures, examples, package READMEs, generated reports, and runtime logs. Use these to choose configured places and source exclusions: version 2 uses
[schema.kinds.<KIND>]and[schema.sources] exclude; version 1 uses[[kinds]]and[scan] include/exclude. Do not add generic folders when the repo already has project-specific artifact homes. - Source layout:
src/,lib/,crates/,packages/,apps/,services/,cmd/,internal/,pkg/,test/,tests/. - Languages from file extensions and manifests such as
Cargo.toml,package.json,pyproject.toml,go.mod,pom.xml,build.gradle,.csproj,Package.swift,Gemfile,composer.json,build.sbt,CMakeLists.txt,dbt_project.yml. - Ignore/build/vendor directories from
.gitignoreand common generated paths. - Existing ID/citation patterns, including headings and tokens that look like
FS-001-login,FS-login,ADR-001,RFC-42, or§FS-.... - Existing rendered-doc target: GitHub default, GitLab, MkDocs, Pandoc, or unknown.
- Whether this is a fresh repo, a docs-heavy repo, or an existing codebase adopting grund.
Asking Style
Ask the user to confirm or change a recommendation, never a blank preference survey. Each prompt must include the recommended value, evidence from repo analysis, pros, cons, and when to choose a different value. Let the user accept the full set quickly while still seeing and overriding every option.
Init Questions
Ask first:
- Target path: default
. - Project name: default target config value, then target directory basename
- Artifact model when existing specs are detected: canonical
grund, canonical core plus project-specific extras, or existing structure with citations - Template and starter files:
--template=software-development(the default, canonical kinds) or--template=none(no kinds, for the existing-structure model);--scaffoldto lay the starter files: default no for existing repos, yes for fresh repos - Existing file behavior: append/update default, or
--force
Existing Specs Adoption
When the repo already contains specs, requirements, ADRs, RFCs, design docs, plans, tests, or other spec-like artifacts, do not silently scaffold over them or refactor them into canonical grund folders. First show the user:
- The canonical
grundartifact types:GRUND— reason / grounding docGOAL— project goalsFS— functional specsAR— architecture specsDF— functional decisionsDA— architectural decisionsE2E— executable scenariosRM— roadmap
- The detected project-specific sections, tags, or document classes, such as
ADR,RFC,REQ,SPEC,DESIGN,PLAN,RUNBOOK, or whatever the repo already uses.
Then ask the user to choose one adoption model:
| Option | When to recommend it | What the agent does |
|---|---|---|
Canonical grund |
Fresh or lightly documented repos, or users who explicitly want to reorganize around grund conventions. |
Use GRUND, GOAL, FS, AR, DF, DA, E2E, and RM as the complete artifact model; add or refactor docs toward canonical homes only after user confirmation. |
| Canonical core plus project-specific extras | Repos with useful existing ADRs/RFCs/requirements but no clear behavior-vs-architecture backbone. | Use GRUND, GOAL, FS, and AR as the grounding backbone, then add custom kinds for project-specific artifacts: [schema.kinds.<KIND>] in version 2, [[kinds]] in version 1. |
| Existing structure with citations | Mature repos with a strong existing taxonomy or high migration cost. | Start from grund init --template=none, whose config declares no kinds; preserve current sections/tags/document classes, configure the kinds and their places around them ([schema.kinds.<KIND>] in version 2; [[kinds]] and [scan] in version 1), and add grund citations/declarations without forcing canonical folders. |
The question should include a recommendation grounded in the inventory. Do not write grund.toml, run grund init --scaffold, move documents, rename headings, or add bulk citations until the user chooses the adoption model. Once selected, use the model to decide whether the setup is only config plus entrypoint refresh, or a broader docs refactor with a visible plan.
Validation
init rule findings earn 1 even with current paths or --dry-run;
--check also fails on pending paths. Read stdout findings separately from
stderr paths: grund guide rules (references/rules.md).
After writing config, run:
grund config validate .
grund init .
grund check .
grund check --full .
The last line checks beyond configured source scope: grund check . uses the ordinary scope, while grund check --full . widens the walk to report unresolved references and section headings outside declaration bodies there (the full-tree scope). Version 1 scopes with [scan] include; version 2 uses configured places and the code complement. Source exclusions still apply: [schema.sources] exclude in v2, [scan] exclude in v1. For workspace boundaries and exclusions, run grund guide members.
Read an unused warning's index-entry location alongside grund refs <ID> and
grund refs <ID> --summary: refs retains the citation and labels it as an index
entry, while check excludes it from use. In mixed summaries, read the annotated
lines (and columns) as the excluded sites only. Keep a useful unused declaration
or cite an actual dependency; do not invent a dependency just to silence the
warning. See the checking guide
and the runnable example.
grund refs on an uncited ID notes grund list --unused: run that once, not refs per ID.
value mismatch for <ID> (component <path>): keep the root citation, fix the whole literal (values guide).
If a project needs its own grammar or independent check, follow
Splitting off a member (grund guide members), then validate from the workspace root.
For an existing version-1 config, grund config migrate --to 2 previews the
translation. Read each listed comment's local reason and destination guidance:
moving a comment from the version-1 include key to the [scan] header still leaves it on a split
attachment. To keep its prose, save it, explicitly authorize the listed drops
with --write --drop-comments, and re-add it at the named version-2 destination
after a successful write. Choose placement manually for a dropped setting or a
comment without a destination. When destinations are unavailable, repair and
preview again first; comment consent clears no setting refusal or comparison
gate. See the migration report contract
and runnable recovery walkthrough.
Maintaining Declarations
Before a rename or file move, run grund refs <ID> to find its citations.
Edit the declaration and authored citation IDs, then run grund fmt --write
from the config, project or workspace root. When cross-reference emission
applies, fmt re-derives generated link destinations and anchors; the
root-scoped write also updates eligible section locks. Run grund check and
grund fmt --check; commit lock changes. File-only moves keep ID-keyed lock
names. Do not hand-edit locks or expect fmt to replace authored IDs, repair
arbitrary URLs, or silently approve a protected section move. Its error names
every stale citation; grund config explain section-address-changed names
the fixes.
A link the author wrote around a citation is theirs in every Markdown form:
inline, wrapped, a reference, a definition, an autolink or HTML <a>. fmt
neither rewrites nor follows it, so repair it by hand; its citation is still
checked. A citation-only image in a kind's index,
, is no entry: write the link beside it, or the ID is reported
missing (authored links,
example).
Describe a write by fmt's report, which names each rewrite, counts
kinds and marks lock files deleted or created. Use the
maintenance guide
and its copy-based rename example.
04 同仓库更多 Skills
review
暂无简介
review
暂无简介
grund-init
Use when bootstrapping or adopting grund in a repository, especially when the user wants an interactive guided setup for grund init, grund.toml, AGENTS.md, docs scaffolding, citation format, scan scope, output format, or Markdown link settings.