---
title: Atlas Shared Project Context Memory Spec
area: projects
tags: [plans, assistant, atlas, context-memory]
created: 2026-05-14
updated: 2026-05-14
status: draft
related: [[Atlas Capability Upgrade Program]], [[Ops Home]], [[Vault Conventions]], [[Projects Home]], [[Runbooks Home]]
---

# Atlas Shared Project Context Memory Spec

## Workstream

Workstream 1 of [[Atlas Capability Upgrade Program]]: shared project/context memory.

## Goal

Create a durable documentation and context system so Atlas, Will, and specialist agents can orient from Obsidian/project files without rereading old chats. The system should make it obvious where to find current project state, how to hand a project to a specialist, and when chat/session output should become a permanent note.

## Recommended owner

Primary owner: `writer` profile for the initial documentation system and templates.

Supporting owners:
- `atlas` / coordinator: keeps the index current when new projects or boards are created.
- `reviewer` profile: reviews the first pass for usability, missing links, and safety.
- Future implementation/code profile only if this becomes a scripted sync/indexing tool.

## Deliverables

1. Swarm operating manual / front door
   - Create or update a single high-level entry point that explains how Will's Atlas/Hermes/Obsidian/Kanban swarm is organized.
   - Proposed path: `Resources/Swarm Operating Manual.md`.
   - Link it from `Ops Home.md` and `Projects/Atlas Capability Upgrade Program.md`.
   - Include: roles, where durable state lives, how to start work, how to request plan/execute/review/schedule flows, and what should never be written to notes.

2. Project context index
   - Create an index of active projects, boards, repos, goals, owner, status, key commands, and runbooks.
   - Proposed path: `Projects/Project Context Index.md`.
   - Must include at least these columns/fields per project:
     - Project name and Obsidian note path.
     - Board/task source, if applicable.
     - Active repository or workspace path.
     - Goal / current status.
     - Owner and reviewer profile.
     - Common commands / smoke tests.
     - Related runbooks, decisions, and context packs.
   - Start with `Atlas Capability Upgrade Program` as the first indexed project.

3. Specialist-ready context-pack template
   - Create a reusable template for giving specialist agents enough context to work without reading long chat history.
   - Proposed path: `Templates/Context Pack.md`.
   - Template sections:
     - Purpose / outcome.
     - Background links.
     - Current state.
     - Relevant files and repos.
     - Commands / verification.
     - Constraints / safety rules.
     - Prior decisions.
     - Open questions.
     - Handoff expectations.
   - Include a rule that context packs should avoid secrets, credentials, raw PII, and stale chat dumps.

4. Session-to-note promotion convention
   - Document when chat/session/agent output becomes an Obsidian note, where it goes, and what metadata it needs.
   - Proposed path: `Runbooks/Promote Session Output to Notes.md` or a section in `Resources/Swarm Operating Manual.md`; use a separate runbook if the procedure is more than one page.
   - Must preserve the existing `Ops Home.md` capture flow:
     - Thread summary -> `Resources/`.
     - Active implementation -> `Projects/`.
     - Operational procedure -> `Runbooks/`.
     - Important choice -> `Decisions/`.
     - Loose capture -> `Inbox/`.
   - Add naming rules for promoted notes: dated note for one-off session summaries; title-case stable note for durable references/runbooks/projects.

5. Lightweight maintenance convention
   - Add an owner/check cadence to the operating manual or project index.
   - Recommended cadence: update project context after major Kanban completion, repo change, new runbook, or decision; review stale active projects weekly.

## Files and notes to touch

Create:
- `Resources/Swarm Operating Manual.md`
- `Projects/Project Context Index.md`
- `Templates/Context Pack.md`
- `Runbooks/Promote Session Output to Notes.md` if the promotion procedure is not kept in the operating manual

