copilot-tracking — Claude Code rule: what it does, how to install
This rule organizes working files for RPI, HVE Builder, and related workflows under .copilot-tracking/. It sets paths and formatting conventions for research, plans, changes, and reviews.
MIT ★ 1,627 updated 2026-11-03
.github/instructions/copilot-tracking.instructions.mdWhat copilot-tracking does
The rule directs intermediate work into .copilot-tracking/ and assigns dated paths for research, plans, plan critiques, change records, and reviews. Task slugs use lower-kebab-case and have a 60-character limit. Longer slugs must be shortened according to the rule’s hyphen-based cutoff.
Plans and change records use backticks for code and commands, and relative Markdown links for existing workspace files. Other tracking artifacts use plain workspace-relative paths. Research findings and decisions belong in the primary research document, while internal tracking references stay out of production code and commit messages.
Install the rule at .claude/rules/copilot-tracking.md. It governs workflow records rather than application files, so teams need to follow its artifact paths when saving that work.
What it helps with
- store research findings in the designated dated artifact
- separate plan critiques and reviews from their source plans
- link existing workspace files from plans and change records
- keep internal tracking paths out of production code
Example prompts for the agent
- Record the research findings for
user-authin the primary artifact under.copilot-tracking/research/. - Write the plan under
.copilot-tracking/plans/and link existing workspace files with relative paths. - Save implementation notes under
.copilot-tracking/changes/and keep internal artifact paths out of commit messages.
How to install copilot-tracking
Manually: put the files in place
.github/instructions/copilot-tracking.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.claude/rules/copilot-tracking.mdThe paths frontmatter field limits the files: move applyTo from the source into paths
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/copilot-tracking.mdcFrontmatter: description, globs, alwaysApply. Move applyTo from the source into globs, or the rule will not attach on its own
Manually: put the files in place
.devin/rules/copilot-tracking.mdManually: put the files in place
.clinerules/copilot-tracking.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about copilot-tracking
How do I install copilot-tracking in Claude Code?
Save the rule at .claude/rules/copilot-tracking.md.
What does copilot-tracking do?
It sets file paths and formatting conventions for intermediate artifacts produced by RPI, HVE Builder, and related workflows.
What format should task slugs use?
Use lower-kebab-case and keep the slug to 60 characters or fewer. For a longer slug, shorten it at the last hyphen within that limit, or at the limit if there is no hyphen.
Source text
copilot-tracking.instructions.md · MIT
---
description: "Shared .copilot-tracking conventions for RPI, HVE Builder, proposal response, and compatibility workflow evidence"
applyTo: '.copilot-tracking/research/**, .copilot-tracking/plans/**, .copilot-tracking/changes/**, .copilot-tracking/reviews/**, .copilot-tracking/rpi-sessions/**, .copilot-tracking/challenges/**, .copilot-tracking/prompts/**, .copilot-tracking/walkthroughs/**, .copilot-tracking/hve-builder/**, .copilot-tracking/proposal-responses/**'
---
# Copilot Tracking Conventions
Apply these conventions whenever an RPI, HVE Builder, or compatibility workflow writes intermediate, working, or scratch artifacts under `.copilot-tracking/`.
## Core Rules
* Default to `.copilot-tracking/` for every intermediate, working, or scratch file a skill produces. This file-based tracking takes precedence over memory: persist durable working state to the dated tracking artifact rather than relying on session, conversation, or working memory.
* Resolve where `.copilot-tracking/` lives and search its gitignored files as `copilot-tracking-location.instructions.md` defines.
* Persist research, planning, details, changes, and review outputs under `.copilot-tracking/` using the conventions below.
* Use `{{task_slug}}` for task slugs and `{{YYYY-MM-DD}}` for dates. Keep `{{task_slug}}` lower-kebab-case and at most 60 characters, because it names every tracking file; shorten a longer slug at the last hyphen within the cap, or at the cap when there is none.
* Generated tracking Markdown starts with `<!-- markdownlint-disable-file -->` and never uses `#file:` directives or line-number references.
* Plans under `.copilot-tracking/plans/` and changes records under `.copilot-tracking/changes/` are read by people in an editor. In those two artifacts, wrap code, commands, and symbols in backticks, and link an existing file or folder with the workspace-relative path as the link text and a path relative to the artifact file as the destination, for example `[scripts/plugins/Sync-PluginManifest.ps1](../../../scripts/plugins/Sync-PluginManifest.ps1)`. Keep a not-yet-created path in backticks.
* Research, critique, review, and other tracking artifacts use plain-text workspace-relative paths without Markdown links or backticks around paths.
* Markdown is the default tracking format. Versioned payload contracts and session state use the YAML or JSON format defined by their owning schema. Do not add `applyTo` metadata or create a `.instructions.md` tracking artifact.
## Handoff Expectations
* Keep the parent skill response compact and evidence-first. Write full detail to the tracking file that the phase owns.
* When a handoff is required, name the next phase and the expected artifact path instead of inlining the downstream workflow.
## RPI Research Evidence Ownership
* The primary research artifact is the only research artifact. It owns synthesized questions, findings, canonical evidence IDs, current and unresolved decisions, planning readiness, and user research decisions.
* A research helper, when one is used, returns source locations, excerpts, and brief notes in conversation. Those returns are suggestions, not tracking artifacts; the research context verifies them at the source before recording evidence.
* Persist user answers, unanswered questions, resulting decisions, and selected further-research items in the primary research artifact before the next research action.
## Tracking File Conventions
* Primary research notes stay under `.copilot-tracking/research/{{YYYY-MM-DD}}/{{task_slug}}-research.md`. When the caller supplies a trusted alternate evidence root, they stay at `<root>/research/{{YYYY-MM-DD}}/{{task_slug}}-research.md`, with the date resolved as `rpi-research` defines.
* Planning evidence stays under `.copilot-tracking/plans/{{YYYY-MM-DD}}/{{task_slug}}-plan.md`.
* Plan critique evidence stays under `.copilot-tracking/reviews/plans/{{YYYY-MM-DD}}/{{task_slug}}-plan-critique.md`. A follow-up critique of the same plan adds a numbered suffix, such as `{{task_slug}}-plan-critique-2.md`.
* Implementation evidence stays under `.copilot-tracking/changes/{{YYYY-MM-DD}}/{{task_slug}}-changes.md`.
* Review evidence stays under `.copilot-tracking/reviews/logs/{{YYYY-MM-DD}}/{{task_slug}}-review.md`. A new review of the same work adds a numbered suffix, such as `{{task_slug}}-review-2.md`.
* A session that takes on a later request names that work's documents for the work instead of numbering them: a short lower-kebab-case name that describes the work and differs from the session's other document names, such as `task-board-polish`, takes the place of `{{task_slug}}` in its research and plan paths. The plan's critique, changes record, and review take the plan's name. The RPI Agent's state lists every document and names the ones the current work uses, and with the documents' references to each other, it ties a session's documents together.
* RPI Agent session state stays under `.copilot-tracking/rpi-sessions/{{YYYY-MM-DD}}/{{session_slug}}/{{task_slug}}-state.json`. One folder holds every task of one session and is dated by the session's first day, and `{{session_slug}}` is at most 40 characters. The RPI Agent's State contract defines how session folders and state file names are derived, shortened, and kept unique, and defines the state fields; research, plan, critique, changes, and review records keep their own dated folders.
* Challenge session records stay under `.copilot-tracking/challenges/{{YYYY-MM-DD}}/{{task_slug}}-challenge.md`.
* Walkthrough decisions-and-changes ledgers stay under `.copilot-tracking/walkthroughs/{{YYYY-MM-DD}}/{{task_slug}}-decisions.md`.
* HVE Builder stage evidence stays under `.copilot-tracking/hve-builder/{{YYYY-MM-DD}}/{{artifact_slug}}-{{stage}}-{{attempt}}.md`. Scan existing files and increment `{{attempt}}` rather than overwriting another run.
* Proposal-response evidence stays under `.copilot-tracking/proposal-responses/{{response_slug}}/response-evidence.yml`. Analyze, contribute, and draft operations update this canonical artifact in place while preserving stable record IDs; requested renderings use stable sibling filenames.
* Keep `.copilot-tracking/` paths and other internal planning, research, or implementation artifact references out of production code, code comments, documentation strings, and commit messages. Internal artifacts guide implementation logic; comments stay self-contained and may cite public materials such as RFCs, specifications, or official documentation.
* For the research phase, keep writes inside `.copilot-tracking/research/`, or inside the caller's trusted alternate evidence root when one is supplied, except for workflow tracking files that the current execution explicitly requires.
* When material gaps remain, re-enter the current phase and update the dated artifact rather than skipping ahead. A user-directed skip of an optional step, such as the plan critique or review, is not a material gap.
## RPI Identity and Marker Conventions
* Use one stable task ID across the plan, critique, changes, and review records.
* Use `Pxx` for phases and `Pxx-Txx` for tasks. Place `<!-- rpi:phase id=P01 -->` or `<!-- rpi:task id=P01-T01 -->` immediately before the matching heading.
* Use descriptive headings and related plan or task markers for implementation evidence. Do not create a second per-entry identity scheme in the changes record.
* Use `PC-xxx` only in the plan critique and `RV-xxx` only in the review record.
* Use stable IDs, markers, and headings to navigate. Do not maintain line numbers, line ranges, or detail-line verification.
© microsoft · MIT · microsoft/hve-core