@c4a/context-cli 0.5.41-beta.7 → 0.6.0-alpha.6

package/plugins/README.md

@@ -0,0 +1,150 @@
+# Context Plugin
+
+> [中文版本](./README_CN.md)
+
+<p align="center"><img src="./assets/logo.svg" alt="C4A Context" width="180"/></p>
+
+Context provides agent commands for maintaining a project-local knowledge workspace. The plugin is installed globally for the agent, while each workspace keeps its own sources, pending review state, approved knowledge, and build output. Public agent entrypoints are intentionally small: initialize once, then use next-step guidance.
+
+Agent dialogue should follow the user's current conversation language. CLI
+commands, flags, ids, status values, JSONL keys, and `source_ref` tokens are
+protocol text and stay unchanged.
+
+## Install
+
+Install the CLI first:
+
+```bash
+npm i -g @c4a/context-cli
+# or
+bun add -g @c4a/context-cli
+```
+
+Then install the bundled plugin marketplace globally:
+
+```bash
+context plugin install
+```
+
+The installer resolves the plugin marketplace from the installed CLI package. Published packages use `dist/plugins`; source checkouts use the same generated tree after `bun run --filter @c4a/context-cli build`. For Codex, it materializes the bundled plugin into `~/.codex/plugins/cache/c4a/context/local/`, matching Codex's local-plugin cache convention.
+
+For a dry run:
+
+```bash
+context plugin install --dry-run
+context plugin path
+```
+
+## Workflow
+
+Run commands from the context project root.
+
+1. Initialize a workspace:
+
+   ```bash
+   context init context
+   cd context
+   bun install
+   ```
+
+2. Continue through the installed agent entry:
+
+   ```bash
+   <host-specific Context continuation command or skill>
+   ```
+
+The continuation entry first runs `context status`, then follows CLI diagnostics. It
+executes safe mechanical `next:` steps instead of only reporting them, and stops
+at `Human gate:` / placeholder next steps, source registration, source scope
+selection, review, package output choice, or source-repo operations that require
+user approval. It must not infer repo sources or extraction scope from the
+surrounding monorepo.
+It uses lower-level CLI primitives only when the workspace state requires them:
+
+- `context source ...`
+- `context run ...`
+- `context review ...`
+- `context close`
+- `context build`
+- `context verify`
+
+## SDK Manual For Agents
+
+After `bun install`, the project has a local SDK manual under:
+
+```text
+node_modules/@c4a/context/docs/
+```
+
+Recommended files:
+
+- `node_modules/@c4a/context/docs/guides/agent-dialogue.md`
+- `node_modules/@c4a/context/docs/guides/agent-guide.md`
+- `node_modules/@c4a/context/docs/reference/project-api.md`
+- `node_modules/@c4a/context/docs/reference/package-templates.md`
+
+Template examples are installed at:
+
+```text
+node_modules/@c4a/context/templates/package-templates/
+```
+
+Agents should read these files instead of probing `node_modules/@c4a/context/dist`
+with ad-hoc scripts.
+
+## Workspace Shape
+
+Committed project state lives in:
+
+- `src/` — project flow and custom code;
+- `sources/repo/index.yaml`, `sources/file/index.yaml`, and
+  `sources/lark/index.yaml` — source registries;
+- `unapproved/entities.jsonl` — draft/rejected/deprecated metadata;
+- `unapproved/structure.yaml` — unconfirmed or confirmed prose structure draft;
+- `knowledge/` — approved Markdown;
+- `knowledge/structure.yaml` — closed structure/edge projection derived from
+  approved knowledge;
+- `dist/` — built packages;
+- `README.md`, `AGENTS.md`, `package.json`.
+
+Runtime scratch lives in `.tmp/context-runtime/` and is ignored.
+
+## Agent Entry Points
+
+The global plugin exposes only the user-facing Context commands for the current workspace:
+
+- `init`
+- `continue`
+
+The CLI still provides lower-level primitives, but they are not public slash
+commands. The continuation entry chooses them based on CLI output and user intent.
+
+Current source registration, document capture discipline, structure planning,
+node classification, reading density, candidate resolution, edge gates,
+source-bound section drafting, refresh/update judgment, semantic conflict
+judgment, and close guidance live in internal procedures under
+`skill-source-scope`, `skill-prose-align`, and `skill-prose-compile`.
+
+Package-time querying is generated into each built package as the
+`knowledge-query` skill. Package output decisions live in `skill-package-output`.
+The current workflow does not expose source deletion, purge, or retraction
+commands. If a user asks for that kind of lifecycle change, stop and explain
+that the current plugin has no approved gate for it; do not recreate
+file-mutating operations outside the current workflow.
+
+Agents should follow the current status route and internal procedures. Do not
+call or reconstruct command shapes or payload protocols that are absent from the
+current CLI/schema views.
+
+The CLI performs mechanical work only. It does not clone, checkout, reset, fetch, or call an LLM silently. When source repos are missing or at the wrong commit, it reports diagnostics and expects the agent to ask the user before running external repo operations.
+
+## Current Workflow Surface
+
+This plugin exposes the current workflow through `init` and `continue`.
+`continue` starts from `context status`, follows the status route, and delegates
+to current source/capture phases, prose align evidence views, source-bound prose
+compile, review, close, verify/build/status guidance, OKF indexes, generated
+knowledge-query skills, and declared project phase previews.
+
+Agents must not simulate lifecycle or retraction work by deleting workspace
+files. Source deletion, purge, and retraction are not current plugin operations.

