timeline

name: timeline description: Use when generating a project milestone timeline from git history. Triggers on "timeline", "milestones", "project history", or when the user wants to see the story of how the project evolved.

Project Timeline

Generate a milestone timeline from git history using chunked parallel analysis and a merge pass.

Core Principles

• Milestones, not features: A milestone is when the project became something it wasn't before — not when it got more of what it already had
• First-of-kind only: The first of a new capability class is a milestone. The Nth is not.
• Commit hashes are sacred: Every entry must reference a real, verified commit hash. Never fabricate.
• Incremental by default: First run processes full history. Subsequent runs process only new commits.
• Divide and conquer: Chunk the log across parallel agents to avoid context overload and hash fabrication.
• Let the history speak: Don't prescribe how many milestones to find. Early history is naturally denser — foundations get laid fast, then the project matures. The distribution is logarithmic, not uniform.

What Is a Milestone?

A milestone changes the project's identity or capability class. Ask: "After this commit, can the project do something fundamentally new?"

IS a milestone:

• First working prototype (the project exists)
• New architectural layer (persistence, automation, compute pipeline)
• Structural reorganization that changes how the project scales
• New category of capability (not a new instance of an existing category)
• Paradigm shift in workflow (fixed pipeline becomes user-composable)

IS NOT a milestone:

• Adding the Nth instance of something that already exists
• Bug fixes, polish, parameter tweaks
• Individual feature additions within an established pattern
• Documentation updates
• Refactors that don't change capability

Output Format

File: docs/timeline.md

# [Project Name] Timeline

<!-- last: <full-commit-hash> -->

**<YYYY-MM-DD>** — **[Milestone Title]** — `<short-hash>`
> One or two sentences: what changed about the project's identity or capabilities.

**<YYYY-MM-DD>** — **[Milestone Title]** — `<short-hash>`
> One or two sentences.

...

Rules:

• Entries in chronological order (oldest first)
• Each entry leads with date for scannability, hash trails at the end
• Date from git log --format='%as' -1 <hash> (author date, YYYY-MM-DD)
• Full hash in the <!-- last: --> comment for incremental tracking
• One-line title, 1-2 sentence description
• Description says what the project became, not what code changed

Phase 1: Determine Range

Goal: Figure out what commits to process.

Actions:

1. Check if docs/timeline.md exists
2. If it exists: extract the <!-- last: <hash> --> comment. Run git log --oneline <hash>..HEAD | wc -l to count new commits.
   • If 0 new commits: tell user "Timeline is up to date" and stop.
   • If new commits exist: set range to <hash>..HEAD
3. If it doesn't exist: set range to full history. Run git log --oneline | wc -l for total count.
4. Report to user: "Processing N commits (full history / since last run)"

Phase 2: Chunk and Dispatch

Goal: Split the commit range into manageable chunks and fan out agents.

Actions:

1. Run git log --oneline --reverse [range] to get the full list
2. Split into chunks of ~200 commits each. Record exact hash boundaries for each chunk.
3. Dispatch one agent per chunk in parallel (single message, multiple Task calls):

Task(
  prompt="[chunk agent prompt below]",
  subagent_type="general-purpose",
  description="Scan commits [start-hash]..[end-hash]"
)

Chunk Agent Prompt

# Find Milestone Candidates

You are scanning a chunk of git history for milestone candidates. A milestone is when the project BECAME SOMETHING IT WASN'T BEFORE — not when it got more of what it already had.

## Your Commit Range

[PASTE THE EXACT `git log --oneline --reverse` OUTPUT FOR THIS CHUNK]

## Rules

- A milestone changes the project's IDENTITY or CAPABILITY CLASS
- The first of a new kind of thing is a candidate. The 2nd, 3rd, Nth is NOT.
- Architectural reorganizations that change how the project scales are candidates.
- Bug fixes, polish, parameter tweaks, documentation are NEVER milestones.
- Adding one more feature within an established pattern is NOT a milestone.
- Most chunks will have 0-2 candidates. Returning an empty list is fine and expected.

## What to Return

For each candidate:

- **Hash**: The exact short hash from the log (copy it character-for-character)
- **Title**: 3-6 word milestone name
- **Description**: One sentence — what the project became after this commit
- **Confidence**: High (clearly transformative) or Medium (judgment call)

If your chunk has no milestones, return an empty list.

Return ONLY the structured list. No commentary.

Phase 3: Merge and Deduplicate

Goal: Combine candidates from all chunks into a final timeline.

Actions:

1. Collect all candidate lists from chunk agents
2. Apply deduplication rules:
   • If multiple candidates describe the same capability emerging, keep only the first
   • If a candidate is "more of what already exists" in context of earlier candidates, drop it
   • Prefer High confidence over Medium when they overlap
3. Verify each surviving candidate's hash: git log --format='%h %as' -1 <hash> — confirm it exists and capture the date
4. Order chronologically

Phase 4: Write Timeline

Goal: Write or update docs/timeline.md

Actions:

Full History (new file)

1. Get the HEAD hash: git rev-parse HEAD
2. Get the project name from the repository root directory name
3. Write docs/timeline.md with all entries and <!-- last: <full-HEAD-hash> -->

Incremental (append to existing)

1. Read existing docs/timeline.md
2. Remove the old <!-- last: --> line
3. Append new entries after the last existing entry
4. Add new <!-- last: <full-HEAD-hash> --> at the end
5. If no new milestones found in the range, just update the <!-- last: --> hash

Phase 5: Summary

Actions:

1. Tell user:
   • How many commits processed
   • How many milestones identified
   • File location
2. If full history: display the complete timeline
3. If incremental with new milestones: display only the new entries

Output Constraints

• ONLY create/modify docs/timeline.md
• Do NOT create branch, PR, or commit (user decides when to commit)
• Do NOT include entries without verified commit hashes and dates

Red Flags - STOP