#319 Rename get-branch-context to get-session-context and centralize artifact resolution

packages/agents/content/skills/_data/artifact-conventions.md

@@ -4,7 +4,7 @@ Standards for AI-generated artifact storage, naming, and lifecycle.
 
 ## Directory structure
 
-All artifacts live under a configurable base directory (`base_dir`, default `~/.ai`):
+All artifacts live under a configurable base directory (`base_dir`, default `~/.ai`). Use `get-session-context` to resolve `artifact_base_dir`:
 
 ```
 {base_dir}/
@@ -26,7 +26,7 @@ All artifacts live under a configurable base directory (`base_dir`, default `~/.
 
 ### Project slug
 
-Always present under `projects/`, even when `.ai/` is inside the project. Constant structure enables simple directory sync for export (`.ai/projects/` ↔ `~/.ai/projects/`). Use `get-project-slug` to obtain.
+Always present under `projects/`, even when `{base_dir}/` is inside the project. Constant structure enables simple directory sync for export. Use `get-session-context` to obtain `project_slug`.
 
 ### Ticket ID
 
@@ -57,13 +57,15 @@ Artifacts under `{base_dir}/` are ephemeral when `base_dir` is a git-ignored pat
 
 ## Path resolution
 
-Skills resolve artifact directories using this algorithm:
+Skills resolve artifact directories by invoking `get-session-context` and reading `artifact_base_dir` and `project_slug` from the manifest. This is the canonical method for all artifact path resolution.
+
+For contexts where the manifest is unavailable (e.g., standalone scripts without skill access), the manual fallback is:
 
 1. Read `artifacts.base_dir` from `.agents/preferences.yaml`
 2. If not found there, read from `~/.agents/preferences.yaml`
-3. If still not found, use default: `base_dir` = `~/.ai`
-4. If `base_dir` is relative, resolve from project root (`git rev-parse --show-toplevel`). If absolute, use as-is.
-5. Use `get-project-slug` for the project slug.
+3. If still not found, use the default base directory
+4. If `base_dir` is relative, resolve from project root. If absolute, use as-is.
+5. Read `project.slug` from `.agents/preferences.yaml`, falling back to `~/.agents/preferences.yaml`, then the bare directory name of the working directory.
 
 ### Ticket-scoped paths
 
@@ -120,7 +122,7 @@ Artifact ordering is explicit via the sequence number. Timing is captured in the
 Example run directory (full orchestrated run with iterative review):
 
 ```
-.ai/projects/williamthorsen-configs-macos/tickets/MAC-68/20260221-034100Z-orchestrated/
+{base_dir}/projects/williamthorsen-configs-macos/tickets/MAC-68/20260221-034100Z-orchestrated/
   run-index.json
   01_orchestrator_run-manifest.md                       # initialization
   02_orchestrator_ticket-requirements.md                # initialization (optional)
@@ -676,10 +678,10 @@ Used by review-producing skills and agents for structured code review findings.
 
 Every level degrades gracefully:
 
-- Missing project `.agents/preferences.yaml` → fall back to global `~/.agents/preferences.yaml`
-- Missing global preferences → fall back to hardcoded default (`~/.ai`)
-- Missing `~/.ai/` directory → created automatically on first artifact save
-- Missing `get-project-slug` result → derive from git remote or directory name
+- Missing project `.agents/preferences.yaml` -> fall back to global `~/.agents/preferences.yaml`
+- Missing global preferences -> fall back to the default base directory
+- Missing `{base_dir}/` directory -> created automatically on first artifact save
+- Missing `project.slug` in preferences -> use the bare directory name of the working directory
 
 ## Migration from status.json (v1) to run-index.json (v2)
 

packages/agents/content/skills/_data/branch-format.md

@@ -30,5 +30,5 @@ Old-format branch names like `MAC-123/agents/feat/add-orchestrator` still parse
 
 ## Related skills
 
-- `get-branch-context` — Parses the branch name and caches all derived metadata (ticket ID, branch name, and other metadata) in a manifest file for single-lookup access. Preferred over individual skills when multiple metadata fields are needed.
+- `get-session-context` — Parses the branch name and caches all derived metadata (ticket ID, branch name, artifact paths, and other metadata) in a manifest file for single-lookup access. Preferred over individual skills when multiple metadata fields are needed.
 - `get-ticket-id` — Extracts the ticket ID segment.

packages/agents/content/skills/condense-branch/SKILL.md

@@ -24,10 +24,10 @@ If branch exists, increment version number.
 
 4. **Condense commits**:
 
-   Use `get-default-branch` to resolve `{default-branch}`.
+   Use `get-session-context` to obtain `default_branch`.
 
    ```bash
