version: "1.0.0" name: session-open description: > Use when an agent begins a work session on any AI-DLC project. Trigger on /session-open, /session_open, or when an agent is greeted by name with a task intent. Loads project context from the Knowledge Base, identifies agent role, runs environment pre-flight checks, generates a session fingerprint for drift detection, applies decay-aware prioritization, checks for replay anchors, and presents a synthesized session brief to the orchestrator. Works with any KB level (markdown through hosted vector DB) and any project tracker (Linear, Jira, GitHub Issues, etc.). user_invocable: true license: holder: S3 Technology contact: don@s3technology.io terms: Apache-2.0 — see LICENSE at suite root copyright: "Copyright (c) 2026 S3 Technology"

Session Open — AI-DLC Generic

Overview

Session Open is the standard entry point for any agent beginning work on an AI-DLC engagement. It loads project context, identifies the agent's role, runs environment checks, and presents a synthesized brief — so the orchestrator sees a ready agent, not a cold start.

Core principle: No agent works without context. No session begins without a brief.

FCE (FORGE'd Context Engine) enhancements: Session-open now generates a session fingerprint (hash of loaded KB entries), applies decay-aware prioritization (stale entries deprioritized), checks for replay anchors from crashed/interrupted sessions, and loads dependency graph context (what's upstream of the current intent).

Trigger

Activate when any of these appear in the user's message:

• /session-open or /session_open
• An agent greeting with task intent (e.g., "Good morning Codey — let's work on the auth flow")
• "Open a session", "start a session", "load context"

Step 1 — Identify Agent Role

Determine who you are from the greeting or project configuration. The agent roster is project-specific and defined in the project's CLAUDE.md, AGENT_ROSTER.md, or equivalent configuration.

If an agent roster exists in the project: Map the greeting to the correct agent identity (name, role, track, responsibilities).

If no roster exists: Default to a general engineering agent. State your role as "Engineering Agent" and ask the orchestrator to confirm or assign a role.

KB Write Authority: Only the CLI agent (CTO / Codey) has write access to the KB. All other agents produce session context exports at session-close. If you are NOT the CLI agent, note this in your brief: "I export context at session-close. Codey writes to KB."

Output: Agent name, role title, track assignment, and KB authority (writer or exporter).

Step 2 — Extract Intent

Pull the task or topic from the message content after the trigger.

If no intent is detected, set intent to general session.

Step 2.5 — Check for Replay Anchor

Before loading KB context, check if a replay anchor exists from a previous interrupted session.

Look for:

