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:

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:

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

---
branch: feature/auth-refactor
user: chris
created: 2026-03-21T14:30:22Z
supersedes: chris-feature-auth-refactor-design-20260320-091500.md
---