Create and manage context, planning files for agents by jstirnaman · Pull Request #6809 · influxdata/docs-v2

jstirnaman · 2026-02-11T03:35:41Z

.claude/commands/plan.md: Creates and manages PLAN.md to guide agent work in the branch. Assumed to be a temporary file.
.claude/commands/finish.md: Cleans up temporary planning file, generates a summary for a PR.
.github/workflows/cleanup-ephemeral-docs.yml: Safety net workflow to remove temporary files before the branch is merged into master (or main)
updates Node deps

Use the /plan command to scaffold a PLAN.md file, tracked by default, in the current branch. You can also use the external worktree-manager tool to scaffold a project folder with worktrees and plan files.
PLAN.md is tracked to persist context across agents and sessions, however it is deleted before the branch is merged into the main branch (master in docs-v2).
The /finish command helps clean up the files and generate the PR and summary.

Run yarn to update lockfile with latest compatible versions.

- **.claude/commands/plan.md**: Creates and manages PLAN.md to guide agent work in the branch. Assumed to be a temporary file. - **.claude/commands/finish.md**: Cleans up temporary planning file, generates a summary for a PR. - **.github/workflows/cleanup-ephermal-docs.yml**: Safety net workflow to remove temporary files before the branch is merged into `master` (or `main`)

Copilot

Pull request overview

Adds agent-oriented planning/cleanup scaffolding to the docs repo, along with a post-merge GitHub Action to remove ephemeral planning files from the default branch, and updates Node/Yarn dependencies.

Changes:

Add /plan and /finish command docs under .claude/commands/ to manage an ephemeral PLAN.md workflow.
Add a GitHub Actions workflow to remove PLAN.md/HANDOVER.md from master/main after PR merge as a safety net.
Update yarn.lock with dependency bumps (including Copilot packages and various tooling deps).

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
`yarn.lock`	Updates lockfile entries for Node/tooling dependencies.
`PLAN.md`	Adds a sample/active planning file at repo root.
`.github/workflows/cleanup-ephemeral-docs.yml`	New workflow to delete ephemeral planning docs after merge by committing to base branch.
`.claude/commands/plan.md`	New command doc describing how agents create/update/status `PLAN.md`.
`.claude/commands/finish.md`	New command doc describing cleanup + PR summary workflow for agents.

Copilot · 2026-02-11T03:52:20Z

.github/workflows/cleanup-ephemeral-docs.yml

+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.base.ref }}
+          fetch-depth: 1
+


The workflow checks out the base branch with fetch-depth: 1 and then does a plain git push. If the base branch advances between checkout and push (or multiple merges happen close together), this can fail with a non-fast-forward error and leave ephemeral files behind. Consider using fetch-depth: 0 and rebasing/pulling before pushing (or adding a small retry loop) so the cleanup is resilient to concurrent merges.

Copilot · 2026-02-11T03:52:21Z

.github/workflows/cleanup-ephemeral-docs.yml

+on:
+  pull_request:
+    types: [closed]
+    branches:
+      - master
+      - main
+
+jobs:
+  cleanup:
+    # Only run when PR is actually merged (not just closed)
+    if: github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+


This uses the pull_request event but needs contents: write to push a cleanup commit. For PRs originating from forks, GITHUB_TOKEN is typically read-only on pull_request, so the job will fail after merge. Consider switching to pull_request_target (while continuing to checkout the base ref), or guard the job with a condition like github.event.pull_request.head.repo.full_name == github.repository to only run when it can actually push.

Copilot · 2026-02-11T03:52:21Z

PLAN.md

+# jts-agentic-workflow
+
+## Source
+
+- **Project**: jts-agentic-workflow
+- **Branch**: `docs-v2-jts-agentic-workflow`
+- **Created**: 2026-02-10


PLAN.md is described as an ephemeral file that should be deleted before merging to the main branch, but this PR adds a concrete, branch-specific PLAN.md at repo root. It would be better to keep the template/example under .claude/ (or similar) and avoid committing a live plan file into the PR, relying on the cleanup workflow only as a last-resort safety net.

