init-architect

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Init Architect

Purpose

用途

Run once after installing skills (and rerun when architecture drifts) to create or refresh architecture-folder artifacts used by

architect-agent

. Also supports scoped updates when invoked from

pr-review-agent

for architecture-impacting PR changes.

在安装Skill后运行一次（当架构发生偏移时重新运行），以创建或刷新供

architect-agent

使用的架构目录工件。当被

pr-review-agent

调用时，还支持针对影响架构的PR变更进行范围化更新。

Runtime Configuration

运行时配置

Read
```
/orchestra-config.json
```
from the repository root before starting.
If
```
/orchestra-config.json
```
is missing, create it at repository root with:
```
{ "issue_tracker": "linear" }
```
Read
```
issue_tracker
```
and use it for any generated tracker-facing instructions.
Allowed
```
issue_tracker
```
values:
```
linear
```
,
```
jira
```
.
For tracker comments in workflow-scoped mode, include:
```
Skill-Version: init-architect@2.0.0
```
.

启动前从仓库根目录读取
```
/orchestra-config.json
```
文件。
如果
```
/orchestra-config.json
```
不存在，在仓库根目录创建该文件，内容为：
```
{ "issue_tracker": "linear" }
```
读取
```
issue_tracker
```
配置，并将其用于所有生成的面向问题追踪工具的指令中。
允许的
```
issue_tracker
```
取值：
```
linear
```
、
```
jira
```
。
在工作流范围模式下，追踪工具的评论中需包含：
```
Skill-Version: init-architect@2.0.0
```
。

When to Invoke

调用时机

Immediately after skill installation, before running
```
architect-agent
```
.
When architecture artifacts are stale after major system changes.
When
```
pr-review-agent
```
flags architecture-impacting changes and provides scoped PR context.

安装Skill后立即运行，在启动
```
architect-agent
```
之前执行。
当架构工件因系统重大变更而过期时。
当
```
pr-review-agent
```
标记出影响架构的变更并提供PR范围上下文时。

Required Inputs

必填输入

Repository root path.
Invocation mode:
```
full
```
(default): repository analysis and full architecture refresh.
```
scoped
```
: targeted update using PR-derived scope.
For
```
scoped
```
mode:
parent issue ID.
PR identifier/link.
changed files list.
concise diff summary.
matched architecture-impact cases.
suggested architecture sections.
Optional existing
```
/architecture/architecture.md
```
.
Optional existing
```
/architecture/docs/*.md
```
.
Optional existing
```
skills/init-architect/ARCHITECTURE.md
```
template.
Most recent prior handoff comment in
```

```
format when running in workflow-scoped mode.

仓库根目录路径。
调用模式：
```
full
```
（默认）：仓库分析与完整架构刷新。
```
scoped
```
：使用PR衍生的范围进行针对性更新。
对于
```
scoped
```
模式：
父问题ID。
PR标识符/链接。
变更文件列表。
简洁的差异摘要。
匹配的架构影响案例。
建议的架构章节。
可选的现有
```
/architecture/architecture.md
```
文件。
可选的现有
```
/architecture/docs/*.md
```
文件。
可选的现有
```
skills/init-architect/ARCHITECTURE.md
```
模板。
在工作流范围模式下运行时，最近的、格式为
```

```
的历史交接评论。

Outputs

输出

```
/orchestra-config.json
```
in repository root (created only if missing).
```
/architecture/architecture.md
```
populated as the architecture index.
```
/architecture/docs/*.md
```
populated for complex domains.
In
```
scoped
```
mode: only impacted sections/documents are updated; unaffected sections remain unchanged.
Optional targeted updates to
```
skills/architect-agent/SKILL.md
```
reference tables so runtime guidance matches generated docs.
For workflow-scoped mode, a handoff comment wrapped exactly as:

JSON

