Back to Details

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 前缀

EnvironmentPrefix
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:
  1. Git remote — extract the repo name (last segment of the URL without 
    .git
    )
  2. 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
）。 如果未设置，则按以下优先级顺序获取：
  1. Git远程仓库 — 提取仓库名称（URL的最后一段，不含 
    .git
    ）
  2. 目录名称 — 当前工作目录的基名
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后——必须完成：

  1. Print summary: 
    [CONPORT] {summary from response}
  2. Execute instructions from the response (read files, apply rules)
  3. 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
    is 
    effective_priority
    . Skip the whole block if 
    backlog.total_todo == 0
    and 
    backlog.total_in_progress == 0
    .
  4. 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.
  5. If the project is empty (no decisions, no patterns, empty 
    product_context
    ) — offer the bootstrap flow from 
    references/bootstrap.md
    .
  6. 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)
    ).
  7. 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.
  1. 打印摘要： 
    [CONPORT] {summary from response}
  2. 执行响应中的指令（读取文件、应用规则）
  3. 报告待办事项： 
    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
    ，则跳过整个块。
  4. 报告路线图： 当响应包含 
    roadmap
    和/或 
    epic_tails
    时，按照「输出格式 → 路线图部分」给定的格式打印。如果项目没有相关内容，则省略这两个部分——此时无需打印任何内容。
  5. 如果项目为空（无决策、无模式、
    product_context
    为空）——提供 
    references/bootstrap.md
    中的引导流程。
  6. 如果响应中存在 
    routine_suggestion
     — 向用户展示该建议，并提供接受（
    set_routine_config(...)
    ，例如使用 
    suggested_config
    ）或永久拒绝（
    set_routine_config(enabled=false)
    ）的选项。
  7. 如果响应中存在 
    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

规划

TriggerTool
"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

执行

TriggerTool
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
or 
CANCELLED
, pass a 
resolution
argument with the verdict (what was done / why cancelled). The server:
  1. Appends a 
    ## Resolution
    section to the task's description (preserves the original spec verbatim).
  2. 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
参数说明结果（完成了什么/为何取消）。服务器会：
  1. 在任务描述中追加 
    ## Resolution
    部分（保留原始规范内容）。
  2. 自动创建关联的 
    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

模式

TriggerTool
"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

搜索

TriggerTool
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

同步

TriggerTool
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

进度

TriggerTool
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

文档

TriggerTool
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 docsauthor 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)

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

TriggerTool
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

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

TriggerTool
"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)
or 
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.
If 
resolved_epic
is 
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:
  1. Replace with 
    <type>-<number>
    if you know the type.
  2. 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+
。如果找到：
  1. 若知道类型，替换为 
    <type>-<number>
    。
  2. 无类型或迁移前ID → 要么删除，要么明确标记（"遗留ID #N，无法解析"），以便读者知道是故意为之，而非疏忽。
目前解析器同时接受遗留的 
#N
和标准的 
<type>-N
，以保持旧内容的链接；新写入内容请仅使用标准格式。

OUTPUT FORMAT

输出格式

MCP tools return JSON with a 
summary
field. Use it to inform the user.
AfterFormat
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
is 
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
's 
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 passedCheck 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:
  1. READ 
    path
     — the name of the broken parameter
  2. READ 
    expected
     — the required type
  3. FIX ONLY THAT PARAMETER
  4. DO NOT TOUCH OTHER PARAMETERS
path
Fix
project_id
"4"
→ 
4
tags
"tag"
→ 
["tag"]
priority
"3"
→ 
3
当出现 
Invalid arguments for tool
错误时：
  1. 读取 
    path
     — 错误参数的名称
  2. 读取 
    expected
     — 要求的类型
  3. 仅修复该参数
  4. 请勿修改其他参数
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.)
TopicPage
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
（新项目引导）。