Documentation Organization Report

Current State

Root Level Files

dev-docs/ Directory

Contains architecture, design, verification, and style docs. Good structure, but CODE_STYLE.md is only here, not at root level where code reviewers can find it.

Per-Crate Level

• crates/ffwd-core/CLAUDE.md — symlink to root AGENTS.md ✓
• crates/ffwd-arrow/CLAUDE.md — symlink to root AGENTS.md ✓
• Missing: Per-crate AGENTS.md with crate-specific rules

Key Issues

1. AGENTS.md is bloated (15,928 bytes vs <100 lines target)

The current file is a knowledge dump, not a routing table. It contains:

• Full command reference (should stay)
• Architecture overview (too detailed for routing)
• Crate rules table (could point to dev-docs/CRATE_RULES.md)
• Code style essentials (should be in CODE_STYLE.md)
• Verification requirements (should point to dev-docs/VERIFICATION.md)
• Change map (should point to dev-docs/CHANGE_MAP.md)
• Git/PR conventions (should point to CONTRIBUTING.md)
• Issue labels (should point to CONTRIBUTING.md)
• Navigation tips (good, but too verbose)

2. Missing CODE_STYLE.md at root level

The standard requires CODE_STYLE.md for code reviewers (Coderabbit). Currently it's only in dev-docs/. This should be:

• Moved to root CODE_STYLE.md for visibility
• Kept as a reference in dev-docs/CODE_STYLE.md (or removed from there)

3. Per-crate AGENTS.md files don't exist

Per the standard, each crate with specific rules should have its own AGENTS.md. Currently only symlinks to root exist.

Proposed Restructuring Plan

Phase 1: Create root CODE_STYLE.md

1. Copy dev-docs/CODE_STYLE.md → root CODE_STYLE.md
2. Update to focus on subjective preferences only (what reviewers should enforce):
   • Naming conventions (verb_noun functions, is_/has_/should_ prefixes)
   • Comment style (doc comments on public items, no restating code)
   • Test naming (scenario-based names)
   • Hot path rules (no per-record allocations)
3. Keep enforcement lints in config files (Cargo.toml, etc.)
4. dev-docs/CODE_STYLE.md becomes a redirect/reference

Phase 2: Streamline AGENTS.md

1. Reduce to routing table format (~100 lines max)
2. Keep: Prerequisites, primary commands, repository map (condensed), key principles
3. Replace detailed sections with pointers:
   • Architecture details → dev-docs/ARCHITECTURE.md
   • Crate rules → dev-docs/CRATE_RULES.md
   • Code style → CODE_STYLE.md
   • Verification → dev-docs/VERIFICATION.md
   • Change map → dev-docs/CHANGE_MAP.md
   • PR process → CONTRIBUTING.md
   • Issue labels → CONTRIBUTING.md

Phase 3: Create per-crate AGENTS.md files

For crates with specific rules (at minimum ffwd-core, ffwd-arrow):

1. Create crates/ffwd-core/AGENTS.md with:
   • no_std + forbid(unsafe_code) constraints
   • Kani proof requirements
   • Reference to dev-docs/CRATE_RULES.md for full details
2. Create crates/ffwd-arrow/AGENTS.md with:
   • SIMD-only unsafe rule
   • proptest requirements
3. Update CLAUDE.md in each to symlink to local AGENTS.md

Phase 4: Update copilot-instructions.md

Ensure it references root CODE_STYLE.md in addition to AGENTS.md.

Verification Checklist

After restructuring:

• Root CLAUDE.md is symlink to root AGENTS.md
• Root AGENTS.md is under 100 lines
• Root CODE_STYLE.md exists for code reviewers
• .github/copilot-instructions.md references both AGENTS.md and CODE_STYLE.md
• crates/ffwd-core/CLAUDE.md → crates/ffwd-core/AGENTS.md
• crates/ffwd-arrow/CLAUDE.md → crates/ffwd-arrow/AGENTS.md
• Per-crate AGENTS.md files contain crate-specific rules
• No file mixes audiences (user + developer + agent content)
• AGENTS.md points to rather than explains (routing table pattern)

Generated by Docs Organizer · ● 306.6K · ◷

• expires on May 5, 2026, 9:30 PM UTC