session-artifacts

Lightweight session memory for AI-assisted development. Automatically persist structured, timestamped artifacts during long coding sessions — reducing token usage, preventing context drift, and making AI-assisted development reproducible across tools and sessions.

---

Why This Skill Exists

Long AI coding sessions lose context. Plans get re-generated. Architecture decisions get forgotten. Token budgets balloon.

session-artifacts solves this by giving the agent a local, structured memory layer — a set of small, well-defined Markdown files written into your project as the session progresses. On the next session, the agent reads these instead of reasoning from scratch.

Benefits:

• 🧠 No context drift — prior decisions are always readable from disk
• 💸 Fewer tokens — no re-generating plans or architecture docs that already exist
• 🔁 Reproducible sessions — any agent, any tool can pick up where the last one left off
• 📋 Audit trail — every build, refactor, and architectural decision is logged

---

Quick Start

Activate for a Session

Tell the agent to use this skill at the start of any substantial session:

Use the session-artifacts skill for this session.

Or reference it directly:

@session-artifacts — start a new session for the auth module refactor.

The agent will:

1. Create artifacts/<YYYY-MM-DD>/<session-slug>/
2. Write metadata.json (status: active)
3. Write 01-summary.md (scope + goals)

Resume a Session

At the start of a follow-up session on the same task:

Resume the session-artifacts session from today's auth-refactor work.

The agent will scan artifacts/ for a matching prior session and load it instead of starting fresh.

---

Directory Layout

<project-root>/
└── artifacts/
    └── YYYY-MM-DD/
        └── <session-slug>/
            ├── metadata.json            ← machine-readable session index
            ├── 01-summary.md            ← scope, decisions, outcome
            ├── 02-implementation-plan.md
            ├── 03-workflow.md
            ├── 04-architecture.md
            ├── 05-build-report.md
            ├── 06-improvements.md
            ├── 07-refactoring-notes.md
            ├── 08-task-breakdown.md
            └── 09-agent-reasoning.md

Session slug — lowercase, hyphen-separated, max 32 chars, derived from the task:

• ✅ native-bootstrap, jni-refactor, compose-ui-build
• ❌ session1, work, my-project-stuff

If a slug for that date already exists, append -v2.

---

Artifact Reference

#	File	Written When	Contains
—	metadata.json	Session start	Project, date, slug, agent, task, status
01	01-summary.md	Session start & end	Scope, key decisions, outcome, next steps
02	02-implementation-plan.md	Before multi-file edits	Goals, components, file list, rollback
03	03-workflow.md	After task completion	Ordered steps, commands run, outcomes
04	04-architecture.md	On structural decisions	Module layout, boundaries, naming rules
05	05-build-report.md	After each build cycle	Command, exit code, errors or success
06	06-improvements.md	On drift / inefficiency	Patterns, mistakes, refinement suggestions
07	07-refactoring-notes.md	Before touching stable code	What changes, why, rollback path
08	08-task-breakdown.md	Multi-step tasks	Checkbox list; updated in-place
09	09-agent-reasoning.md	Non-obvious agent choices	Decision, alternatives, rationale

Write only the artifacts that apply. Skip types that aren't relevant to the current session.

---

Session Lifecycle

Session Start
  ├─ Create artifacts/<date>/<slug>/
  ├─ Write metadata.json           (status: "active")
  └─ Write 01-summary.md           (scope + goals)

During Session
  ├─ Write 02-implementation-plan.md   BEFORE multi-file edits
  ├─ Write 04-architecture.md          WHEN structural decisions are made
  ├─ Write 07-refactoring-notes.md     BEFORE touching stable files
  ├─ Append to 05-build-report.md      AFTER each build attempt
  ├─ Update 08-task-breakdown.md       AS tasks complete
  └─ Append to 06-improvements.md      WHEN drift or inefficiency is detected

Session End
  ├─ Finalize 01-summary.md        (outcome + final status)
  ├─ Write 03-workflow.md          (ordered step log)
  └─ Update metadata.json          (status: "complete")

---

Core Rules

1. Write before large operations — persist state before refactors, architecture changes, or multi-file edits.
2. Never overwrite — artifacts are append-only. Create new files; never modify completed session documents.
3. Incremental only — write the smallest useful artifact. Avoid verbose logs or full file dumps.
4. Reuse first — always scan artifacts/ for prior context before regenerating plans or decisions.
5. Deterministic naming — use the numbering + slug format above. Do not invent new conventions.
6. Markdown by default — all artifacts are .md; only metadata.json uses JSON.

---

Reuse Protocol

At the start of any new session, the agent will:

1. Check if artifacts/<today>/ exists
2. Scan metadata.json files for sessions with matching task scope
3. Read 01-summary.md and 04-architecture.md from the closest prior session
4. Incorporate those decisions — not regenerate content already captured

This is the primary mechanism for reducing token usage and context drift across sessions.

---

Templates

Pre-built templates for every artifact type live in templates/. The agent reads and fills these automatically.

Template	Purpose
metadata.json	Session index with status tracking
summary.md	Scope, decisions, outcome, next steps
implementation-plan.md	Goals, in-scope/out-of-scope, file list, verification
workflow.md	Ordered log of steps and commands
architecture.md	Module layout, boundary rules, naming conventions
build-report.md	Commands, exit codes, errors
improvements.md	Drift patterns, mistakes, refinement suggestions
refactoring-notes.md	What is changing, why, rollback path
task-breakdown.md	Checkbox task list
agent-reasoning.md	Decision log with alternatives and rationale

---

Anti-Patterns

Warning

Do NOT dump full file contents into artifacts — reference file paths instead.

Do NOT log every tool call in build reports — record only commands, exit codes, and key errors.

Do NOT create a new session slug when resuming work on the same task on the same day.

Do NOT write artifacts for trivial actions (formatting fixes, comment additions, single-line changes).

Do NOT regenerate plans or architecture docs if a valid artifact already exists for the current task.

---

Skill Location

C:\Users\<you>\.gemini\config\skills\session-artifacts\
├── SKILL.md       ← agent instruction protocol
├── README.md      ← this file
└── templates/     ← one template per artifact type

---

When to Use This Skill

Scenario	Use It?
Multi-file refactor spanning >1 session	✅ Yes
Building a new feature with architecture decisions	✅ Yes
Long debug session with multiple build attempts	✅ Yes
Quick single-file fix or formatting change	❌ No
Adding a comment or renaming a variable	❌ No