groundwork
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinese<!-- GENERATED — edit .claude/skills/groundwork/ instead. Synced by sync-from-dev.mjs. -->
<!-- 生成文件 — 请编辑 .claude/skills/groundwork/ 下的文件。由 sync-from-dev.mjs 同步。 -->
groundwork — research → plan → orchestrate → act, packaged
groundwork — 研究→规划→编排→执行,一站式封装
This file is a router. Each action and each agent role lives in its own file under and ; load on demand. The state mechanism (, fences, hash-diff, IDs) is fully specified in — every action obeys it. Read before doing anything that writes to disk.
actions/agents/.groundwork.jsonlib/state.mdlib/state.mdThe full design lives in ; locked decisions in (Rounds 1–4). This skill is the executable form of that plan.
plans/groundwork/01-plan.mdplans/groundwork/04-discussion.md本文件为路由文件。每个操作和Agent角色都位于和下的独立文件中;按需加载。状态机制(、标记块、哈希差异、ID)在中有完整说明——所有操作均遵循该机制。在执行任何写入磁盘的操作前,请先阅读。
actions/agents/.groundwork.jsonlib/state.mdlib/state.md完整设计方案位于;已锁定的决策记录在(第1-4轮)。本skill是该规划的可执行版本。
plans/groundwork/01-plan.mdplans/groundwork/04-discussion.mdWhat groundwork is for
groundwork的用途
Stripped to one sentence: a stateless action-set that scaffolds and maintains a folder of living planning documents, with traceable IDs threading plan → tracking → orchestration → board, so re-runs augment instead of clobber and a multi-agent kickoff falls out the back end. Originated from the planning workflow; generalized so it works for non-code, non-Ikenga work too.
com.ikenga.studioSurface model:
| Surface | What it is | Trigger |
|---|---|---|
Scaffolder ( | First-run interview + folder skeleton drop | User has a goal but no plan folder |
Action: | Researcher agent fills | After scaffolder, or to refresh |
Action: | Produces ≥2 comparable | Visual/UX work, profile-gated |
Action: | Scaffolds a focused | A hard piece needs its own focused doc (critical-path PR plan, between-round deliberation, postmortem) |
Action: | Reviewer agent → new Round in | Recurring, highest-value |
Action: | Readiness gate before | Before kickoff |
Action: | Generates | When ready to kick off |
Action: | (Re)generates | Whenever board falls behind |
Action: | Regenerates the | When the living-spec's auto tabs fall behind |
Action: | Read-only freshness + ID + design-coverage + sub-plan report | Anytime |
init.groundwork.jsoninit一句话概括:一套无状态操作集,用于搭建和维护动态规划文档文件夹,通过可追踪ID串联规划→跟踪→编排→看板,确保重复执行时仅增强而非覆盖内容,同时支持多Agent协作启动。源自的规划工作流;已通用化,适用于非代码、非Ikenga相关工作。
com.ikenga.studio表层模型:
| 模块 | 说明 | 触发条件 |
|---|---|---|
脚手架( | 首次运行引导对话 + 文件夹骨架生成 | 用户有目标但无规划文件夹 |
操作: | Researcher Agent填充 | 脚手架完成后,或需刷新研究内容时 |
操作: | 为当前阶段生成≥2个可对比的 | 视觉/UX工作,受配置文件限制 |
操作: | 从三种原型(diff-plan / decision-doc / bug-doc)中搭建聚焦的 | 某一复杂部分需要独立的聚焦文档(如关键路径PR规划、轮次间审议、事后分析) |
操作: | Reviewer Agent → 在 | 定期执行,价值最高的操作之一 |
操作: | 执行 | 启动前执行 |
操作: | 从 | 准备启动时执行 |
操作: | (重新)生成 | 看板内容滞后时 |
操作: | 根据 | 动态规范的自动标签页内容滞后时 |
操作: | 只读的新鲜度 + ID + 设计覆盖范围 + 子规划报告 | 随时可执行 |
init.groundwork.jsoninitRouting
路由规则
Match the user's request against the table; load the matching action file and follow it. Do not inline action behavior in this file — the actions are the source of truth.
| If the user says… | Load this | Then |
|---|---|---|
| "scaffold groundwork", "init", "new plan folder", "start groundwork in X/" | | Interview goal + profile, scaffold, write |
| "groundwork research", "do a research pass", "fill 02/03" | | Spawn researcher; write inside fences |
| "groundwork design", "design pass", "mock up the UI options" | | Profile-gated; compose design skill or plain HTML; lock one |
| "groundwork subplan", "scaffold an NN-*.md", "new diff-plan / decision-doc / bug-doc" | | Scaffold a focused sub-plan from one of three archetypes; register in |
| "groundwork review", "review pass", "gap analysis" | | Spawn reviewer; append Round; re-sync via IDs |
| "groundwork clarify", "ready to orchestrate?" | | Scan for open questions + unspecified IDs + missing locked designs |
| "groundwork orchestrate", "generate 09", "wave plan" | | Runs clarify first; emits |
| "refresh the board", "update artifact/board.html" | | Re-derive board data from current docs |
| "refresh the living spec", "update artifact/index.html", "the Phasing/Decisions/Risks tabs are stale" | | Regenerate only the |
| "groundwork status", "where are we" | | Read-only report |
将用户请求与下表匹配;加载对应的操作文件并执行。请勿在此文件中嵌入操作逻辑——操作文件才是事实来源。
| 用户请求示例 | 加载文件 | 后续操作 |
|---|---|---|
| "scaffold groundwork"、"init"、"new plan folder"、"start groundwork in X/" | | 引导对话收集目标+配置文件,搭建文件夹,写入 |
| "groundwork research"、"do a research pass"、"fill 02/03" | | 启动Researcher;在标记块内写入内容 |
| "groundwork design"、"design pass"、"mock up the UI options" | | 受配置文件限制;组合设计skill或生成纯HTML;锁定一个版本 |
| "groundwork subplan"、"scaffold an NN-*.md"、"new diff-plan / decision-doc / bug-doc" | | 从三种原型中搭建聚焦子规划;在 |
| "groundwork review"、"review pass"、"gap analysis" | | 启动Reviewer;追加轮次;通过ID重新同步 |
| "groundwork clarify"、"ready to orchestrate?" | | 扫描未解决问题 + 未指定ID + 缺失的锁定设计 |
| "groundwork orchestrate"、"generate 09"、"wave plan" | | 先执行clarify;生成 |
| "refresh the board"、"update artifact/board.html" | | 从当前文档重新生成看板数据 |
| "refresh the living spec"、"update artifact/index.html"、"the Phasing/Decisions/Risks tabs are stale" | | 仅重新生成 |
| "groundwork status"、"where are we" | | 生成只读报告 |
Discover vs. fast path
发现路径 vs 快速路径
- Discover path — invoked cold ("scaffold a plan for X"). Run the interview to capture goal + profile, then suggest
initas the next step.research - Fast path — invoked in an existing groundwork folder ("groundwork review"). Read , dispatch to the named action immediately. No interview unless the action itself needs one.
.groundwork.json
If invoked from inside a folder with no , treat as discover even if the action name was given — refuse the action with a one-line "this folder isn't a groundwork plan yet; run first."
.groundwork.jsoninit- 发现路径 — 首次调用(如“为X搭建规划”)。执行引导对话收集目标+配置文件,然后建议下一步执行
init。research - 快速路径 — 在已有的groundwork文件夹中调用(如“groundwork review”)。读取,直接分发到指定操作。除非操作本身需要,否则无需引导对话。
.groundwork.json
如果在无的文件夹中调用,即使指定了操作名称,也视为发现路径——拒绝执行操作,并提示“此文件夹尚未是groundwork规划;请先执行”。
.groundwork.jsoninitClick-to-fire prompts (per-action)
一键触发提示(按操作分类)
Each action file under carries a section at the bottom with two flavors: a standalone slash form () and a seeded-session form (a self-contained brief that works even in a chat where the skill isn't loaded). The Phase-4 board surfaces (Kickoff card / ⌘K palette / argument pickers) read these as their canonical strings — they are the single source of truth shared between the FE and the orchestrator agent. Substitution variables are documented inline per action (typically , , , ).
actions/## Click-to-fire prompt/groundwork <action> [args]{plan_folder}{plan_title}{plan_slug}{profile}actions/## Click-to-fire prompt/groundwork <action> [args]{plan_folder}{plan_title}{plan_slug}{profile}Profiles
配置文件(Profiles)
A profile swaps vocabulary and optional blocks, not the spine. Templates use placeholders (same substitution convention as 's /).
{{vocab.*}}ikenga-pkg-builder{{id}}{{slug}}| Profile | Default for | | | Optional |
|---|---|---|---|---|
| Ikenga features, any code work | "work package" / PR | | schema, manifest, adapter contracts, critical files |
| Non-code work — campaigns, org changes, research | "workstream" / "deliverable" | | stakeholders, deliverables, success metrics |
| Editorial/marketing — content series, campaigns with key art | "piece" / "asset" | | editorial standards, distribution plan |
Maintenance model: a single base + thin per-profile overlays. declares ; only diffs need to live in the overlay. Format spec in §"Domain profiles."
profiles/_shared/profile.jsonextends: "_shared"01-plan.mdstatus配置文件替换的是词汇和可选模块,而非核心框架。模板使用占位符(与的/替换规则一致)。
{{vocab.*}}ikenga-pkg-builder{{id}}{{slug}}| 配置文件 | 默认适用场景 | | | |
|---|---|---|---|---|
| Ikenga功能、各类代码工作 | "work package" / PR | | 架构、清单、适配器契约、关键文件 |
| 非代码工作——活动、组织变更、研究 | "workstream" / "deliverable" | | 利益相关者、交付物、成功指标 |
| 编辑/营销类——内容系列、带核心素材的活动 | "piece" / "asset" | | 编辑标准、分发计划 |
维护模型:单个基础模板 + 轻量化的配置文件覆盖层。声明;仅需在覆盖层中保留差异内容。格式规范见 §“Domain profiles”。
profiles/_shared/profile.jsonextends: "_shared"01-plan.mdstatusState, identity & idempotency
状态、标识与幂等性
The contract that makes stateless actions safe over an existing folder:
- at the folder root is the identity + state anchor every action reads first.
.groundwork.json - Generated-region fences (…
<!-- groundwork:auto:start ID -->) demarcate the only blocks an action may write. Everything outside a fence is hand-authored and never touched.<!-- groundwork:auto:end ID --> - Re-runs diff, not overwrite — an action recomputes a region, hashes it, and writes only when the hash differs.
- Stable IDs (gaps,
G-NNwork packages,WP-NNgates,G-<NAME>designs) threadD-NN→01→05→ board; the review action computes the affected-doc set from IDs + hashes, not from guessing.09
The full schema, fence grammar, hash-diff algorithm, and a worked example: . Read it before any action that writes.
lib/state.md确保无状态操作在现有文件夹中安全执行的契约:
- 位于文件夹根目录,是所有操作首先读取的标识+状态锚点。
.groundwork.json - 生成区域标记块(…
<!-- groundwork:auto:start ID -->)划定了操作仅可写入的区块。标记块外的所有内容均为手写,永远不会被修改。<!-- groundwork:auto:end ID --> - 重新执行时对比差异而非覆盖 — 操作重新计算区域内容,生成哈希值,仅当哈希值不同时才写入。
- 稳定ID(阶段、
G-NN工作包、WP-NNgate、G-<NAME>设计)串联D-NN→01→05→ 看板;review操作根据ID+哈希值计算受影响的文档集,而非猜测。09
完整的 schema、标记块语法、哈希差异算法及示例:。执行任何写入操作前请先阅读。
lib/state.mdComposition
组合能力
groundwork composes existing skills rather than reimplementing them. Soft dependencies — every composed skill has a fallback:
| Capability | Preferred skill | Fallback |
|---|---|---|
| Plan-board artifact | | Self-contained template at |
Design-quality spine (every | | Plain self-contained HTML under Claude's own craft direction |
| Interactive / data-bearing design mockup | | Plain self-contained HTML (studio's mockups needed nothing more) |
| Scroll-driven narrative mockup | | Plain self-contained HTML |
| Hi-fi / production frontend | | huashu-design alone |
| Anti-slop polish / critique / audit pass | | huashu's own expert-review pass |
| Build handoff for Ikenga pkgs | | |
| Requirements interviews | | n/a — always present in Claude Code |
The action does not pick one skill from this list — is the always-on quality spine and Claude layers any combination of the others on top, deciding the blend while building (no limits). If is absent, writes the self-contained fallback template. If no design skill at all is installed, falls back to plain HTML.
designhuashu-designikenga-artifact-builderrefresh-boarddesigngroundwork组合现有skill而非重新实现。软依赖——每个组合的skill都有 fallback方案:
| 能力 | 首选skill | 降级方案 |
|---|---|---|
| 规划看板制品 | | |
设计质量核心框架(每次 | | Claude自主生成的纯独立HTML |
| 交互式/带数据的设计原型 | | 纯独立HTML(工作室原型无需更多内容) |
| 滚动驱动叙事原型 | | 纯独立HTML |
| 高保真/生产级前端 | | 仅使用huashu-design |
| 精细化打磨/评审/审计 | | huashu自身的专家评审流程 |
| Ikenga包构建交付 | | |
| 需求访谈 | | 无——Claude Code中始终存在 |
designhuashu-designikenga-artifact-builderrefresh-boarddesignPortability
可移植性
groundwork| Capability | In Ikenga shell | Plain Claude Code / terminal | Any browser |
|---|---|---|---|
| Scaffold + actions | ✅ | ✅ | n/a |
| Research / review / orchestrate | ✅ | ✅ | n/a |
| Plan-board (view) | ✅ live status | ✅ open file | ✅ static |
| Copy brief from board | ✅ | ✅ | ✅ |
| Start session (click-to-implement) | ✅ (Phase 2) | ➖ copy-prompt | ➖ copy-prompt |
| Live tracking binding | ✅ (Phase 2) | ➖ reads | ➖ |
Phase 1 (this skill) ships everything in the "Plain Claude Code / terminal" column and the static-board column. The verb + live-tracking binding land in Phase 2 and are explicitly out of scope here — do not modify or .
host.startChatSessionshell/contract/groundwork| 能力 | 在Ikenga shell中 | 纯Claude Code / 终端 | 任意浏览器 |
|---|---|---|---|
| 搭建 + 操作 | ✅ | ✅ | 不适用 |
| 研究 / 评审 / 编排 | ✅ | ✅ | 不适用 |
| 规划看板(查看) | ✅ 实时状态 | ✅ 打开文件 | ✅ 静态查看 |
| 从看板复制简要说明 | ✅ | ✅ | ✅ |
| 启动会话(一键执行) | ✅ (Phase 2) | ➖ 复制提示语 | ➖ 复制提示语 |
| 实时跟踪绑定 | ✅ (Phase 2) | ➖ 读取 | ➖ |
**Phase 1(当前skill)**包含“纯Claude Code / 终端”列和静态看板列的所有功能。动词 + 实时跟踪绑定将在Phase 2推出,不在当前范围内——请勿修改或。
host.startChatSessionshell/contract/Critical files (this skill)
关键文件(本skill)
groundwork/
├── SKILL.md ← you are here (router only)
├── lib/state.md ← state machine spec — every action obeys
├── actions/
│ ├── init.md
│ ├── research.md
│ ├── design.md
│ ├── subplan.md ← scaffold NN-*.md sub-plans (diff-plan / decision-doc / bug-doc)
│ ├── review.md
│ ├── clarify.md
│ ├── orchestrate.md
│ ├── refresh-board.md
│ └── status.md
├── agents/
│ ├── researcher.md ← brief template the research action spawns
│ ├── reviewer.md ← brief template the review action spawns
│ └── orchestrator.md ← brief template the orchestrate action spawns
└── profiles/
├── _shared/
│ ├── profile.json ← base vocab + spine list
│ ├── templates/ ← spine docs with {{vocab.*}} + fences
│ │ ├── 00-README.md
│ │ ├── 01-plan.md
│ │ ├── 02-research-external.md
│ │ ├── 03-research-internal.md
│ │ ├── 04-discussion.md
│ │ ├── 05-tracking.md
│ │ ├── subplans/ ← NN-*.md archetype templates
│ │ │ ├── diff-plan.md
│ │ │ ├── decision-doc.md
│ │ │ └── bug-doc.md
│ │ └── artifact/ ← scaffolded into <plan>/artifact/
│ │ ├── manifest.json
│ │ └── data/ ← optional external data sources
│ └── board/index.html ← self-contained Mission Control + Wave-toggle
├── software/
│ ├── profile.json ← `extends: _shared`, produces_designs: true
│ └── templates/ ← thin overlays (only the docs that differ)
└── general/
├── profile.json ← `extends: _shared`, produces_designs: false
└── templates/The reference instance — the canonical worked example of every artifact in this spine — is in this workspace. Re-derive the spine from it on major bumps.
plans/studio/spine_versionCaveat on the studio reference: studio predates two later locks — the living-spec / tracking-board split (commit : studio's is a single tabbed artifact, not the living-spec + tracking-board pair this skill scaffolds) and the state anchor (studio has none). Read studio for the spine shape and the prose conventions (Round bodies, WP briefs, lifted-from headers, per-phase design discipline) — not as a literal current-shape template. The dogfood at is the up-to-date worked example of the post-split, anchored layout.
a6bc357artifact/index.htmlindex.htmlboard.html.groundwork.jsonplans/groundwork/groundwork/
├── SKILL.md ← 当前文件(仅路由)
├── lib/state.md ← 状态机规范——所有操作均遵循
├── actions/
│ ├── init.md
│ ├── research.md
│ ├── design.md
│ ├── subplan.md ← 搭建NN-*.md子规划(diff-plan / decision-doc / bug-doc)
│ ├── review.md
│ ├── clarify.md
│ ├── orchestrate.md
│ ├── refresh-board.md
│ └── status.md
├── agents/
│ ├── researcher.md ← research操作启动的简要模板
│ ├── reviewer.md ← review操作启动的简要模板
│ └── orchestrator.md ← orchestrate操作启动的简要模板
└── profiles/
├── _shared/
│ ├── profile.json ← 基础词汇 + 核心框架列表
│ ├── templates/ ← 带{{vocab.*}} + 标记块的核心框架文档
│ │ ├── 00-README.md
│ │ ├── 01-plan.md
│ │ ├── 02-research-external.md
│ │ ├── 03-research-internal.md
│ │ ├── 04-discussion.md
│ │ ├── 05-tracking.md
│ │ ├── subplans/ ← NN-*.md原型模板
│ │ │ ├── diff-plan.md
│ │ │ ├── decision-doc.md
│ │ │ └── bug-doc.md
│ │ └── artifact/ ← 搭建到<plan>/artifact/中
│ │ ├── manifest.json
│ │ └── data/ ← 可选外部数据源
│ └── board/index.html ← 独立的Mission Control + Wave-toggle模板
├── software/
│ ├── profile.json ← `extends: _shared`, produces_designs: true
│ └── templates/ ← 轻量化覆盖层(仅包含差异文档)
└── general/
├── profile.json ← `extends: _shared`, produces_designs: false
└── templates/参考实例——本核心框架中所有制品的标准示例——是本工作区中的。在核心框架版本重大更新时,可从中重新生成核心框架。
plans/studio/spine_version工作室参考注意事项:工作室版本早于两个后续锁定的功能——动态规范/跟踪看板拆分(提交:工作室的是单个标签页制品,而非本skill搭建的动态规范 + 跟踪看板组合)和状态锚点(工作室版本无此文件)。请参考工作室版本的核心框架结构和行文规范(轮次内容、WP简要说明、标题提取、分阶段设计原则)——而非作为当前结构的字面模板。中的自用示例是拆分后、带锚点布局的最新示例。
a6bc357artifact/index.htmlindex.htmlboard.html.groundwork.jsonplans/groundwork/What this skill does NOT do (in P1)
本skill在P1阶段不支持的功能
- No shell or contract changes. is Phase 2 — board actions are copy-prompt only.
host.startChatSession - No live tracking binding. The board reads markdown; harness-Tasks mirroring is Phase 2.
- No board "Start session" button beyond copy-prompt. Same reason.
- No automatic renumbering of IDs. Once allocated, an ID stays — retire instead of free.
- No action. The dogfood at
groundwork kickoffis a hand-authored cross-session resumption snapshot (phase scope, locked decisions, what's-next) — useful, but a dogfood-specific artifact, not part of the scaffolded spine. Aplans/groundwork/KICKOFF.mdaction that auto-snapshots the current phase boundary is a deferred stretch idea (Phase 2+, oncekickoffmakes a snapshot worth seeding a session from); it is not in P1 andhost.startChatSessiondoes not scaffold a KICKOFF.md.init
If the user asks for any of the above, say so explicitly and route them to the right phase.
- 不修改shell或契约。属于Phase 2——看板操作仅支持复制提示语。
host.startChatSession - 无实时跟踪绑定。看板读取Markdown;与harness-Tasks的镜像同步属于Phase 2。
- 看板“启动会话”按钮仅支持复制提示语。原因同上。
- 不自动重排ID。ID一旦分配即保留——需停用而非释放。
- 无操作。
groundwork kickoff中的自用示例是手写的跨会话恢复快照(阶段范围、已锁定决策、下一步计划)——有用,但属于自用特定制品,并非搭建的核心框架的一部分。自动快照当前阶段边界的plans/groundwork/KICKOFF.md操作是延期的扩展想法(Phase 2+,当kickoff使快照可用于启动会话时);不属于P1阶段,host.startChatSession不会搭建KICKOFF.md。init
若用户请求上述任一功能,请明确告知,并引导至对应阶段。