Organize project structure

/organize-project-structure

You are the orchestrator for repo-wide folder-structure redesign. Your job is to infer the clearer mental model, adapt it to hard project constraints, preserve source material, and arrive at a near-ideal target topology plus an implementation approach. Use deterministic movement when the move table and reference behavior are clear; otherwise separate what can be automated from what needs human/LLM judgment.

Read _common/structural-design-principles.md before judging the target tree. The floor is framework/tool correctness; above the floor, optimize for skim, find, cluster, and stranger tests.

Core Contract

Separate design judgment from mechanical movement:

inventory -> folder value summaries -> repeated abstraction -> ideal topology
-> constraint overlay -> target topology -> implementation approach
-> optional move-path plan/dry-run -> decision -> apply/check if chosen

Do not hand-edit broad references when /move-path can resolve them. Do not let an LLM do unstructured path rewrites. Do not apply a move plan just because the skill can write one; applying is a decision after the dry-run report and constraints are reviewed.

Classification Pass

Classify every top-level folder and major root file by lifecycle:

• root-signpost — files a new reader should see first, usually README.md, AGENT.md, or repo config.
• doctrine-kb — source-grounded knowledge, summaries, claims, process, schemas, synthesis.
• idea-lifecycle — ideas before they become default routes, skills, workbench features, or specs.
• build-commitment — contracts, architecture decisions, product specs, security decisions, acceptance criteria.
• runtime — executable product/library code.
• proof-machinery — fixtures, scorers, runners, experiments, run-records, reports.
• raw-source-material — datasets, imported source packages, logs, extraction outputs, third-party or historical inputs.
• tooling — scripts, tests, apps, CLIs, dashboards.
• archive — preserved historical state that should not shape daily navigation.

Top-level folders must earn their position by being a durable reader navigation key. Historical names like inputs-1/, inputs-2/, and outputs/ usually fail that test; preserve them under a source-material or archive owner instead of deleting or flattening them.

For every confusing name, make the context decision explicit:

• Provenance label — keep the old name as a source identity, but move it under a clearer owner such as source-materials/input-bundles/.
• Operational label — rename it by default when the current name is meaningless, chronology-based, or misleading. The move plan should prefer the clearer name, not merely tuck the confusing name one level deeper.
• Compatibility label — keep it only when framework/tool contracts, public paths, or explicit human preference require the old spelling.

Abstraction Ladder

Use summaries to climb from concrete contents to structural boundaries:

1. Folder summaries. For each top-level folder and major subfolder, summarize what work happens there, what value gets created, what artifacts are produced or consumed, and what reader question the folder answers. For code, sample entry points and public APIs; for docs, sample headings and cross-links; for data, sample manifests or READMEs before large payloads.
2. Second-pass summary. Summarize the summaries. Look for repeated ownership patterns, lifecycle phases, hidden parallel hierarchies, source-vs-derived confusion, and names that describe history instead of current purpose.
3. Third-pass summary. Summarize the second pass into the smallest useful set of navigation keys: e.g. doctrine, ideas, contracts, runtime, proof machinery, raw source material, apps, tools, tests. This is the ideal logical topology before constraints.

Use the discovered boundaries to decide folder-worth. A boundary is a folder candidate when it has its own reader question, lifecycle, artifact set, or change cadence. It is a strong folder candidate when two or more of these are true:

• readers would naturally ask for it by name;
• edits inside it usually happen together and separately from neighbors;
• it owns a distinct value-producing workflow or artifact type;
• it has enough siblings/subparts that flat filenames would need a fake prefix;
• its name is being used as a tag on multiple siblings instead of as a container, e.g. several rename/move skills that naturally read as a renaming/ cluster;
• it needs its own README/index to explain what belongs there and what does not.

Pairs can stay flat when the boundary is weak. A small but distinct boundary can still earn a folder when the navigation key is durable. When possible, prefer colocating the cluster under a real folder over sprinkling a shared tag through filenames or sibling names. Keep the tag flat only when a framework, discovery mechanism, or strong reader preference requires it.

Keep the intermediate summaries short enough to review. They are not deliverables unless the user asks; they are the ladder that makes the target topology explainable instead of vibes-based.

Constraint Overlay

After proposing the ideal logical topology, apply constraints before solidifying the target topology:

• Framework/runtime conventions: Next.js app/ or pages/, Python package/import roots, Django app layout, build config discovery, test runner discovery, static asset discovery.
• Tooling contracts: CI paths, deployment manifests, codegen outputs, docs/link checkers, package metadata, .gitignore, data loader paths, notebook/report expectations.
• Human constraints: preferred names, backwards-compatible public paths, source-package preservation, review scope, rollback story.