{
  "execution_trace": "Execution-Trace:\nActions:\n1. <action>\n2. <action>\nDecisions:\n- <architecture update decision + reason>\nReferences:\n- <changed files or architecture docs>\nAssumptions:\n- <assumption>\nOpen-Questions: none|<question list>\nSkill-Version: init-architect@2.0.0",
  "handoff_summary": {
    "from_skill": "init-architect",
    "to_skill": "architect-agent|pr-review-agent",
    "status": "ready|blocked|completed",
    "delta": ["<what changed in architecture artifacts>"],
    "key_decisions": [{"decision": "<decision>", "reason": "<reason>"}],
    "relevant_artifacts": [
      {
        "artifact": "architecture-index-or-doc",
        "hash": "sha256:<hash>",
        "last_modified": "<ISO-8601>",
        "summary": "<updated sections and rationale>"
      }
    ],
    "open_blockers": [{"blocker": "<text>", "owner": "<owner>", "next_action": "<action>"}],
    "next_guidance": {
      "need_full": ["architecture/architecture.md"],
      "focus": ["<sections downstream agents must re-check>"]
    }
  }
}

```
handoff_summary
```
must be <= 600 tokens.

仓库根目录下的
```
/orchestra-config.json
```
文件（仅在缺失时创建）。
已填充内容的
```
/architecture/architecture.md
```
作为架构索引。
为复杂领域填充的
```
/architecture/docs/*.md
```
文件。
在
```
scoped
```
模式下：仅更新受影响的章节/文档；未受影响的章节保持不变。
可选地针对性更新
```
skills/architect-agent/SKILL.md
```
中的参考表格，使运行时指南与生成的文档保持一致。
在工作流范围模式下，输出格式严格如下的交接评论：

JSON

{
  "execution_trace": "Execution-Trace:\nActions:\n1. <action>\n2. <action>\nDecisions:\n- <architecture update decision + reason>\nReferences:\n- <changed files or architecture docs>\nAssumptions:\n- <assumption>\nOpen-Questions: none|<question list>\nSkill-Version: init-architect@2.0.0",
  "handoff_summary": {
    "from_skill": "init-architect",
    "to_skill": "architect-agent|pr-review-agent",
    "status": "ready|blocked|completed",
    "delta": ["<what changed in architecture artifacts>"],
    "key_decisions": [{"decision": "<decision>", "reason": "<reason>"}],
    "relevant_artifacts": [
      {
        "artifact": "architecture-index-or-doc",
        "hash": "sha256:<hash>",
        "last_modified": "<ISO-8601>",
        "summary": "<updated sections and rationale>"
      }
    ],
    "open_blockers": [{"blocker": "<text>", "owner": "<owner>", "next_action": "<action>"}],
    "next_guidance": {
      "need_full": ["architecture/architecture.md"],
      "focus": ["<sections downstream agents must re-check>"]
    }
  }
}

```
handoff_summary
```
的内容长度必须≤600个token。

Context Gathering Order (Strict)

上下文收集顺序（严格执行）

Locate the most recent comment containing
```

```
from the previous skill.
Parse the JSON inside it. This is your primary context.
Look at its
```
relevant_artifacts
```
list and hashes.
Declare exactly which artifacts you need via
```
need_full
```
.
Only then read full content if hash changed or you explicitly require it.
In non-workflow bootstrap mode with no prior handoff, continue with repository artifacts only.

定位上一个Skill生成的、包含
```

```
的最新评论。
解析其中的JSON内容，这将作为你的主要上下文。
查看其
```
relevant_artifacts
```
列表及哈希值。
通过
```
need_full
```
明确声明你需要的工件。
仅当哈希值变更或你明确需要时，才读取完整内容。
在无历史交接记录的非工作流引导模式下，仅基于仓库工件继续执行。

Procedure

执行流程

Ensure
```
/orchestra-config.json
```
exists and has key
```
issue_tracker
```
.
Execute the strict context gathering order above when in workflow-scoped mode.
Ensure scaffold exists:

```
skills/init-architect/ARCHITECTURE.md
```
.

Ensure generated artifact paths exist:

```
/architecture/architecture.md
```
.
```
/architecture/docs/
```
.

If architecture content currently lives under
```
/ARCHITECTURE.md
```
or
```
/docs/
```
, migrate relevant content into
```
/architecture/
```
and stop updating legacy root-level copies.
Determine mode:

If scoped payload is present, run
```
scoped
```
mode.
Otherwise run
```
full
```
mode.

In
```
full
```
mode, analyze repository structure (do not read every source file):

stack, entry points, boundaries, data layer, integrations, auth, sensitive areas, conventions.

In
```
full
```
mode, write/update
```
/architecture/architecture.md
```
as a concise index:

system overview.
component map.
sensitive areas.
conventions.
reference docs table.

