temper-vault

name

temper-vault

description

Work with temper-compatible knowledge vaults — markdown files with YAML frontmatter organized into sessions, tickets, milestones, concepts, and research notes by project. Use this skill whenever the user mentions a knowledge vault, knowledge base, temper vault, session notes, ticket management, milestone roadmapping, epic planning, or wants to organize development work using markdown-based project tracking. Also trigger when the user references vault primitives (tickets, milestones, sessions, concepts, sources) or asks about scope-based workflow routing (patch/feature/epic). This skill does NOT require the temper CLI — it works directly with the vault's file structure and frontmatter conventions.

Temper Vault — Knowledge Base Workflow

This skill teaches you how to work with a temper-compatible knowledge vault: a directory of markdown files with YAML frontmatter, organized by project, that tracks development work through sessions, tickets, milestones, concepts, and research notes.

The vault is the source of truth for strategic context. You read and write markdown files directly — no CLI or database required. Everything is human-readable, version-controllable, and portable.

Cloud access: If a Temper MCP server is configured, you can also access the knowledge base through MCP resources and tools instead of (or alongside) local file access. The MCP server supports both reading and writing — use create_resource with a content field to create resources with full content, and search for text-based discovery. See knowledge-base.md for MCP access patterns and claude-desktop.md for Claude Desktop setup.

Post-cloud-only: Temper is now cloud-only — the server is authoritative. The local vault directory is a read-only projection cache materialized on demand via temper pull <context>; it is no longer the source of truth. All writes route through the cloud API (temper resource create/update). Removing a projected file with rm has no server effect — it's just a local cache miss that temper pull re-materializes. To actually delete a resource, use temper resource delete.

Important distinction: The vault holds the strategic layer — milestones, tickets, sessions, concepts. Design specs, implementation plans, and code live in the project repositories themselves (often under docs/superpowers/specs/ and docs/superpowers/plans/). The vault tracks what work exists, why it matters, and what happened. The project repo tracks how it gets built.

Finding the Vault

The vault root contains a temper.toml configuration file. To locate it:

1. If the user tells you where it is, use that path
2. Look for temper.toml in the current working directory or its parents
3. Check common locations: ~/projects/knowledge, ~/knowledge, ~/vault

Read temper.toml to understand which projects are configured, what directories to use, and how the vault is organized. The [projects.*] sections define the project names and paths you'll work with.

Default directory layout (these are configurable in temper.toml under [vault]):