-   git reset --soft $(git merge-base {default-branch} HEAD)
+   git reset --soft $(git merge-base {default_branch} HEAD)
    git add --all
    git commit --message "{title}" --message "{body}" --no-gpg-sign --no-verify
    ```

packages/agents/content/skills/create-devlog/SKILL.md

@@ -48,14 +48,9 @@ Summarize changes made in recent commits or the working tree.
 
 ## Saving
 
-Resolve artifact directory:
-
-1. Read `artifacts.base_dir` and `artifacts.paths.devlogs` from `.agents/preferences.yaml`
-2. If not found there, read from `~/.agents/preferences.yaml`
-3. If still not found, use defaults: base_dir=`.ai`, path=`devlogs`
-4. If base_dir is relative, resolve from project root (`git rev-parse --show-toplevel`). If absolute, use as-is.
-5. Use `get-project-slug` for the project slug.
-6. Full path: `{base_dir}/projects/{project-slug}/{path}/`
+Resolve artifact directory using `get-session-context` to obtain `artifact_base_dir`, `project_slug`, and `artifact_paths`. The devlogs path is `artifact_paths.devlogs` (default: `devlogs`).
+
+Full path: `{artifact_base_dir}/projects/{project_slug}/{devlogs_path}/`
 
 Follow [artifact conventions](_data/artifact-conventions.md).
 

packages/agents/content/skills/create-pr/SKILL.md

@@ -11,19 +11,19 @@ Create a pull request using the GitHub CLI and existing PR description.
 ## Process
 
 1. **Find PR description file**:
-   - Use `get-ticket-id` and `get-project-slug`
-   - Look for most recently modified `*_change-summary.md` in `.ai/projects/{project-slug}/tickets/{ticket-id}/`
+   - Use `get-session-context` to obtain `ticket_id`, `project_slug`, `artifact_base_dir`, and `default_branch`
+   - Look for most recently modified `*_change-summary.md` in `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
 
 2. **Extract title**:
    - Use the first `#` heading from the file as PR title
 
 3. **Check branch sync**:
-   - ⚠️ If current branch is not up to date with remote, **STOP THIS TASK** 🚨
+   - If current branch is not up to date with remote, **STOP THIS TASK**
    - Run `git status` to verify
 
 4. **Create PR**:
 
-   Use `get-default-branch name-only` to resolve `{default-branch}`.
+   Derive the bare branch name from `default_branch` by stripping the remote prefix (e.g., `origin/main` -> `main`).
 
    Extract body from `## What` onward:
 
@@ -32,13 +32,13 @@ Create a pull request using the GitHub CLI and existing PR description.
    gh pr create \
      --title "{extracted title from file}" \
      --body "$BODY" \