In
```
full
```
mode, create/update
```
/architecture/docs/*.md
```
only for domains that need detail beyond the index.
In
```
scoped
```
mode, use provided PR scope first and update only impacted architecture artifacts:

map changed files and matched cases to existing sections in
```
/architecture/architecture.md
```
.
update only relevant sections in
```
/architecture/architecture.md
```
.
update or create only the necessary
```
/architecture/docs/*.md
```
files tied to those sections.
keep unrelated sections/documents untouched.

In
```
scoped
```
mode, preserve current architecture structure and terminology unless the PR clearly introduces a new boundary or domain.
Keep index shallow; move depth to domain docs.
If generated docs change domain/sensitive-area mapping, update relevant sections in
```
skills/architect-agent/SKILL.md
```
.
In workflow-scoped mode, post handoff JSON with
```
status: completed
```
or
```
status: blocked
```
.

确保
```
/orchestra-config.json
```
存在且包含
```
issue_tracker
```
键。
在工作流范围模式下，严格执行上述上下文收集顺序。
确保模板文件存在：

```
skills/init-architect/ARCHITECTURE.md
```
。

确保生成的工件路径存在：

```
/architecture/architecture.md
```
。
```
/architecture/docs/
```
目录。

如果架构内容当前存储在
```
/ARCHITECTURE.md
```
或
```
/docs/
```
目录下，将相关内容迁移至
```
/architecture/
```
目录，并停止更新根目录下的旧版本文件。
确定运行模式：

如果存在范围化负载，运行
```
scoped
```
模式。
否则运行
```
full
```
模式。

在
```
full
```
模式下，分析仓库结构（无需读取所有源文件）：

技术栈、入口点、边界、数据层、集成组件、认证机制、敏感区域、编码规范。

在
```
full
```
模式下，编写/更新
```
/architecture/architecture.md
```
作为简洁的索引：

系统概述、组件映射、敏感区域、编码规范、参考文档表格。

在
```
full
```
模式下，仅为需要超出索引详细内容的领域创建/更新
```
/architecture/docs/*.md
```
文件。
在
```
scoped
```
模式下，优先使用提供的PR范围，仅更新受影响的架构工件：

将变更文件和匹配的案例映射到
```
/architecture/architecture.md
```
中的现有章节。
仅更新
```
/architecture/architecture.md
```
中的相关章节。
更新或创建与这些章节关联的必要
```
/architecture/docs/*.md
```
文件。
保持无关章节/文档不变。

在
```
scoped
```
模式下，除非PR明确引入了新的边界或领域，否则保留现有架构的结构和术语。
保持索引简洁；将详细内容放在领域文档中。
如果生成的文档改变了领域/敏感区域的映射，更新
```
skills/architect-agent/SKILL.md
```
中的相关章节。
在工作流范围模式下，发布状态为
```
completed
```
或
```
blocked
```
的交接JSON。

Guardrails

约束规则

This skill owns architecture artifact generation;
```
architect-agent
```
must not regenerate architecture docs.
Do not overwrite
```
skills/init-architect/ARCHITECTURE.md
```
template files.

Keep generated architecture artifacts under

/architecture/

(

/architecture/architecture.md

/architecture/docs/*.md

Prefer clarity over coverage; do not scan the full codebase unnecessarily.
In
```
scoped
```
mode, do not perform a full repository rescan unless scoped context is insufficient.
In
```
scoped
```
mode, prioritize consistency with existing architecture docs and produce minimal diffs.

本Skill负责架构工件的生成；
```
architect-agent
```
不得重新生成架构文档。
不得覆盖
```
skills/init-architect/ARCHITECTURE.md
```
模板文件。

将生成的架构工件保存在

/architecture/

目录下（

/architecture/architecture.md

、

/architecture/docs/*.md

）。

优先保证清晰度而非覆盖范围；无需不必要地扫描整个代码库。
在
```
scoped
```
模式下，除非范围化上下文不足，否则不得执行完整的仓库重新扫描。
在
```
scoped
```
模式下，优先保证与现有架构文档的一致性，并生成最小化的差异。

Handoff

交接对象

Primary consumers:

architect-agent

pr-review-agent

(scoped invocation).

主要使用者：

architect-agent

、

pr-review-agent

（范围化调用场景）。