Route Claude Code plan files to gitignored .claude/plans; document .agents/tasks convention#30
Open
alexander-yevsyukov wants to merge 3 commits into
Open
Route Claude Code plan files to gitignored .claude/plans; document .agents/tasks convention#30alexander-yevsyukov wants to merge 3 commits into
.claude/plans; document .agents/tasks convention#30alexander-yevsyukov wants to merge 3 commits into
Conversation
Claude Code writes plan-mode files — and the resumable status notes agents append to them — under `~/.claude/plans/` by default. That is outside the repository, so plans and hand-off reports are invisible to the team and to other agents, which breaks the cross-session resume workflow this repo's `.agents/tasks/` convention is built around. Set `plansDirectory` to `.agents/tasks` so plan files land in the durable, git-tracked task directory instead: - Add `.claude/settings.json` pinning `plansDirectory` for anyone working in this repo (team-wide, not just per-developer). - Document the redirect in `.agents/tasks/README.md`, including how to normalize plan mode's random-slug filenames into meaningful task slugs. This repo does not consume `config`, so its `.claude/settings.json` is self-owned and not overwritten by `config/migrate`; a separate change to the `config` repo will carry the same setting to consumer repos. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR standardizes where Claude Code “plan mode” files are written by redirecting them into the repo’s durable, git-tracked task area (.agents/tasks/), aligning Claude plan artifacts with the existing task hand-off workflow.
Changes:
- Add repo-level
.claude/settings.jsonsettingplansDirectoryto.agents/tasks. - Document the redirect in
.agents/tasks/README.md, including guidance for renaming Claude’s random plan slugs into meaningful task slugs.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
.claude/settings.json |
Sets plansDirectory to write Claude plan-mode files into .agents/tasks instead of ~/.claude/plans/. |
.agents/tasks/README.md |
Documents the redirect and recommended rename/frontmatter workflow for plan files. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 68420b30f8
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
`guidelines/safety-rules.md` (lines 76-79) documents that the project's `.claude/settings.json` keeps `Bash(git commit:*)` in `permissions.ask` as defense-in-depth against agents writing git history under permissive global settings. This repo previously had no `.claude/settings.json`, so the introduced file must carry that guard rather than silently omit it. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…le convention Claude Code's plan-mode filename is a harness-assigned random slug that cannot be controlled — there is no naming setting and the model has no say. Routing those files into `.agents/tasks/` therefore mixed random-named artifacts into the meaningfully-named, committed task namespace. Split the two instead: - Point `plansDirectory` at `.claude/plans` and gitignore it, so plan-mode files stay in the working tree but out of version control and out of `.agents/tasks/`. - Durable task and hand-off notes are authored by the agent as `.agents/tasks/<meaningful-slug>.md` (Write tool) — meaningful from creation, never renamed. - Document the split in `.agents/tasks/README.md` and add an AGENTS.md orientation bullet so agents follow it without re-reading the README. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
alexander-yevsyukov
changed the title
.agents/tasks.claude/plans; document .agents/tasks convention
armiol
approved these changes
Jul 8, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Configure how this repo handles Claude Code plan-mode files and durable task files, and document the convention.
Why
Claude Code's plan mode writes a file with a harness-assigned random slug (e.g.
twinkling-booping-flask.md) that is not controllable — no naming setting exists and the model has no say. By default it lands under~/.claude/plans/, outside the repo, where durable status/hand-off notes appended to it are invisible to the team. (This surfaced from a real hand-off report that landed at~/.claude/plans/twinkling-booping-flask.md.)Design: dual-file split
.agents/tasks/<meaningful-slug>.mdwith the Write tool. It picks the slug, so the name is meaningful from creation and never needs renaming..agents/tasks/namespace.Changes
.claude/settings.json(new) —plansDirectory: .claude/plans(gitignored scratch), pluspermissions.ask: ["Bash(git commit:*)"]as the defense-in-depth guard documented inguidelines/safety-rules.md(added during review)..gitignore— ignore.claude/plans/..agents/tasks/README.md— document the dual-file split and naming.AGENTS.md— one orientation bullet so agents follow the convention without re-reading the README.Reviewer notes
config, so its.claude/settings.jsonis self-owned. A separateconfig-repo change will distribute the sameplansDirectory: .claude/plans+ gitignore to consumer repos.🤖 Generated with Claude Code