Refactor INITIAL.md to streamline PHP agentic framework details and remove outdated INITIAL_EXAMPLE.md

.claude/commands/execute-prp.md

@@ -0,0 +1,40 @@
+# Execute BASE PRP
+
+Implement a feature using using the PRP file.
+
+## PRP File: $ARGUMENTS
+
+## Execution Process
+
+1. **Load PRP**
+   - Read the specified PRP file
+   - Understand all context and requirements
+   - Follow all instructions in the PRP and extend the research if needed
+   - Ensure you have all needed context to implement the PRP fully
+   - Do more web searches and codebase exploration as needed
+
+2. **ULTRATHINK**
+   - Think hard before you execute the plan. Create a comprehensive plan addressing all requirements.
+   - Break down complex tasks into smaller, manageable steps using your todos tools.
+   - Use the TodoWrite tool to create and track your implementation plan.
+   - Identify implementation patterns from existing code to follow.
+
+3. **Execute the plan**
+   - Execute the PRP
+   - Implement all the code
+
+4. **Validate**
+   - Run each validation command
+   - Fix any failures
+   - Re-run until all pass
+
+5. **Complete**
+   - Ensure all checklist items done
+   - Run final validation suite
+   - Report completion status
+   - Read the PRP again to ensure you have implemented everything
+
+6. **Reference the PRP**
+   - You can always reference the PRP again if needed
+
+Note: If validation fails, use error patterns in PRP to fix and retry.

.claude/commands/generate-prp.md

@@ -0,0 +1,88 @@
+# Create PRP
+
+YOU MUST DO IN-DEPTH RESEARCH, FOLLOW THE <RESEARCH PROCESS>
+
+<RESEARCH PROCESS>
+
+   - Don't only research one page, and don't use your own webscraping tool - instead scrape many relevant pages from all documentation links mentioned in the initial.md file
+   - Take my tech as sacred truth, for example if I say a model name then research that model name for LLM usage - don't assume from your own knowledge at any point
+   - When I say don't just research one page, I mean do incredibly in-depth research, like to the ponit where it's just absolutely ridiculous how much research you've actually done, then when you creat the PRD document you need to put absolutely everything into that including INCREDIBLY IN DEPTH CODE EXMAPLES so any AI can pick up your PRD and generate WORKING and COMPLETE production ready code.
+
+</RESEARCH PROCESS>
+
+## Feature file: $ARGUMENTS
+
+Generate a complete PRP for general feature implementation with thorough research. Ensure context is passed to the AI agent to enable self-validation and iterative refinement. Read the feature file first to understand what needs to be created, how the examples provided help, and any other considerations.
+
+The AI agent only gets the context you are appending to the PRP and training data. Assuma the AI agent has access to the codebase and the same knowledge cutoff as you, so its important that your research findings are included or referenced in the PRP. The Agent has Websearch capabilities, so pass urls to documentation and examples.
+
+## Research Process
+
+1. **Codebase Analysis**
+   - Search for similar features/patterns in the codebase
+   - Identify files to reference in PRP
+   - Note existing conventions to follow
+   - Check test patterns for validation approach
+
+2. **External Research**
+   - Search for similar features/patterns online
+   - Library documentation (include specific URLs)
+   - Implementation examples (GitHub/StackOverflow/blogs)
+   - Best practices and common pitfalls
+   - Don't only research one page, and don't use your own webscraping tool - instead scrape many relevant pages from all documentation links mentioned in the initial.md file
+   - Take my tech as sacred truth, for example if I say a model name then research that model name for LLM usage - don't assume from your own knowledge at any point
+   - When I say don't just research one page, I mean do incredibly in-depth research, like to the ponit where it's just absolutely ridiculous how much research you've actually done, then when you creat the PRD document you need to put absolutely everything into that including INCREDIBLY IN DEPTH CODE EXMAPLES so any AI can pick up your PRD and generate WORKING and COMPLETE production ready code.
+
+3. **User Clarification** (if needed)
+   - Specific patterns to mirror and where to find them?
+   - Integration requirements and where to find them?
+
+## PRP Generation
+
+Generate 2 Phases
+
+Phase 1: Skeleton Code with detailed implementation comments on exactly how to implement it
+Phase 2: Full and complete production ready code with every single feature fully implemented
+
+Using PRPs/templates/prp_base.md as template:
+
+### Critical Context to Include and pass to the AI agent as part of the PRP
+- **Documentation**: URLs with specific sections
+- **Code Examples**: Real snippets from codebase
+- **Gotchas**: Library quirks, version issues
+- **Patterns**: Existing approaches to follow
+
+### Implementation Blueprint
+- Start with pseudocode showing approach
+- Reference real files for patterns
+- Include error handling strategy
+- list tasks to be completed to fullfill the PRP in the order they should be completed
+
+### Validation Gates (Must be Executable) eg for python
+```bash
+# Syntax/Style
+ruff check --fix && mypy .
+
+# Unit Tests
+uv run pytest tests/ -v
+
+```
+
+*** CRITICAL AFTER YOU ARE DONE RESEARCHING AND EXPLORING THE CODEBASE BEFORE YOU START WRITING THE PRP ***
+
+*** ULTRATHINK ABOUT THE PRP AND PLAN YOUR APPROACH THEN START WRITING THE PRP ***
+
+## Output
+Save as: `PRPs/{phase-1-feature-name}.md`
+Save as: `PRPs/{phase-2-feature-name}.md`
+
+## Quality Checklist
+- [ ] All necessary context included
+- [ ] Validation gates are executable by AI
+- [ ] References existing patterns
+- [ ] Clear implementation path
+- [ ] Error handling documented
+
+Score the PRP on a scale of 1-10 (confidence level to succeed in one-pass implementation using claude codes)
+
+Remember: The goal is one-pass implementation success through comprehensive context.

.claude/hooks/README.md

@@ -0,0 +1,50 @@
+# Claude Code Hooks
+
+This directory contains Claude Code hooks that automatically provide relevant documentation before coding operations.
+
+## Documentation Hook
+
+The `doc-reader-hook.py` script automatically:
+
+1. **Extracts keywords** from your code (imports, API calls, etc.)
+2. **Searches** the `/research/` directory for relevant documentation
+3. **Shows documentation** to Claude before writing/editing files
+4. **Ensures accuracy** by providing up-to-date API documentation
+
+## Setup
+
+The hooks are automatically configured via `.claude/settings.json`. When you use Write, Edit, MultiEdit, or Task tools, the hook will:
+
+- Search for relevant docs in the `research/` folder
+- Display documentation excerpts to Claude
+- Block the operation initially to show the docs
+- Allow Claude to retry with the documentation context
+
+## How It Works
+
+```mermaid
+graph LR
+    A[Write/Edit Code] --> B[Hook Extracts Keywords]
+    B --> C[Search research/ Directory]
+    C --> D[Find Relevant Docs]
+    D --> E[Show Docs to Claude]
+    E --> F[Claude Writes Better Code]
+```
+
+## Research Directory Structure
+
+The hook expects documentation in this structure:
+```
+research/
+├── openai/
+│   ├── quickstart.md
+│   ├── chat-completions.md
+│   └── function-calling.md
+├── pydantic-ai/
+│   ├── agents.md
+│   └── tools.md
+└── other-apis/
+    └── docs.md
+```
+
+This ensures Claude always has the latest, accurate documentation when implementing features.