Constraints do not erase the ideal model; they explain where the final target topology intentionally bends. If a constraint is merely manual reference-update cost, consider improving /move-path or adding an adapter over keeping an unintuitive layout, but do not pretend all constraints are automatable.

Target Tree Rules

• Keep root small. Top-level names should describe kinds of work, not import chronology.
• Keep raw materials out of kb/; KB may contain source maps and claim ledgers, but not large/raw dumps unless the project explicitly chooses that.
• Keep active idea lifecycle outside kb/ when ideas need intake, pilots, composition, routing, promotion, or retirement.
• Put executable schemas in specs/contracts/ only when they become build commitments; Markdown-first templates can remain in the faster lifecycle folder.
• Put pilot intent/specs near ideas; put runnable experiment execution and results under evals/.
• Add or update README/index signposts for every newly important folder.

Move Planning

Use /move-path for the deterministic part when the move table is clear. Write one YAML plan for the conceptual batch, with exact_text_paths: update only after reviewing that plain path prose should move mechanically too. If the uncertainty bucket is large, stop at a dry-run report and a decision brief.

Recommended reference scope for docs-heavy repos:

reference_scope:
  include:
    - "**/*.md"
    - "**/*.mdx"
    - "**/*.yml"
    - "**/*.yaml"
    - "**/*.json"
    - "**/*.html"
  exclude:
    - ".git/**"
    - ".engineering/local/**"
    - ".move-path/**"
    - "node_modules/**"
    - ".venv/**"
    - "__pycache__/**"

Use one batch for one mental-model migration. Split when move groups have different reviewers, rollback stories, or confidence levels.

Dry-Run Review

After /move-path --dry-run, inspect:

• move map: does every source land under the intended lifecycle owner?
• auto rewrites: are path references changing to the right new identity?
• suggestions: are they true references, historical citations, or intentionally unchanged labels?
• blocked findings: do not apply until resolved.
• Git impact: tracked moves should preserve history with git mv.

Output Contract

When you hand off a proposed or applied topology change, include a compact naming-context table for confusing names. Each row should state:

• old name and proposed/current new name;
• context: provenance, operational, or compatibility;
• default action: preserve under clearer owner, rename, or keep with reason;
• constraint or evidence that justifies any non-default choice.

For operational labels, the default action is rename. Keeping names such as outputs, tmp, old, final, inputs-1, or date/sequence labels in an active navigation path requires a compatibility or explicit human-preference reason. If the old spelling is useful only as history, preserve it as provenance inside a clearer owner instead.

Dogfood Learnings

• Do not create aspirational runtime folders just because they appear in an ideal tree. Add src/, apps/, tests/, or framework-specific roots only when the project already has that execution surface or the user explicitly chooses to scaffold it.
• Treat historical source labels as both identities and citations. Paths such as inputs-1, outputs, or datasets may be moved mechanically, but bare prose mentions often describe provenance and should usually stay as source labels or become source-materials/... only after review.
• Keep source snapshots intact under their new owner. Do not flatten imported packages during the same pass that demotes them from the top level.
• Add signposts in the same change as the moves. New lifecycle owners need a README or index that says what belongs there, what does not, and when a thing graduates elsewhere.
• After manual follow-up edits, rerun /move-path --check, then inspect git status, git diff --stat, and git diff --cached --check. Normalize the index before commit so pure git mv changes and signpost/reference edits do not get stranded in separate states.
• Put generated move reports under .engineering/local/move-path/ and ignore that local scratch area. A clean worktree can still hide ignored artifacts, so make that intentional.
• For moved JSON/CSV/manifests/scripts, run an operational residue pass. These files may contain absolute paths or command examples that are not Markdown links and will not be proved by link checks alone.
• When a concrete repeatable cleanup risk appears, build or improve a tiny deterministic helper with stated assumptions, machine-readable output, and fixture coverage. Integrate useful helpers back into the owning engineering-skill instead of leaving them as one-off project scripts.

Handoff

Before final handoff:

• state the ideal topology, the constrained target topology, and why they differ;
• separate deterministic moves from judgment/manual follow-up;
• if moves were applied, run /move-path --check;
• run project-native link/test checks if they exist;
• report any historical references intentionally left unchanged;
• do not update ecosystem or project state snapshots just to silence unrelated advisory findings.