context-preservation-protocol

Metadata Schema

Core Fields (Recommended)

Standardized Values

status Field

report_type Field

technologies Field

Array of lowercase technology identifiers representing the SUBJECT MATTER of the task itself.

The following guidance is CRITICAL for understanding what to include vs exclude:

Examples of Correct Usage:

Examples of INCORRECT Usage:

Example values (illustrative, not exhaustive): use any lowercase identifier that describes your task's subject matter -- e.g. languages (python, typescript, go, rust), frameworks (fastapi, react, django), databases (postgresql, mongodb, redis), infrastructure (docker, kubernetes, terraform).

Example:

"technologies": ["python", "fastapi", "postgresql"]

Optional Fields

Advanced: Worktree Metadata Fields

This section is relevant for environments that use git worktrees. If you are not using worktrees, you can skip this section.

When working in a git worktree environment, include these fields for proper context isolation:

Project Name Derivation:

The project field MUST be derived using this fallback chain to ensure consistency across git worktrees:

1. Parse from git remote URL (PREFERRED)

   • Try origin remote first: git remote get-url origin
   • Parse repository name from URL:
     • https://github.com/user/my-project.git -> my-project
     • git@github.com:user/my-project.git -> my-project
   • If origin unavailable, try upstream, then first available remote

2. Git toplevel basename (FALLBACK for repos without remotes)

   • git rev-parse --show-toplevel -> extract last path component
   • Example: /home/user/projects/my-project -> my-project

3. Current directory basename (FALLBACK for non-git directories)

   • Extract last directory name from working directory path
   • Example: /home/user/work/my-project -> my-project

Why this matters:

• Different worktrees of the same repository have different directory names
• Using directory name causes context isolation to break across worktrees
• Remote URL provides true canonical identity across all worktrees and users

Example with worktree fields:

{
  "agent_name": "developer",
  "task_name": "Implement feature X",
  "status": "done",
  "project": "my-project",
  "worktree_id": "feature-branch",
  "worktree_path": "/home/user/projects/feature-branch",
  "is_linked_worktree": true,
  "technologies": ["python", "fastapi"],
  "report_type": "implementation",
  "references": {}
}

References Field

The references field stores cross-system identifiers for traceability. All values are arrays.

Core Reference Types:

Open for extension following {system}_{entity_type}s convention (e.g., github_prs, jira_issues).

Usage Guidelines:

• Include relevant references when storing context
• Use empty object {} if no external references exist
• context_ids: Reference related entries in the same or other threads
• urls: Store any external reference as a full URL (issues, PRs, documentation pages, commit URLs, etc.)
• git_commits: Use FULL SHA only (40 characters for SHA-1, 64 characters for SHA-256). Within a single-project session where project metadata identifies the repository, bare SHAs are unambiguous and directly usable with git show

Cross-Repository Disambiguation:

When context spans multiple repositories (e.g., a task involving changes across a backend and frontend repo), bare SHAs in git_commits may be ambiguous because the same hash format provides no indication of which repository it belongs to. In such cases, supplement git_commits with platform URLs in urls to provide full context:

"references": {
  "git_commits": ["abc1234def5678901234567890abcdef12345678"],
  "urls": ["https://github.com/org/backend-repo/commit/abc1234def5678901234567890abcdef12345678"]
}

Both fields serve complementary purposes: git_commits provides typed, validated commit identifiers usable across any git platform (including local repos without hosting); urls provides human-readable, clickable links with full repository context.

Examples:

"references": {
  "context_ids": [2322, 2325],
  "urls": ["https://github.com/org/repo/pull/445", "https://docs.example.com/guide"],
  "git_commits": ["abc1234def5678901234567890abcdef12345678"]
}

"references": {}