Back to Details

ziw-setup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Setup

设置

Create or refresh 
docs/agents/workflow/config.md
, the workflow lookup table. Finish with verified changes, working adapter links, and named gaps blocking only the affected workflows.
创建或刷新 
docs/agents/workflow/config.md
，即工作流查找表。 完成时，应提供经过验证的更改、可正常工作的适配器链接，并明确指出仅阻塞相关工作流的缺口。

Inputs

输入

Repo path, existing config/rules, and the requested setup or refresh scope.
仓库路径、现有配置/规则，以及请求的设置或刷新范围。

Steps

步骤

  1. Read existing config first. On initial setup, use project-config.md as the canonical field index; read only applicable sections. On refresh, patch the existing config.
  2. Set verification scope from the request and evidence of drift.
  3. Verify values from repo files and read-only provider queries.
  4. Write stable config, preserving repo conventions.
  5. Update adapters and report changes, checks, and remaining gaps.
  1. 首先读取现有配置。初始设置时，使用 project-config.md 作为规范字段索引， 且只读取适用的章节。刷新时，对现有配置进行补丁式更新。
  2. 根据请求和漂移证据设置验证范围。
  3. 根据仓库文件和只读 provider 查询验证值。
  4. 编写稳定配置，并保留仓库约定。
  5. 更新适配器，并报告更改、检查结果和剩余缺口。

Set verification scope

设置验证范围

  • Run once per repo, then refresh when workflow changes or the user requests verification.
  • Initial setup or explicit full verification: verify every applicable field.
  • Scoped refresh: verify changed or suspect fields and their dependencies. Preserve unrelated stable mappings without rediscovering them or claiming they were revalidated. An unrelated optional integration does not block this work.
  • Evidence of stale commands, renamed labels, moved projects, CI changes, delegation changes, or environment changes expands only the affected scope.
  • For tracker mappings in scope, make at least one read-only query using the configured IDs and query-safe names. Replace stale names only when a verified ID or canonical name resolves the same scope.
  • Change only missing, stale, wrong, or newly verified fields. Preserve explicit human decisions unless current evidence or the user contradicts them.
Load supporting references only for matching work:
  • Tracker states, labels, readiness, body shape, or estimates: issue-tracker-contract.md.
  • Workers, unattended hooks, continuation, loop limits, capacity, or merge safety: operating-profile.md.
  • Linear + Cursor delegation: linear-cursor-example.md.
  • Role responsibilities or adapters: agent-workflow.md.
  • Handoff shape: handoff.md.
  • Unmapped glossary paths: glossary-discovery.md.
  • Encountered friction: friction-log.md, using the configured complaint store and this role's authority.
  • 每个仓库运行一次；之后在 workflow 发生变化或用户要求验证时刷新。
  • 初始设置或明确要求完整验证： 验证每个适用字段。
  • 限定范围刷新： 仅验证已更改或可疑的字段及其依赖项。 保留无关的稳定映射，无需重新发现这些映射，也不得声称已重新验证。 无关的可选集成不会阻塞此项工作。
  • 命令过期、标签重命名、项目迁移、CI 更改、委派更改或环境更改等证据， 仅会扩大受影响的范围。
  • 对范围内的 tracker 映射，至少使用已配置的 ID 和 query-safe 名称执行一次只读查询。 只有当经过验证的 ID 或规范名称能够解析到相同范围时，才替换过期名称。
  • 仅更改缺失、过期、错误或新近验证的字段。除非当前证据或用户提出异议， 否则应保留明确的人工决策。
仅加载与当前工作匹配的 supporting references：
  • tracker 状态、labels、readiness、正文结构或估算值： issue-tracker-contract.md。
  • workers、无人值守 hooks、continuation、循环限制、容量或合并安全： operating-profile.md。
  • Linear + Cursor 委派： linear-cursor-example.md。
  • 角色职责或 adapters： agent-workflow.md。
  • 交接结构： handoff.md。
  • 未映射的 glossary 路径： glossary-discovery.md。
  • 遇到的阻力： friction-log.md， 并使用已配置的 complaint store 和当前角色的权限。

Verify values

验证值

Use current evidence for fields within the verification scope:
  • Repo rules, package scripts, lockfiles, Make/Just/Turbo files, Git metadata, and CI establish identity, package manager, commands, generated artifacts, default branch, PR conventions, and gates. Code-host queries establish branch protections, linked checks, and PR query shapes when needed.
  • Spec indexes, glossaries, context maps, ADRs, runbooks, and user instruction establish planning authority, paths, status conventions, and documentation checks.
  • Read-only tracker calls establish provider location, projects/boards/teams, statuses, labels, priorities, estimates, relations, templates, and query contracts. Record exact query-safe names, stable IDs, and accepted field names.
  • Tracker metadata, verified config, or user instruction establish delegation, environment labels, continuation handles, and remote worker mechanics. Record supported paths, not a full assignee inventory.
  • Resolve target-repo Claude/Codex/editor files, symlinks, imports, and generated metadata from a clean path. Verify distribution mode, source, lockfile, refresh command, project paths, symlink layout, and plugin marketplace.
  • Deployment/environment config, CI, runbooks, service inventories, and user instruction establish preview rules, hosted checks, credentials, and production approval.
  • For enabled hosted review, inspect provider config, docs, or app settings. CodeRabbit's root 
    .coderabbit.yaml
    maps 
    reviews.auto_review
    .
