技能设计血统
- 作者仓库星标 3,406
- 作者仓库 claude-octopus
- 领域
- 设计与多媒体
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @nyldn · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
第 1 步:保存设计
在集思广益、规划或定义工作流程产生设计输出后,将其与元数据一起保存到标准位置。设计文档在创建后是只读的。要修改设计,请创建一个新文档,并引用先前版本的`supersedes`。
第 2 步:发现先前的设计
在编写新设计之前,使用关键字匹配搜索相关的先前设计。限制: 关键字搜索仅限于 10 个结果,以避免过多的上下文 通过`grep -li` 搜索不区分大小写 仅在当前项目 slug 的目录中搜索
第 3 步:链接修订链
如果同一分支存在先前的设计,则新的设计文档在其 frontmatter 中包含一个指向先前文件名的 `supersedes` 字段。这将创建一个链接的修订链: 要遍历分支的完整修订历史记录:
步骤 4:跨会话发现
下游命令(交付、审查、开发)通过在开始工作之前检查设计目录来自动发现设计上下文。下游技能应在开始工作之前检查设计:流程发现:检查现有设计以避免重复研究流程定义:将先前的设计约束纳入需求流程开发:从最新设计中读取推荐的方法
> **Host: Codex CLI** — This skill was designed for Claude Code and adapted for Codex.
> Cross-reference commands use installed skill names in Codex rather than `/octo:*` slash commands.
> Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it.
> For host tool equivalents, see `skills/blocks/codex-host-adapter.md`.
# Design Document Lineage
## Overview
Persist design documents from brainstorming and planning sessions with branch tracking, revision chains, and cross-session discoverability. Design docs are immutable after creation -- new revisions supersede prior versions rather than editing in place.
## Storage Location
All design documents are stored under:
```
~/.claude-octopus/designs/<project-slug>/
```
The project slug is derived from the current git repository name or working directory basename:
```bash
SLUG=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
DESIGNS_DIR="${HOME}/.claude-octopus/designs/${SLUG}"
mkdir -p "$DESIGNS_DIR"
```
## Filename Format
Design documents follow a strict naming convention:
```
{user}-{branch}-design-{datetime}.md
```
Where:
- `{user}` -- the current OS username (`$USER` or `whoami`)
- `{branch}` -- the current git branch, sanitized (slashes replaced with dashes)
- `{datetime}` -- ISO 8601 compact timestamp (`YYYYMMDD-HHmmss`)
Example:
```
chris-feature-auth-refactor-design-20260321-143022.md
```
Resolution:
```bash
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo "no-branch")
DATETIME=$(date -u +"%Y%m%d-%H%M%S")
FILENAME="${USER}-${BRANCH}-design-${DATETIME}.md"
```
## Design Document Template
Each design document contains YAML frontmatter followed by structured sections.
### Frontmatter Metadata
```yaml
branch: feature/auth-refactor
user: chris
created: 2026-03-21T14:30:22Z
supersedes: chris-feature-auth-refactor-design-20260320-091500.md
```
Fields:
- `branch` -- the git branch at time of creation
- `user` -- the OS username who created the document
- `created` -- ISO 8601 timestamp of creation
- `supersedes` -- filename of the prior design document this revision replaces (omitted if this is the first design for the branch)
### Document Sections
```markdown
# Design: [Title]
## Problem Statement
[What problem does this design solve? Why does it matter?]
## Constraints
[Technical, timeline, resource, or organizational constraints that bound the solution space.]
## Approaches Considered
[List each approach evaluated, with brief pros/cons for each.]
### Approach A: [Name]
- **Pros:** ...
- **Cons:** ...
### Approach B: [Name]
- **Pros:** ...
- **Cons:** ...
## Recommendation
[Which approach is recommended and why. Include the key trade-off that drove the decision.]
## Open Questions
[Unresolved questions that may affect implementation or require follow-up.]
```
## Step 1: Save Design
After a brainstorm, planning, or define workflow produces design output, save it to the standard location with metadata.
```bash
SLUG=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
DESIGNS_DIR="${HOME}/.claude-octopus/designs/${SLUG}"
mkdir -p "$DESIGNS_DIR"
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo "no-branch")
DATETIME=$(date -u +"%Y%m%d-%H%M%S")
FILENAME="${USER}-${BRANCH}-design-${DATETIME}.md"
FILEPATH="${DESIGNS_DIR}/${FILENAME}"
cat > "$FILEPATH" <<EOF
branch: $(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "no-branch")
user: ${USER}
created: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
${SUPERSEDES:+supersedes: ${SUPERSEDES}}
# Design: [Title]
## Problem Statement
[Content from brainstorm/planning session]
## Constraints
[Identified constraints]
## Approaches Considered
[Evaluated approaches]
## Recommendation
[Selected approach and rationale]
## Open Questions
[Unresolved items]
EOF
```
Design docs are **read-only after creation**. To revise a design, create a new document with a `supersedes` reference to the prior version.
## Step 2: Discover Prior Designs
Before writing a new design, search for related prior designs using keyword matching.
```bash
SLUG=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
DESIGNS_DIR="${HOME}/.claude-octopus/designs/${SLUG}"
# Search for designs matching keywords (case-insensitive)
KEYWORDS="auth refactor"
grep -li "$KEYWORDS" "${DESIGNS_DIR}"/*.md 2>/dev/null | head -10
```
Constraints:
- Keyword search is limited to **10 results** to avoid overwhelming context
- Search is case-insensitive via `grep -li`
- Only searches within the current project slug's directory
When prior designs are found, present them to the user:
```
Found 2 prior designs related to "auth refactor":
1. chris-feature-auth-refactor-design-20260320-091500.md (2026-03-20)
2. chris-main-design-20260315-140000.md (2026-03-15)
Would you like to review any of these before creating a new design?
```
## Step 3: Link Revision Chain
If a prior design exists for the same branch, the new design document includes a `supersedes` field in its frontmatter pointing to the prior filename.
```bash
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo "no-branch")
# Find the most recent design for this branch
PRIOR=$(ls -t "${DESIGNS_DIR}"/*-${BRANCH}-design-*.md 2>/dev/null | head -1)
if [[ -n "$PRIOR" ]]; then
SUPERSEDES=$(basename "$PRIOR")
fi
```
This creates a linked chain of revisions:
```
v3 (supersedes: v2) -> v2 (supersedes: v1) -> v1 (no supersedes)
```
To walk the full revision history for a branch:
```bash
current="$FILENAME"
while [[ -n "$current" ]]; do
echo "$current"
current=$(grep '^supersedes:' "${DESIGNS_DIR}/${current}" 2>/dev/null | sed 's/supersedes: *//' || true)
done
```
## Step 4: Cross-Session Discovery
Downstream commands (deliver, review, develop) auto-discover design context by checking the designs directory before starting work.
```bash
SLUG=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
DESIGNS_DIR="${HOME}/.claude-octopus/designs/${SLUG}"
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo "no-branch")
# Find designs for current branch
BRANCH_DESIGNS=$(ls -t "${DESIGNS_DIR}"/*-${BRANCH}-design-*.md 2>/dev/null | head -3)
if [[ -n "$BRANCH_DESIGNS" ]]; then
echo "Design context found for branch ${BRANCH}:"
for design in $BRANCH_DESIGNS; do
echo " - $(basename "$design")"
done
# Read the most recent design for context
LATEST_DESIGN=$(echo "$BRANCH_DESIGNS" | head -1)
DESIGN_CONTEXT=$(<"$LATEST_DESIGN")
fi
```
Downstream skills should check for designs before starting work:
- **flow-discover**: Check for existing designs to avoid duplicate research
- **flow-define**: Incorporate prior design constraints into requirements
- **flow-develop**: Read the recommended approach from the latest design
- **skill-brainstorm**: Surface prior designs as starting context
## Caps and Limits
- **Max 50 design docs per project slug** -- when the limit is reached, warn the user and suggest archiving old designs
- **Keyword search limited to 10 results** -- prevents context overload
- **Design doc template max 500 lines** -- encourages concise, actionable designs
Cap enforcement:
```bash
DOC_COUNT=$(ls "${DESIGNS_DIR}"/*.md 2>/dev/null | wc -l | tr -d ' ')
if [[ "$DOC_COUNT" -ge 50 ]]; then
echo "Warning: ${DOC_COUNT} design docs in ${DESIGNS_DIR}. Consider archiving old designs."
fi
```
## Integration Notes
### Works With
- **flow-discover** -- Design docs capture research findings for persistence
- **flow-define** -- Design constraints feed into requirement definitions
- **skill-brainstorm** -- Brainstorm output can be saved as a design document
- **skill-thought-partner** -- Exploration sessions can produce design artifacts
### Downstream Discovery
- **flow-develop** -- Reads latest design before implementation
- **flow-deliver** -- References design decisions during review
- **skill-code-review** -- Checks implementation against design recommendations
### Immutability Rule
Design docs are **read-only after creation**. To update a design:
1. Create a new design document
2. Set `supersedes` to the prior document's filename
3. The prior document remains unchanged for audit trail
This ensures a complete history of design evolution is always available.
章节与文件索引
按说明文件中的顺序排列。
存放地点
文件名格式
设计文档模板
前沿元数据
第 1 步:保存设计
文件/命令 -> /octo:* · skills/blocks/codex-host-adapter.md · {user} · $USER · whoami · {branch} · {datetime} · YYYYMMDD-HHmmss
内容校验值 -> 51bc53f8e9cd
当前原文的自动摘译,尚未人工审校。
存放地点
所有设计文档都存储在: 项目 slug 源自当前 git 存储库名称或工作目录基本名称:
文件名格式
设计文档遵循严格的命名约定: 其中:
{user}-- 当前操作系统用户名($USER或whoami){branch}-- 当前 git 分支,已清理(斜杠替换为破折号){datetime}-- ISO 8601 紧凑时间戳 (YYYYMMDD-HHmmss)设计文档模板
每个设计文档都包含 YAML frontmatter,后跟结构化部分。
前沿元数据
字段:
branch- 创建时的 git 分支user- 创建文档的操作系统用户名created- ISO 8601 创建时间戳supersedes- 此版本替换的先前设计文档的文件名(如果这是分支的第一个设计,则省略)