package/plugins/README_CN.md

@@ -0,0 +1,136 @@
+# Context Plugin
+
+> [English version](./README.md)
+
+<p align="center"><img src="./assets/logo.svg" alt="C4A Context" width="180"/></p>
+
+Context 提供面向 Agent 的知识工作区命令。Plugin 安装到全局 Agent 环境;每个知识工作区只保存自己的源声明、待审状态、已批准知识和构建产物。公开入口刻意收口:初始化一次,之后通过 next-step guidance 推进。
+
+Agent 与用户对话时应使用当前对话语言;CLI 命令、参数、id、状态枚举、JSONL key 和 `source_ref` 属于协议文本,保持英文或原样。
+
+## 安装
+
+先安装 CLI:
+
+```bash
+npm i -g @c4a/context-cli
+# 或
+bun add -g @c4a/context-cli
+```
+
+再把随 CLI 包发布的 plugin marketplace 安装到全局:
+
+```bash
+context plugin install
+```
+
+安装器会从当前 CLI 包动态解析 marketplace 目录。发布包使用 `dist/plugins`;源码 checkout 在执行 `bun run --filter @c4a/context-cli build` 后也使用同样的生成目录。对 Codex,安装器会把随包生成的插件复制到 `~/.codex/plugins/cache/c4a/context/local/`,符合 Codex 本地插件的 cache 约定。
+
+只查看将执行的操作:
+
+```bash
+context plugin install --dry-run
+context plugin path
+```
+
+## 工作流
+
+在 context 项目根目录执行命令。
+
+1. 初始化工作区:
+
+   ```bash
+   context init context
+   cd context
+   bun install
+   ```
+
+2. 通过已安装的 Agent 入口继续推进:
+
+   ```bash
+   <当前宿主暴露的 Context continuation command 或 skill>
+   ```
+
+Continuation 入口会先运行 `context status`,然后跟随 CLI 诊断。安全的机械 `next:` 步骤会直接执行,不会只把命令复述给用户;遇到 `Human gate:`、带占位符的 next、source 注册、source 范围选择、审阅、package 输出选择或需要用户授权的 source repo 操作才会停下来确认。它不能根据周边 monorepo 自行推断 repo source 或提取范围,只在工作区状态需要时调用底层 CLI 能力:
+
+- `context source ...`
+- `context run ...`
+- `context review ...`
+- `context close`
+- `context build`
+- `context verify`
+
+## Agent 可读的 SDK 手册
+
+执行 `bun install` 后,项目内会有 SDK 手册:
+
+```text
+node_modules/@c4a/context/docs/
+```
+
+推荐先读:
+
+- `node_modules/@c4a/context/docs/guides/agent-dialogue.md`
+- `node_modules/@c4a/context/docs/guides/agent-guide.md`
+- `node_modules/@c4a/context/docs/reference/project-api.md`
+- `node_modules/@c4a/context/docs/reference/package-templates.md`
+
+模板示例在:
+
+```text
+node_modules/@c4a/context/templates/package-templates/
+```
+
+Agent 应读取这些文件,不要通过临时脚本反查 `node_modules/@c4a/context/dist`
+来猜 SDK API。
+
+## 工作区形态
+
+需要提交的项目状态在:
+
+- `src/`:项目流程和定制代码;
+- `sources/repo/index.yaml`、`sources/file/index.yaml`、`sources/lark/index.yaml`:源 registry;
+- `unapproved/entities.jsonl`:draft/rejected/deprecated 元信息;
+- `unapproved/structure.yaml`:未确认或已确认的文档结构草稿;
+- `knowledge/`:approved Markdown;
+- `knowledge/structure.yaml`:由 approved knowledge 派生的结构与关系投影;
+- `dist/`:构建产物;
+- `README.md`、`AGENTS.md`、`package.json`。
+
+运行缓存放在 `.tmp/context-runtime/`,并被忽略。
+
+## Agent 入口
+
+全局 plugin 只暴露面向用户的 Context 命令:
+
+- `init`
+- `continue`
+
+CLI 仍保留底层能力,但它们不是公开 slash command。Continuation 入口根据 CLI 输出和用户意图选择要调用的底层命令。
+
+当前 source 注册、文档 capture 纪律、structure planning、Node 分类、阅读密度、
+候选处理、edge gates、source-bound section drafting、refresh/update 判断、
+语义冲突判断和 close 指引都在 `skill-source-scope`、`skill-prose-align`、
+`skill-prose-compile` 下面的内部 procedure。
+
+包内查询能力在构建包时生成到 `knowledge-query` skill。package 输出决策在
+`skill-package-output`。当前工作流不暴露 source 删除、purge 或撤回命令。
+如果用户要求这类生命周期变更,先停下来说明当前 plugin 没有已批准门禁;
+Agent 不得在当前工作流之外重建文件变更类操作。
+
+Agent 应按当前 status route 和内部 procedure 推进。不要调用或重建当前
+CLI/schema views 没有暴露的命令形态或 payload 协议。
+
+CLI 只做机械操作。它不会静默 clone、checkout、reset、fetch,也不会调用 LLM。源仓库缺失或 commit 不匹配时,CLI 只返回诊断;Agent 需要先征询用户,再决定是否执行外部 repo 操作。
+
+## 当前工作流入口
+
+本 plugin 只暴露当前工作流入口: `init` 和 `continue`。`continue` 从
+`context status` 开始,按 status route 分发到 source/capture phase、prose
+align evidence views、source-bound prose compile、review、close、
+verify/build/status guidance、OKF indexes、生成包里的 knowledge-query skill,
+以及已声明 project phase 的只读预览。
+
+Agent 不得通过直接删除 `sources/`、`knowledge/`、`unapproved/`、`dist/`
+或 `.tmp` 来模拟生命周期或撤回操作。source 删除、purge 和撤回不是当前
+plugin 操作。

