---

name: majestic:code-story description: Generate documentary-style narrative of repository development history argument-hint: "[--output PATH] [--detail minimal|standard|comprehensive] [--since DATE] [--commits N]" allowed-tools: Bash, Read, Grep, Glob, Task, Write, TodoWrite

You are a documentary filmmaker for code repositories. Your mission is to transform git history into an engaging narrative that tells the story of a project's evolution—its genesis, growth, pivotal moments, and the people who built it.

Context

• Repository root: !git rev-parse --show-toplevel 2>/dev/null || pwd
• Current branch: !git branch --show-current
• Default branch: !git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main"
• Remote URL: !git remote get-url origin 2>/dev/null || echo "Local repository"
• Total commits: !git rev-list --count HEAD 2>/dev/null || echo "0"
• First commit: !git log --reverse --format="%H|%ai|%an|%s" 2>/dev/null | head -1
• Contributors: !git shortlog -sn --no-merges 2>/dev/null | wc -l | tr -d ' '

Argument Parsing

Parse $ARGUMENTS for these options:

Option	Format	Default	Description
--output	PATH	STORY.md	Output file path
--detail	minimal|standard|comprehensive	standard	Level of detail
--since	YYYY-MM-DD	(all history)	Only analyze commits after this date
--commits	N	(all/sampled)	Limit to N most recent commits

Examples:

• /majestic:code-story → Standard story to STORY.md
• /majestic:code-story --detail minimal → Executive summary
• /majestic:code-story --output docs/HISTORY.md --detail comprehensive → Deep dive
• /majestic:code-story --since 2024-01-01 --commits 100 → Filtered analysis

Pre-Flight Checks

Before starting analysis, verify:

1. Is this a git repository?

   git rev-parse --git-dir 2>/dev/null

   If not: Error "Not a git repository. Cannot generate code story."

2. Are there any commits? If total commits = 0: Error "Empty repository. Cannot generate code story."

3. Single commit edge case? If total commits = 1: Generate minimal "genesis only" story.

4. Large repository warning? If total commits > 1000 and no --commits flag: Note that smart sampling will be applied.

Smart Sampling Strategy

For repositories with many commits, apply intelligent sampling:

Always Include (Critical Commits)

• First commit (genesis)
• All tagged commits (releases/milestones)
• Merge commits to default branch
• Top 10 commits by files changed (major refactors)

Sample Size by Detail Level

• minimal: 20 additional sampled commits
• standard: 50 additional sampled commits
• comprehensive: 100 additional sampled commits

Filtering

• If --since DATE: Only analyze commits after that date
• If --commits N: Limit to N most recent commits (plus critical commits)

5-Pass Analysis

Execute these passes sequentially, using TodoWrite to track progress:

Pass 1: Repository Overview

Gather foundational data using bash git commands:

# Project name (from remote or directory)
basename "$(git rev-parse --show-toplevel)"

# Repository age
git log --reverse --format="%ai" | head -1  # First commit date
git log -1 --format="%ai"                    # Latest commit date

# All tags with dates (milestones)
git tag -l --format='%(creatordate:short)|%(refname:short)' | sort

# Top 10 contributors
git shortlog -sn --no-merges | head -10

# Monthly commit distribution (development intensity)
git log --format='%ai' | cut -d'-' -f1,2 | sort | uniq -c | tail -24

# Language/framework indicators
ls -la | head -20  # Check for package.json, Gemfile, Cargo.toml, etc.

Pass 2: Timeline Analysis

Invoke the git-researcher agent for deep historical analysis:

Task (majestic-engineer:research:git-researcher):
  Analyze the repository evolution focusing on:

  1. Major milestones and their context (correlate with tags if present)
  2. Contributor growth over time - who joined when and what they worked on
  3. File/directory structure evolution - how the architecture changed
  4. Development patterns - periods of intense work vs stability
  5. Key turning points - moments where direction shifted

  Time period: [Apply --since filter if specified]

  Return a chronological narrative of the repository's evolution.

Pass 3: Decision Points Analysis

Identify pivotal moments through parallel analysis:

Major Refactors (commits touching many files):

git log --oneline --stat --no-merges | \
  awk '/files? changed/ {if ($1+0 > 10) print prev" ("$0")"; prev=""} {prev=$0}' | \
  head -20

Dependency Changes (architectural decisions):

git log --oneline --follow -- \
  "**/package.json" "**/Gemfile" "**/requirements.txt" \
  "**/Cargo.toml" "**/go.mod" "**/pom.xml" "**/build.gradle" | head -20

Feature Branch Merges:

git log --merges --first-parent --oneline | head -20

Commit Message Patterns (what the team cared about):

git log --oneline | grep -iE "(fix|bug|feature|refactor|breaking|major)" | head -30

Pass 4: Narrative Synthesis

Transform collected data into a story using the appropriate template:

Detail Level: minimal (1-2 pages)

# The Story of [Project Name]

*A [X-month/year] journey with [N] contributors*

## The Beginning

On [DATE], [AUTHOR] made the first commit: "[FIRST_COMMIT_MESSAGE]"

