| name | agent-artifacts |
| description | Agent artifact placement conventions. Use when creating plans, tasks, research, reviews, brainstorms, or any agent-generated files. Ensures artifacts go to docs/.claude/ (gitignored) instead of polluting the repo. |
Agent Artifact Placement
Agent-generated files (plans, tasks, research, reviews, orchestration output) MUST go to docs/.claude/, never the repo root. This directory is gitignored per git-repo-standards.
Directory Structure
docs/.claude/
├── tasks/ # Todo lists, checklists, work tracking
├── plans/ # Implementation plans, design docs, architecture
├── research/ # Research results, analysis, findings
├── reviews/ # Consensus review reports, audit results
├── orchestration/ # Orchestration state, dispatch logs
└── brainstorms/ # Brainstorm sessions, ideation output
Rules
- NEVER write agent artifacts to the repo root (TODO.md, PLAN.md, etc.)
- ALWAYS use
docs/.claude/<subdir>/ for generated files
- CREATE subdirectories as needed — the structure above is the default set
- CHECK
.claude/fs-dev-settings.json for project-specific overrides
File Routing
| Artifact Type | Directory | Examples |
|---|
| Plans | docs/.claude/plans/ | implementation plans, design approaches, architecture docs |
| Tasks | docs/.claude/tasks/ | todo lists, checklists, work items |
| Research | docs/.claude/research/ | technical research, competitive analysis, findings |
| Reviews | docs/.claude/reviews/ | consensus review reports, code audits |
| Orchestration | docs/.claude/orchestration/ | multi-agent dispatch state, execution logs |
| Brainstorms | docs/.claude/brainstorms/ | brainstorm transcripts, ideation notes |
Project Settings
Projects can customize via .claude/fs-dev-settings.json:
{
"agentArtifacts": {
"baseDir": "docs/.claude",
"allowedSubdirs": [
"tasks", "plans", "orchestration",
"research", "reviews", "brainstorms"
]
}
}
If the settings file doesn't exist, use the defaults above.
What Is NOT an Agent Artifact
These belong at the repo root — do not redirect them:
CLAUDE.md, .claude.local.md — Claude Code configurationREADME.md, CHANGELOG.md, LICENSE — repo documentation.gitignore, .gitleaks.toml — repo configurationSECURITY.md, CONTRIBUTING.md, CODEOWNERS — repo standards- Source code, tests, configs — normal project files
