scaffold

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Scaffold a mise project

搭建mise项目

This skill stands up a project's mise setup — or upgrades an existing one — so it matches a consistent house pattern and people start shipping immediately instead of reinventing a task runner per repo.

The governing idea: this is advisory, not enforcing. A standard is a strong recommendation, a pattern to adapt to context — not a rule to impose. At every decision point, state the recommended default, explain the pros, cons, and risk of deviating, default to the recommendation, and let the user choose. You are flexible about what gets built (which toolchains, which modules) and opinionated about how it's built (the task contract, the file layout). That combination is what makes a scaffold both fast and consistent.

The goal is to cover the repeated work — the handful of commands a human runs weekly and CI runs on every push (setup, lint, test, build, dev, deploy) — not every conceivable operation. A lean scaffold that nails the common loop beats an exhaustive one nobody reads.

本skill用于为项目搭建mise配置——或升级现有配置——使其符合团队统一模式，让团队成员无需为每个仓库重新设计任务运行器，即可快速投入开发。

核心理念：仅提供建议，不强制执行。标准是强烈的建议，是可根据场景调整的模式——而非必须遵守的规则。在每个决策节点，说明推荐的默认选项，解释优势、劣势以及偏离标准的风险，默认采用推荐方案，同时由用户自主选择。对于构建内容（如工具链、模块）保持灵活，对于构建方式（任务契约、文件布局）则坚持自身主张。这种组合让脚手架既高效又能保证一致性。

目标是覆盖重复性工作——即开发人员每周会运行几次、CI在每次推送时都会执行的少数命令（环境搭建、代码检查、测试、构建、开发、部署）——而非所有可能的操作。能够精准覆盖常用流程的精简脚手架，胜过无人问津的 exhaustive 脚手架。

The model in one breath

核心模式概述

```
mise.toml
```
stays lean:
```
[settings]
```
,
```
[tools]
```
(pinned),
```
[env]
```
. No inline
```
[tasks]
```
.
Every repeatable workflow is a file task at
```
.mise/tasks/<namespace>/<task>
```
. The directory path becomes the task name with
```
:
```
as the separator —
```
.mise/tasks/tf/apply
```
→
```
mise run tf:apply
```
,
```
.mise/tasks/node/setup
```
→
```
mise run node:setup
```
. Run a step across all modules with the glob:
```
mise run '**:setup'
```
.
Future agents get a generated "mise" house-rules skill so they reach for
```
mise run <task>
```
instead of ad-hoc
```
cd packages/x && npm run y
```
.

```
mise.toml
```
保持精简：仅包含
```
[settings]
```
、
```
[tools]
```
（固定版本）、
```
[env]
```
。不包含内联
```
[tasks]
```
。
每个可重复的工作流都是一个文件任务，存放在
```
.mise/tasks/<namespace>/<task>
```
路径下。目录路径会转换为以
```
:
```
分隔的任务名称——例如
```
.mise/tasks/tf/apply
```
对应
```
mise run tf:apply
```
，
```
.mise/tasks/node/setup
```
对应
```
mise run node:setup
```
。可通过通配符跨所有模块执行某一步骤：
```
mise run '**:setup'
```
。
为后续Agent生成**“mise”内部规范skill**，使其优先使用
```
mise run <task>
```
，而非临时编写
```
cd packages/x && npm run y
```
这类命令。

How to work

操作流程

Work through these in order. Lean on the reference files for the actual templates — keep this file in mind for the flow and the why, and open a reference when you reach its step.

Detect the context. Scan the target directory for signals:
```
go.mod
```
,
```
package.json
```
,
```
*.tf
```
/
```
*.tofu
```
,
```
platformio.ini
```
,
```
*.ino
```
/
```
sketch.yaml
```
,
```
compose.y*ml
```
/
```
docker-compose.y*ml
```
,
```
requirements.txt
```
/
```
pyproject.toml
```
, and any existing
```
mise.toml
```
or
```
.mise/
```
. An empty (or nearly-empty) directory is greenfield; anything with code already is brownfield → read
```
references/audit.md
```
and follow the audit path instead of generating blindly.
Pick the toolchains. Greenfield: ask which of {terraform, python, node, go, localstack, docker, arduino, pio, aws-auth} apply. Brownfield: pre-select what you detected and recommend the rest. The namespaces fall out of this choice — picking
```
node
```
+
```
terraform
```
gives you
```
node:*
```
+
```
tf:*
```
.
Talk through the advisory forks. For namespacing, env-file format, version pinning, how to handle account-specific internals, and where the generated agent assets live, read
```
references/standard.md
```
— it has the recommended default and the tradeoffs for each. Present them, recommend, let the user decide. Capture their choices; they drive every template below.
Resolve tool versions. Recommended: pin major.minor resolved at scaffold time (e.g.
```
node = "24"
```
,
```
terraform = "1.13"
```
). It balances reproducibility against staying current. Offer exact-patch (max reproducibility) or major-only (loosest) as alternatives.
Materialize the files (show the tree and diffs first; on brownfield, never overwrite — propose patches and apply on approval):
- ```
mise.toml
```
  — skeleton in