vault-root/
├── temper.toml        — vault configuration
├── sessions/          — session notes, organized by project
│   ├── {project}/
│   └── general/       — cross-project sessions
├── tickets/           — tickets, organized by project
│   └── {project}/
├── milestones/        — milestone definitions, organized by project
│   └── {project}/
├── concepts/          — concept notes (cross-project ideas and threads)
├── sources/           — source index stubs pointing to documents elsewhere
├── templates/         — note templates
├── docs/              — design documents and plans
└── .temper/           — index artifacts (managed by temper CLI, don't edit)

Vault Primitives

Each primitive is a markdown file with YAML frontmatter. The type field identifies what kind of note it is. Read references/frontmatter.md for the complete field reference.

Tickets

Tickets are units of work. They live in tickets/{project}/ and track through four stages: backlog → in-progress → done (or cancelled).

Filename convention: {date}-{slug}.md where date is YYYY-MM-DD and slug is the kebab-cased title. Example: 2026-03-24-ground-state-data-quality.md

Scope controls the workflow applied to a ticket:

Scope	Nature	What happens
patch	Tactical fix	Implement directly, no ceremony
feature	Deliberate build	Design → plan → implement
epic	Strategic planning	Map problem space → milestone roadmap → first ticket

When scope is missing, ask the user: "Does this feel like a patch, feature, or epic?"

Milestones

Milestones group tickets into strategic chunks. They live in milestones/{project}/ and have a status field: active, completed, or paused.

A good milestone explains why it exists, what it enables, and how it sequences work. See the Epic Workflow section for how milestones are created.

Sessions

Session notes capture what happened during a working session. They live in sessions/{project}/ (or sessions/general/ for cross-project work).

Filename convention: {date} — {title}.md

Session notes follow a standard structure (Goal, What happened, Decisions, What connected, To pick up) that creates a narrative thread across working sessions. They are curated observations, not raw logs — write them as if a future version of yourself will read them to pick up where you left off.

Concepts

Concept notes capture ideas and threads that span projects. They live in concepts/ and track where a concept appears, how it manifests, and what open questions remain.

Research

Research notes are high-fidelity investigations into a specific question. They capture findings, sources, implications, and open questions.

Sources

Source index stubs that point to documents in other repositories. Lightweight pointers with tags for cross-referencing.

Epic Workflow — The Primary Focus

Epics are strategic. The output is a milestone roadmap, not delivered code. Each subsequent session works one ticket from the roadmap, learns, evolves the roadmap, and creates the next ticket.

Starting an Epic

When a ticket has scope epic (or the user describes strategic/exploratory work):

1. Read the ticket — understand what problem space to map
2. Discovery — read related sessions, milestones, concepts, and source code to build a picture of the landscape. Favor vault content over assumptions.
3. Map the problem space — identify the key dimensions, constraints, dependencies, unknowns, and competing concerns. This is brainstorming, not implementation design.
4. Produce a milestone roadmap — create a milestone file that includes:
   • A throughline summary (why this work matters, what it enables)
   • Sequenced deliverable chunks with clear boundaries
   • Validation gates between phases
   • Dependencies and prerequisites
   • Open questions that will resolve through doing the work
5. Create the FIRST actionable ticket — scoped as patch or feature, linked to the milestone, concrete enough to start immediately
6. Save a session note — capture the discovery, decisions, and what to pick up next

The Epic Philosophy

The roadmap guides session work, not ticket-spread. Don't create 15 tickets upfront. Create ONE ticket — the next thing to do. After completing it, learn from the experience, evolve the roadmap if needed, and create the next ticket. This prevents premature decomposition and lets the roadmap breathe.

Milestones are living documents. As sessions reveal new information, update the milestone: refine the sequencing, resolve open questions, add newly discovered constraints. The roadmap should reflect your current understanding, not your initial guess.

What a Good Milestone Looks Like

A milestone born from an epic workflow has these characteristics:

• Narrative motivation — not just "what to build" but "why this gap exists now and what makes it legible." Often a milestone becomes necessary because previous work succeeded in ways that exposed a new layer of complexity.
• Scope boundaries — explicit prerequisites (what must be done first), the work itself (sequenced chunks), and what it enables downstream.
• Design questions — the hard questions that the work will answer. These aren't blockers; they're the intellectual terrain the milestone maps.
• Relationship context — what other milestones/tiers this depends on or enables.

For example, a milestone might explain: "Tier B produced a grammar of narrative — archetypes, dynamics, state variables across 30 genres. But grammar without vocabulary produces aesthetically coherent yet narratively hollow output. This milestone bridges that gap by designing world-building data structures and generating test worlds."

That framing tells a future session why it's doing this work, not just what files to edit.

Epic Session Rhythm

Each session working under an epic milestone follows a rhythm:

1. Read the milestone and the current ticket
2. Do the work (the ticket is scoped as patch or feature)
3. Capture what you learned — especially surprises, revised assumptions, new constraints
4. Update the milestone if what you learned changes the plan
5. Create the next ticket (or mark the milestone complete if you're done)
6. Save the session note with specifics

Mid-Session Drift Detection

Watch for scope mismatch during a session:

• Patch drifting up: needs design decisions, touches 3+ files, considering multiple approaches → suggest promoting to feature
• Feature drifting up: needs decomposition into multiple deliverables, spans multiple sessions → suggest promoting to epic
• Epic drifting down: first ticket is obvious, roadmap has only 1-2 items → suggest feature or just start working

Writing Vault Files

When creating or updating vault files, follow these conventions:

Frontmatter

Read references/frontmatter.md for exact field schemas. Key rules:

• IDs: Use UUIDv7 format (time-ordered). Generate with appropriate tooling or use a placeholder like {{id}} if generation isn't available.
• Dates: ISO 8601. created uses full datetime with timezone for tickets, date-only for milestones and sessions. updated tracks the last modification.
• Slugs: Derived from the title — lowercase, kebab-case, no special characters. Ticket slugs are prefixed with the creation date: 2026-03-24-my-ticket-title.
• Strings with colons or special chars: Always quote in YAML frontmatter.

Content Quality

Session notes, milestone descriptions, and ticket bodies should be written with care. These aren't throwaway notes — they're the institutional memory of the project.

• Sessions: Write as curated narrative, not raw transcript. Future sessions will read these to pick up context. Include specific details: file paths, function names, data counts, branch names, number of commits, test results. A session that says "Fixed the loader" is far less useful than one that says "Added _is_valid_value() sentinel check to loader.py, eliminating 22 entities with 'null' string slugs. Result: 0 sentinel slugs in DB." The specificity is what makes these useful across sessions.
• Sessions — "What connected": This section captures cross-project patterns and insights. Use [[wiki-link]] syntax to reference concepts. This is where the knowledge graph grows — don't skip it even when the session was heads-down implementation.
• Sessions — "To pick up": Make these concrete and actionable, not vague aspirations. "LLM trope family classification — use Ollama structured generation to classify the 108 unclassified tropes into canonical families" is actionable. "Continue working on data quality" is not.
• Milestones: Explain the why before the what. A milestone that says "Implement auth" is less useful than one that explains why auth is needed now, what it enables, and how it fits into the larger arc.
• Tickets: Include enough context that someone (or a future AI session) starting cold can understand what to do and why. For non-trivial tickets, include: a summary, the specific issues or requirements, proposed approaches (with tradeoffs), scope boundaries, and links to related sessions and files.

Linking

Use [[wiki-link]] syntax for cross-references between vault notes. These are compatible with Obsidian and create a navigable knowledge graph.

Session Lifecycle

Starting a Session

When beginning work:

1. Read recent session notes for the relevant project (sessions/{project}/)
2. Check for in-progress tickets (tickets/{project}/ where stage: in-progress)
3. Review the relevant milestone if one exists
4. Orient before acting — understand where the work left off

During a Session

• Track decisions and their rationale as you go
• Notice connections to other concepts or projects
• If scope drift occurs, flag it rather than silently absorbing complexity

Ending a Session

Create a session note following the template structure (Goal, What happened, Decisions, What connected, To pick up). The template is a floor, not a ceiling — add sections like Observations for unexpected findings or pattern recognition that doesn't fit neatly into the standard structure.

If the session was working a ticket, update the ticket's frontmatter:

• Set stage to the new state (done, or keep in-progress if continuing)
• Update the updated timestamp
• Add branch and pr if applicable

Customization

Vault Location

Set the vault path in your workflow. The skill looks for temper.toml to identify the root.

Adding Projects

Add project entries to temper.toml:

[projects.myapp]
repo = "org/myapp"
path = "~/projects/myapp"

Custom Templates

Place custom templates in the vault's templates/ directory. The skill uses whatever templates it finds there. At minimum you want: ticket.md, milestone.md, session.md.

Adapting the Workflow

The scope routing (patch/feature/epic) is a framework, not a cage. If a project doesn't need the ceremony of scope-based routing, just use tickets and sessions directly. The vault structure works regardless of how much process you layer on top.