conport

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ConPort — Project Management System

ConPort — 项目管理系统

ConPort stores everything about the project: tasks, documents, decisions, infrastructure. Without init, context is unavailable. Without search, you are answering blindly.

This skill carries the always-on discipline — what you must do every session regardless of topic. Deep, situational reference (recipe semantics, the gap system, the semantic pass, the full per-tool parameter tables, the block model, the documentation-graph callout reference, the spec append-only rationale) lives in the live docs — see the Live docs section below. Fetch the relevant page before acting on one of those topics; don't act from memory.

**ConPort 存储项目的所有信息：**任务、文档、决策、基础设施。 **未执行init则无法获取上下文。**未进行搜索就盲目作答是不可取的。

本技能遵循全程执行规范——无论会话主题是什么，你在每次会话中都必须执行这些操作。深度场景参考（配方语义、缺口系统、语义扫描、完整工具参数表、块模型、文档图谱标注参考、规范追加-only理由）都存放在实时文档中——请参阅下方的「实时文档」部分。在处理这些主题之前，请先获取相关页面内容；不要凭记忆操作。

MCP Prefix

MCP 前缀

Environment	Prefix
Claude Code CLI	`mcp__conport__`
Claude.ai Chat	`mcp__claude_ai_conport__`

环境	前缀
Claude Code CLI	`mcp__conport__`
Claude.ai Chat	`mcp__claude_ai_conport__`

FIRST ACTION OF THE SESSION

会话的第一个操作

Step 1: Determine the project name

步骤1：确定项目名称

Claude Code CLI — the env var

CONPORT_PROJECT_NAME

is already available (from

.claude/settings.local.json

). If it's not set, fall back in this priority order:

Git remote — extract the repo name (last segment of the URL without
```
.git
```
)
Directory name — basename of the current working directory

Claude.ai Chat — ask the user (the file system is not available).

Claude Code CLI — 环境变量

CONPORT_PROJECT_NAME

已可用（来自

.claude/settings.local.json

）。如果未设置，则按以下优先级顺序获取：

Git远程仓库 — 提取仓库名称（URL的最后一段，不含
```
.git
```
）
目录名称 — 当前工作目录的基名

Claude.ai Chat — 询问用户（无法访问文件系统）。

Step 2: Call init

步骤2：调用init

mcp__conport__init({
  name: "<detected_name>",
  skill_id: "conport",
  skill_version: "<metadata.version from this SKILL.md frontmatter>",  // substitute the real value; never send this placeholder
  client_type: "claude-code"  // or claude-ai / cursor / codex
})

skill_id

skill_version

client_type

are optional but strongly recommended — they let the server tell you when SKILL.md has been updated upstream so manual installs (Claude.ai project files, hand-copied skills) don't silently drift. Pick

client_type

from the list above; fall back to omitting it if running somewhere else.

If auto-detection of the project name did not work, ask the user.

mcp__conport__init({
  name: "<detected_name>",
  skill_id: "conport",
  skill_version: "<metadata.version from this SKILL.md frontmatter>",  // 替换为实际值；请勿发送此占位符
  client_type: "claude-code"  // 或 claude-ai / cursor / codex
})

skill_id

skill_version

client_type

为可选参数，但强烈建议提供——它们能让服务器告知你SKILL.md是否已在 upstream 更新，避免手动安装（Claude.ai项目文件、手动复制的技能）出现静默版本漂移。从上述列表中选择

client_type

；如果在其他环境运行，可以省略该参数。

如果自动检测项目名称失败，请询问用户。

After init — MANDATORY:

执行init后——必须完成：

Print summary:
```
[CONPORT] {summary from response}
```
Execute instructions from the response (read files, apply rules)

Report backlog:

N tasks in TODO, M in progress. Top 5:

— use

backlog.top

from the response. Line format:

Pk · #id title (n subtasks)

, skipping

(n subtasks)

when zero.

Pk

effective_priority

. Skip the whole block if

backlog.total_todo == 0

and

backlog.total_in_progress == 0

Report the roadmap: when the response carries
```
roadmap
```
and/or
```
epic_tails
```
, print them in the format given under OUTPUT FORMAT → Roadmap sections. Both sections are omitted when the project has nothing to show — then print nothing.
If the project is empty (no decisions, no patterns, empty
```
product_context
```
) — offer the bootstrap flow from
```
references/bootstrap.md
```
.
If
routine_suggestion
is present in the response — surface it to the user and offer to accept (
```
set_routine_config(...)
```
, e.g. with the
```
suggested_config
```
) or dismiss permanently (
```
set_routine_config(enabled=false)
```
).
If
skill_update_available
is present in the response — emit ONE short notice at the very start of your first reply (after the
```
[CONPORT]
```
line). Format:
```
[SKILL UPDATE] {skill_id} {current} → {latest} ({severity}). Changelog: {changelog_url} · Install: {install_guide}
```
- When
```
current == "unknown"
```
  — phrase as
```
cannot determine version, see {install_guide}
```
  .
- When
```
severity == "security"
```
  — emit a stronger line (
```
[SECURITY UPDATE]
```
  ) and recommend updating before proceeding.
- Do NOT re-emit the notice in subsequent turns — once per session.
Never decide "is there an update" by hand-comparing version numbers. The conport plugin (this skill + superpowers-conport + plugin.json + marketplace) versions independently from
```
conport-agent
```
, which is a separate privately-distributed unit with its own version line. Numbers from different units are NOT comparable. The ONLY correct signal is
```
skill_update_available
```
above: present → update; absent → you're current. If you catch yourself reasoning "my number looks higher than that other unit's, so I'm ahead" — stop, that's the exact mistake this signal prevents.