```
references/standard.md
```
  .
- The selected
```
.mise/tasks/**
```
  scripts — templates in
```
references/catalog.md
```
  . Substitute the user's parameters, then
```
chmod +x
```
  each file.
- ```
.env.yaml
```
  (or
```
.env
```
  ),
```
.node-version
```
  /
```
.python-version
```
  ,
```
.gitignore
```
  entries.
- The agent layer —
```
references/agent-layer.md
```
  .
- A short "Tasks" section in the README (or CONTEXT.md) listing what was generated and how to run it.
Verify. Run
```
mise tasks
```
— every generated task must list without a parse error. Then confirm a representative task resolves (e.g.
```
mise run --help
```
or a dry
```
mise run <ns>:lint
```
where safe).

按以下顺序执行操作。参考文件中包含实际模板——本文件用于说明流程和设计思路，执行到对应步骤时可打开参考文件查看细节。

检测上下文。扫描目标目录中的信号：
```
go.mod
```
、
```
package.json
```
、
```
*.tf
```
/
```
*.tofu
```
、
```
platformio.ini
```
、
```
*.ino
```
/
```
sketch.yaml
```
、
```
compose.y*ml
```
/
```
docker-compose.y*ml
```
、
```
requirements.txt
```
/
```
pyproject.toml
```
，以及任何已存在的
```
mise.toml
```
或
```
.mise/
```
目录。空目录（或几乎为空）属于新项目（greenfield）；已有代码的目录属于已有项目（brownfield） → 阅读
```
references/audit.md
```
，按照审计流程操作，而非盲目生成配置。
选择工具链。新项目：询问用户需要用到哪些工具链（可选：terraform、python、node、go、localstack、docker、arduino、pio、aws-auth）。已有项目：预先选中检测到的工具链，并推荐其他可用工具链。命名空间会根据所选工具链自动生成——例如选择
```
node
```
+
```
terraform
```
会生成
```
node:*
```
+
```
tf:*
```
的命名空间。
说明可调整的建议选项。关于命名空间、环境文件格式、版本固定方式、特定账户内部逻辑的处理方式，以及生成的Agent资产存放位置，请阅读
```
references/standard.md
```
——其中包含每个选项的推荐默认值及权衡分析。向用户展示这些选项，给出推荐建议，由用户做决定。记录用户的选择，这些选择将指导后续所有模板的生成。
确定工具版本。推荐方案：在搭建时固定major.minor版本（例如
```
node = "24"
```
、
```
terraform = "1.13"
```
）。这种方式在可重复性和保持版本更新之间取得平衡。同时提供两种备选方案：固定精确补丁版本（最高可重复性）或仅固定大版本（最宽松的版本约束）。
生成文件（先展示文件树和差异；对于已有项目，绝不直接覆盖——提出补丁方案，经用户批准后再应用）：
- ```
mise.toml
```
  ——模板见
```
references/standard.md
```
  中的骨架。
- 选中的
```
.mise/tasks/**
```
  脚本——模板见
```
references/catalog.md
```
  。替换用户指定的参数后，为每个文件添加可执行权限
```
chmod +x
```
  。
- ```
.env.yaml
```
  （或
```
.env
```
  ）、
```
.node-version
```
  /
```
.python-version
```
  、
```
.gitignore
```
  中的相关条目。
- Agent层——模板见
```
references/agent-layer.md
```
  。
- 在README（或CONTEXT.md）中添加简短的“Tasks”部分，列出已生成的任务及运行方式。
验证。运行
```
mise tasks
```
——所有生成的任务必须能正常列出，无解析错误。然后验证代表性任务可正常执行（例如
```
mise run --help
```
，或安全情况下执行 dry run：
```
mise run <ns>:lint
```
）。

The task-file contract (and why it matters)

任务文件契约（及其重要性）

Every

.mise/tasks/<ns>/<task>

file follows the same shape. This isn't ceremony — mise parses these headers to list and document tasks, so a missing

description

means an undiscoverable task, and missing

set -e

means a failing step can silently pass CI.

bash

#!/usr/bin/env bash
#MISE description="One-line, human-readable — shows up in `mise tasks`"
#MISE dir="packages/frontend"          # optional: working directory, relative to repo root
#USAGE arg "<module>" help="…"         # optional: positional args  → $usage_module
#USAGE flag "--auto-approve"           # optional: flags            → $usage_auto_approve
set -e