package/plugins/VERSION

@@ -0,0 +1 @@
+0.6.0-alpha.6

package/plugins/assets/icon.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 758 296" fill="none">
+  <path fill-rule="evenodd" clip-rule="evenodd" d="M647.569 0.78043C613.4 3.48518 581.318 15.3269 533.021 43.0605C527.45 46.2597 498.781 61.8832 490.42 67.9156C464.4 83.1281 440.36 99.9754 407.462 125.999C399.965 131.93 392.626 137.658 391.153 138.729C389.68 139.8 382.798 145.128 375.858 150.569C368.919 156.01 358.504 163.98 352.714 168.281L343.516 175.006L348.516 179.006C351.553 181.229 358.164 187.09 362.516 190.006L370.516 196.006L379.016 190.006C384.498 185.597 392.279 178.726 395.782 175.811C399.285 172.896 411.776 162.857 414.201 160.847C416.626 158.838 420.318 155.949 427.144 150.29C445.631 134.963 481.502 112.007 494.26 102.533C581.313 47.1925 633.705 27.2029 682.312 46.6436C688.772 50.1275 692.158 52.8781 699.014 60.2106C706.594 68.3166 708.17 70.6632 712.305 79.9992C717.792 92.3865 720.263 102.609 721.288 117.182C723.104 142.96 716.794 171.243 703.236 198.108C693.06 218.269 684.3 229.708 671.088 242.211C628.153 272.315 597.665 274.481 543.801 261.017C510.873 246.43 487.481 230.006 448.016 193.506C444.204 190.241 440.144 186.014 439.516 186.006C438.281 185.991 399.991 214.634 399.516 216.006C399.235 216.815 404.057 219.412 409.016 222.506C410.702 223.559 412.975 225.335 416.516 227.006C433.391 238.059 468.991 255.632 482.516 262.006C485.929 263.614 490.402 264.707 492.545 265.749C509.884 274.195 533.276 282.099 555.644 287.07C564.55 289.049 601.674 289.814 609.103 288.171C612.031 287.523 616.387 286.554 618.782 286.017C633.747 282.66 656.745 272.897 670.289 264.153C708.746 239.325 740.493 194.104 753.016 146.317C764.533 102.359 755.681 60.2459 728.902 31.5909C712.119 13.6333 693.371 4.36271 667.389 1.17066C661.613 0.461953 656.637 -0.0628543 656.33 0.00607299C656.023 0.0750003 652.081 0.42386 647.569 0.78043ZM122.268 6.91848C100.692 8.62683 75.6783 17.7423 58.0176 30.3336C30.2119 50.158 12.2534 76.5887 3.92103 109.95C0.744084 122.668 -0.943192 149.281 0.550004 163.097C6.34545 216.709 38.9366 261.239 87.8925 282.436C108.528 291.37 128.098 295.45 152.658 295.937C173.489 296.35 191.779 294.037 213.531 288.238C254.082 277.427 282.658 266.098 328.68 231.976C341.818 222.235 344.259 221.314 342.05 219.506C337.696 215.941 316.951 199.525 316.016 199.506C315.451 199.495 312.641 202.192 307.128 205.872C245.084 247.275 198.239 258.453 151.476 252.979C138.261 251.432 123.184 247.836 114.645 244.194C82.5503 230.506 61.7452 207.016 52.8018 174.371C50.4952 165.952 50.3622 164.208 50.7059 146.886C51.0496 129.561 51.2517 127.827 53.8915 119.499C58.217 105.86 62.5516 96.3835 68.4271 87.7254C96.678 46.0924 144.857 34.898 199.322 57.3119C205.245 59.7489 221.144 67.3217 224.619 69.361C245.505 81.6138 248.559 83.5927 268.609 97.8683C286.178 110.375 299.632 125.4 316.016 139.031C330.379 150.982 332.229 144.373 335.6 144.44C337.306 142.561 337.353 141.225 335.571 139.031C334.554 137.779 334.892 138.21 331.041 133.458C307.893 104.899 285.92 82.0366 264.533 63.4627C232.185 35.3673 200.085 17.5822 168.343 10.1701C158.514 7.87465 132.964 6.07147 122.268 6.91848Z" fill="#ef6f2e"/>
+</svg>

