File Placement Policy

File Placement Policy

Load this skill at session start if the project has .agentharness-guarded-paths.json. Read the file before touching anything.

Rule: check before creating

Before creating any new file or directory, check whether the target location is guarded:

python3 -c "
import json
d = json.load(open('.agentharness-guarded-paths.json'))
print('Root guarded:', d['guard_root_level_new_items'])
print('Guarded dirs:', d['guarded_dirs'])
"

If the path is guarded: stop and ask the user for permission.

What counts as guarded

• Any new file at the root level (when guard_root_level_new_items: true)
• Any file under src/, docs/, tests/, conf/, logs/, etc.
• Any root-level config file already listed in guarded_root_files

Asking for permission

"I need to create docs/architecture/NEW_SECTION.md to document X. This is in the guarded docs/ directory. May I proceed?"

Wait for an explicit yes/ok/go ahead response.

After getting permission: record it

Add the approved path to .agentharness-allowed-additions.txt:

echo "docs/architecture/NEW_SECTION.md" >> .agentharness-allowed-additions.txt

The pre-commit hook reads this file to allow the commit.

No guarded-paths file = early-stage project

If .agentharness-guarded-paths.json doesn't exist:

1. Run: python3 tools/analyze_structure.py . --recommend
2. Present the recommendations to the user.
3. If accepted, create the structure and generate the config: python3 tools/analyze_structure.py . --output .agentharness-guarded-paths.json

Pre-commit enforcement

The hook at tools/check-file-placement.sh runs automatically before every commit. If a staged file is in a guarded location and not in .agentharness-allowed-additions.txt, the commit is blocked with a clear message.

Reference

Full protocol: patterns/file-placement-policy/POLICY.md Analyzer: tools/analyze_structure.py Hook: tools/check-file-placement.sh