• docs/kb/REPLAY_ANCHOR.md (or the project's equivalent path)
• The most recent internal_kb entry with category session that includes a replay_anchor section

If a replay anchor is found:

1. Read the anchor content (git state, work state, open questions, critical context)
2. Present it to the orchestrator:

⚡ Replay Anchor Found — [date]
 
Previous session was interrupted at: [task/ticket in progress]
Branch: [branch name]
Last commit: [hash — message]
Open questions: [N]
Critical context: [2-3 bullet points]
 
Resume from this anchor, or start fresh?

1. If orchestrator says "resume": Load the anchor as primary context, skip broader KB query (the anchor IS the context). Proceed to Step 4.
2. If orchestrator says "fresh" or the anchor is stale: Discard and proceed normally to Step 3.

If no replay anchor exists: Proceed to Step 3.

Step 3 — Load Project Context from Knowledge Base

The KB level determines how context is loaded. Check the project's configuration to determine which level applies.

Level 1–2: Local Markdown KB

# Find the KB directory (common locations)
# Check project docs for the canonical path
KB_DIR="docs/kb"  # or docs/session_context, or as configured
 
# Load recent session entries by this agent
ls -t "$KB_DIR"/*session* 2>/dev/null | head -3
 
# Load recent decision entries
ls -t "$KB_DIR"/*decision* 2>/dev/null | head -5
 
# Load current context file if it exists
cat "$KB_DIR/CONTEXT.md" 2>/dev/null || echo "No CONTEXT.md found"

Read the most recent session export, the current CONTEXT.md, and any decision log entries relevant to the extracted intent.

Level 3: Static Site KB

Same as Level 1–2 but the KB may be in a content directory (e.g., content/kb/, src/kb/). Check the project's static site config.

Level 4: Hosted Vector DB (Supabase / pgvector / Pinecone)

Query the KB using the project's session-memory-read endpoint or direct DB access:

POST [PROJECT_SESSION_MEMORY_READ_URL]
Authorization: Bearer [PROJECT_SERVICE_ROLE_KEY]
Content-Type: application/json
 
{
  "intent": "<extracted intent>",
  "agent": "<agent name>",
  "max_tokens": 1200
}

Finding credentials:

• Check the project's .env, .env.development, or .env.local for the service role key
• Check CLAUDE.md or ARCHITECTURE.md for the endpoint URL
• Never hardcode credentials — always read from environment files

If no KB endpoint exists and no markdown KB is found: Report this to the orchestrator. A project without a KB is a project without memory. Recommend initializing one per AI-DLC: Full Cycle, Phase 0.

Step 3.4 — Load Agent Learnings and Best Practices

After loading general KB context, query specifically for agent learnings and best practices.

For Level 4 KB (hosted vector DB): Query kb_entries with category filter:

SELECT title, content, category
FROM kb_entries
WHERE active = true
  AND category IN ('best_practice', 'agent_learning')
ORDER BY created_at DESC
LIMIT 20

For Level 1-2 KB (local markdown): Read docs/AIDLC/CodeBestPractices.md and docs/AIDLC/CTOGrowthLog.md directly.

If the extracted intent names specific files or patterns: Also run a semantic query against the best_practice entries to find practices relevant to the files being worked on. Example: if the intent mentions "Edge Functions", the query should surface METHOD_GUARD, GUARD_ACTIONS_BY_METHOD, ALLOWLIST_UPDATE_FIELDS, etc.

Include in the session brief:

**Agent Learnings Loaded**
Best practices: [N] validated | Agent learnings: [N] emerging
Applicable to this intent: [list of pattern tags, if any match]

Step 3.5 — Decay-Aware Prioritization (FCE Enhancement)

After loading KB entries, apply decay-aware scoring to prioritize results.

Each KB entry has a decay classification (assigned at session-close):

How to apply:

For Level 4 KB: Adjust the similarity score by decay factor before ranking:

effective_score = similarity * decay_factor(entry.decay, entry.created_at)
 
where decay_factor:
  permanent → 1.0 (always)
  long → 1.0 if < 90 days, then linear decay to 0.5 at 180 days
  medium → 1.0 if < 30 days, then linear decay to 0.5 at 90 days
  short → 1.0 if < 7 days, then linear decay to 0.3 at 30 days

For Level 1-2 KB: Prioritize by file modification date, but always include entries tagged permanent regardless of age.

Entries that fall below the similarity threshold after decay adjustment are still loaded but tagged as `[POSSIBLY STALE]` in the brief. The orchestrator decides whether to trust them.

If a loaded entry has no decay tag (legacy entry): Default to medium decay.

Step 3.6 — Session Fingerprint Generation (FCE Enhancement)

After loading KB entries, generate a session fingerprint.

The fingerprint is a hash of the KB entry IDs that were loaded into this session's context. It serves as a baseline for drift detection at session-close.

fingerprint = hash([entry_1.id, entry_2.id, ..., entry_N.id])

Store this fingerprint in session state (memory, temp file, or environment variable). Session-close compares what was loaded against what was produced to detect silent drift.

Also record the full list of loaded entry IDs — the fingerprint is for quick comparison, but the full list is needed for dependency tracking at session-close.

Step 3.7 — Dependency Graph Context (FCE Enhancement)

For Level 4 KB: Query the dependency graph for entries upstream of the current intent.

If the project tracks KB dependencies (the consumed/produced chain from session-close), query for:

1. Direct dependencies — KB entries that previous sessions consumed to make decisions related to the current intent
2. Recently superseded entries — Entries that were replaced in the last 2 sessions (the agent should know what changed)

Present any dependency chain insights in the session brief:

**Context Chain**
This intent builds on decisions from:
- [KB entry title] (session [date], by [agent]) — [1-line summary]
- [KB entry title] (session [date], by [agent]) — [1-line summary]
 
Recently superseded (may affect your work):
- [Old entry] was replaced by [New entry] on [date]

If no dependency graph exists (Level 1-2 or early project): Skip this step.

Step 4 — Load Reference Documents

After loading KB context, ingest the project's living documents. These are the authoritative source of truth:

Always load if they exist:

• CLAUDE.md — agent operating rules and project conventions
• CONTEXT.md — current project state
• ARCHITECTURE.md — system structure

Load if relevant to intent:

• DECISION_LOG.md — if intent involves architectural or product decisions
• RISK_REGISTER.md — if intent involves risk-adjacent work
• SCOPE_BOUNDARY.md — if intent involves new features or scope questions

Check locations: Project root, docs/, docs/kb/, or as configured in the project.

Step 4.5 — AIDLC Touchchain Detection

Before running pre-flight checks, detect whether this project is running under the AIDLC touchchain suite. If so, the kickoff/project-touchchain Resume Router is the authoritative way to open the session — not the generic brief below.

Detection signals (any ONE triggers touchchain mode):

• ProjectState.md exists in project root
• kickoff-ledger.md exists in project root
• handoff/*.md directory with cards matching the hand-off card schema
• CLAUDE.md contains the string aidlc-kickoff-touchchain

If detected:

1. Read ProjectState.md to identify current mode:

• current_epic: <slug> + open tickets → MID-EPIC → hand off to

aidlc-project-touchchain

• current_epic: null + epics remaining → BETWEEN-EPICS → hand

off to aidlc-kickoff-touchchain Resume Router

• current_epic: null + no epics remaining → PROJECT-COMPLETE →

emit closing summary, do not advance

1. Load kickoff-ledger.md to get the last RDAI decisions (most recent

10 entries) as additional context

1. Load the most recent handoff/<epic>-handoff-card.md if present
2. Hand off to the appropriate touchchain skill by invoking:

• /aidlc-kickoff-touchchain (BETWEEN-EPICS / PROJECT-COMPLETE)
• /aidlc-project-touchchain (MID-EPIC) — also read the

active_handoff_card field to find the current epic's card

1. Skip the generic session brief in Step 6. The touchchain skill

produces its own brief and drives the next action.

If NOT detected: proceed to Step 5 normally.

Step 5 — Run Environment Pre-Flight

Run project-appropriate pre-flight checks. The checks depend on the project's stack.

Detect the stack and run the appropriate checks:

Pre-flight is informational, not blocking. If tests fail, report the failure count and let the orchestrator decide whether to proceed or fix first.

Step 6 — Synthesize and Present Session Brief

Combine all loaded context into a structured brief. Do not dump raw KB entries — synthesize.

Session open. Context loaded.
 
**I'm [Agent Name], [Role Title] — [Track]**
**KB Authority:** [Writer (CLI agents) | Exporter (Desktop agents)]
 
My role:
- [2-4 responsibilities, agent-specific]
- Session opens with /session-open | Session closes with /session-close
 
I report to **[Orchestrator Name]** (Founder/Project Engineer).
 
**Session Context**
Project: [project name]
Intent: [extracted intent]
KB level: [1-4]
Facts/entries loaded: [N] ([N] permanent, [N] fresh, [N] possibly stale)
Session fingerprint: [short hash]
Current phase: [N — if available from KB]
 
**Project State**
[2-3 sentences synthesized from CONTEXT.md and recent KB entries]
 
**Recent Decisions**
[Any decision entries relevant to intent — or "None loaded"]
[Mark any that are POSSIBLY STALE based on decay scoring]
 
**Context Chain** (if dependency graph available)
[Upstream decisions that inform current intent]
[Recently superseded entries that may affect work]
 
**Active Risks**
[Any open risk entries — or "None loaded"]
 
**My Last Session**
[Summary from most recent session entry by this agent — or "No prior session found"]
 
**Pre-Flight**
[Test baseline or stack health — e.g., "142 tests passing, 0 analyzer issues"]
 
What's the task?

What NOT to Do at Session Open

• Do not start working without presenting the brief. The orchestrator needs to see what you loaded.
• Do not assume context from a previous conversation. Load it from the KB or report that you couldn't.
• Do not skip pre-flight. Even if you think the codebase is clean — verify.
• Do not fabricate context. If the KB is empty or inaccessible, say so. An honest "no context loaded" is better than a hallucinated summary.
• Do not trust stale entries without flagging them. If decay scoring marks an entry as possibly stale, tell the orchestrator.
• Do not skip the replay anchor check. A crashed session's context is the most valuable thing to recover.
• Do not skip fingerprint generation. Without it, session-close can't detect drift.

Reference Documents

Supporting Files in This Skill

AI-DLC Skills Referenced

This skill implements the session open protocol defined in:

• AI-DLC: Full Cycle → "KB Memory Model — RAG+" → "Standard Session Open Query"
• AI-DLC: Full Cycle → "The Knowledge Base — Initialized First, Lives Forever"
• AI-DLC: Full Cycle → "FCE Opt-Out" → Project-level KB level acknowledgement
• AI-DLC: Agent Team → Agent role definitions and track assignments
• AI-DLC: Execution Agent → Scope boundaries and initialization protocol

For KB schema, entry format, and RAG+ retrieval stack details, see aidlc-full-cycle skill.