Commands may be verified from their definitions without execution. Do not run install, deploy, expensive hosted actions, or credentialed provider actions solely to verify setup without explicit approval. Read-only metadata queries use existing authorized access. Report which commands were not executed.
For in-scope values that cannot be verified, omit the value and name the missing evidence. Required gaps block only their affected workflow. Track actionable follow-ups within write authority; otherwise report the owner and action.
对于验证范围内的字段，应使用当前证据：
  • 仓库规则、package scripts、lockfiles、Make/Just/Turbo 文件、Git 元数据 和 CI 可用于确定仓库身份、包管理器、命令、生成产物、默认分支、PR 约定 和关卡。必要时，可通过代码托管平台查询确定分支保护、关联检查和 PR 查询结构。
  • 规格索引、glossaries、context maps、ADRs、runbooks 和用户指令可用于确定 规划权威来源、路径、状态约定和文档检查。
  • 只读 tracker 调用可用于确定 provider 位置、projects/boards/teams、状态、 labels、优先级、估算值、关联关系、模板和查询约定。记录准确的 query-safe 名称、 稳定 ID 和可接受的字段名称。
  • Tracker 元数据、经过验证的配置或用户指令可用于确定委派、环境 labels、 continuation handles 和远程 worker 机制。记录受支持的路径，而不是完整的 assignee 清单。
  • 从干净路径解析目标仓库中的 Claude/Codex/editor 文件、symlinks、imports 和生成的元数据。验证分发模式、source、lockfile、刷新命令、项目路径、 symlink 布局和 plugin marketplace。
  • 部署/环境配置、CI、runbooks、服务清单和用户指令可用于确定预览规则、 托管检查、凭据和生产审批要求。
  • 对于已启用的托管评审，检查 provider 配置、文档或应用设置。 CodeRabbit 根目录的 
    .coderabbit.yaml
    映射 
    reviews.auto_review
    。
无需执行命令，也可以根据其定义验证命令。未经明确批准，不得仅为验证设置而运行 安装、部署、代价高昂的托管操作或需要凭据的 provider 操作。只读元数据查询应使用 现有的授权访问权限。必须报告哪些命令未执行。
对于范围内无法验证的值，省略该值并指出缺失的证据。必需项的缺口仅阻塞其相关工作流。 在写入权限范围内跟踪可执行的后续事项；否则报告负责人和所需操作。

Gate parity

Gate 对齐

  • Map hooks, local checks, and required CI jobs to their actual commands. Name gaps when the local entrypoint omits required tasks; preserve thresholds, environment requirements, and secret-scan scope.
  • Record trusted task caches and only specific tasks whose cache keys miss inputs.
  • Verify unattended enforcement and production approval through the operating profile.
  • Prefer the configured MCP complaint writer; inspect its schema without filing a fictitious event. Tracker fallback requires explicit configuration.
  • 将 hooks、本地检查和必需的 CI jobs 映射到实际命令。当本地入口遗漏必需任务时， 应明确列出缺口；同时保留阈值、环境要求和 secret 扫描范围。
  • 记录可信的任务缓存，并且仅记录缓存键未命中输入的具体任务。
  • 通过 operating profile 验证无人值守执行机制和生产审批流程。
  • 优先使用已配置的 MCP complaint writer；可以检查其 schema，但不得提交虚构事件。 Tracker 回退方案必须具有明确配置。

Write stable config

编写稳定配置

  • Keep repeatedly needed values, paths, commands, IDs, routing, limits, and policies terse. Include applicable planning, tracker/readiness, delegation, agent access, review/merge, environment safety, complaint, and handoff mappings.
  • Use the tracker contract's taxonomy as defaults, not proof labels exist. Preserve verified repo conventions and keep separate label docs aligned with config.
  • Keep readiness, risk, review evidence, type, area, and ownership policy consistent.
  • Preserve glossary paths; default new glossaries to 
    GLOSSARY.md
    and multi-context maps to 
    GLOSSARY-MAP.md
    .
  • Record actual skill distribution: project, plugin/marketplace, managed, user/global, or mixed. Classify generated 
    ziw-*
    copies as committed dependencies, symlink fanout, ignored cache, absent, or repo-authored skills. Committed generated dependencies retain source/lockfile and update mechanically.
  • Store project progress, blockers, baseline failures, and verification follow-ups in the tracker. Read CI/PR/review/deploy health and provider availability live. Status names and IDs describe schema, not current work state.
