feat: Add file location standards to agent template and operational rules #7
Conversation
…ules Prevents common mistake of creating ADRs and documentation in `.claude/` directory instead of proper project documentation locations. Adds: - File Location Standards section to AGENT-TEMPLATE.md - File Location Standards section to OPERATIONAL-RULES.md - Clear DO/DON'T guidance for ADRs, tasks, and research docs This ensures new agents created from the template inherit correct file placement guidance, reducing documentation location drift. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
📝 WalkthroughSummary by CodeRabbitRelease Notes
✏️ Tip: You can customize this high-level summary in your review settings. WalkthroughUpdated agent templates and operational documentation to establish standardized file location conventions for architectural decision records (ADRs), tasks, research documents, and agent definitions across the project, with version increments and date updates. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Warning Review ran into problems🔥 ProblemsErrors were encountered while retrieving linked issues. Errors (2)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In @.claude/agents/AGENT-TEMPLATE.md:
- Around line 302-303: Update the "Last Updated" date in the AGENT-TEMPLATE
header from 2025-01-28 to the correct PR creation date 2026-01-28 by editing the
"Last Updated" line (the header block containing "Template Version" and "Last
Updated") so it reads **Last Updated: 2026-01-28**; leave "Template Version"
unchanged.
- Around line 227-240: Update the Tasks entry in the "File Location Standards
(MANDATORY)" table in AGENT-TEMPLATE.md so it reflects the full folder pattern
used elsewhere (not just delegation/tasks/1-backlog/); replace the single
example with the canonical pattern (e.g., delegation/tasks/{number}-{status}/)
or list the status folders (2-todo/, 3-in-progress/, 5-done/, etc.) to match
OPERATIONAL-RULES.md and other references in this template.
In @.claude/agents/OPERATIONAL-RULES.md:
- Around line 3-4: Update the "Last Updated" metadata in
.claude/agents/OPERATIONAL-RULES.md from "2025-01-28" to "2026-01-28": locate
the header block containing "**Version**: 2.1" and "**Last Updated**:
2025-01-28" and change the date string to 2026-01-28 so the file reflects the PR
creation date.
| ## File Location Standards (MANDATORY) | ||
|
|
||
| When creating project documentation, use the correct locations: | ||
|
|
||
| | Document Type | Location | Example | | ||
| |---------------|----------|---------| | ||
| | **ADRs** | `docs/decisions/adr/` | `ADR-004-feature-name.md` | | ||
| | **Tasks** | `delegation/tasks/1-backlog/` | `TASK-0030-task-name.md` | | ||
| | **Research** | `[project-specific]/research/<topic>/` | `analysis.md` | | ||
|
|
||
| **DO NOT create ADRs or documentation in `.claude/`** - that directory is for agent definitions and settings only. | ||
|
|
||
| **Before creating an ADR**: Read `.agent-context/workflows/ADR-CREATION-WORKFLOW.md` for template and numbering. | ||
|
|
There was a problem hiding this comment.
Excellent addition! The File Location Standards section addresses the PR objectives effectively.
The new section provides clear guidance on where to place different document types and explicitly prohibits using .claude/ for ADRs/docs. This should prevent the downstream confusion mentioned in the PR objectives.
However, there's a minor inconsistency in the table:
Fix: Tasks location should reflect all status folders, not just backlog.
Line 234 shows only delegation/tasks/1-backlog/ for Tasks, but this template itself references multiple status folders throughout:
- Line 46:
2-todo/ - Line 53:
3-in-progress/ - Line 71:
5-done/ - Line 191: references numbered folders
The table should align with the comprehensive guidance in OPERATIONAL-RULES.md.
📝 Proposed fix
-| **Tasks** | `delegation/tasks/1-backlog/` | `TASK-0030-task-name.md` |
+| **Tasks** | `delegation/tasks/[status-folder]/` | `TASK-0030-task-name.md` |Or show the full pattern with status folders:
-| **Tasks** | `delegation/tasks/1-backlog/` | `TASK-0030-task-name.md` |
+| **Tasks** | `delegation/tasks/{1-backlog,2-todo,3-in-progress,5-done}/` | `TASK-0030-task-name.md` |🤖 Prompt for AI Agents
In @.claude/agents/AGENT-TEMPLATE.md around lines 227 - 240, Update the Tasks
entry in the "File Location Standards (MANDATORY)" table in AGENT-TEMPLATE.md so
it reflects the full folder pattern used elsewhere (not just
delegation/tasks/1-backlog/); replace the single example with the canonical
pattern (e.g., delegation/tasks/{number}-{status}/) or list the status folders
(2-todo/, 3-in-progress/, 5-done/, etc.) to match OPERATIONAL-RULES.md and other
references in this template.
| **Template Version**: 1.2.0 | ||
| **Last Updated**: 2025-01-28 |
There was a problem hiding this comment.
Fix the year in the Last Updated date.
The Last Updated date shows 2025-01-28, but the PR was created on 2026-01-28 (per PR objectives). The year appears to be incorrect.
📅 Proposed fix
**Template Version**: 1.2.0
-**Last Updated**: 2025-01-28
+**Last Updated**: 2026-01-28
**Project**: agentive-starter-kit🤖 Prompt for AI Agents
In @.claude/agents/AGENT-TEMPLATE.md around lines 302 - 303, Update the "Last
Updated" date in the AGENT-TEMPLATE header from 2025-01-28 to the correct PR
creation date 2026-01-28 by editing the "Last Updated" line (the header block
containing "Template Version" and "Last Updated") so it reads **Last Updated:
2026-01-28**; leave "Template Version" unchanged.
| **Version**: 2.1 | ||
| **Last Updated**: 2025-01-28 |
There was a problem hiding this comment.
Fix the year in the Last Updated date.
Same issue as the template file: the Last Updated date shows 2025-01-28, but the PR was created on 2026-01-28. The year should be 2026.
📅 Proposed fix
**Version**: 2.1
-**Last Updated**: 2025-01-28
+**Last Updated**: 2026-01-28
**Applies To**: ALL agents in this project📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| **Version**: 2.1 | |
| **Last Updated**: 2025-01-28 | |
| **Version**: 2.1 | |
| **Last Updated**: 2026-01-28 |
🤖 Prompt for AI Agents
In @.claude/agents/OPERATIONAL-RULES.md around lines 3 - 4, Update the "Last
Updated" metadata in .claude/agents/OPERATIONAL-RULES.md from "2025-01-28" to
"2026-01-28": locate the header block containing "**Version**: 2.1" and "**Last
Updated**: 2025-01-28" and change the date string to 2026-01-28 so the file
reflects the PR creation date.
Summary
AGENT-TEMPLATE.md(inherited by all new agents)OPERATIONAL-RULES.md(applies to all agents).claude/instead of proper locationsMotivation
In downstream projects, agents were creating ADRs in
.claude/directory instead ofdocs/decisions/adr/. This happened because agent instructions didn't explicitly specify file locations.Adding explicit standards to:
Changes
AGENT-TEMPLATE.md
OPERATIONAL-RULES.md
Test plan
🤖 Generated with Claude Code