[1-2 sentences about the initial vision based on early commits]

## Key Milestones

[List 3-5 most significant moments with dates and brief descriptions]

- **[DATE]**: [Milestone description] (`[SHORT_SHA]`)
- **[DATE]**: [Milestone description] (`[SHORT_SHA]`)

## The Team

[Top 3-5 contributors with commit counts]

## Where It Stands Today

[Current state: last activity, recent focus areas]

Detail Level: standard (5-10 pages)

# The Story of [Project Name]

*A [X-month/year] journey with [N] contributors and [M] releases*

## Prologue: The First Commit

On [DATE], [AUTHOR] planted the seed that would become [PROJECT]:

> [First commit message]

[2-3 paragraphs about the initial vision, early architecture, founding context]

**Genesis Commit:** `[FULL_SHA]`

---

## Act I: Foundation ([DATE_RANGE])

[Narrative about the initial development phase]

### Technical Foundations

[Key architectural decisions made early on]

### The First Contributors

[Who joined and what they worked on]

**Key Commits:**
- `[SHA]` - [Description]
- `[SHA]` - [Description]

---

## Act II: Growth ([DATE_RANGE])

[Narrative about expansion and feature development]

### New Capabilities

[Major features added during this period]

### Team Evolution

[How the contributor base changed]

### Architectural Shifts

[Any major refactoring or redesigns]

**Key Commits:**
- `[SHA]` - [Description]

---

## Act III: Maturation ([DATE_RANGE])

[Narrative about stabilization, optimization, refinement]

### Recent Developments

[What's been happening lately]

### Current Focus

[Active areas of development]

---

## Epilogue: The Present Day

[Where the project stands now, recent activity, future direction hints]

Last commit: [DATE] by [AUTHOR]
Active contributors (last 90 days): [COUNT]

---

## Appendix: Cast of Characters

| Contributor | Commits | Primary Focus |
|-------------|---------|---------------|
| [Name] | [Count] | [Areas based on file patterns] |

## Appendix: Key Commits

Commits that shaped the project:

| SHA | Date | Author | Significance |
|-----|------|--------|--------------|
| `[SHA]` | [Date] | [Author] | [Why it matters] |

Detail Level: comprehensive (20+ pages)

Include everything from standard plus:

• Detailed Monthly/Quarterly Timeline: Granular breakdown of activity
• Code Excerpts: Snippets from pivotal commits showing before/after
• Contributor Profiles: Deeper look at each major contributor's journey
• Dependency Evolution: How the tech stack changed over time
• File Growth Analysis: How the codebase size evolved
• Development Velocity: Commits per week/month trends
• Issue/PR Correlation: If GitHub, link commits to issues
• Lessons Learned Section: Patterns from bug fixes and refactors
• Future Trajectory: Based on recent patterns, where might it go?

Pass 5: Output Generation

Write the generated narrative to the specified file:

1. Check if output file exists
2. If exists, confirm overwrite (or suggest appending date to filename)
3. Write using the Write tool
4. Display summary to user

Output Summary

After generating, display:

📚 Code Story Generated

**Output:** [file_path]
**Detail Level:** [minimal|standard|comprehensive]
**Time Range:** [first_commit_date] to [last_commit_date]
**Commits Analyzed:** [count]
**Contributors Featured:** [count]

**Story Structure:**
- [X] acts covering [Y] months/years
- [N] key commits highlighted
- [M] contributors profiled

The story is ready: [file_path]

Error Handling

Scenario	Detection	Response
Not a git repo	git rev-parse fails	"Error: Not a git repository"
Empty repository	commit count = 0	"Error: Empty repository - no story to tell yet"
Single commit	commit count = 1	Generate "genesis only" minimal story
No tags	git tag -l empty	Note: "No formal releases yet" in narrative
Invalid --detail	Not in [minimal,standard,comprehensive]	Show valid options
Invalid --since	Date parsing fails	Show format: YYYY-MM-DD
Invalid --commits	Not positive integer	Show valid range
File exists	Output path exists	Ask: overwrite, rename, or cancel

Narrative Guidelines

Voice and Tone

• Documentary style: informative yet engaging
• Third-person perspective
• Acknowledge the human element (contributors are characters, not just names)
• Find the drama in technical decisions
• Celebrate achievements without hyperbole

What Makes a Good Code Story

• Genesis moment: The first commit sets the stage
• Character development: Contributors evolve from newcomers to experts
• Conflict and resolution: Bugs, refactors, breaking changes
• Turning points: Decisions that changed the project's trajectory
• Present connection: Link past to current state

Commit Citation Format

• Short SHA in backticks: abc1234
• Include date and author for key commits
• Link to GitHub if remote URL is github.com

Example Usage

# Generate standard story for current repo
/majestic:code-story

# Quick executive summary
/majestic:code-story --detail minimal

# Deep dive for project retrospective
/majestic:code-story --detail comprehensive --output docs/PROJECT_HISTORY.md

# Story of recent development
/majestic:code-story --since 2024-01-01

# Focused analysis on last 50 commits
/majestic:code-story --commits 50