project-structure-governance

Project Structure Governance

Purpose

Keep the repository understandable after the agent leaves. Treat structure, temporary artifacts, test scripts, and documentation entrypoints as part of the deliverable, not as cleanup someone else will do later.

Repository state

1. Read references/project-activity-contract.md.
2. Identify the project type, existing conventions, and current documentation entrypoint (README.md, docs/README.md, RUNBOOK.md, AGENTS.md, CLAUDE.md, or equivalent).
3. Inspect the repo root and common scratch locations for clutter: one-off scripts, generated outputs, screenshots, temp logs, duplicate instructions, abandoned migration helpers, and stale test harnesses.
4. Confirm where temporary/test artifacts should live for this repo. Prefer an existing convention; otherwise use a dedicated ignored workspace such as .agent-work/, .tmp/agent/, or tools/agent/ depending on project norms.
5. Record any required cleanup, consolidation, or documentation-entrypoint work before implementation expands the file surface.

Structure rules

1. Structure contract. Define or verify the top-level repo map: source, tests, tools, docs, scripts, infra, assets, fixtures, generated artifacts, and agent-only workspace.
2. Artifact routing. Route every new file before creating it: production source, test fixture, reusable tool, temporary experiment, generated output, documentation, or project memory.
3. Temporary isolation. Put throwaway scripts, debug probes, generated logs, screenshots, benchmark scratch, and exploratory outputs in the dedicated agent/test workspace. Do not place them in repo root.
4. Reusable promotion. Promote a temporary script only if it has a stable name, documented purpose, safe flags, validation command, owner, and a permanent home such as tools/, scripts/, tests/fixtures/, or docs/examples/.
5. Documentation entrypoint. Maintain one canonical entrypoint that links outward: README for project overview, docs/README.md for deep docs when needed, and one runbook/index for operation. Avoid multiple competing “START_HERE”, “HOW_TO”, “FINAL”, “NEW_README”, or duplicate setup files.
6. Runbook hygiene. If operational commands, install steps, local dev setup, release, rollback, or incident response changed, update the canonical runbook/index instead of adding a standalone note.
7. Root cleanliness check. Before handoff, verify the repo root contains only intentional files. Move, delete, or document anything temporary according to the contract.
8. Graph update. Hand documentation changes to documentation-graph-curator so Obsidian memory points to the canonical entrypoint and does not preserve obsolete instructions as current truth.