Time Capsule

Write messages to your future self — or your future team — that unlock when specific code conditions are met. "Dear future me: if you're reading this, someon...

Security Scan

The skill's stated goal (burying messages that auto-open on repo events) is plausible but the SKILL.md is vague about what the agent will actually read, write, or install — it doesn't declare the permissions or mechanism needed, which is inconsistent and could allow unexpected repository or CI changes.

Purpose & Capability

The skill claims to embed messages in a codebase and surface them on triggers (file edits, dependency upgrades, first contributor, dates). Achieving that legitimately requires read/write access to the repository, access to git history, and likely CI/webhook integration or scheduled runners. The package declares no required credentials, tokens, or config paths that would be needed for remote hooks/CI setup, so there's a mismatch between the claimed capabilities and the declared requirements.

Instruction Scope

SKILL.md is instruction-only and largely descriptive; it does not show concrete, constrained runtime steps. A real runtime implementation would need to (a) scan the repo and commit history, (b) add or modify files (capsule payloads), and (c) possibly add CI workflows or webhook listeners to detect triggers. Those actions involve reading potentially sensitive files and writing persistent code into the repository; the instructions are open-ended and grant broad discretion without detailing safeguards (e.g., making changes via PRs, code review, or read-only discovery).

Install Mechanism

No install spec and no code files are present, so the skill itself won't drop binaries or archives on disk. This lowers supply-chain risk relative to skills that download and execute external code.

Credentials

The skill declares no required environment variables or credentials, but the described features (detecting new contributors, watching for dependency upgrades, integrating with CI or scheduled triggers) typically require access to repository metadata and/or CI tokens (e.g., GITHUB_TOKEN), or at least a mechanism to run on a scheduled basis. The absence of declared credentials is disproportionate to the capability and leaves unclear whether the skill will request or create secrets at runtime.

Persistence & Privilege

The skill does not set always:true, but its intended behavior implies writing persistent artifacts into the repository (capsule files, annotations, or CI/workflow files). That persistence can create long-lived functionality (e.g., workflows that run on push) and thus raises privilege concerns if the agent is allowed to commit or create workflow files without review. The SKILL.md does not describe safeguards (e.g., making changes via PRs rather than direct pushes).

What to consider before installing

This skill's idea is reasonable, but the instructions are vague about exactly what the agent will read and write. Before installing: 1) Request the full SKILL.md runtime steps showing any git/CI operations. 2) Require the skill to operate read-only or to propose changes as pull requests (not direct commits). 3) Refuse or closely review any added CI/workflow files — these can run with repo permissions and exfiltrate secrets. 4) Confirm whether any credentials (e.g., GITHUB_TOKEN, CI secrets) are needed and why; prefer short-lived tokens and explicit consent. 5) If you allow it, run the skill in a sandboxed repository and review all created files and commits before merging to main. If the author cannot provide concrete, minimal runtime steps and clear safeguards, treat the skill as untrusted.

"The best time to document your decisions was when you made them. The second best time is to leave a message for whoever has to deal with them later."

What It Does

You know things right now that will be desperately needed later — but you don't know when later. Time Capsule lets you bury messages in the codebase that surface automatically when specific conditions are triggered:

• When someone finally touches that file nobody's touched in 2 years
• When the TODO count in a module exceeds a threshold
• When a specific dependency gets upgraded
• When test coverage drops below a certain percentage
• When a new developer makes their first commit
• On a specific date ("Hey team, the API license expires next month")

The message arrives exactly when it's relevant — not before (when it would be noise) and not after (when it would be too late).

Capsule Types

The Welcome Capsule

Triggered when a new contributor makes their first commit

╔══════════════════════════════════════════════════════════════╗
║  ⏳ TIME CAPSULE OPENED!                                     ║
║  Buried by: @jcooley on 2025-06-15                          ║
║  Trigger: New contributor detected                          ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║  Dear new team member,                                       ║
║                                                              ║
║  Welcome! Here's what I wish someone told me on day one:     ║
║                                                              ║
║  1. The "legacy" folder isn't legacy — it's the billing      ║
║     engine and it handles $2M/day. Don't rename anything.    ║
║                                                              ║
║  2. Tests in /integration are slow (40 min). Run /unit       ║
║     first. Only run integration before pushing to main.      ║
║                                                              ║
║  3. If you see a function called `doTheThing()` in           ║
║     auth.ts — yes, we know. No, don't fix it yet. There's   ║
║     a Time Capsule on it. You'll understand when it opens.   ║
║                                                              ║
║  4. The real architecture diagram is in /docs/actual.png,    ║
║     not /docs/architecture.png (which is from 2023).         ║
║                                                              ║
║  Good luck. You're going to love it here.                    ║
║  — The team, June 2025                                       ║
╚══════════════════════════════════════════════════════════════╝

