Back to Details

swain-status

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<!-- swain-model-hint: sonnet, effort: low -->
<!-- swain-model-hint: sonnet, effort: low -->

Status

状态

Cross-cutting project status dashboard. Aggregates data from artifact lifecycle (
swain chart
), task tracking (tk), git, GitHub issues, and session state into an activity-oriented view.
跨项目状态仪表盘，将工件生命周期（
swain chart
）、任务跟踪（tk）、Git、GitHub Issues以及会话状态的数据聚合为以活动为导向的视图。

When invoked

调用方式

Locate and run the status script from 
skills/swain-status/scripts/swain-status.sh
:
bash
undefined
从
skills/swain-status/scripts/swain-status.sh
找到并运行状态脚本：
bash
undefined

Find the script from the project root or installed skills directories

从项目根目录或已安装的技能目录中查找脚本

SKILL_DIR="$(find . .claude .agents -path '*/swain-status/scripts/swain-status.sh' -print -quit 2>/dev/null)" bash "$SKILL_DIR" --refresh

If the path search fails, glob for `**/swain-status/scripts/swain-status.sh`.

The script's terminal output uses OSC 8 hyperlinks for clickable artifact links. Let the terminal output scroll by — it is reference data, not the primary output.

**After the script runs, present a structured agent summary** following the template in `references/agent-summary-template.md`. The agent summary is what the user reads for decision-making. It must lead with a Recommendation section (see below), then Decisions Needed, then Work Ready to Start, then reference data — following the template in `references/agent-summary-template.md`.

The script collects from five data sources:

1. **Artifacts** — `swain chart` vision-rooted hierarchy (epic progress, ready/blocked items, dependency info). Use `bash "$(find "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" -path '*/swain-design/scripts/chart.sh' -print -quit 2>/dev/null)" recommend` for ranked artifact view; respects focus lane automatically.
2. **Tasks** — tk (in-progress, recently completed)
3. **Git** — branch, working tree state, recent commits
4. **GitHub** — open issues, issues assigned to the user
5. **Session** — bookmarks and context from swain-session
SKILL_DIR="$(find . .claude .agents -path '*/swain-status/scripts/swain-status.sh' -print -quit 2>/dev/null)" bash "$SKILL_DIR" --refresh

如果路径搜索失败，可使用通配符查找`**/swain-status/scripts/swain-status.sh`。

脚本的终端输出使用OSC 8超链接实现可点击的工件链接。让终端输出自然滚动即可——这些是参考数据，并非主要输出内容。

**脚本运行完成后，请按照`references/agent-summary-template.md`中的模板呈现结构化的Agent摘要**。Agent摘要是供用户进行决策阅读的内容，必须以“建议”部分（见下文）开头，接着是“待做决策”、“可启动工作”，最后是参考数据——严格遵循`references/agent-summary-template.md`中的模板。

脚本从五个数据源收集信息：

1. **工件** —— `swain chart`基于愿景的层级结构（史诗任务进度、就绪/阻塞项、依赖信息）。使用`bash "$(find "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" -path '*/swain-design/scripts/chart.sh' -print -quit 2>/dev/null)" recommend`获取排序后的工件视图；会自动适配聚焦领域。
2. **任务** —— tk（进行中、近期已完成）
3. **Git** —— 分支、工作树状态、近期提交
4. **GitHub** —— 未关闭的Issues、分配给当前用户的Issues
5. **会话** —— swain-session中的书签和上下文

Compact mode (MOTD integration)

紧凑模式（MOTD集成）

The script supports 
--compact
for consumption by swain-stage's MOTD panel:
bash
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/skills/swain-status/scripts/swain-status.sh" --compact
This outputs 4-5 lines suitable for the MOTD box: branch, active epic progress, current task, ready count, assigned issue count.
脚本支持
--compact
参数，用于集成到swain-stage的MOTD面板：
bash
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/skills/swain-status/scripts/swain-status.sh" --compact
此模式会输出4-5行适合MOTD框的内容：分支、活跃史诗任务进度、当前任务、就绪项数量、分配的Issues数量。

Cache

缓存

The script writes a JSON cache to the project-local agents directory:
.agents/status-cache.json
  • TTL: 120 seconds (configurable via 
    status.cacheTTL
    in settings)
  • Force refresh: 
    --refresh
    flag bypasses TTL
  • JSON access: 
    --json
    flag outputs raw cache for programmatic use
The MOTD can read this cache cheaply between full refreshes.
Migration: If 
.agents/status-cache.json
does not exist but 
~/.claude/projects/<project-path-slug>/memory/status-cache.json
does, read the old location once and write to the new location going forward.
脚本会将JSON缓存写入项目本地的agents目录：
.agents/status-cache.json
  • TTL（生存时间）： 120秒（可通过设置中的
    status.cacheTTL
    配置）
  • 强制刷新： 
    --refresh
    标志可绕过TTL限制
  • JSON访问： 
    --json
    标志可输出原始缓存供程序化使用
MOTD可以在两次完整刷新之间低成本地读取此缓存。
迁移： 如果
.agents/status-cache.json
不存在，但
~/.claude/projects/<project-path-slug>/memory/status-cache.json
存在，则读取一次旧位置的内容，并在后续写入新位置。

Recommendation

建议

The recommendation uses a scoring formula:
score = unblock_count × vision_weight
Where 
vision_weight
is inherited from the artifact's Vision ancestor (high=3, medium=2, low=1, default=medium). Read 
.priority.recommendations[0]
from the JSON cache for the top-ranked item.
Tiebreakers (applied in order):
  1. Higher decision debt in the artifact's vision
  2. Decision-type artifacts over implementation-type
  3. Artifact ID (deterministic fallback)