package/plugins/assets/logo.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 758 296" fill="none">
+  <path fill-rule="evenodd" clip-rule="evenodd" d="M647.569 0.78043C613.4 3.48518 581.318 15.3269 533.021 43.0605C527.45 46.2597 498.781 61.8832 490.42 67.9156C464.4 83.1281 440.36 99.9754 407.462 125.999C399.965 131.93 392.626 137.658 391.153 138.729C389.68 139.8 382.798 145.128 375.858 150.569C368.919 156.01 358.504 163.98 352.714 168.281L343.516 175.006L348.516 179.006C351.553 181.229 358.164 187.09 362.516 190.006L370.516 196.006L379.016 190.006C384.498 185.597 392.279 178.726 395.782 175.811C399.285 172.896 411.776 162.857 414.201 160.847C416.626 158.838 420.318 155.949 427.144 150.29C445.631 134.963 481.502 112.007 494.26 102.533C581.313 47.1925 633.705 27.2029 682.312 46.6436C688.772 50.1275 692.158 52.8781 699.014 60.2106C706.594 68.3166 708.17 70.6632 712.305 79.9992C717.792 92.3865 720.263 102.609 721.288 117.182C723.104 142.96 716.794 171.243 703.236 198.108C693.06 218.269 684.3 229.708 671.088 242.211C628.153 272.315 597.665 274.481 543.801 261.017C510.873 246.43 487.481 230.006 448.016 193.506C444.204 190.241 440.144 186.014 439.516 186.006C438.281 185.991 399.991 214.634 399.516 216.006C399.235 216.815 404.057 219.412 409.016 222.506C410.702 223.559 412.975 225.335 416.516 227.006C433.391 238.059 468.991 255.632 482.516 262.006C485.929 263.614 490.402 264.707 492.545 265.749C509.884 274.195 533.276 282.099 555.644 287.07C564.55 289.049 601.674 289.814 609.103 288.171C612.031 287.523 616.387 286.554 618.782 286.017C633.747 282.66 656.745 272.897 670.289 264.153C708.746 239.325 740.493 194.104 753.016 146.317C764.533 102.359 755.681 60.2459 728.902 31.5909C712.119 13.6333 693.371 4.36271 667.389 1.17066C661.613 0.461953 656.637 -0.0628543 656.33 0.00607299C656.023 0.0750003 652.081 0.42386 647.569 0.78043ZM122.268 6.91848C100.692 8.62683 75.6783 17.7423 58.0176 30.3336C30.2119 50.158 12.2534 76.5887 3.92103 109.95C0.744084 122.668 -0.943192 149.281 0.550004 163.097C6.34545 216.709 38.9366 261.239 87.8925 282.436C108.528 291.37 128.098 295.45 152.658 295.937C173.489 296.35 191.779 294.037 213.531 288.238C254.082 277.427 282.658 266.098 328.68 231.976C341.818 222.235 344.259 221.314 342.05 219.506C337.696 215.941 316.951 199.525 316.016 199.506C315.451 199.495 312.641 202.192 307.128 205.872C245.084 247.275 198.239 258.453 151.476 252.979C138.261 251.432 123.184 247.836 114.645 244.194C82.5503 230.506 61.7452 207.016 52.8018 174.371C50.4952 165.952 50.3622 164.208 50.7059 146.886C51.0496 129.561 51.2517 127.827 53.8915 119.499C58.217 105.86 62.5516 96.3835 68.4271 87.7254C96.678 46.0924 144.857 34.898 199.322 57.3119C205.245 59.7489 221.144 67.3217 224.619 69.361C245.505 81.6138 248.559 83.5927 268.609 97.8683C286.178 110.375 299.632 125.4 316.016 139.031C330.379 150.982 332.229 144.373 335.6 144.44C337.306 142.561 337.353 141.225 335.571 139.031C334.554 137.779 334.892 138.21 331.041 133.458C307.893 104.899 285.92 82.0366 264.533 63.4627C232.185 35.3673 200.085 17.5822 168.343 10.1701C158.514 7.87465 132.964 6.07147 122.268 6.91848Z" fill="#ef6f2e"/>
+</svg>

