Purpose of the .copilot-tracking Directory in HVE-Core AI-Assisted Workflows

The .copilot-tracking directory serves as an ephemeral, git-ignored workspace that stores machine-generated artifacts to maintain context across AI-assisted workflow phases without polluting repository history.

The microsoft/hve-core repository implements a structured AI-assisted development methodology called RPI (Research → Plan → Implement). At the center of this system lies the .copilot-tracking directory, a runtime storage area that enables AI agents to persist context across chat sessions and hand off work between specialized agents.

What Is the .copilot-tracking Directory?

The .copilot-tracking folder is a workspace-only storage area created by HVE-Core agents at runtime. It functions as a temporary ledger that holds machine-generated outputs including research documents, implementation plans, change logs, and review comments. According to the installation documentation in docs/getting-started/install.md (lines 188-194), this directory is explicitly added to .gitignore to ensure its contents never enter version control.

Core Design Characteristics

Ephemeral and Git-Ignored Storage

The directory is strictly ephemeral. As documented in docs/getting-started/install.md (lines 200-207), HVE-Core automatically adds .copilot-tracking/ to the project's .gitignore file. This design keeps generated AI artifacts out of the permanent codebase while allowing agents to reference prior work during active development sessions.

Phase-Specific Artifact Organization

Files organize into sub-folders matching the RPI methodology: research/, plans/, changes/, and reviews/. Each agent writes to specific locations—for example, the task-researcher agent stores findings in .copilot-tracking/research/ (documented in docs/rpi/task-researcher.md, lines 44-45), while planners consume these files from docs/rpi/task-planner.md to generate implementation instructions.

Context Bridge Across Chat Sessions

When users execute /clear to reset chat history, AI agents lose conversational context. However, as explained in docs/rpi/context-engineering.md (lines 66-78), agents retrieve persisted artifacts from .copilot-tracking to continue multi-step workflows reliably. This mechanism ensures that clearing chat history does not destroy work-in-progress research or planning documents.

Validation Exclusions

The frontmatter validator in scripts/linting/Modules/FrontmatterValidation.psm1 (lines 761-762) deliberately skips this directory. This exclusion prevents linting tools from failing on machine-generated files that may not conform to standard frontmatter requirements.

How Agents Interact with the Directory

All built-in agents follow unified conventions when reading from and writing to .copilot-tracking. The task-researcher generates markdown research files, the task-planner reads these to create instruction files in plans/, and the task-implementor writes change logs to changes/. This standardized contract enables seamless hand-offs between the research, planning, and implementation phases without requiring users to manually transfer files.

Working with .copilot-tracking in Practice

Below are practical snippets illustrating how to configure and utilize the .copilot-tracking directory in HVE-Core projects.

First, ensure the directory is ignored by version control:

# Add to .gitignore if not present

Add-Content -Path ".gitignore" -Value "`n.copilot-tracking/"

Open generated research artifacts before invoking subsequent agents:

# View research output created by task-researcher

code .copilot-tracking/research/2025-01-28-blob-storage-research.md

# The planner automatically detects the latest research file when invoked next

Trigger implementation using specific plan files:

# Manually invoke task-implementor with a specific plan

$plan = ".copilot-tracking/plans/2025-01-28-blob-storage-plan.instructions.md"
copilot task-implementor -plan $plan

# Output writes to .copilot-tracking/changes/

Clean up artifacts after completion:

# Remove all temporary AI-generated files

Remove-Item -Recurse -Force ".copilot-tracking/*"
Write-Host "All temporary AI artifacts cleared."

Summary

• The .copilot-tracking directory provides ephemeral storage for AI-generated artifacts, explicitly excluded from version control via .gitignore as specified in docs/getting-started/install.md.
• It implements a phase-specific folder structure (research/, plans/, changes/, reviews/) that aligns with the RPI (Research → Plan → Implement) methodology.
• The directory acts as a context bridge allowing agents to maintain workflow state even when chat history is cleared (/clear), according to docs/rpi/context-engineering.md.
• Validation tools skip this directory, as implemented in FrontmatterValidation.psm1, preventing linting errors on machine-generated content.
• All HVE-Core agents follow unified conventions for reading and writing, enabling seamless hand-offs between specialized AI assistants.

Frequently Asked Questions

Does .copilot-tracking get committed to Git?

No. The directory is automatically added to .gitignore during HVE-Core setup (see docs/getting-started/install.md, lines 188-194). This ensures machine-generated artifacts remain local-only and never pollute the repository history.

What happens to files in .copilot-tracking when I clear my chat history?

The files persist on disk. As documented in docs/rpi/context-engineering.md (lines 66-78), agents retrieve artifacts from this directory to reconstruct context after a /clear command, allowing workflows to continue uninterrupted despite the loss of conversational memory.

Can I manually edit files inside .copilot-tracking?

Yes. While agents generate the initial content, users can modify files in research/, plans/, or other subdirectories. The planner and implementor agents read these files dynamically, so manual edits affect subsequent AI actions in the workflow.

How do I clean up old artifacts from the directory?

Delete the contents manually or use a cleanup script. The artifacts are disposable by design—removing files from .copilot-tracking/ (using commands like Remove-Item -Recurse -Force) simply clears the AI's working memory without affecting your actual codebase.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}