每个

.mise/tasks/<ns>/<task>

文件都遵循相同的格式。这并非形式主义——mise会解析这些头部信息来列出和文档化任务，因此缺少

description

会导致任务无法被发现，缺少

set -e

会导致失败步骤在CI中静默通过。

bash

#!/usr/bin/env bash
#MISE description="单行、易读的描述——会显示在`mise tasks`中"
#MISE dir="packages/frontend"          # 可选：工作目录，相对于仓库根目录
#USAGE arg "<module>" help="…"         # 可选：位置参数 → $usage_module
#USAGE flag "--auto-approve"           # 可选：标志 → $usage_auto_approve
set -e

… the actual work …

… 实际执行的操作 …


Full per-toolchain templates (already parameterized) live in `references/catalog.md`.


针对各工具链的完整模板（已参数化）见`references/catalog.md`。

The agent layer

Agent层

Two kinds of generated skill, for two different reasons:

Always: one project "mise" house-rules skill. Regenerated with this project's actual namespaces, it teaches future agents the local convention — use
```
mise run
```
, where tasks live, how to add one. Without it, agents drift back to
```
cd x && npm run y
```
and the standard rots. Template in
```
references/agent-layer.md
```
.
Selectively: per-task command-skills, only for destructive or multi-step tasks (
```
tf:apply
```
,
```
tf:plan
```
,
```
localstack:deploy
```
). These carry guardrails — confirm before applying, one resource at a time. A trivial
```
node:lint
```
doesn't need its own skill; the house-rules skill plus raw
```
mise run
```
covers it. Adding a skill per task just dilutes triggering and adds files nobody reads.

生成两种类型的skill，分别用于不同场景：

必选：一个项目级“mise”内部规范skill。根据当前项目的实际命名空间重新生成，用于指导后续Agent遵循本地约定——使用
```
mise run
```
、任务存放位置、添加新任务的方式。如果没有这个skill，Agent会退回到
```
cd x && npm run y
```
这类命令，导致标准逐渐失效。模板见
```
references/agent-layer.md
```
。
可选：针对任务的命令skill，仅用于破坏性或多步骤任务（如
```
tf:apply
```
、
```
tf:plan
```
、
```
localstack:deploy
```
）。这类skill包含防护机制——执行前确认、逐个处理资源。像
```
node:lint
```
这类简单任务不需要单独的skill；内部规范skill加上原生的
```
mise run
```
即可覆盖。为每个任务都添加skill只会分散触发逻辑，增加无人阅读的文件。

Keep account-specific internals out of the repo

避免在仓库中存储特定账户的内部逻辑

Tasks frequently need an AWS account id, a private-registry domain, a region. Never hard-code these — they leak internal identifiers (especially bad for a public repo) and make the task only work in one account. Parameterize them through env (

${AWS_ACCOUNT_ID}

${CODEARTIFACT_DOMAIN}

${AWS_REGION}

) sourced from

.env.yaml

, and treat

aws-auth

as a sourced helper other tasks pull in — see

references/catalog.md

任务经常需要AWS账户ID、私有镜像仓库域名、区域等信息。绝不要硬编码这些信息——这会泄露内部标识符（对于公共仓库尤其危险），且会导致任务仅能在单个账户中运行。通过环境变量（

${AWS_ACCOUNT_ID}

、

${CODEARTIFACT_DOMAIN}

、

${AWS_REGION}

）从

.env.yaml

中获取这些参数，并将

aws-auth

作为其他任务可调用的辅助工具——详见

references/catalog.md

。

Reference files

参考文件

```
references/standard.md
```
— the conventions with their tradeoffs (namespacing, env format, pinning, internals, agent-asset destination) + the
```
mise.toml
```
skeleton. Read at step 3–4.
```
references/catalog.md
```
— the per-toolchain core task templates (parameterized bash). Read at step 5.
```
references/agent-layer.md
```
— the house-rules skill template + the command-skill template + the rule for which tasks qualify. Read at step 5.
```
references/audit.md
```
— brownfield drift detection and the report-then-fix-on-approval procedure. Read at step 1 whenever the directory already has code.

```
references/standard.md
```
——包含各项约定及其权衡分析（命名空间、环境文件格式、版本固定方式、内部逻辑处理、Agent资产存放位置）+
```
mise.toml
```
骨架。在步骤3-4时阅读。
```
references/catalog.md
```
——针对各工具链的核心任务模板（已参数化的bash脚本）。在步骤5时阅读。
```
references/agent-layer.md
```
——内部规范skill模板 + 命令skill模板 + 任务筛选规则。在步骤5时阅读。
```
references/audit.md
```
——已有项目的偏差检测流程，以及“先报告、经批准后修复”的操作步骤。当目录中已有代码时，在步骤1阅读。