The Warning Capsule

Triggered when someone modifies a specific dangerous file

╔══════════════════════════════════════════════════════════════╗
║  ⏳ TIME CAPSULE OPENED!                                     ║
║  Buried by: @sarah on 2025-09-22                            ║
║  Trigger: src/payments/reconciliation.ts was modified        ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║  STOP. Read this before you change anything.                 ║
║                                                              ║
║  This file handles payment reconciliation with Stripe.       ║
║  It looks simple. It is NOT simple. Here's what you need     ║
║  to know:                                                    ║
║                                                              ║
║  - The 3-second delay on line 47 is NOT arbitrary.           ║
║    Stripe's webhook delivery has a race condition.            ║
║    Without the delay, 1 in ~500 payments double-charges.     ║
║    We learned this the hard way. Ticket: INC-2847.           ║
║                                                              ║
║  - The `Math.round()` on line 63 MUST stay.                  ║
║    Floating point + currency = disaster. We lost $12,847     ║
║    over 3 weeks before we found this. Ticket: INC-3012.      ║
║                                                              ║
║  - If you need to test this, use the Stripe sandbox with     ║
║    the webhook replay tool. Do NOT test with real charges.    ║
║    (Yes, someone did. No, we don't talk about it.)           ║
║                                                              ║
║  If you're refactoring: keep all three invariants above.     ║
║  If you're fixing a bug: check INC-2847 and INC-3012 first. ║
║                                                              ║
║  — Sarah, the last person who touched this file              ║
╚══════════════════════════════════════════════════════════════╝

The Date Capsule

Triggered on a specific calendar date

╔══════════════════════════════════════════════════════════════╗
║  ⏳ TIME CAPSULE OPENED!                                     ║
║  Buried by: @mike on 2025-11-01                             ║
║  Trigger: Date reached: March 1, 2026                       ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║  Hey team,                                                   ║
║                                                              ║
║  The GeoLocation API license expires on March 31, 2026.     ║
║  Renewal costs $4,800/year. The free alternative (OpenCage)  ║
║  exists but doesn't support batch queries.                   ║
║                                                              ║
║  Decision needed:                                            ║
║  1. Renew the license ($4,800)                               ║
║  2. Migrate to OpenCage (est. 3 dev-days)                    ║
║  3. Build our own geocoding cache (est. 2 dev-weeks)         ║
║                                                              ║
║  I buried this 4 months early so you have time to decide.    ║
║  Don't let it expire accidentally like the SSL cert in 2024. ║
║                                                              ║
║  — Mike                                                      ║
╚══════════════════════════════════════════════════════════════╝

The Threshold Capsule

Triggered when a code metric crosses a threshold

╔══════════════════════════════════════════════════════════════╗
║  ⏳ TIME CAPSULE OPENED!                                     ║
║  Buried by: @jcooley on 2025-08-10                          ║
║  Trigger: src/checkout/ test coverage dropped below 80%      ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║  Coverage dropped below 80%. I knew this day would come.     ║
║                                                              ║
║  When I wrote the checkout tests in August 2025, coverage    ║
║  was 94%. I'm writing this capsule because I know that       ║
║  deadline pressure will slowly erode it. Here's the deal:    ║
║                                                              ║
║  The untested code paths are where the money bugs hide.      ║
║  Specifically: multi-currency, discount stacking, and        ║
║  partial refunds. If coverage dropped, it's probably         ║
║  because someone added a feature without adding tests.       ║
║                                                              ║
║  Recovery plan:                                              ║
║  1. Run: npm test -- --coverage checkout/                    ║
║  2. The red lines are the new code without tests             ║
║  3. Priority: anything touching money gets tests FIRST       ║
║  4. Don't let this drop below 70%. Below 70%, the           ║
║     checkout module becomes unfixable without fear.          ║
║                                                              ║
║  I've buried another capsule at 70%. You don't want to       ║
║  read that one.                                              ║
║                                                              ║
║  — Past You (who had more test coverage and more optimism)   ║
╚══════════════════════════════════════════════════════════════╝

The Dependency Capsule

Triggered when a specific dependency is updated

╔══════════════════════════════════════════════════════════════╗
║  ⏳ TIME CAPSULE OPENED!                                     ║
║  Buried by: @dev_b on 2025-07-20                            ║
║  Trigger: react upgraded past v19                            ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║  You're upgrading React. Brave. Here's the map:             ║
║                                                              ║
║  Known pain points from our codebase:                        ║
║  1. UserDashboard uses a class component with               ║
║     componentWillMount (deprecated). Convert to useEffect.   ║
║  2. We have a custom useRouter hook that wraps React Router. ║
║     Check if the new React version broke the Router API.     ║
║  3. The theme provider in src/ui/theme.tsx uses              ║
║     legacy context API. Must migrate to createContext.       ║
║  4. Our test setup mocks ReactDOM.render(). If React 19+    ║
║     changes the render API, ALL test mocks need updating.    ║
║                                                              ║
║  Estimated effort: 2-3 days if you know about these.        ║
║  Estimated effort: 2-3 WEEKS if you don't.                  ║
║                                                              ║
║  You're welcome.                                             ║
╚══════════════════════════════════════════════════════════════╝

The Achievement Capsule

Triggered when a milestone is reached

╔══════════════════════════════════════════════════════════════╗
║  ⏳ TIME CAPSULE OPENED!                                     ║
║  Buried by: @jcooley on 2025-03-15                          ║
║  Trigger: Repository reached 1,000 commits                  ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║  🎉 1,000 COMMITS! 🎉                                        ║
║                                                              ║
║  When I buried this capsule, we had 247 commits and          ║
║  2 developers. I wasn't sure we'd make it here.              ║
║                                                              ║
║  Whoever opened this: look how far we've come.               ║
║  The early commits were messy. The architecture was wrong.   ║
║  We rewrote auth twice and the database three times.         ║
║  But here we are — 1,000 commits of learning, building,     ║
║  breaking, and fixing.                                       ║
║                                                              ║
║  Take a moment. Then get back to work. There's a capsule    ║
║  at 10,000 and it's going to be even better.                 ║
║                                                              ║
║  — Commit #247                                               ║
╚══════════════════════════════════════════════════════════════╝

Trigger Types

Trigger	Condition	Use Case
File Touch	Specific file is modified	Warn about landmines, explain non-obvious code
Date	Calendar date is reached	License expiry, scheduled reviews, reminders
Threshold	Metric crosses a value	Coverage drop, bug count spike, dependency age
Dependency	Package is updated/removed	Migration guides, known gotchas
New Contributor	First commit from unknown author	Onboarding tips, welcome messages
Milestone	Commit count, tag, release	Celebrations, retrospective notes
Pattern	Specific code pattern appears	"If you're writing another retry loop, see utils/retry.ts"
Absence	No commits for N days	"If nobody's touched this in 6 months, here's what to know..."

Burying a Capsule

╔══════════════════════════════════════════════════════════════╗
║                  ⏳ BURY A TIME CAPSULE                      ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║  TRIGGER: When does this capsule open?                       ║
║  > When someone modifies src/payments/reconciliation.ts      ║
║                                                              ║
║  MESSAGE: What should future developers know?                ║
║  > [Your message here...]                                    ║
║                                                              ║
║  AUTHOR: Who buried this?                                    ║
║  > @sarah                                                    ║
║                                                              ║
║  EXPIRY: When should this capsule be destroyed if not opened?║
║  > Never (default) / After 1 year / After specific date     ║
║                                                              ║
║  ✅ Capsule buried.                                           ║
║  It will open the next time someone modifies                 ║
║  src/payments/reconciliation.ts.                             ║
╚══════════════════════════════════════════════════════════════╝

When to Invoke

• After making a non-obvious decision — bury a capsule explaining WHY for the next person who touches it
• Before leaving a team or project — leave capsules with everything the next person needs to know
• When you discover a landmine — mark it so the next person doesn't step on it
• For scheduled events — license renewals, deprecation deadlines, review dates
• For celebrations — commit milestones, release targets, team achievements
• When writing code you know will be confusing — leave a map for the future explorer

Why It Matters

Comments go stale. Documentation goes unread. Slack messages get buried. Wiki pages get forgotten. But a Time Capsule that opens exactly when someone needs it — triggered by the very action that makes the knowledge relevant — that's institutional memory with a pulse.

It's fun to bury them. It's even more fun to discover them. And the knowledge they carry can save hours, days, or (in the case of the Stripe reconciliation capsule) thousands of dollars.

Zero external dependencies. Zero API calls. Pure event-triggered knowledge delivery.