package/plugins/claude/.claude-plugin/plugin.json

@@ -0,0 +1,16 @@
+{
+  "name": "context",
+  "description": "Maintain a project-local knowledge workspace through init and next-step agent guidance.",
+  "version": "0.6.0-alpha.6",
+  "author": {
+    "name": "c4a"
+  },
+  "license": "MIT",
+  "keywords": [
+    "context",
+    "knowledge-base",
+    "wiki",
+    "claude-plugin",
+    "c4a"
+  ]
+}

package/plugins/claude/.generated

@@ -0,0 +1 @@
+generated by packages/context-cli/scripts/build-plugin.ts

package/plugins/claude/CLAUDE.md

@@ -0,0 +1,5 @@
+# Generated Claude plugin build
+
+This directory is generated by `bun run build:plugin`.
+Do not edit files here directly.
+Edit `packages/context-cli/plugin/` and rerun the build instead.

package/plugins/claude/README.md

@@ -0,0 +1,5 @@
+# Generated Claude plugin build
+
+This directory is generated by `bun run build:plugin`.
+Do not edit files here directly.
+Edit `packages/context-cli/plugin/` and rerun the build instead.

package/plugins/claude/commands/continue.md

@@ -0,0 +1,34 @@
+---
+description: "Inspect the Context workspace, decide the next useful action, and proceed."
+argument-hint: "[user intent]"
+allowed-tools: Bash(context:*), Bash(bun:*), Bash(cd *)
+---
+
+## Your Task
+
+Use this as the conversational entry for an existing Context workspace. There is
+no `context continue` CLI primitive; the command runs lower-level `context ...`
+commands only when the workspace state requires them.
+
+If the user is starting a new workspace or a new batch from a raw repository
+root, do not run `context status` first. Use the public Context init entry or
+`context init` to create the workspace, complete the init setup command, then
+return here from the initialized workspace.
+
+If `context status` reports `workspace-not-found` and points at a configured
+`context.workspaceDir`, do not keep working from the host repository root. Enter
+that workspace when it exists, or initialize it through the init workflow after
+confirming with the user.
+
+Language policy: explain, ask, confirm, and summarize in the user's current
+conversation language. Keep CLI commands, flags, paths, ids, status enum values,
+JSONL payload keys, `source_ref` values, and copied CLI output tokens unchanged.
+
+Use the internal `context:skill-continue-workflow` procedure end to end. It owns the
+status loop, safe mechanical next steps, source/scope gate, review gate, package
+gate, and final report rules.
+
+Do not infer repo sources, extraction scope, review decisions, or package output
+choices from surrounding files. Do not call source-repo operations such as
+clone, checkout, reset, fetch, install, build, or test without explicit user
+approval.

