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

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

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

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.

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.

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:

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.

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:

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.