# Skill Design Lineage

Persist design documents with branch tracking, revision chains, and cross-session...

- Repository: https://github.com/nyldn/claude-octopus (4351 stars)
- Category: Design
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add nyldn/claude-octopus --skill skill-design-lineage -g -a claude-code -y`
Codex: `npx skills add nyldn/claude-octopus --skill skill-design-lineage -g -a codex -y`
Cursor: `npx skills add nyldn/claude-octopus --skill skill-design-lineage -g -a cursor -y`
Gemini CLI: `npx skills add nyldn/claude-octopus --skill skill-design-lineage -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add nyldn/claude-octopus`

## Description

Persist design documents with branch tracking, revision chains, and cross-session discovery

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Design Document Lineage

When a design introduces or changes domain terms, load
`skills/blocks/domain-modeling.md`. Record each definition in the existing design
lineage artifact with its evidence source, checked time, and scope. A changed
definition invalidates dependent decisions. Link and reopen them instead of
leaving stale implementation guidance marked current.

## 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
---
```

The rest: https://github.com/nyldn/claude-octopus/blob/HEAD/.claude/skills/skill-design-lineage/SKILL.md