Rename get-branch-context to get-session-context and add artifact_base_dir

[williamthorsen]

Rename get-branch-context to get-session-context and add artifact_base_dir

Problem

16 skills inline their own artifacts.base_dir resolution logic (read .agents/preferences.yaml → fall back to ~/.agents/preferences.yaml → default ~/.ai, expand ~, resolve relative paths). This duplication leads to agents skipping steps and writing artifacts to the wrong directory — exactly what happened in the node-monorepo-tools #30 review, where the agent used ~/.ai instead of the configured ~/repos/vaults/code-artifacts.

Context

• get-branch-context already reads preferences.yaml once and caches project_slug, default_branch, ticket_id, and branch_name in a branch manifest file. Adding artifact_base_dir is a natural extension — same file read, one extra field, cached on the same hit path.
• The name "branch context" doesn't reflect the skill's actual role as the general-purpose "read preferences once, cache everything" utility. Renaming to get-session-context makes the scope explicit.
• The skill maintains a zero-Bash contract (Read and Write tools only), which must be preserved. ~ expansion uses the home directory from the system prompt; relative path resolution uses the working directory from the system prompt. The manifest stores the resolved absolute path, so downstream consumers never need Bash.
• get-project-slug and get-default-branch remain as lightweight alternatives for callers that don't need the full manifest.

Solution

1. Rename get-branch-context → get-session-context

Rename the skill directory, update the SKILL.md name/description, and update all call sites across the skill corpus.

2. Extend the manifest schema

Add two fields to the branch manifest:

Field	Source	Description
artifact_base_dir	artifacts.base_dir from preferences, resolved to absolute	Base directory for all AI-generated artifacts
artifact_paths	artifacts.paths.* from preferences	Category suffixes (chats, devlogs, plans) with defaults

The derivation step resolves artifact_base_dir to an absolute path (expanding ~, resolving relative paths against the working directory) so consumers can use it directly without any resolution logic.

artifact_paths stores relative suffixes (e.g., "chats", "devlogs", "plans"), not resolved absolute paths. Consumers assemble full paths as {artifact_base_dir}/projects/{project_slug}/{category_suffix}/. This keeps paths flexible for cross-repo artifact saving.

3. Update consuming skills

Replace inline artifacts.base_dir resolution in ~16 skills with "invoke get-session-context and read artifact_base_dir from the result." This is largely find-and-replace: each skill's saving/path-resolution section shrinks to a single reference.

4. Update artifact-conventions.md

Update the path resolution algorithm in _data/artifact-conventions.md to reference get-session-context as the canonical resolution method.

Acceptance criteria

• get-branch-context skill directory renamed to get-session-context
• Manifest schema includes artifact_base_dir (resolved absolute path) and artifact_paths (relative category suffixes)
• Zero-Bash contract preserved — derivation uses only Read and Write tools
• All skills that previously inlined artifacts.base_dir resolution now reference get-session-context
• get-project-slug and get-default-branch remain functional as standalone skills
• artifact-conventions.md updated to reference get-session-context
• Backward compatibility: old .branch-manifest.json files without the new fields trigger re-derivation (or graceful fallback)
• Manifest file extension unchanged (.branch-manifest.json)

[williamthorsen]

Insights from orchestrated run 20260317-095858Z

I1: artifact-conventions.md retains two ~/.ai references — distinct concepts.
The stated base_dir default (line 7) and the export-ai-artifacts.sh export destination (line 56) are separate concerns. The export destination is a hardcoded target for the export script, not an artifact resolution path. The plan required "at most once as the stated default value" — the second reference is correctly preserved as a different concept.

I2: orchestrate/SKILL.md init_run MCP parameter description left unchanged — divergence risk.
The init_run MCP parameter description documents the MCP server's own autonomous base_dir resolution. It was correctly left unchanged because the skill does not control the server's behavior. However, this creates a known divergence risk: if the MCP server's resolution logic drifts from the skill's get-session-context resolution, artifacts could land in different directories depending on the entry point (MCP vs. fallback).