-     --base "{default-branch}" \
+     --base "{bare branch name}" \
      --draft
    ```
 
 ## Important
 
-- Use `get-default-branch name-only` for `--base`
+- Strip the remote prefix from `default_branch` (e.g., `origin/main` -> `main`) for `--base`
 - Do NOT use full reference (`origin/main`) - GitHub CLI expects branch name only
 - Creates PR as draft by default
 - If instructions are unclear, ask for confirmation before creating

packages/agents/content/skills/create-ticket/SKILL.md

@@ -12,11 +12,10 @@ Create a ticket on the appropriate platform. The remote platform (e.g., GitHub)
 
 ### 1. Resolve project metadata
 
-Get `project_slug` and `base_dir` — but NOT `ticket_id` (that comes from the platform in step 5).
+Get `project_slug` and `artifact_base_dir` -- but NOT `ticket_id` (that comes from the platform in step 5).
 
-- Read `project.slug` from `.agents/preferences.yaml`; if absent, use `get-project-slug`
+- Use `get-session-context` to obtain `project_slug` and `artifact_base_dir`
 - Read `project.ticket_prefix` from `.agents/preferences.yaml` (e.g., `CODY-`); if absent, default to empty string
-- Read `artifacts.base_dir` from `.agents/preferences.yaml`, falling back to `~/.agents/preferences.yaml`, then default `~/.ai`. If relative, resolve from project root. If absolute, use as-is.
 
 ### 2. Write ticket content
 
@@ -87,7 +86,7 @@ If `integrations.jira.enabled: true`, note that Jira creation needs additional c
 
 ### 5. Save local artifacts
 
-Ticket directory: `{base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
+Ticket directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
 
 `mkdir -p` the target directory before writing.
 

packages/agents/content/skills/design-and-plan/SKILL.md

@@ -172,13 +172,8 @@ Present the plan to the user. Revise until approved.
 ### Phase 5: Save artifacts and stop
 
 1. Resolve artifact directory using `save-artifact` conventions:
-   - Use `get-ticket-id` for ticket ID (auto-generate `{YYYYMMDD}-{4 random hex}` if none found)
-   - Use `get-project-slug` for project slug
-   - Resolve `artifacts.base_dir` by checking these sources in order. Use the first value found:
-     1. `.agents/preferences.yaml`
-     2. `~/.agents/preferences.yaml`
-     3. Default: `~/.ai`
-   - Target: `{base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
+   - Use `get-session-context` to obtain `ticket_id`, `project_slug`, and `artifact_base_dir` (auto-generate ticket ID as `{YYYYMMDD}-{4 random hex}` if none found)
+   - Target: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
    - `mkdir -p` the target directory
 
 2. Resolve provenance data:

packages/agents/content/skills/ex-post-facto/SKILL.md

@@ -10,7 +10,7 @@ Write an issue ticket (e.g., Jira issue) describing the issues that would have n
 
 ## Process
 
-1. **Analyze branch changes** using `get-default-branch`:
+1. **Analyze branch changes** using `get-session-context` to obtain `default_branch`:
 
 ```bash
 git diff $DEFAULT_BRANCH...HEAD
@@ -63,13 +63,11 @@ git diff $DEFAULT_BRANCH...HEAD
 
 ### Path resolution
 
-1. Read `artifacts.base_dir` from `.agents/preferences.yaml`, falling back to `~/.agents/preferences.yaml`, then default `~/.ai`
-2. If base_dir is relative, resolve from project root. If absolute, use as-is.
-3. Use `get-project-slug` for the project slug.
+Use `get-session-context` to obtain `artifact_base_dir`, `project_slug`, and `ticket_id`.
 
 Follow [artifact conventions](_data/artifact-conventions.md).
 
-Ticket directory: `{base_dir}/projects/{project-slug}/tickets/{ticket-id}/`
+Ticket directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
 
 Artifact type: `ticket`. Filename format:
 

packages/agents/content/skills/find-orchestration-savings/SKILL.md

@@ -17,7 +17,7 @@ Analyze a completed orchestrated run to identify cost-saving opportunities while
 1. **Resolve run directory:**
    - If a run directory path is provided, use it.
    - If a run is active in the current session (run-index.json path known), use that.
-   - Otherwise, use `get-branch-context` to get project_slug and ticket_id, then scan `{artifacts.base_dir}/projects/{project_slug}/tickets/{ticket_id}/` for the most recent completed run (directory with latest timestamp).
+   - Otherwise, use `get-session-context` to get `project_slug`, `ticket_id`, and `artifact_base_dir`, then scan `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/` for the most recent completed run (directory with latest timestamp).
    - If no run found, report "No completed run found for this context" and exit.
 
 2. **Verify the run directory** contains `run-log.jsonl` and `run-index.json`. If either is missing, report and exit.