docs: consolidate developer workflow documentation into DEVELOPER_GUIDE.md

Author: PEZ

dev/DEVELOPER_GUIDE.md

@@ -2,6 +2,46 @@
 
 Welcome, Clojure cult member! This guide provides practical instructions for developing, testing, and contributing to the Calva MCP Server project. Pair programming, data-orientation, and functional thinking are encouraged throughout.
 
+## Documentation-Driven Development
+
+This project follows these principles:
+
+1. Define the API and interfaces first
+2. Document expected behaviors and edge cases
+3. Implement against the documentation
+4. Validate implementation against documentation
+5. Update documentation based on implementation insights
+6. Repeat
+
+This approach ensures that we have a clear destination before starting to code, and that our implementation aligns with our design intentions.
+
+## Interactive Development Workflow
+
+The project leverages ClojureScript's interactive development capabilities:
+- Use shadow-cljs for continuous hot reloading during development
+- Apply changes to the running extension without restarting
+- Utilize the REPL to experiment with and test code in real-time
+
+### Complete Workflow
+
+1. Start the REPL server:
+   ```sh
+   npm run watch
+   ```
+   - This only starts the server. The following steps must be performed by the human:
+2. Connect to the REPL using Calva (<kbd>Ctrl+Alt+C Ctrl+Alt+C</kbd>)
+3. Start the Extension Development Host (<kbd>F5</kbd> in VS Code)
+4. Activate the extension in the development host (run the command "Calva MCP Server: Say hello!" from Command Palette)
+5. Enjoy hot reloading and interactive development!
+
+### Human/AI Collaboration Model
+
+- **Initial development phase**: Human developer handles REPL connection and activation steps
+- **As functionality matures**: AI gradually leverages the interactive environment
+- **Eventually**: The AI assistant will use the very MCP server being developed
+
+This creates a bootstrap process where the tool we're building ultimately empowers the AI collaborating on its development.
+
 ## End-to-End (e2e) Testing
 
 To validate the extension in a real VS Code environment, use the provided Babashka task for e2e tests:
@@ -10,6 +50,9 @@ To validate the extension in a real VS Code environment, use the provided Babash
 bb run-e2e-tests-ws
 ```
 
+- The test runner will automatically download and use VS Code Insiders (it does not need to be installed).
+- **Important:** VS Code Insiders must not be running when you start the e2e tests, or the test runner will fail.
+
 This will:
 - Set up a test workspace
 - Launch VS Code with the extension and Joyride installed
@@ -21,16 +64,34 @@ Test runner logic: `e2e-test-ws/launch.js`, `e2e-test-ws/runTests.js`
 
 > Use this workflow before merging or publishing to ensure the extension works as expected in a real VS Code environment.
 
-## Development Workflow (Summary)
+## Testing Strategy
 
-1. Start the REPL server:
-   ```sh
-   npm run watch
-   ```
-2. Connect to the REPL using Calva (human action)
-3. Start the Extension Development Host (F5 in VS Code, human action)
-4. Activate the extension in the development host (human action)
-5. Enjoy hot reloading and interactive development!
+- **Unit tests**: Write tests for core functions (shadow-cljs automatically discovers and runs tests in namespaces ending with `-test`)
+- **Integration tests**: Test API endpoints and component interactions
+- **End-to-end tests**: Use the Babashka task as described above for full workflow validation
+- **Property-based tests**: Consider for robust behavior validation where appropriate
+
+## Commit and Documentation Practices
+
+- Make small, frequent commits with descriptive messages that tell the story of development
+- Keep code and documentation changes in sync
+- Ensure that each commit represents a coherent unit of work
+- Update the development log (`dev/DEVELOPMENT_LOG.md`) regularly with progress, decisions, and insights
+- Be super aware of when a decision point is reached. When a significant decision needs to be made, document the options and reasoning in the decision log (`dev/DECISION_LOG.md`) before proceeding.
+
+## Deployment and Distribution
+
+- Automated publishing workflow is configured in the project
+  - It includes linting, formatting check, unit testing and end-to-end testing
+- The extension will be available through VS Code Marketplace
+- Distribution occurs through standard VS Code extension mechanisms
+- Version compatibility information will be included in documentation
+
+## References
+
+- For architectural and protocol details, see `dev/MCP_OVERVIEW.md` and `dev/EVENT_LOOP_ARCHITECTURE.md`
+- For project requirements and philosophy, see `dev/PROJECT_REQUIREMENTS.md`
+- For template-based setup and onboarding, see `doc/TEMPLATE_README.md`
 
 ## More to Come
 

dev/PROJECT_REQUIREMENTS.md

@@ -141,60 +141,6 @@ Errors will be handled gracefully and returned in a structured format:
 
 ## 7. Development Approach
 
-### 7.1 Documentation Driven Development
-Following the principles of Documentation Driven Development:
-1. Define the API and interfaces first
-2. Document expected behaviors and edge cases
-3. Implement against the documentation
-4. Validate implementation against documentation
-5. Update documentation based on implementation insights
-6. Repeat
-
-Alongside this approach, the project will:
-- Make frequent, small commits with descriptive messages
-- Chain git commands (add, commit, push) for efficiency
-- Keep code and documentation changes in sync
-- Ensure that each commit represents a coherent unit of work
-- Maintain history that clearly tells the story of development
-
-### 7.2 Interactive Development
-The project will leverage ClojureScript's interactive development capabilities:
-- Use shadow-cljs for continuous hot reloading during development
-- Apply changes to the running extension without restarting
-- Utilize the REPL to experiment with and test code in real-time
-
-The development workflow follows these steps:
-1. **Start the REPL server**: Run `npm run watch` to start the nREPL server (this does not automatically connect the REPL)
-2. **Connect to the REPL**: Use Calva to connect to the running REPL server
-3. **Start the Extension Host**: Launch the Development Extension Host with F5
-4. **Activate the Extension**: Run a command that activates our extension in the host
-5. **Verify REPL Connection**: Confirm Calva is connected to the extension's REPL
-
-Development roles during this process:
-- **Initial development phase**: Human developer handles REPL connection and activation steps
-- **Development communication**: AI assistant explicitly requests human intervention when these steps are needed
-- **As functionality matures**: AI assistant will increasingly leverage the REPL capabilities
-- **Eventually**: The AI assistant will use the very MCP server being developed
-
-This approach creates a bootstrap process where the tool we're building (Calva MCP Server) will eventually empower the AI assistant collaborating on its development.
-
-### 7.3 Development Log
-
-The project will maintain a detailed development log to:
-- Track progress and decisions made during implementation
-- Record challenges encountered and solutions applied
-- Document insights gained throughout the development process
-- Serve as a historical record for future reference
-- Complement the PRD by documenting the actual path taken
-
-### 7.4 Testing Strategy
-- Unit tests for core functions
-- Integration tests for API endpoints
-- End-to-end tests for full workflows
-- Property-based tests for robust behavior validation
-
-### 7.5 Deployment and Distribution
-- Available through VS Code Marketplace
-- Clear installation and setup instructions
-- Version compatibility information
-- Updates managed through standard VS Code extension mechanisms
+The development approach for this project follows documentation-driven development, interactive development with REPL, comprehensive testing, and regular documentation updates.
+
+For detailed development workflow, testing procedures, and contributor guidelines, please refer to [DEVELOPER_GUIDE.md](./DEVELOPER_GUIDE.md).