PHP - Dossier for AI Coding Agents

<!-- Blog Post: Project Dossier Launch -->
<article class="project-dossier-launch">
    <h1>Stop Letting Your AI Guess Your Codebase. Meet Project Dossier.</h1>

    <div class="lead-paragraph">
        <p>If you have ever unleashed an AI Coding Assistant (like Gemini, Claude, or GitHub Copilot) onto an existing PHP codebase, you know the exhilarating feeling of asking it to build a new feature. And then... you know the crushing disappointment that follows ten seconds later.</p>
    </div>

    <h2>The "Playing Go Fish" Phase</h2>
    <p>A few months ago, I was working on a mid-sized, slightly battle-scarred PHP application. I booted up my favorite AI coding agent and asked a simple question: <em>"Can you add a 'reset password' endpoint to the User module?"</em></p>
    
    <p>Instead of writing code, I watched the AI embark on a token-burning expedition that I had seen a hundred times before.</p>
    
    <ul>
        <li><strong>First, it played "Find the Controller":</strong> It ran <code>find . -name "*Controller*.php"</code>. The terminal spat out 200 files. The AI panicked and tried to <code>cat</code> three random ones to figure out the namespace structure.</li>
        <li><strong>Then, it played "Find the Route":</strong> It grepped for <code>Route::post</code>. But this project used a legacy XML routing file. The AI confidently hallucinated a <code>routes/web.php</code> file and tried to append code to a file that didn't exist.</li>
        <li><strong>Finally, it ignored the House Rules:</strong> After ten minutes of corrections, it finally wrote the controller logic. But it used raw SQL queries instead of the project's mandated Entity classes, and it tried to render a React component instead of a Twig template.</li>
    </ul>

    <p>After watching this happen across multiple projects, it hit me: <strong>AI agents are terrible at contextual hide-and-seek.</strong></p>
    
    <p>When a human jumps into a new codebase, we click around. We look at the folder structure. We read a `BaseController` to see how things wire up. But when an LLM has to do this via terminal commands, it burns massive amounts of its context window just trying to figure out which way is up. It pays a massive "Token Tax" just to discover what we already know.</p>

    <h2>The Agent-First Solution: The Mission Map</h2>
    <p>I realized we needed to stop treating AI agents like junior developers who should "figure it out," and start treating them like highly capable machines that need a precise, pre-compiled map.</p>
    <p>That's why I built <strong>Project Dossier</strong>.</p>
    
    <p>Project Dossier is a zero-dependency CLI toolkit that statically analyzes your entire PHP architecture and generates two essential, high-signal files: <strong>PROJECT_DOSSIER.md</strong> and <strong>PROJECT_AUDIT.md</strong>.</p>
    
    <p>Unlike standard documentation which is wordy and written to be read by humans, these files are designed exclusively for AI ingestion. They contain:</p>
    <ul>
        <li><strong>Machine-Readable Metadata:</strong> Embedded JSON blocks so the LLM knows the exact scale and framework instantly.</li>
        <li><strong>The Functional Trace Table:</strong> A side-by-side mapping of Route &rarr; Controller Method &rarr; View Template. The AI never has to guess how a feature connects again.</li>
        <li><strong>Agent Guidance (House Rules):</strong> Automated rules based on your specific code (e.g., "All logic here must extend BaseController" or "Use Twig, not raw PHP views").</li>
        <li><strong>Risk Heatmaps:</strong> Explicit warnings to the Agent about complex, fragile files it shouldn't touch without human permission.</li>
    </ul>

    <h2>Stop Pasting. Start Shipping.</h2>
    <p>By running a simple command (<code>php dossier.php generate:dossier /path/to/project</code>) and dropping the resulting map into your Cursor, Gemini CLI, or Claude chat, you completely bypass the grueling discovery phase.</p>

    <p>The AI knows exactly where every symbol lives, how the architecture flows, and what rules it must follow. No more running <code>find</code>. No more hallucinating routing files. Just instant, accurate code generation.</p>

    <p><strong><a href="https://github.com/startmd/dossier-for-ai-agents" target="_blank" rel="noopener noreferrer">Check out Project Dossier on GitHub today</a></strong>, and give your AI the map it deserves.</p>
</article>