package/plugins/claude/commands/init.md

@@ -0,0 +1,21 @@
+---
+description: "Initialize a Context knowledge workspace."
+argument-hint: "[project-dir] [--name <name>]"
+allowed-tools: Bash(context:*), Bash(bun:*), Bash(cd *)
+---
+
+## Your Task
+
+Initialize a Context workspace with the global CLI, then continue only through
+safe mechanical setup steps until the first human decision gate.
+
+Language policy: explain, ask, confirm, and summarize in the user's current
+conversation language. Keep CLI commands, flags, file paths, package names,
+enum values, payload keys, and copied CLI output tokens unchanged.
+
+Use the internal `context:skill-init-workspace` procedure end to end. It owns
+the `context init` invocation, dependency install follow-up, generated
+`AGENTS.md` handoff, status handoff, and stop conditions.
+
+Do not add extra project-local agent setup. Do not infer repo sources or
+extraction scope from the surrounding monorepo after setup.

package/plugins/claude/skills/skill-continue-workflow/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: skill-continue-workflow
+description: >
+  Internal procedure invoked by the public Context continuation entry; not a user slash command.
+  Runs the status-driven Context process, executes safe mechanical next steps,
+  and delegates human gates to source, review, and package procedures.
+tools:
+  - Bash
+---
+
+# skill-continue-workflow
+
+Continue an existing Context workspace from its current state.
+
+## TL;DR
+
+- Use this only inside an initialized Context workspace. If the user is starting
+  a new knowledge workspace or a new batch from a raw project/repo root, do not
+  run `context status` first; use the init workflow and complete setup before
+  returning here.
+- If `context status` reports `workspace-not-found` with a configured
+  `context.workspaceDir`, stop. If the directory exists, enter it and rerun
+  status. If it does not exist, ask whether to initialize it through the init
+  workflow; do not treat the host repository root as the workspace.
+- There is no `context continue` CLI command. Start with `context status`.
+- `context status` and CLI diagnostics are the source of truth.
+- Execute safe mechanical `next:` steps; stop at semantic choices and human
+  gates.
+- Delegate source/scope decisions to
+  `${CLAUDE_PLUGIN_ROOT}/skills/skill-source-scope/SKILL.md`.
+- Delegate review to `${CLAUDE_PLUGIN_ROOT}/skills/skill-review-gate/SKILL.md`.
+- Delegate package output choices to
+  `${CLAUDE_PLUGIN_ROOT}/skills/skill-package-output/SKILL.md`.
+- Delegate document investigation and structure confirmation to
+  `${CLAUDE_PLUGIN_ROOT}/skills/skill-prose-align/SKILL.md`.
+- Delegate source-bound prose compile requests to
+  `${CLAUDE_PLUGIN_ROOT}/skills/skill-prose-compile/SKILL.md`.
+- Do not inspect `.tmp`, `unapproved/`, `knowledge/`, `dist/`, or
+  `node_modules/@c4a/context/dist` with ad hoc scripts to decide project state.
+- Only run commands surfaced by the current status route, current phase view,
+  review gate, verify/build gate, or package guidance. Do not invent alternate
+  lifecycle commands from memory.
+
+<reference>
+
+## Safe Mechanical Commands
+
+These can run when already implied by current status and no placeholder/human
+choice remains:
+
+| State / hint | Allowed action |
+|---|---|
+| source already declared | `context source ensure`, `context source list`, `context source get` |
+| declared phase that does not read new source body or require a semantic choice | `context run <phase-id>` |
+| prose align evidence read | `context run align:<type>:<source>:<collection> --view <view>` |
+| prose structure validation | `context run align:<type>:<source>:<collection> --validate --input <structure.yaml>` |
+| prose compile evidence read | `context run compile:<type>:<source>:<collection> --view <view>` |
+| prose compile action validation | `context run compile:<type>:<source>:<collection> --validate --input <compile-actions.yaml>` |
+| copied review payload supplied by user | `context review apply <payload-file>` |
+| close required after review | `context close --format json` |
+| package already declared and close is clean | `context build` |
+| validation requested | `context verify` |
+
+Capture phases are not safe mechanical commands by default. `capture:file:*`
+and `capture:lark:*` read local or remote source bodies and update committed
+snapshots, so they require the source read-permission gate unless the current
+turn already contains explicit user confirmation for that exact source.
+
+## Human Gates
+
+Stop and ask, or wait for user input, for:
+
+- `Human gate:` in CLI output.
+- placeholders such as `<name>`, `<repo-or-subdir>`, `<phase-id>`, `<collection>`.
+- missing source selection.
+- source boundary/name decisions, because they affect `knowledge/` paths and
+  `source_ref` prefixes.
+- source repo operations: clone, checkout, reset, fetch, install, build, test.
+- source scope, package/subdirectory, symbol group, or glob choices.
+- file/Lark capture or refresh, including capture preview, until the user has
+  confirmed which local path or remote document may be read.
+- review approval/rejection decisions.
+- document structure confirmation, section ownership, edge confirmation,
+  rewrite intent, conflict, weak-evidence, or cross-document organization
+  choices unless they are being handled through prose align/compile evidence
+  views and validation.
+- package output type or template choices.
+
+When a human gate has a fixed small option set, use the host's native
+multi-choice tool when available (Claude Code `AskUserQuestion`, Codex's
+available native user-input tool such as `request_user_input` when exposed,
+Cursor Plan Mode `AskQuestion`). If unavailable, fall back to Markdown `A/B/C`
+choices. Each option must include the effect of choosing it.
+
+</reference>
+
+<procedures>
+
+### Step 0 — Confirm Workspace Exists
+
+If the current task is to create a new Context workspace, or the user has not
+identified an initialized Context workspace root for this turn, do not continue
+with this workflow. Initialize through the public Context init entry or
+`context init` first, run the setup command printed by init, then return to this workflow from the
+created workspace.
+
+### Step 1 — Read Status
+
+Run:
+
+```bash
+context status
+```
+
+Use the output as evidence. Explain status and next step in the user's language;
+do not forward a long raw transcript unless requested.
+
+### Step 2 — Route The State
+
+1. If status says `missing-source` or `needs-capture`,
+   source boundary/name is unclear, source scope is unclear, or an extract
+   phase needs first-run scope confirmation, follow
+   `${CLAUDE_PLUGIN_ROOT}/skills/skill-source-scope/SKILL.md`.
+2. If status says `captured-ready-to-investigate` or `needs-structure`, or the
+   user asks to split, merge, classify, relate, or semantically organize
+   document evidence before draft pages exist, follow
+   `${CLAUDE_PLUGIN_ROOT}/skills/skill-prose-align/SKILL.md`.
+3. If status says `needs-prose-compile` or `structure-ready`, or the user asks
+   to turn confirmed structure into source-bound draft pages, follow
+   `${CLAUDE_PLUGIN_ROOT}/skills/skill-prose-compile/SKILL.md`.
+4. If status says `compile-ready-for-review` or review is needed, follow
+   `${CLAUDE_PLUGIN_ROOT}/skills/skill-review-gate/SKILL.md`.
+5. If status says `compile-close-needed`, run `context close --format json`
+   unless CLI diagnostics require human repair, then return to **Step 1**.
+6. If status says `ready-to-build`, `built`, `needs-package-output`, or approved knowledge exists but
+   package output is not chosen or declared,
+   follow `${CLAUDE_PLUGIN_ROOT}/skills/skill-package-output/SKILL.md`.
+7. If the next command is safe per [Safe Mechanical Commands](#safe-mechanical-commands),
+   run it and return to **Step 1**.
+8. If the next command crosses a [Human Gate](#human-gates), ask or wait; do not
+   guess.
+
+### Step 3 — Execute Safely
+
+Before editing `src/index.ts` or package templates, read:
+
+```text
+node_modules/@c4a/context/docs/guides/agent-guide.md
+node_modules/@c4a/context/docs/guides/package-outputs.md
+node_modules/@c4a/context/docs/reference/project-api.md
+node_modules/@c4a/context/docs/reference/package-templates.md
+```
+
+Do not write one-off scripts to parse source packages, count extracted symbols,
+or sample candidates. Use `context source inspect` and the extract no-write
+preview command.
+
+### Step 4 — Report
+
+Report only the meaningful state transition: commands run, current status,
+human gate reached, and the precise user decision needed next. Never present
+`context build`, `context verify`, or file counts as proof that a deliverable is
+usable; inspect generated package structure when package output is involved.
+
+### Step 5 — Self-verify Checklist
+
+- [ ] `context status` was run first. If not, return to **Step 1**.
+- [ ] No human gate was crossed. If not, stop and report the protocol error.
+- [ ] No ad hoc file/script probing replaced CLI views. If not, discard that
+  conclusion and use the CLI view.
+
+</procedures>

package/plugins/claude/skills/skill-init-workspace/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: skill-init-workspace
+description: >
+  Internal procedure invoked by the public Context init entry; not a user slash command.
+  Initializes a Context knowledge workspace, executes only safe setup follow-up,
+  then hands off to the next-step workflow until the first human gate.
+tools:
+  - Bash
+---
+
+# skill-init-workspace
+
+Initialize a Context workspace. The CLI creates files; the agent follows safe
+setup hints and stops before source/scope choices.
+
+## TL;DR
+
+- Use `context init`; do not add any extra project-local agent setup.
+- If init prints the standard setup `next:` command, run it instead of only
+  repeating it.
+- After the setup command succeeds, enter the workspace and read `AGENTS.md`
+  before running `context status`.
+- After setup, use `${CLAUDE_PLUGIN_ROOT}/skills/skill-continue-workflow/SKILL.md`
+  for status-driven continuation.
+- Stop at source registration, extraction scope, review, package output, or any
+  external repo operation that needs user choice.
+- Explain in the user's conversation language. Keep CLI commands, flags, paths,
+  status values, JSONL keys, and copied CLI tokens unchanged.
+
+<procedures>
+
+### Step 1 — Run Init
+
+1. If the user gave no directory, run `context init`.
+2. If the user gave a directory, run `context init <project-dir>`.
+3. If the user supplied a project name option, pass it as `--name <name>`.
+4. Read the CLI feedback block and preserve the project root path.
+
+### Step 2 — Execute Safe Setup
+
+1. If CLI prints `next: cd "<project-root>" && bun install`,
+   execute that command.
+2. If install fails, report the failure and stop.
+3. If setup succeeds, read `<project-root>/AGENTS.md`.
+4. After reading `AGENTS.md`, run `context status` from `<project-root>` and
+   treat that output as the current workspace state.
+
+### Step 3 — Handoff Or Stop
+
+1. If status is ready for a safe mechanical step, continue with
+   `${CLAUDE_PLUGIN_ROOT}/skills/skill-continue-workflow/SKILL.md`.
+2. If status is `missing-source`, `Human gate:`, or contains placeholders such as
+   `<name>`, `<repo-or-subdir>`, `<phase-id>`, or `<collection>`, ask for the
+   missing human choice and stop. For missing sources, ask for the knowledge
+   source boundary first; do not ask for a raw source name as an isolated
+   parameter.
+3. Do not infer repo source, source boundary, source name, package, or
+   extraction scope from cwd, parent directories, package names, monorepo
+   layout, or git remote.
+
+### Step 4 — Report
+
+Summarize what was initialized, what setup command ran, current status, and the
+human choice needed next. Do not paste a long raw CLI transcript unless the user
+asks for exact output.
+
+### Step 5 — Self-verify Checklist
+
+- [ ] Safe setup was executed when CLI provided the standard setup `next:`. If
+  not, return to **Step 2**.
+- [ ] No repo source or extraction scope was inferred. If not, stop and ask the
+  user to confirm the source boundary and scope.
+
+</procedures>