When a focus lane is set, recommendations are scoped to that vision/initiative. Peripheral visions are summarized separately (see Peripheral Awareness).
If attention drift is detected for the recommended item's vision, include it as context in the recommendation.
建议使用以下评分公式：
score = unblock_count × vision_weight
其中
vision_weight
继承自工件的愿景祖先（高=3，中=2，低=1，默认=中）。从JSON缓存的
.priority.recommendations[0]
中获取排名第一的项。
平局决胜规则（按顺序应用）：
  1. 工件愿景中更高的决策债务
  2. 决策类工件优先于实现类工件
  3. 工件ID（确定性兜底）
当设置了聚焦领域时，建议会限定在该愿景/计划范围内。外围愿景会单独汇总（见“外围感知”部分）。
如果检测到用户对推荐项所属愿景的注意力分散，需将其作为上下文包含在建议中。

Mode Inference

模式推断

swain-status infers the operating mode from context (first match wins):
  1. Both specs in review AND strategic decisions pending → ask: "Steering or reviewing?"
  2. Specs awaiting operator review (agent finished, needs sign-off) → detail mode
  3. Focus lane set with pending strategic decisions → vision mode within that lane
  4. No specs in review, decisions piling up → vision mode
  5. Nothing actionable in either mode → vision mode (show the master plan mirror)
Once the operator answers, swain remembers for the session via swain-session bookmark.
swain-status会根据上下文推断操作模式（匹配到第一个即生效）：
  1. 既有规格在审核中，又有战略决策待处理 → 询问：“要进行指导还是审核？”
  2. 规格等待操作员审核（Agent已完成，需要签字确认） → 详情模式
  3. 设置了聚焦领域且有战略决策待处理 → 该领域内的愿景模式
  4. 无规格在审核，决策堆积 → 愿景模式
  5. 两种模式下均无可行操作 → 愿景模式（展示主计划镜像）
操作员回答后，swain会通过swain-session书签在本次会话中记住该选择。

Focus Lane

聚焦领域

The operator can set a focus lane via swain-session to scope recommendations to a single vision or initiative:
bash
bash "$(find . .claude .agents -path '*/swain-session/scripts/swain-focus.sh' -print -quit 2>/dev/null)" set VISION-001
When set, 
.priority.recommendations
only includes items under that vision. Non-focus visions appear in the Peripheral Awareness section.
操作员可通过swain-session设置聚焦领域，将建议限定在单个愿景或计划内：
bash
bash "$(find . .claude .agents -path '*/swain-session/scripts/swain-focus.sh' -print -quit 2>/dev/null)" set VISION-001
设置后，
.priority.recommendations
仅包含该愿景下的项。非聚焦愿景会出现在“外围感知”部分。

Peripheral Awareness

外围感知

When a focus lane is set, non-focus visions with pending decisions are summarized: "Meanwhile: [Vision] has N pending decisions (weight: W)"
This is a mirror, not a recommendation — the operator decides when accumulation warrants redirection.
当设置了聚焦领域时，待决策的非聚焦愿景会被汇总为："同时：[愿景] 有N项待决策（权重：W）"
这只是一个镜像，而非建议——由操作员决定何时需要转移注意力处理这些堆积的事项。

Active epics with all specs resolved

所有规格已完成的活跃史诗任务

When an Active epic has 
progress.done == progress.total
:
  • Show "→ ready to close" in the Readiness column of the Epic Progress table
  • Do NOT show it in the Work Ready to Start bucket (it's not implementation work)
  • Do NOT show it as "work on child specs"
当活跃史诗任务的
progress.done == progress.total
时：
  • 在史诗任务进度表的“就绪状态”列中显示“→ 可关闭”
  • 不要将其显示在“可启动工作”区域（这不属于实现工作）
  • 不要显示为“处理子规格”

Settings

设置

Read from 
swain.settings.json
(project) and 
~/.config/swain/settings.json
(user override).
KeyTypeDefaultDescription
status.cacheTTL
number
120
Cache time-to-live in seconds
从项目的
swain.settings.json
和用户级别的
~/.config/swain/settings.json
（优先级更高）读取配置。
键类型默认值描述
status.cacheTTL
数字
120
缓存生存时间（秒）

Session bookmark

会话书签

After presenting status, update the bookmark with the most actionable highlight: 
bash "$(find . .claude .agents -path '*/swain-session/scripts/swain-bookmark.sh' -print -quit 2>/dev/null)" "Checked status — {key highlight}"
展示状态后，用最具行动价值的亮点更新书签：
bash "$(find . .claude .agents -path '*/swain-session/scripts/swain-bookmark.sh' -print -quit 2>/dev/null)" "Checked status — {key highlight}"

Error handling

错误处理

  • If chart.sh / specgraph is unavailable: skip artifact section, show other data
  • If tk is unavailable: skip task section
  • If gh CLI is unavailable or no GitHub remote: skip issues section
  • If 
    .agents/session.json
    doesn't exist: skip bookmark
  • Never fail hard — show whatever data is available
  • 如果chart.sh / specgraph不可用：跳过工件部分，展示其他可用数据
  • 如果tk不可用：跳过任务部分
  • 如果gh CLI不可用或无GitHub远程仓库：跳过Issues部分
  • 如果
    .agents/session.json
    不存在：跳过书签部分
  • 绝不直接崩溃——展示所有可用的数据