Save-first. Save decisions (

sync_decision

) and progress (

log_progress

) as they happen, not in a batch at the end of the session. The moment a choice is made or a step is finished, persist it — saving at the end loses rationale and an interrupted session leaves nothing behind. (Live docs →

core/save-first

Without init you cannot: answer questions about the project or work with tasks. Ignoring instructions is FORBIDDEN.

打印摘要：
```
[CONPORT] {summary from response}
```
执行响应中的指令（读取文件、应用规则）

报告待办事项：

N tasks in TODO, M in progress. Top 5:

— 使用响应中的

backlog.top

。格式：

Pk · #id title (n subtasks)

，当子任务数为0时省略

(n subtasks)

。

Pk

为

effective_priority

。如果

backlog.total_todo == 0

且

backlog.total_in_progress == 0

，则跳过整个块。

报告路线图： 当响应包含
```
roadmap
```
和/或
```
epic_tails
```
时，按照「输出格式 → 路线图部分」给定的格式打印。如果项目没有相关内容，则省略这两个部分——此时无需打印任何内容。
如果项目为空（无决策、无模式、
```
product_context
```
为空）——提供
```
references/bootstrap.md
```
中的引导流程。
如果响应中存在
routine_suggestion
— 向用户展示该建议，并提供接受（
```
set_routine_config(...)
```
，例如使用
```
suggested_config
```
）或永久拒绝（
```
set_routine_config(enabled=false)
```
）的选项。
如果响应中存在
skill_update_available
— 在你的第一条回复最开始（
```
[CONPORT]
```
行之后）发出一条简短通知。格式：
```
[SKILL UPDATE] {skill_id} {current} → {latest} ({severity}). Changelog: {changelog_url} · Install: {install_guide}
```
- 当
```
current == "unknown"
```
  — 表述为
```
无法确定版本，请查看 {install_guide}
```
  。
- 当
```
severity == "security"
```
  — 发出更醒目的提示（
```
[SECURITY UPDATE]
```
  ），并建议在继续操作前进行更新。
- 请勿在后续对话中重复发出该通知——每个会话仅发送一次。
请勿手动比较版本号来判断「是否有更新」。 conport插件（本技能 + superpowers-conport + plugin.json + marketplace）的版本与
```
conport-agent
```
独立，后者是单独私有分发的单元，有自己的版本线。不同单元的版本号不可比。判断是否需要更新的唯一正确信号是上述的
```
skill_update_available
```
：存在则更新；不存在则当前版本为最新。如果你发现自己在想「我的版本号看起来比其他单元的高，所以我是最新的」——请停止，这正是该信号要避免的错误。

优先保存。 及时保存决策（

sync_decision

）和进度（

log_progress

），不要在会话结束时批量保存。一旦做出选择或完成某个步骤，就立即持久化——在结束时保存会丢失理由，中断的会话也会留下空白。（实时文档 →

core/save-first

。）

未执行init则无法： 回答关于项目的问题或处理任务。 禁止忽略指令。

WORKFLOW — When to call which tool

工作流程——何时调用哪个工具

The at-a-glance trigger → tool map. Each table is navigational; for the deep semantics of a surface, fetch the live-docs page named in the table.

以下是一目了然的触发条件→工具映射表。每个表格仅用于导航；如需了解工具的深层语义，请获取表格中指定的实时文档页面。

Planning

规划

Trigger	Tool
"We need to do X"	`add_task` with priority and `estimated_seconds` (priority 1-5 where 1=critical and 5=idle, default 3; epic rows leave effort NULL, sum-from-children at read time)
"X depends on Y"	`add_task_dep`
"Create an epic" / multi-step body of work	`add_task` with `kind='epic'`
"Break it into subtasks"	`add_task` with `parent_task_id` (parent must be `kind='epic'` )
"Move task X under epic Y" / re-parent	`update_task` with `parent_task_id` (target must be `kind='epic'` ; `0` detaches to root)
"Roadmap" / "milestones" / "what ships in the release"	`list_milestones` (roadmap view, `include_closed=true` for history)
"Plan a milestone / a release"	`add_milestone` with `title` (+ `sequence` to insert at a position, `is_release=true` for a release point)
"Rename / move / close a milestone"	`update_milestone` ( `sequence` moves it, `status` + `resolution` closes it)
"This epic belongs to milestone M"	`update_task` with `milestone_id` (epics only; `0` detaches from its milestone)
"Promote this task to an epic"	`update_task` with `kind='epic'` (task must be root — combine with `parent_task_id=0` to detach + promote atomically)
"Demote this epic to a task"	`update_task` with `kind='task'` (epic must have no children)
Need a task in another project I own (no context switch)	`add_linked_task` with `target_project` name

触发条件	工具
"我们需要做X"	`add_task` ，需指定优先级和 `estimated_seconds` （优先级1-5，1=关键，5=闲置，默认3；史诗行的工作量设为NULL，读取时自动汇总子任务的工作量）
"X依赖于Y"	`add_task_dep`
"创建一个史诗" / 多步骤工作体	`add_task` ，设置 `kind='epic'`
"将其拆分为子任务"	`add_task` ，设置 `parent_task_id` （父任务必须为 `kind='epic'` ）
"将任务X移至史诗Y下" / 重新指定父任务	`update_task` ，设置 `parent_task_id` （目标必须为 `kind='epic'` ； `0` 表示移至根目录）
"路线图" / "里程碑" / "版本发布内容"	`list_milestones` （路线图视图， `include_closed=true` 可查看历史）
"规划里程碑/版本发布"	`add_milestone` ，设置 `title` （+ `sequence` 指定插入位置， `is_release=true` 表示发布节点）
"重命名/移动/关闭里程碑"	`update_milestone` （ `sequence` 用于移动， `status` + `resolution` 用于关闭）
"此史诗属于里程碑M"	`update_task` ，设置 `milestone_id` （仅适用于史诗； `0` 表示脱离里程碑）
"将此任务升级为史诗"	`update_task` ，设置 `kind='epic'` （任务必须为根任务——可结合 `parent_task_id=0` 实现原子化脱离+升级）
"将此史诗降级为任务"	`update_task` ，设置 `kind='task'` （史诗必须无子任务）
需要在我拥有的另一个项目中创建任务（无需切换上下文）	`add_linked_task` ，设置 `target_project` 名称

Execution

执行

Trigger	Tool
Starting work	`update_task` → IN_PROGRESS (before the first write on a task)
Done / Finished	`update_task` → DONE with `resolution=...` (see below)
Cancelled	`update_task` → CANCELLED with `resolution=...` (why dropped)
Blocked	`update_task` → BLOCKED
Milestone finished	`update_milestone` → DONE with `resolution=...` (all its epics must be closed first)
Milestone dropped	`update_milestone` → CANCELLED with `resolution=...` (why it left the roadmap)

IN_PROGRESS gate. Before your first ConPort write against a task, move it to IN_PROGRESS. This keeps

current_focus

accurate and the backlog honest.

An epic closes only with its children closed — the server refuses

update_task(status='DONE')

on an epic that still has open children with

epic_not_ready

, listing them. A snoozed child counts as open.

Epic progress is counted ONLY from
epic_progress
/
list_tasks(parent_task_id=…)
— never from a plan file's task list. A plan document is a snapshot of the intent; the epic's children are the state. Every write that touches a child (

add_task

under an epic,

update_task

status or re-parent,

delete_task

) echoes

epic_progress

— read that rollup, print it per OUTPUT FORMAT, and when it says

closable

, close the epic with a

resolution

right then instead of leaving the tail to rot.

Closing tasks — always pass
resolution
: On

status=DONE

CANCELLED

, pass a

resolution

argument with the verdict (what was done / why cancelled). The server:

Appends a
```
## Resolution
```
section to the task's description (preserves the original spec verbatim).
Auto-creates a linked
```
progress_entry
```
so the close shows up in
```
recent_activity
```
,
```
list_progress
```
, and search.

Do NOT call
log_progress
separately for task closes — that would duplicate the entry.

log_progress

is for progress events that don't belong to a single closing task (e.g. mid-implementation notes, infra changes).

Roadmap discipline. A milestone is an ordered group of epics; the current milestone is the open one with the smallest

sequence

, and

init

get_agenda

return it in the

roadmap

section.

Work the current milestone. In an interactive session, picking up work that belongs to a later milestone needs an explicit decision by the owner — say which milestone the work sits in and ask before starting; never silently pull work forward because it looked convenient. Work attached to no milestone (
```
milestone_id: null
```
) is not off-limits, but say so when you take it, so the owner can attach its epic to the roadmap or leave it aside deliberately. (An autonomous routine run has no owner to ask: the conport-routine skill overrides this rule with its own — unattached rows are fair game, later-milestone rows are not.)
Closing a milestone always carries
resolution
— what was delivered (DONE) or why it was dropped (CANCELLED). The server logs a progress entry from it.
A release milestone (
is_release=true
) closes only after the release actually happened. "Every epic is DONE" is not a release; the resolution names the shipped version/artifact. If the release hasn't shipped, leave the milestone open and say so.
milestone_not_ready
is a prescription, not an error to route around.
```
update_milestone(status='DONE')
```
is refused while any epic of the milestone is open;
```
context.open_epics
```
lists exactly what to close first (an empty milestone is refused too — attach the epic that carries the work). Do the prescribed closes, then retry. Never CANCEL a milestone just to get past the refusal.

→ Deep detail: live docs

projects/roadmap

触发条件	工具
开始工作	`update_task` → IN_PROGRESS（在任务的第一次写入前执行）
完成/结束	`update_task` → DONE 并指定 `resolution=...` （见下文）
取消	`update_task` → CANCELLED 并指定 `resolution=...` （说明取消原因）
阻塞	`update_task` → BLOCKED
里程碑完成	`update_milestone` → DONE 并指定 `resolution=...` （其下所有史诗必须先关闭）
里程碑取消	`update_milestone` → CANCELLED 并指定 `resolution=...` （说明从路线图中移除的原因）

IN_PROGRESS 门限。 在针对任务进行第一次ConPort写入之前，需将其状态改为IN_PROGRESS。这能保证

current_focus

的准确性和待办事项的真实性。

仅当所有子任务关闭后，史诗才能关闭——如果史诗仍有未关闭的子任务，服务器会拒绝执行

update_task(status='DONE')

，并返回

epic_not_ready

，列出未关闭的子任务。已暂停的子任务视为未关闭。

史诗进度仅通过
epic_progress
/
list_tasks(parent_task_id=…)
统计——绝不能从计划文件的任务列表中统计。计划文档是意图的快照；史诗的子任务才是实际状态。每次修改子任务（在史诗下

add_task

、

update_task

状态或重新指定父任务、

delete_task

）都会同步

epic_progress

——读取该汇总信息，按照「输出格式」打印，当显示

closable

为true时，立即使用

resolution

关闭史诗，不要拖延。

关闭任务——必须传入
resolution
：当设置

status=DONE

或

CANCELLED

时，需传入

resolution

参数说明结果（完成了什么/为何取消）。服务器会：

在任务描述中追加
```
## Resolution
```
部分（保留原始规范内容）。
自动创建关联的
```
progress_entry
```
，以便关闭操作显示在
```
recent_activity
```
、
```
list_progress
```
和搜索结果中。

关闭任务时请勿单独调用
log_progress
——这会导致条目重复。

log_progress

用于不属于单个关闭任务的进度事件（例如，实施过程中的笔记、基础设施变更）。

路线图规范。 里程碑是一组有序的史诗；当前里程碑是

sequence

值最小的未关闭里程碑，

init

get_agenda

会在

roadmap

部分返回该里程碑。

优先处理当前里程碑的工作。 在交互式会话中，若要处理后续里程碑的工作，需要所有者明确同意——说明工作所属的里程碑，并在开始前询问；绝不能因为看起来方便就擅自提前处理工作。未关联到任何里程碑的工作（
```
milestone_id: null
```
）并非不可处理，但在处理时需告知所有者，以便所有者将其史诗关联到路线图或故意留待以后处理。（自动例行运行时无所有者可询问：conport-routine 技能会用自己的规则覆盖此规则——未关联的任务可处理，后续里程碑的任务不可处理。）
关闭里程碑时必须传入
resolution
——说明交付内容（DONE）或取消原因（CANCELLED）。服务器会据此记录进度条目。
发布里程碑（
is_release=true
）仅在实际发布后才能关闭。「所有史诗已完成」并不等同于发布；
```
resolution
```
需指定发布的版本/制品。如果尚未发布，请保持里程碑为打开状态并告知用户。
milestone_not_ready
是要求，而非需要绕过的错误。如果里程碑下仍有未关闭的史诗，
```
update_milestone(status='DONE')
```
会被拒绝；
```
context.open_epics
```
会列出需要先关闭的史诗（空里程碑也会被拒绝——需关联承载工作的史诗）。先完成要求的关闭操作，然后重试。绝不能为了绕过拒绝而取消里程碑。

→ 详细内容：实时文档

projects/roadmap

。

Patterns

模式

Trigger	Tool
"Show me the patterns"	`list_patterns`
"Record a pattern"	`log_pattern` with name, description, tags
"Update / rename / re-tag a pattern"	`update_pattern`
"What approaches do we use?"	`list_patterns` or `search` by topic

触发条件	工具
"展示模式"	`list_patterns`
"记录模式"	`log_pattern` ，需指定name、description、tags
"更新/重命名/重新标记模式"	`update_pattern`
"我们使用哪些方法？"	`list_patterns` 或按主题 `search`

Search

搜索

Trigger	Tool
Question about the project	`search` BEFORE answering
"What was decided about Y?"	`search` by topic
"Which projects do I own?" / bootstrapping without a known project_id	`list_projects`

触发条件	工具
关于项目的问题	先执行 `search` 再作答
"关于Y的决策是什么？"	按主题 `search`
"我拥有哪些项目？" / 未指定project_id时引导初始化	`list_projects`

Sync

同步

Trigger	Tool
Technology choice	`sync_decision`
Trade-off with rationale	`sync_decision`
Read one decision's full body (id → tags + currency) before amending	`get_decision`
Amend / re-tag an existing decision	`update_decision`
Decision no longer holds, NO replacement	`deprecate_decision` (reason required)
Un-retire a decision	`reactivate_decision`
Decision candidates auto-extracted from `log_progress`	never committed directly — they wait in the proposals queue: `semantic_proposals_list` → approve/reject/defer; `list_decisions` filters provenance via `source` ( `manual` \| `progress_extraction` )

触发条件	工具
技术选择	`sync_decision`
带有理由的权衡	`sync_decision`
修改决策前读取完整内容（id → tags + 有效性）	`get_decision`
修改/重新标记现有决策	`update_decision`
决策不再适用，且无替代方案	`deprecate_decision` （需提供理由）
恢复已弃用的决策	`reactivate_decision`
从 `log_progress` 自动提取的候选决策	请勿直接提交——它们会在提案队列中等待： `semantic_proposals_list` → 批准/拒绝/推迟； `list_decisions` 可通过 `source` 筛选来源（ `manual` \| `progress_extraction` ）

Progress

进度

Trigger	Tool
Standalone progress note (not a task close)	`log_progress`
Closing a task	`update_task` with `resolution=...` (auto-creates progress; do not also call `log_progress` )
Context has changed	`update_active_context`

触发条件	工具
独立进度记录（非任务关闭）	`log_progress`
关闭任务	`update_task` ，指定 `resolution=...` （自动创建进度记录；请勿同时调用 `log_progress` ）
上下文已变更	`update_active_context`

Documentation

文档

Trigger	Tool
Spec / API docs	`add_document`
Wholesale body / metadata update	`update_document(content=<full markdown>, ...)`
List a doc's blocks (pick ulids before a surgical edit)	`list_blocks(document_id)`
Read / edit / insert / delete one block	`get_block` / `update_block` / `insert_block` / `delete_block`
Read a doc (with rendered Wave 5 stubs)	`get_document` ( `raw=true` for unmodified markdown)
"Who references this doc/block?"	`get_block_backlinks` (omit `block_ulid` for whole doc)
"What's similar to this block but not yet linked?"	`get_semantically_related_blocks`
Overlapping content / linking two docs	author one callout — `[!supersedes]` / `[!resolves]` / `[!extends]` / `[!relates-to]`

Block-level editing is the default for any narrow change — including specs. Use

update_block

insert_block

delete_block

for surgical edits; only one block re-embeds and the spec append-only invariant doesn't engage.

update_document(content=...)

is the wholesale-rewrite channel.

Spec append-only invariant.

update_document

on a

doc_type='spec'

body requires

change_kind

amend

(clarification/typo — allowed, logged with a mandatory

reason

) or

substantive

(a meaningful claim change — rejected; author a new spec and link the old one with

link_items(relationship='supersedes')

). Don't chain block edits to rewrite a spec's claims either.

Don't create a doc when an edit will do. Never

add_document

whose purpose is to describe / amend / react to an existing doc — that accumulates synthesis drift. Edit the original, or author an addendum with an explicit callout (

> [!extends] [[doc-N]]

> [!supersedes] [[doc-N]]

); default to

> [!relates-to]

when unsure.

→ Deep detail: live docs

projects/block-model

projects/spec-append-only

core/documentation-callouts

; full agent reference in

references/documentation_graph.md

触发条件	工具
规范/API文档	`add_document`
批量更新内容/元数据	`update_document(content=<full markdown>, ...)`
列出文档的块（在精准编辑前获取ulids）	`list_blocks(document_id)`
读取/编辑/插入/删除单个块	`get_block` / `update_block` / `insert_block` / `delete_block`
读取文档（包含渲染后的Wave 5占位符）	`get_document` （ `raw=true` 获取未修改的markdown）
"哪些内容引用了此文档/块？"	`get_block_backlinks` （省略 `block_ulid` 可查看整个文档的引用）
"哪些块与此块相似但尚未关联？"	`get_semantically_related_blocks`
内容重叠/关联两个文档	添加标注—— `[!supersedes]` / `[!resolves]` / `[!extends]` / `[!relates-to]`

块级编辑是窄范围修改的默认方式——包括规范修改。使用

update_block

insert_block

delete_block

进行精准编辑；仅修改一个块时不会触发规范追加-only规则。

update_document(content=...)

是批量重写渠道。

规范追加-only规则。 对

doc_type='spec'

的内容执行

update_document

时，需指定

change_kind

：

amend

（澄清/拼写错误——允许，需提供必填的

reason

）或

substantive

（有意义的声明变更——拒绝；需创建新规范并使用

link_items(relationship='supersedes')

关联旧规范）。也请勿通过多次块编辑来重写规范的声明。

无需创建新文档时请勿创建。 若目的是描述/修改/回应现有文档，请勿使用

add_document

——这会导致内容偏差。请编辑原始文档，或创建带有明确标注的补充内容（

> [!extends] [[doc-N]]

> [!supersedes] [[doc-N]]

）；不确定时默认使用

> [!relates-to]

。

→ 详细内容：实时文档

projects/block-model

projects/spec-append-only

core/documentation-callouts

；完整代理参考见

references/documentation_graph.md

。

Routines (periodic backlog cycles)

例行程序（定期待办事项周期）

Trigger	Tool
Starting a periodic cycle run	`get_agenda` (single-call briefing), `routine_run_start`
"Set up / tune the cycle policy"	`get_routine_config` / `set_routine_config` (cadence, run limits, autonomy 0-2, selection `threshold` \| `tagged` )
Mark a task as agent-executable	`update_task` with `routine_eligible=true` (opt-in pool for `selection='tagged'` cycles)
Finishing a run	`routine_run_finish` with `outcome` (auto-logs progress — no separate `log_progress` )
"Show recent runs"	`list_routine_runs`
Calibrating before estimating tasks	`get_estimation_stats` (median ratio, p50/p90 actuals)
Picking unblocked work deep in the backlog	`list_tasks` with `ready=true` , `order="priority"` , `offset`
Deferring a task to a date	`update_task` with `snooze_until` (empty string clears)

→ Full runbook: the conport-routine skill; live docs

projects/routines

触发条件	工具
开始定期周期运行	`get_agenda` （单次调用简报）、 `routine_run_start`
"设置/调整周期策略"	`get_routine_config` / `set_routine_config` （周期、运行限制、自主性0-2、选择方式 `threshold` \| `tagged` ）
标记任务为可代理执行	`update_task` ，设置 `routine_eligible=true` （加入 `selection='tagged'` 周期的可选池）
完成运行	`routine_run_finish` ，指定 `outcome` （自动记录进度——无需单独调用 `log_progress` ）
"展示最近的运行记录"	`list_routine_runs`
估算任务前校准	`get_estimation_stats` （中位数比率、p50/p90实际值）
从待办事项深处选择未阻塞的工作	`list_tasks` ，设置 `ready=true` , `order="priority"` , `offset`
将任务推迟到指定日期	`update_task` ，设置 `snooze_until` （空字符串清除设置）

→ 完整运行手册：conport-routine 技能；实时文档

projects/routines

。

Context assembly, gaps, semantic pass

上下文组装、缺口、语义扫描

Trigger	Tool
"Open task #N and brief me"	`assemble_context` with `recipe='task_briefing'` , `start_id='task-N'`
"Implementation status of spec doc-N?"	`assemble_context` with `recipe='spec_implementation_status'` , `start_id='doc-N'`
"What recipes are available?"	`list_context_recipes`
"Current architecture of subsystem X?"	`render_current_architecture` with `scope=[...]`
"Is this architecture doc safe to archive?"	`audit_doc_l1_coverage(doc_id)`
Init response shows gaps / "show all gaps"	review `gaps.fresh` ; `gap_list` , `gap_ack` , `gap_dismiss` (reason), `gap_dismiss_bulk` , `gap_undismiss` , `gap_stats`
"Clean up the graph"	`semantic_cleanup` (one-click; runs in background — poll `semantic_pass_stats` )
Manual semantic flow	`semantic_pass_run(dry_run=true)` → `semantic_proposals_list` → approve/reject/defer → `semantic_proposals_apply` ; `semantic_pass_stats`

start_id
convention. Prefer the prefix form

'<type>-<id>'

(

'task-271'

'doc-76'

); type vocabulary

task

doc

decision

pattern

progress

. The wikilink form

'[[task-271]]'

is also accepted verbatim. Plain integers work as a legacy fallback but the prefix form gives a clean 400 on type mismatch.

→ Deep detail: live docs

projects/context-recipes

projects/gaps

projects/semantic-pass

触发条件	工具
"打开任务#N并进行简报"	`assemble_context` ，设置 `recipe='task_briefing'` , `start_id='task-N'`
"规范doc-N的实施状态？"	`assemble_context` ，设置 `recipe='spec_implementation_status'` , `start_id='doc-N'`
"有哪些可用的配方？"	`list_context_recipes`
"子系统X的当前架构？"	`render_current_architecture` ，设置 `scope=[...]`
"此架构文档是否可以安全归档？"	`audit_doc_l1_coverage(doc_id)`
Init响应显示缺口 / "展示所有缺口"	查看 `gaps.fresh` ；使用 `gap_list` , `gap_ack` , `gap_dismiss` （需提供理由）, `gap_dismiss_bulk` , `gap_undismiss` , `gap_stats`
"清理图谱"	`semantic_cleanup` （一键操作；后台运行——轮询 `semantic_pass_stats` ）
手动语义流程	`semantic_pass_run(dry_run=true)` → `semantic_proposals_list` → 批准/拒绝/推迟 → `semantic_proposals_apply` ；使用 `semantic_pass_stats`

start_id
约定。优先使用前缀形式

'<type>-<id>'

（

'task-271'

'doc-76'

）；类型词汇包括

task

doc

decision

pattern

progress

。也接受维基链接形式

'[[task-271]]'

。纯整数作为遗留兼容方式也可使用，但前缀形式在类型不匹配时会返回清晰的400错误。

→ 详细内容：实时文档

projects/context-recipes

projects/gaps

projects/semantic-pass

。

TASK HIERARCHY (2 levels, schema-enforced)

任务层级（2级，架构强制）

The task tree is two levels and the database enforces it:

```
kind='task'
```
— leaf node. May have
```
parent_task_id
```
pointing to an epic. Cannot have children.
```
kind='epic'
```
— root container. Always
```
parent_task_id=NULL
```
. Other tasks attach under it.

No third level. Trying to attach a task under another task (kind=task with kind=task parent) is rejected at the DB level. The MCP/REST layer maps the rejection to a structured

parent_not_epic

payload with two recovery options.

任务树为两级，由数据库强制实施：

```
kind='task'
```
— 叶子节点。可设置
```
parent_task_id
```
指向史诗。不能有子任务。
```
kind='epic'
```
— 根容器。
```
parent_task_id
```
始终为NULL。其他任务可关联到其下。

不存在第三级。尝试将任务关联到另一个任务（kind=task的父任务为kind=task）会在数据库层面被拒绝。MCP/REST层会将拒绝转换为结构化的

parent_not_epic

负载，并提供两种恢复选项。

Recovery:

parent_not_epic

error

恢复：

parent_not_epic

错误

When

add_task(parent_task_id=X)

update_task(parent_task_id=X)

returns:

json

{
  "error": "parent_not_epic",
  "message": "Cannot attach a task under task-X — a task can only have an epic as parent.",
  "context": {
    "intended_parent": {"id": X, "kind": "task", "title": "..."},
    "resolved_epic":   {"id": Y, "kind": "epic", "title": "..."}
  },
  "suggestions": [
    {"action": "promote_parent",  "call": "update_task(task_id=X, kind='epic')"},
    {"action": "attach_to_epic",  "call": "add_task(..., parent_task_id=Y)"}
  ]
}

Decide by local context:

promote_parent when X is itself a substantial body of work and the new task is a subtask of it → make X an epic, attach the new task under it.
attach_to_epic when X is just another leaf inside an epic Y → attach the new task to Y as a sibling of X.

resolved_epic

null

, only

promote_parent

is offered — there's no ancestor epic in the chain.

当

add_task(parent_task_id=X)

或

update_task(parent_task_id=X)

json

{
  "error": "parent_not_epic",
  "message": "Cannot attach a task under task-X — a task can only have an epic as parent.",
  "context": {
    "intended_parent": {"id": X, "kind": "task", "title": "..."},
    "resolved_epic":   {"id": Y, "kind": "epic", "title": "..."}
  },
  "suggestions": [
    {"action": "promote_parent",  "call": "update_task(task_id=X, kind='epic')"},
    {"action": "attach_to_epic",  "call": "add_task(..., parent_task_id=Y)"}
  ]
}

根据本地上下文决定：

promote_parent — 当X本身是大量工作，且新任务是其子任务时→将X升级为史诗，将新任务关联到其下。
attach_to_epic — 当X只是史诗Y下的一个叶子任务时→将新任务关联到Y，作为X的同级任务。

如果

resolved_epic

为

null

，则仅提供

promote_parent

选项——链中没有祖先史诗。

Promote / demote rules

升级/降级规则

Promote
task
→
epic
: task must be root (no parent). Combine
```
kind='epic'
```
with
```
parent_task_id=0
```
in one
```
update_task
```
call to atomically detach + promote.
Demote
epic
→
task
: epic must have no children. Close or reparent subtasks first.

Cross-references stay

task-N

for both kinds — epic is a subtype, not a separate namespace.

升级
task
→
epic
：任务必须为根任务（无父任务）。在一次
```
update_task
```
调用中同时设置
```
kind='epic'
```
和
```
parent_task_id=0
```
，实现原子化脱离+升级。
降级
epic
→
task
：史诗必须无子任务。需先关闭或重新指定子任务的父任务。

交叉引用对两种类型都使用

task-N

— 史诗是子类型，而非单独的命名空间。

CROSS-REFERENCE FORMAT (canonical grammar)

交叉引用格式（标准语法）

Every reference to another ConPort item — in

summary

rationale

description

, document body, commit messages — uses the canonical form

<type>-<number>

Type vocabulary (lowercase):

decision

task

doc

pattern

progress

. No aliases (no

document

, no

tasks

, no

dec

Forms accepted by the parser:

Plain prose:
```
decision-321
```
,
```
task-271
```
,
```
doc-76
```
.
Wikilink:
```
[[decision-321]]
```
,
```
[[task-271]]
```
,
```
[[doc-76]]
```
— preferred inside document bodies; the autolinker reifies them as item-graph edges.
Block anchor (documents only):
```
[[doc-89#<block_ulid>]]
```
— link to a specific block (Wave 6).

Anti-patterns (silently break tag/graph navigation):

❌ Don't write	✅ Write
`decision #321` (typed legacy with `#` )	`decision-321`
`Task #123, #124, #125` (untyped continuation)	`task-123, task-124, task-125`
`#634` (untyped, ambiguous)	`decision-634` (or the correct type)
`decision #1155` (pre-migration global id)	drop — autolinker can't resolve; cite the new per-project id

Microcheck (extends POST-WRITE VERIFICATION): Before the write call, scan your

summary

rationale

description

payload for

#\d+

. If you find one:

Replace with
```
<type>-<number>
```
if you know the type.
Untyped or pre-migration id → either drop, or flag explicitly ("legacy id #N, not resolvable") so a reader knows it's intentional, not an oversight.

The parser currently accepts both legacy

#N

and canonical

<type>-N

so older corpus stays linked; emit canonical-only in new writes.

所有对ConPort其他项的引用——包括

summary

rationale

description

, 文档内容, 提交信息——都使用标准格式

<type>-<number>

。

类型词汇（小写）：

decision

task

doc

pattern

progress

。无别名（不能用

document

tasks

dec

）。

解析器接受的格式：

普通文本：
```
decision-321
```
,
```
task-271
```
,
```
doc-76
```
。
维基链接：
```
[[decision-321]]
```
,
```
[[task-271]]
```
,
```
[[doc-76]]
```
— 文档内容中首选；自动链接器会将其转换为项目图谱的边。
块锚点（仅文档）：
```
[[doc-89#<block_ulid>]]
```
— 链接到特定块（Wave 6）。

反模式（会静默破坏标签/图谱导航）：

❌ 请勿这样写	✅ 正确写法
`decision #321` （带 `#` 的遗留写法）	`decision-321`
`Task #123, #124, #125` （无类型的连续写法）	`task-123, task-124, task-125`
`#634` （无类型，歧义）	`decision-634` （或正确类型）
`decision #1155` （迁移前的全局ID）	删除——自动链接器无法解析；请引用新的项目内ID

微检查（扩展自写入后验证）： 在调用写入操作前，扫描你的

summary

rationale

description

负载中的

#\d+

。如果找到：

若知道类型，替换为
```
<type>-<number>
```
。
无类型或迁移前ID → 要么删除，要么明确标记（"遗留ID #N，无法解析"），以便读者知道是故意为之，而非疏忽。

目前解析器同时接受遗留的

#N

和标准的

<type>-N

，以保持旧内容的链接；新写入内容请仅使用标准格式。

OUTPUT FORMAT

输出格式

MCP tools return JSON with a

summary

field. Use it to inform the user.

After	Format
`init`	`[CONPORT] {summary}`
`search`	`[ConPort: N results found for "query"] ...`
`update_task`	`✅ {summary}`
Task DONE/CANCELLED	`✅ {summary}` (progress entry was auto-logged from `resolution` ) + suggest updating active_context
`add_milestone` / `update_milestone`	`✅ {summary}` (carries id, title, `seq N` , `[release]` , epics-closed rollup)
Any write response carrying `epic_progress`	`[EPIC] task-{epic_id}: {open_children} of {total_children} children open` — when `closable` is true, print `[EPIC] task-{epic_id} ready to close — close it with a resolution now` instead, and do it. Print this line only when the summary you already printed doesn't carry the rollup itself: `add_task` / `update_task` summaries end with either `— epic task-N: K of M children open` or, on the closable branch, `— epic task-N ready to close: update_task(...)` — either way the count/prescription is already on screen; `delete_task` and the REST responses need the explicit `[EPIC]` line

Roadmap sections.

init

and

get_agenda

return

roadmap

and

epic_tails

only when the project has them — a missing section means "nothing to show", print nothing. When present:

[ROADMAP] milestone-{current.milestone_id} «{current.title}»{ [release]}{ · ready to close} · {open_milestones_total} milestones open
· task-{task_id} {title} — {open_children}/{total_children} subtasks open
Next: milestone-{next.milestone_id} «{next.title}»

One

·

line per entry of

current.epics

(only the open epics of the current milestone are listed — a closed one is already delivered); add

 [release]

only when

current.is_release

is true and

 · ready to close

only when

current.ready_to_close

is true; drop the

Next:

line entirely when

next

null

[TAILS] task-{epic_id} {title} — {suggested_action}

One line per entry of

epic_tails

, in the order returned (closest to closing first;

closable=true

means nothing is left but the close itself).

suggested_action

is prescribed by the server — print it and follow it, don't substitute your own plan.

MCP create / update tools return a slim payload (not the full entity body) to save agent context —

id

tags

(echoed even as

[]

summary

, and context-specific fields (

version

status

kind

, …). Need the full body? Use the matching read tool (

get_task

get_document

list_decisions

, …). The slim

tags

kind

echo is your POST-WRITE verification channel. (Live docs →

core/post-write-verification

Decision currency. Read surfaces (

get_decision

list_decisions

search

) annotate each decision with

currency

(

current

superseded

deprecated

) and

age_days

. Before citing a decision as authoritative, check

currency

: if

superseded

, follow

superseded_by

to the current decision; if

deprecated

, treat it as retired (see

deprecation_reason

) and do not present it as current. A high

age_days

on a

current

decision is a prompt to verify it still holds, not proof that it's stale.

MCP工具返回带有

summary

字段的JSON。请使用该字段告知用户。

操作后	格式
`init`	`[CONPORT] {summary}`
`search`	`[ConPort: N results found for "query"] ...`
`update_task`	`✅ {summary}`
任务DONE/CANCELLED	`✅ {summary}` （进度条目已从 `resolution` 自动记录） + 建议更新active_context
`add_milestone` / `update_milestone`	`✅ {summary}` （包含id、标题、 `seq N` 、 `[release]` 、已关闭史诗汇总）
任何返回包含 `epic_progress` 的写入响应	`[EPIC] task-{epic_id}: {open_children} of {total_children} children open` — 当 `closable` 为true时，打印 `[EPIC] task-{epic_id} ready to close — close it with a resolution now` 并执行该操作。仅当你已打印的摘要未包含汇总信息时才打印此条： `add_task` / `update_task` 摘要末尾会显示 `— epic task-N: K of M children open` 或在可关闭分支显示 `— epic task-N ready to close: update_task(...)` ——无论哪种情况，计数/要求已显示在屏幕上； `delete_task` 和REST响应需要显式的 `[EPIC]` 行

路线图部分。

init

和

get_agenda

仅在项目有相关内容时返回

roadmap

和

epic_tails

— 缺失的部分表示"无内容可展示"，无需打印。如果存在：

[ROADMAP] milestone-{current.milestone_id} «{current.title}»{ [release]}{ · ready to close} · {open_milestones_total} milestones open
· task-{task_id} {title} — {open_children}/{total_children} subtasks open
Next: milestone-{next.milestone_id} «{next.title}»

current.epics

中的每个条目对应一行

·

（仅列出当前里程碑的未关闭史诗——已关闭的史诗已交付）；仅当

current.is_release

为true时添加

 [release]

，仅当

current.ready_to_close

为true时添加

 · ready to close

；如果

next

为

null

，则完全省略

Next:

行。

[TAILS] task-{epic_id} {title} — {suggested_action}

epic_tails

中的每个条目对应一行，按返回顺序排列（最接近关闭的排在前面；

closable=true

表示只需执行关闭操作即可）。

suggested_action

由服务器指定——请打印并执行，不要替换为自己的计划。

MCP创建/更新工具返回精简负载（而非完整实体内容）以节省代理上下文——包含

id

tags

（即使为空数组也会返回）,

summary

，以及特定上下文字段（

version

status

kind

, …）。如需完整内容，请使用对应的读取工具（

get_task

get_document

list_decisions

, …）。返回的精简

tags

kind

是你的写入后验证渠道。（实时文档 →

core/post-write-verification

。）

决策有效性。 读取界面（

get_decision

list_decisions

search

）会为每个决策标注

currency

（

current

superseded

deprecated

）和

age_days

。在引用决策作为权威依据前，请检查

currency

：如果是

superseded

，请跟随

superseded_by

查看当前决策；如果是

deprecated

，则视为已弃用（查看

deprecation_reason

），不要将其作为当前决策展示。

current

决策的

age_days

较高提示你需验证其是否仍然适用，而非证明其已过时。

POST-WRITE VERIFICATION

写入后验证

Some MCP clients silently drop an optional parameter when the surrounding tool-call XML is malformed — the dropped value folds into the previous string field and the call returns 200 OK with a truncated payload. A real incident lost a

sync_decision

tags

array (they ended up inside

rationale

); the decision landed untagged and broke graph navigation.

The server now rejects any write whose string field contains literal tool-call fragments (

<parameter …>

<invoke …>

</invoke>

<function_calls>

antml:*

) with a structured

mcp_payload_contaminated

error — the bad write does not land; re-issue with the field cleaned. That guard catches the worst class; the echo check below still catches the subtler cases.

After every create/update call that took optional fields, verify the response echo against intent:

You passed	Check on the response
`tags=[...]`	Response `tags` is non-empty and matches intent (count + values)
`description=...`	`description` length ≈ what you sent (not visibly truncated)
`priority=N`	`priority` equals `N`
`parent_task_id` , links	Field is present and equal to intent
`kind='epic'` / `kind='task'`	Response `kind` matches the promote/demote you asked for
`milestone_id=N` / `milestone_id=0` on a task	Response `milestone_id` is `N` (or `null` after a detach)
`sequence` / `is_release` on a milestone	Response `sequence` / `is_release` match intent — milestone writes echo `sequence` , `is_release` , `status` (not `title` ), so those are the verification channel

On mismatch. Re-issue the call with the field re-stated (often one retry fixes the XML glitch). If a second attempt still loses it, flag the mismatch to the user verbatim ("graph integrity: tags lost on decision N, please re-run") rather than silently moving on — the damage is mute graph drift, easy to miss.

Applies to:

sync_decision

add_task

update_task

add_milestone

update_milestone

log_progress

log_pattern

add_document

update_document

update_active_context

update_product_context

, block ops (

update_block

insert_block

delete_block

当周围的工具调用XML格式错误时，部分MCP客户端会静默丢弃可选参数——丢弃的值会合并到前一个字符串字段中，调用会返回200 OK但负载被截断。曾发生过一起事件：

sync_decision

的

tags

数组丢失（它们被合并到

rationale

中）；决策未被标记，破坏了图谱导航。

现在，服务器会拒绝任何字符串字段包含字面工具调用片段（

<parameter …>

<invoke …>

</invoke>

<function_calls>

antml:*

）的写入操作，并返回结构化的

mcp_payload_contaminated

错误——错误的写入不会生效；请清理字段后重新调用。该防护措施能捕获最严重的情况；下面的回显检查仍能捕获更细微的情况。

在每次包含可选字段的创建/更新调用后，请验证响应回显是否符合预期：

你传入的参数	检查响应中的内容
`tags=[...]`	响应中的 `tags` 非空且与预期一致（数量+值）
`description=...`	`description` 长度与你发送的大致相当（未明显截断）
`priority=N`	`priority` 等于 `N`
`parent_task_id` , 链接	字段存在且与预期一致
`kind='epic'` / `kind='task'`	响应中的 `kind` 与你请求的升级/降级一致
任务的 `milestone_id=N` / `milestone_id=0`	响应中的 `milestone_id` 为 `N` （或脱离后为 `null` ）
里程碑的 `sequence` / `is_release`	响应中的 `sequence` / `is_release` 与预期一致——里程碑写入操作会回显 `sequence` , `is_release` , `status` （不回显 `title` ），因此这些是验证渠道

不匹配时。 重新调用并重新指定该字段（通常重试一次即可修复XML故障）。如果第二次尝试仍丢失该字段，请直接向用户标记不匹配情况（"图谱完整性：决策N的标签丢失，请重新运行"），不要静默继续——这种损害是静默的图谱漂移，容易被忽略。

适用于：

sync_decision

add_task

update_task

add_milestone

update_milestone

log_progress

log_pattern

add_document

update_document

update_active_context

update_product_context

, 块操作（

update_block

insert_block

delete_block

）。

MCP ERROR HANDLING

MCP 错误处理

On an

Invalid arguments for tool

error:

READ
path
— the name of the broken parameter
READ
expected
— the required type
FIX ONLY THAT PARAMETER
DO NOT TOUCH OTHER PARAMETERS

`path`	Fix
`project_id`	`"4"` → `4`
`tags`	`"tag"` → `["tag"]`
`priority`	`"3"` → `3`

当出现

Invalid arguments for tool

错误时：

读取
path
— 错误参数的名称
读取
expected
— 要求的类型
仅修复该参数
请勿修改其他参数

`path`	修复方式
`project_id`	`"4"` → `4`
`tags`	`"tag"` → `["tag"]`
`priority`	`"3"` → `3`

CHECKLIST

检查清单

Has
```
init
```
been run?
Question about the project → has
```
search
```
been done?
Starting work on a task → moved to IN_PROGRESS before the first write?
New work → task created/updated?
Work finished → task = DONE with
resolution
?
Closing a task → did NOT call
```
log_progress
```
separately (it's auto-logged)?
Interactive session, work from a later milestone → owner explicitly agreed to it?
Milestone finished →
```
update_milestone
```
with
```
resolution
```
(and, if
```
is_release
```
, only after the release actually shipped)?
Decision made →
```
sync_decision
```
?
Important information → document created?
After every write → response echo verified (tags / description / priority match intent)?
Cross-references in write payload → all in canonical
```
<type>-<number>
```
form (no
```
#N
```
, no
```
decision #321
```
)?
Deep topic (recipes / gaps / semantic pass / block model / tool params) → fetched the live-docs page before acting?

是否已运行
```
init
```
？
关于项目的问题 → 是否已执行
```
search
```
？
开始处理任务 → 是否已在第一次写入前将其改为IN_PROGRESS状态？
新工作 → 是否已创建/更新任务？
工作完成 → 任务是否设为DONE 并指定
resolution
？
关闭任务 → 是否未单独调用
```
log_progress
```
（已自动记录）？
交互式会话，处理后续里程碑的工作 → 是否已获得所有者明确同意？
里程碑完成 → 是否已使用
```
update_milestone
```
并指定
```
resolution
```
（如果是发布里程碑，是否仅在实际发布后执行）？
做出决策 → 是否已执行
```
sync_decision
```
？
重要信息 → 是否已创建文档？
每次写入后 → 是否已验证响应回显（标签/描述/优先级与预期一致）？
写入负载中的交叉引用 → 是否都为标准
```
<type>-<number>
```
格式（无
```
#N
```
，无
```
decision #321
```
）？
深度主题（配方/缺口/语义扫描/块模型/工具参数） → 是否已在操作前获取实时文档页面？

Live docs

实时文档

The deep, situational reference lives at https://conport.app and is the single source of truth. Before acting on a deep topic, fetch the relevant page. Public index: https://conport.app/llms.txt. (No web fetch? Use the

conport docs <topic>

CLI.)

Topic	Page
Save-first discipline	`core/save-first`
Knowledge-graph model (item links + GraphRAG)	`core/graph-model`
Cross-reference grammar	`core/cross-references`
Documentation-graph callouts (full reference)	`core/documentation-callouts`
Post-write verification / slim responses	`core/post-write-verification`
`assemble_context` recipes / `render_current_architecture`	`projects/context-recipes`
Knowledge-base gaps	`projects/gaps`
Semantic pass	`projects/semantic-pass`
Spec append-only invariant	`projects/spec-append-only`
Block-level document model	`projects/block-model`
Task hierarchy	`projects/task-hierarchy`
Roadmap milestones	`projects/roadmap`
Full per-tool parameter reference	`projects/tool-reference`

Local references (shipped with the skill):

references/command_list.md

(full MCP tool API),

references/documentation_graph.md

(long-form callout reference),

references/bootstrap.md

(fresh-project onboarding).

深度场景参考存放在 https://conport.app**，是唯一的事实来源。**在处理深度主题之前，请获取相关页面内容。 公开索引：**https://conport.app/llms.txt**。（无法网页获取？使用

conport docs <topic>

CLI。）

主题	页面
优先保存规范	`core/save-first`
知识图谱模型（项目链接 + GraphRAG）	`core/graph-model`
交叉引用语法	`core/cross-references`
文档图谱标注（完整参考）	`core/documentation-callouts`
写入后验证 / 精简响应	`core/post-write-verification`
`assemble_context` 配方 / `render_current_architecture`	`projects/context-recipes`
知识库缺口	`projects/gaps`
语义扫描	`projects/semantic-pass`
规范追加-only规则	`projects/spec-append-only`
块级文档模型	`projects/block-model`
任务层级	`projects/task-hierarchy`
路线图里程碑	`projects/roadmap`
完整工具参数参考	`projects/tool-reference`

本地参考（随技能提供）：

references/command_list.md

（完整MCP工具API）、

references/documentation_graph.md

（长篇标注参考）、

references/bootstrap.md

（新项目引导）。

conport

Original

Translation

ConPort — Project Management System

ConPort — 项目管理系统

MCP Prefix

MCP 前缀

FIRST ACTION OF THE SESSION

会话的第一个操作

Step 1: Determine the project name

步骤1：确定项目名称

Step 2: Call init

步骤2：调用init

After init — MANDATORY:

执行init后——必须完成：

WORKFLOW — When to call which tool

工作流程——何时调用哪个工具

Planning

规划

Execution

执行

Patterns

模式

Search

搜索

Sync

同步

Progress

进度

Documentation

文档

Routines (periodic backlog cycles)

例行程序（定期待办事项周期）

Context assembly, gaps, semantic pass

上下文组装、缺口、语义扫描

TASK HIERARCHY (2 levels, schema-enforced)

任务层级（2级，架构强制）

Recovery: parent_not_epic error

恢复：parent_not_epic 错误

Promote / demote rules

升级/降级规则

CROSS-REFERENCE FORMAT (canonical grammar)

交叉引用格式（标准语法）

OUTPUT FORMAT

输出格式

POST-WRITE VERIFICATION

写入后验证

MCP ERROR HANDLING

MCP 错误处理

CHECKLIST

检查清单

Live docs

实时文档

Recovery:
`parent_not_epic`
error

恢复：
`parent_not_epic`
错误