@copilot

PLAN.md is described as an ephemeral file that should be deleted before merging to the main branch, but this PR adds a concrete, branch-specific PLAN.md at repo root. It would be better to keep the template/example under .claude/ (or similar) and avoid committing a live plan file into the PR, relying on the cleanup workflow only as a last-resort safety net.

PLAN.md is there to test that it's removed on merge. The actual template is in the .claude/commands/plan.md command instruction. Would it be more helpful to Copilot to refactor the template out of that command? Or can Copilot use the command as-is?

Copilot · 2026-02-11T03:52:21Z

.claude/commands/plan.md

+- PLAN.md is ephemeral - delete before merging to main
+- Use `/finish` skill to properly cleanup and merge
+- Tasks use standard markdown checkbox format: `- [ ]` and `- [x]`
+- The startup hook auto-injects PLAN.md at session start


This note says “The startup hook auto-injects PLAN.md at session start”, but there doesn’t appear to be any corresponding hook/config in the repo (no other references found). To avoid misleading users/agents, either link to the actual hook implementation/config location or remove/soften this statement.

Suggested change

- The startup hook auto-injects PLAN.md at session start

- A startup hook can be configured to auto-inject PLAN.md at session start

Copilot · 2026-02-12T17:05:06Z

@jstirnaman I've opened a new pull request, #6821, to work on those changes. Once the pull request is ready, I'll request review from you.

jstirnaman · 2026-02-12T17:10:22Z

@copilot open a new pull request to apply changes based on the comments in this thread

Copilot · 2026-02-12T17:10:31Z

@jstirnaman I've opened a new pull request, #6822, to work on those changes. Once the pull request is ready, I'll request review from you.

jstirnaman added 2 commits February 10, 2026 16:54

chore(deps): update yarn dependencies

3e1c4ab

Run yarn to update lockfile with latest compatible versions.

jstirnaman marked this pull request as ready for review February 11, 2026 03:37

jstirnaman requested a review from a team as a code owner February 11, 2026 03:37

jstirnaman requested review from sanderson and removed request for a team and sanderson February 11, 2026 03:37

jstirnaman changed the title ~~jDocs v2 jts agentic workflow~~ Create and manage context, planning files for agents Feb 11, 2026

jstirnaman requested a review from Copilot February 11, 2026 03:47

jstirnaman self-assigned this Feb 11, 2026

Copilot started reviewing on behalf of jstirnaman February 11, 2026 03:48 View session

Copilot AI reviewed Feb 11, 2026

View reviewed changes

Copilot AI mentioned this pull request Feb 12, 2026

Refactor PLAN.md template management for better Copilot integration #6821

Draft

jstirnaman marked this pull request as draft February 12, 2026 17:05

Merge branch 'master' into docs-v2-jts-agentic-workflow

51dffde

Copilot AI mentioned this pull request Feb 12, 2026

Improve cleanup workflow resilience and fork compatibility #6822

Draft

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Create and manage context, planning files for agents#6809

Create and manage context, planning files for agents#6809
jstirnaman wants to merge 3 commits intomasterfrom
docs-v2-jts-agentic-workflow

jstirnaman commented Feb 11, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 11, 2026

Uh oh!

Copilot AI Feb 11, 2026

Uh oh!

Copilot AI Feb 11, 2026

Uh oh!

jstirnaman Feb 12, 2026

Uh oh!

Copilot AI Feb 11, 2026

Uh oh!

Copilot AI commented Feb 12, 2026

Uh oh!

jstirnaman commented Feb 12, 2026

Uh oh!

Copilot AI commented Feb 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	- The startup hook auto-injects PLAN.md at session start
	- A startup hook can be configured to auto-inject PLAN.md at session start

Conversation

jstirnaman commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

jstirnaman Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Feb 12, 2026

Uh oh!

jstirnaman commented Feb 12, 2026

Uh oh!

Copilot AI commented Feb 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jstirnaman commented Feb 11, 2026 •

edited

Loading