Create and manage context, planning files for agents#6809

Draft

jstirnaman wants to merge 5 commits intomaster from

docs-v2-jts-agentic-workflow

Draft

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

Conversation

@jstirnaman

Copy link

Contributor

@jstirnaman jstirnaman commented Feb 11, 2026 •

edited

Loading

.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.

jstirnaman added 2 commits

February 10, 2026 16:54

@jstirnaman


 chore(deps): update yarn dependencies

3e1c4ab

Run yarn to update lockfile with latest compatible versions.

@jstirnaman


 chore(ci): Install context harness management commands and workflow

4f8dc03

- **.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`)

@jstirnaman jstirnaman marked this pull request as ready for review

February 11, 2026 03:37

@jstirnaman jstirnaman requested a review from a team as a code owner

February 11, 2026 03:37

@jstirnaman jstirnaman requested review from sanderson and removed request for a team and sanderson

February 11, 2026 03:37

@jstirnaman jstirnaman changed the title ~~(削除) jDocs v2 jts agentic workflow (削除ここまで)~~ (追記) Create and manage context, planning files for agents (追記ここまで)

Feb 11, 2026

@jstirnaman jstirnaman requested a review from Copilot

February 11, 2026 03:47

@jstirnaman 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

Copy link

Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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

Comment on lines 39 to 44

- name: Checkout repository

uses: actions/checkout@v4

with:

ref: ${{ github.event.pull_request.base.ref }}

fetch-depth: 1

Copy link

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.

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

Comment on lines 22 to 37

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

Copy link

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.

PLAN.md

Comment on lines +1 to +7

# jts-agentic-workflow

## Source

- **Project**: jts-agentic-workflow

- **Branch**: `docs-v2-jts-agentic-workflow`

- **Created**: 2026年02月10日

Copy link

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.

Copy link

Contributor Author

@jstirnaman jstirnaman Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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?

.claude/commands/plan.md Outdated

Copy link

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.

Copy link

Contributor Author

@jstirnaman jstirnaman Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@claude Review project hooks

Copilot AI mentioned this pull request

Feb 12, 2026

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

Draft

Copy link

Contributor

Copilot AI commented Feb 12, 2026

@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 jstirnaman marked this pull request as draft

February 12, 2026 17:05

@jstirnaman


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

51dffde

@jstirnaman

Copy link

Contributor Author

jstirnaman commented Feb 12, 2026

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

Copilot AI mentioned this pull request

Feb 12, 2026

Improve cleanup workflow resilience and fork compatibility #6822

Merged

Copy link

Contributor

Copilot AI commented Feb 12, 2026

@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 and others added 2 commits

February 17, 2026 09:20

@jstirnaman


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

a8a0121

@jstirnaman


 Improve cleanup workflow resilience and fork compatibility ( #6822 )

* Initial plan
* fix(ci): improve cleanup workflow resilience and fork compatibility
- Switch from pull_request to pull_request_target for fork compatibility
- Use fetch-depth: 0 to get full history
- Add git pull --rebase before push to handle concurrent merges
- Soften startup hook reference to clarify it's configurable
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>
* fix(ci): add error handling and security documentation
- Add fallback to regular merge if rebase fails due to conflicts
- Document security considerations for pull_request_target usage
- Clarify why this workflow is safe for fork PRs
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>
* fix(ci): make merge strategy explicit in fallback
Use --no-rebase --no-edit flags to ensure merge doesn't prompt for editor
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>

Conversation

@jstirnaman 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 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!

@jstirnaman jstirnaman Feb 17, 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

Comments

@jstirnaman jstirnaman commented Feb 11, 2026 •

edited

Loading