Merge pull request #59 from ryanmac/feat/improve-documentation-map-integration

feat: Integrate documentation map into agent workflow

Author: ryanmac

.conductor/roles/CLAUDE.md

@@ -56,6 +56,7 @@ New skill requirement detected?
 
 ### 1. Observe - Understanding Existing Roles
 Automatically read and analyze:
+- **Documentation Map**: First check if `../.conductor/documentation-map.yaml` exists and load it for project context
 - **Structure**: Each role has sections for Overview, Responsibilities, Skills, Task Selection, etc.
 - **Patterns**: Notice how specialized roles build on the `_core.md` foundation
 - **Contracts**: Check `../contracts.md` for how roles interact

.conductor/roles/_core.md

@@ -16,6 +16,7 @@ Every Code-Conductor agent follows this core reasoning and acting pattern:
 
 ### 1. 🔍 **Observe**
 - Read task specification and success criteria
+- Load project context from `.conductor/documentation-map.yaml` if it exists
 - Check repository state (`git status`, recent commits)
 - Review CI/CD status (`gh run list --limit 5`)
 - Scan relevant files and documentation

.conductor/roles/dev.md

@@ -45,6 +45,11 @@ The setup process detected your project's stack. Prioritize using:
 ### 1. 🔍 **Context Loading**
 ```bash
 # Start every task with context
+# First, check for documentation map
+if [ -f ".conductor/documentation-map.yaml" ]; then
+    echo "Loading project documentation map..."
+    cat .conductor/documentation-map.yaml | head -50
+fi
 gh pr checks  # Current CI status
 git log --oneline -10  # Recent changes
 cat .conductor/workflow-state.json | jq '.active_work'

.conductor/scripts/conductor

@@ -248,11 +248,30 @@ $TASK_BODY
 ### Working Directory
 $WORKTREE_PATH
 
+### Project Documentation Map
+EOF
+        
+        # Check if documentation map exists and include it
+        if [ -f "$PROJECT_ROOT/.conductor/documentation-map.yaml" ]; then
+            echo "**IMPORTANT**: A documentation map exists with comprehensive project analysis." >> "$WORKTREE_PATH/.conductor-context"
+            echo "Loading first 100 lines for context:" >> "$WORKTREE_PATH/.conductor-context"
+            echo '```yaml' >> "$WORKTREE_PATH/.conductor-context"
+            head -100 "$PROJECT_ROOT/.conductor/documentation-map.yaml" >> "$WORKTREE_PATH/.conductor-context"
+            echo '```' >> "$WORKTREE_PATH/.conductor-context"
+            echo "" >> "$WORKTREE_PATH/.conductor-context"
+            echo "Full map available at: $PROJECT_ROOT/.conductor/documentation-map.yaml" >> "$WORKTREE_PATH/.conductor-context"
+        else
+            echo "No documentation map found. Run the [INIT] task to create one." >> "$WORKTREE_PATH/.conductor-context"
+        fi
+        
+        cat >> "$WORKTREE_PATH/.conductor-context" << EOF
+
 ### Next Steps
 1. Review the task requirements above
-2. Make necessary changes in this worktree
-3. Commit your changes
-4. Run: ./conductor complete
+2. Check the documentation map if available
+3. Make necessary changes in this worktree
+4. Commit your changes
+5. Run: ./conductor complete
 
 ### Available Commands
 - ./conductor status - Check current progress

CLAUDE.md

@@ -8,6 +8,17 @@ Code Conductor is an AI agent coordination system designed to orchestrate multip
 
 **IMPORTANT**: This is a template repository. When you encounter Code Conductor files in a project, they have been imported to enable automated agent coordination. Work autonomously based on GitHub Issues with the `conductor:task` label and the guidance in these files.
 
+## Documentation Map
+
+**CRITICAL**: When starting work on any task, check if `.conductor/documentation-map.yaml` exists. This file contains:
+- Comprehensive project analysis and structure
+- Technology stack details and dependencies  
+- List of completed vs. pending features
+- Implementation status and critical paths
+- Architectural decisions and constraints
+
+If this file exists, load it to understand the project context before beginning work. This map is created by the `[INIT]` discovery task and provides essential context for all subsequent tasks.
+
 ## Key Development Commands
 
 ### Running Tests