# Purpose of the .copilot-tracking Directory in HVE-Core AI-Assisted Workflows > Discover the purpose of the .copilot-tracking directory in HVE-Core AI-assisted workflows. Learn how it maintains context for machine-generated artifacts without cluttering repository history. - Repository: [Microsoft/hve-core](https://github.com/microsoft/hve-core) - Tags: how-to-guide - Published: 2026-03-09 --- **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`](https://github.com/microsoft/hve-core/blob/main/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`](https://github.com/microsoft/hve-core/blob/main/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`](https://github.com/microsoft/hve-core/blob/main/docs/rpi/task-researcher.md), lines 44-45), while planners consume these files from [`docs/rpi/task-planner.md`](https://github.com/microsoft/hve-core/blob/main/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`](https://github.com/microsoft/hve-core/blob/main/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: ```powershell # Add to .gitignore if not present Add-Content -Path ".gitignore" -Value "`n.copilot-tracking/" ``` Open generated research artifacts before invoking subsequent agents: ```powershell # 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: ```powershell # 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: ```powershell # 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`](https://github.com/microsoft/hve-core/blob/main/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`](https://github.com/microsoft/hve-core/blob/main/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`](https://github.com/microsoft/hve-core/blob/main/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`](https://github.com/microsoft/hve-core/blob/main/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.