When removing existing state notes, preserve actionable gaps outside config. Search prior setup titles/descriptions with a bounded query scoped to the tracker location and repo route. Within write authority, transfer nonduplicates to the configured intake without readiness labels. Otherwise preserve the notes awaiting transfer and report the required action. Disabled optional integrations stay disabled.
  • 简洁记录反复需要的值、路径、命令、ID、路由、限制和策略。 包含适用的规划、tracker/readiness、委派、Agent access、review/merge、 环境安全、complaint 和 handoff 映射。
  • 可以将 tracker contract 的分类体系用作默认值，但不能以此证明 labels 确实存在。 保留已验证的仓库约定，并确保独立的 label 文档与 config 保持一致。
  • 确保 readiness、risk、review evidence、type、area 和 ownership policy 保持一致。
  • 保留 glossary 路径；新 glossary 默认使用 
    GLOSSARY.md
    ，多 context 映射默认使用 
    GLOSSARY-MAP.md
    。
  • 记录实际的 skill 分发方式：project、plugin/marketplace、managed、 user/global 或 mixed。将生成的 
    ziw-*
    副本归类为已提交依赖、symlink 扇出、 被忽略的缓存、缺失或仓库自编 skill。已提交的生成依赖应保留 source/lockfile， 并以机械方式更新。
  • 在 tracker 中记录项目进度、阻塞项、基线失败和验证后续事项。实时读取 CI/PR/review/deploy 健康状况和 provider 可用性。状态名称和 ID 描述的是 schema， 而非当前工作状态。
删除现有状态记录时，应在 config 之外保留可执行的缺口。使用范围受限的查询， 按 tracker 位置和 repo 路由搜索以往的设置标题/描述。在写入权限范围内，将不重复项 转移到已配置的 intake，且不附带 readiness labels。否则，应保留等待转移的记录并报告 所需操作。已禁用的可选集成应保持禁用。

Update adapters

更新适配器

  • Update existing 
    AGENTS.md
    , 
    CLAUDE.md
    , editor/agent rules, and local usage docs to read config before workflow skills. Keep them short using the adapter reference.
  • Configure the target repo's Claude integration, not this skills repo. Use its registration rules and import its agent Markdown, usually one-line 
    @AGENTS.md
    .
  • Symlink only where that integration requires exact paths; verify targets from a clean checkout. Report refused paths and track repairs instead of guessing.
  • 更新现有 
    AGENTS.md
    、
    CLAUDE.md
    、editor/agent 规则和本地使用文档， 使其在 workflow skills 之前读取 config。按照 adapter reference 保持文档简短。
  • 配置目标仓库的 Claude 集成，而不是当前 skills 仓库。遵循其注册规则并导入其 agent Markdown，通常只需一行 
    @AGENTS.md
    。
  • 仅在该集成要求精确路径时使用 symlink；通过全新检出环境验证目标。 报告无法创建 symlink 的路径并跟踪修复，不要进行猜测。

Never

禁止事项

  • Invent values, retain contradicted values, regenerate existing config from scratch, or turn disabled optional integrations into work.
  • Store state snapshots, execution evidence, tasks, transcripts, or an 
    Unknowns
    checklist in config.
  • Discard state awaiting transfer or substitute a local backlog when tracker-write authority is absent.
  • Probe workers by assigning real implementation issues, or test complaint storage with fictitious events.
  • Hand-edit downstream generated skills or copy agent Markdown instead of importing it.
  • Include secrets, tokens, signed URLs, customer payloads, or private logs in config.
  • Deploy or mutate production while setting up config.
  • 不得臆造值、保留已被证伪的值、从头重新生成现有 config，或将已禁用的可选集成 纳入待办工作。
  • 不得在 config 中存储状态快照、执行证据、任务、对话记录或 
    Unknowns
    检查清单。
  • 不得丢弃等待转移的状态，也不得在缺少 tracker 写入权限时以本地 backlog 替代。
  • 不得通过分配真实实现 issue 来探测 workers，也不得使用虚构事件测试 complaint storage。
  • 不得手动编辑下游生成的 skills，也不得复制 agent Markdown 而不进行导入。
  • config 中不得包含 secrets、tokens、签名 URL、客户数据载荷或私有日志。
  • 设置 config 期间，不得部署或变更生产环境。

Done

完成标准

Report config path, initial/full/scoped mode, fields verified/changed/preserved, adapters and commands found, executed checks, gaps and authorized follow-ups, and whether the affected workflow can proceed. Do not claim whole-config verification after a scoped refresh.
报告 config 路径、初始/完整/限定范围模式、已验证/已更改/已保留的字段、找到的 adapters 和 commands、已执行的检查、缺口和已授权的后续事项，以及受影响的工作流 能否继续。限定范围刷新后，不得声称已完成整个 config 的验证。