Edit narrowly:
- `Ops Home.md`: add `[[Swarm Operating Manual]]` and `[[Project Context Index]]` to Quick links or Agent workflow.
- `Projects/Atlas Capability Upgrade Program.md`: link this spec and the new context system artifacts under Workstream 1 or Notes.
- `Conventions.md`: only if new tags/folder rules are introduced.

Do not overwrite existing notes. Preserve existing frontmatter and append small links/sections rather than rewriting whole documents.

## Implementation steps

1. Inventory existing vault structure and relevant notes.
   - Read `Ops Home.md`, `Conventions.md`, `Projects/Projects Home.md`, `Runbooks/Runbooks Home.md`, `Resources/Resources Home.md`, and `Projects/Atlas Capability Upgrade Program.md`.
   - Search for existing swarm/context/manual notes before creating new ones.

2. Draft the four core artifacts.
   - Use existing frontmatter conventions from `Conventions.md`.
   - Use Obsidian wikilinks for every related note.
   - Keep each artifact practical and short enough for an agent to consume.

3. Seed the project context index.
   - Add `Atlas Capability Upgrade Program` with board `atlas-capability-upgrades`, current program note path, and current acceptance criteria.
   - Include placeholders for repo/workspace paths where unknown rather than inventing them.

4. Wire navigation.
   - Add links from `Ops Home.md` and the program note.
   - Ensure a new agent starting at `Ops Home.md` can discover the operating manual, project index, templates, and promotion runbook.

5. Review and tighten.
   - Remove duplicated guidance.
   - Confirm all paths are valid.
   - Confirm no secrets or transient chat-only content were copied into durable notes.

## Verification steps

- File existence:
  - `Resources/Swarm Operating Manual.md` exists.
  - `Projects/Project Context Index.md` exists.
  - `Templates/Context Pack.md` exists.
  - `Runbooks/Promote Session Output to Notes.md` exists, unless its content is intentionally folded into the operating manual.

- Link/navigation check:
  - `Ops Home.md` links to the operating manual and project context index.
  - `Projects/Atlas Capability Upgrade Program.md` links to the new workstream artifacts.
  - Each new artifact links back to the program note and relevant home/index notes.

- Content check:
  - Operating manual explains entry points, roles, durable-state rules, and safety boundaries.
  - Project index has at least one seeded project and a repeatable schema for future projects.
  - Context-pack template is directly usable by a specialist worker.
  - Promotion convention maps outputs to the right vault folders.

- Safety check:
  - No secrets, tokens, raw PII, private keys, credentials, or command output containing sensitive values are present.
  - Existing notes were edited by narrow append/patch only.

- Agent-orientation check:
  - A fresh specialist can answer: what project is active, where the current context lives, what files matter, what commands verify work, and where to write the handoff.

## Risks and mitigations

- Risk: duplicated or conflicting guidance across `Ops Home.md`, `Conventions.md`, and the new manual.
  - Mitigation: keep `Ops Home.md` as navigation, `Conventions.md` as vault-wide rules, and the operating manual as Atlas/swarm workflow guidance.

- Risk: the project index becomes stale.
  - Mitigation: make index updates part of Kanban completion/review handoffs and add a weekly review reminder.

- Risk: context packs grow into chat dumps.
  - Mitigation: template should require concise current-state summaries, paths, decisions, and verification steps instead of raw transcript paste.

- Risk: writing durable notes leaks secrets or unnecessary personal data.
  - Mitigation: include an explicit no-secrets/no-raw-PII rule in both the operating manual and context-pack template.

- Risk: repo/workspace paths are unknown during first pass.
  - Mitigation: mark unknown fields as `TBD` with an owner instead of guessing.

## Acceptance criteria

This workstream is done when:
- The four documentation/context artifacts exist or the promotion convention is intentionally included in the operating manual.
- `Ops Home.md` and the Atlas program note link to the new context system.
- The project index has a seeded `Atlas Capability Upgrade Program` entry.
- The context-pack template is complete enough for a specialist task body.
- Verification confirms navigation, content, and safety checks pass.
