chore: #60 - docs: Add comprehensive documentation for NL processing system

.claude/commands/conditional_docs.md

@@ -293,3 +293,16 @@ This prompt helps you determine what documentation you should read based on the
     - When understanding test coverage for app/server/tests/core/test_project_detector.py
     - When troubleshooting project detection test failures
     - When extending test coverage for issue formatter functionality
+
+- app_docs/feature-5e6a13af-nl-processing-docs.md
+  - Conditions:
+    - When understanding the comprehensive NL processing documentation structure
+    - When working with API documentation for nl_processor, issue_formatter, project_detector, or github_poster modules
+    - When creating or updating usage guides, architecture documentation, or examples for NL processing
+    - When implementing new documentation following the established patterns and structure
+    - When understanding how mermaid diagrams are used to document system architecture
+    - When creating working code examples or example input/output JSON files
+    - When enhancing README sections with technical documentation links
+    - When setting up project templates or scaffolding scripts (setup_new_project.sh, integrate_existing.sh)
+    - When troubleshooting documentation organization or cross-referencing between docs
+    - When understanding the documentation coverage for the tac-webbuilder project

.claude/commands/test.md

@@ -41,33 +41,33 @@ TEST_COMMAND_TIMEOUT: 5 minutes
 
 1. **Python Syntax Check**
    - Preparation Command: None
-   - Command: `cd app/server && uv run python -m py_compile server.py main.py core/*.py`
+   - Command: `cd projects/tac-webbuilder/app/server && uv run python -m py_compile server.py main.py core/*.py`
    - test_name: "python_syntax_check"
    - test_purpose: "Validates Python syntax by compiling source files to bytecode, catching syntax errors like missing colons, invalid indentation, or malformed statements"
 
 2. **Backend Code Quality Check**
    - Preparation Command: None
-   - Command: `cd app/server && uv run ruff check .`
+   - Command: `cd projects/tac-webbuilder/app/server && uv run ruff check .`
    - test_name: "backend_linting"
    - test_purpose: "Validates Python code quality, identifies unused imports, style violations, and potential bugs"
 
 3. **All Backend Tests**
    - Preparation Command: None
-   - Command: `cd app/server && uv run pytest tests/ -v --tb=short`
+   - Command: `cd projects/tac-webbuilder/app/server && uv run pytest tests/ -v --tb=short`
    - test_name: "all_backend_tests"
    - test_purpose: "Validates all backend functionality including file processing, SQL security, LLM integration, and API endpoints"
 
 ### Frontend Tests
 
 4. **TypeScript Type Check**
    - Preparation Command: None
-   - Command: `cd app/client && bun tsc --noEmit`
+   - Command: `cd projects/tac-webbuilder/app/client && bun tsc --noEmit`
    - test_name: "typescript_check"
    - test_purpose: "Validates TypeScript type correctness without generating output files, catching type errors, missing imports, and incorrect function signatures"
 
 5. **Frontend Build**
    - Preparation Command: None
-   - Command: `cd app/client && bun run build`
+   - Command: `cd projects/tac-webbuilder/app/client && bun run build`
    - test_name: "frontend_build"
    - test_purpose: "Validates the complete frontend build process including bundling, asset optimization, and production compilation"
 

.mcp.json

@@ -5,7 +5,7 @@
       "args": [
         "-y",
         "@anaisbetts/mcp-playwright@latest",
-        "/Users/Warmonger0/tac/tac-7/trees/afc2e0dd/playwright-mcp-config.json"
+        "/Users/Warmonger0/tac/tac-7/trees/5e6a13af/playwright-mcp-config.json"
       ]
     }
   }

app_docs/agentic_kpis.md

@@ -8,13 +8,13 @@ Summary metrics across all ADW runs.
 
 | Metric            | Value          | Last Updated                 |
 | ----------------- | -------------- | ---------------------------- |
-| Current Streak    | 16             | Tue Nov 11 07:44:49 PST 2025 |
-| Longest Streak    | 16             | Tue Nov 11 07:44:49 PST 2025 |
-| Total Plan Size   | 3641 lines     | Tue Nov 11 07:44:49 PST 2025 |
-| Largest Plan Size | 566 lines      | Tue Nov 11 07:44:49 PST 2025 |
-| Total Diff Size   | 33222 lines    | Tue Nov 11 07:44:49 PST 2025 |
-| Largest Diff Size | 8252 lines     | Tue Nov 11 07:44:49 PST 2025 |
-| Average Presence  | 1.00           | Tue Nov 11 07:44:49 PST 2025 |
+| Current Streak    | 17             | Mon Nov 11 11:00:28 PST 2025 |
+| Longest Streak    | 17             | Mon Nov 11 11:00:28 PST 2025 |
+| Total Plan Size   | 3895 lines     | Mon Nov 11 11:00:28 PST 2025 |
+| Largest Plan Size | 566 lines      | Mon Nov 11 11:00:28 PST 2025 |
+| Total Diff Size   | 41824 lines    | Mon Nov 11 11:00:28 PST 2025 |
+| Largest Diff Size | 8602 lines     | Mon Nov 11 11:00:28 PST 2025 |
+| Average Presence  | 1.00           | Mon Nov 11 11:00:28 PST 2025 |
 
 ## ADW KPIs
 
@@ -38,3 +38,4 @@ Detailed metrics for individual ADW workflow runs.
 | 2025-11-10 | 23bd15ec | 49           | /chore      | 1        | 114               | 180/7/5                         | Mon Nov 10 19:58:20 PST 2025 |                              |
 | 2025-11-10 | 0a6c3431 | 53           | /chore      | 1        | 169               | 873/10/10                       | Mon Nov 10 20:27:00 PST 2025 |                              |
 | 2025-11-11 | afc2e0dd | 58           | /feature    | 1        | 265               | 322/1/6                         | Tue Nov 11 07:44:49 PST 2025 |                              |
+| 2025-11-11 | 5e6a13af | 60           | /chore      | 1        | 254               | 8572/30/63                      | Mon Nov 11 11:00:28 PST 2025 |                              |

app_docs/feature-5e6a13af-nl-processing-docs.md

@@ -0,0 +1,176 @@
+# Natural Language Processing Documentation
+
+**ADW ID:** 5e6a13af
+**Date:** 2025-11-11
+**Specification:** specs/issue-60-adw-5e6a13af-sdlc_planner-nl-processing-docs.md
+
+## Overview
+
+This chore created comprehensive documentation for the tac-webbuilder natural language processing system. The documentation includes API references, usage guides, architecture documentation with diagrams, and practical examples to help developers understand and use the NL processing capabilities effectively.
+
+## What Was Built
+
+- Complete API reference documentation for all NL processing modules
+- Comprehensive usage guide with examples and best practices
+- Architecture documentation with mermaid diagrams showing system design
+- Working code examples demonstrating basic, advanced, and edge case scenarios
+- JSON files with example inputs and outputs
+- Updated README with NL processing section and documentation links
+- Enhanced inline code comments in core modules
+
+## Technical Implementation
+
+### Files Modified
+
+- `projects/tac-webbuilder/README.md`: Added comprehensive Natural Language Processing section with quick examples, setup requirements, and links to all documentation
+- `projects/tac-webbuilder/app/server/core/nl_processor.py`: Enhanced docstrings and inline comments for intent analysis logic
+- `projects/tac-webbuilder/app/server/core/issue_formatter.py`: Added detailed comments explaining template system
+- `projects/tac-webbuilder/app/server/core/project_detector.py`: Added comments for detection heuristics and complexity calculation
+
+### New Documentation Files Created
+
+- `projects/tac-webbuilder/docs/api.md`: Main API documentation hub (505 lines)
+- `projects/tac-webbuilder/docs/api/nl-processing.md`: Complete API reference with 948 lines documenting all modules, functions, parameters, return types, and exceptions
+- `projects/tac-webbuilder/docs/guides/nl-processing-guide.md`: Step-by-step usage guide (822 lines) with prerequisites, quick start, advanced examples, configuration, best practices, and troubleshooting
+- `projects/tac-webbuilder/docs/architecture.md`: Main architecture documentation hub (436 lines)
+- `projects/tac-webbuilder/docs/architecture/nl-processing-architecture.md`: System architecture (766 lines) with mermaid diagrams showing component relationships and data flow
+- `projects/tac-webbuilder/docs/cli.md`: CLI documentation (291 lines)
+- `projects/tac-webbuilder/docs/examples.md`: Examples overview (453 lines)
+- `projects/tac-webbuilder/docs/web-ui.md`: Web UI documentation (403 lines)
+- `projects/tac-webbuilder/docs/troubleshooting.md`: Troubleshooting guide (609 lines)
+
+### Example Code Files Created
+
+- `projects/tac-webbuilder/examples/nl-processing/README.md`: Examples overview and index (168 lines)
+- `projects/tac-webbuilder/examples/nl-processing/basic_usage.py`: Minimal working example demonstrating complete NL processing workflow (123 lines)
+- `projects/tac-webbuilder/examples/nl-processing/advanced_usage.py`: Complex scenarios with error handling and customization (281 lines)
+- `projects/tac-webbuilder/examples/nl-processing/edge_cases.py`: Edge case handling examples with explanations (321 lines)
+- `projects/tac-webbuilder/examples/nl-processing/example_inputs.json`: Sample natural language inputs for different scenarios (102 lines)
+- `projects/tac-webbuilder/examples/nl-processing/example_outputs.json`: Corresponding generated GitHubIssue outputs (290 lines)
+
+### Template Files Created
+
+- `projects/tac-webbuilder/templates/existing_webapp/integration_guide.md`: Guide for integrating ADW into existing webapps (222 lines)
+- `projects/tac-webbuilder/templates/template_structure.json`: Template structure definition (74 lines)
+- Multiple project templates:
+  - `projects/tac-webbuilder/templates/new_webapp/nextjs/`: Complete Next.js template with MCP configuration
+  - `projects/tac-webbuilder/templates/new_webapp/react-vite/`: React + Vite template with MCP configuration
+  - `projects/tac-webbuilder/templates/new_webapp/vanilla/`: Vanilla JavaScript template
+
+### Scripts Created
+
+- `projects/tac-webbuilder/scripts/setup_new_project.sh`: Interactive script for scaffolding new projects (307 lines)
+- `projects/tac-webbuilder/scripts/integrate_existing.sh`: Script for integrating ADW into existing projects (438 lines)
+
+### Key Changes
+
+- Created comprehensive API documentation covering all public methods, classes, parameters, return types, and exceptions for nl_processor, issue_formatter, project_detector, github_poster, and data_models modules
+- Developed step-by-step usage guide with prerequisites, quick start examples, advanced usage patterns, configuration options, best practices, and troubleshooting sections
+- Designed architecture documentation with mermaid diagrams illustrating component relationships, data flow pipeline, and integration points
+- Implemented working Python examples demonstrating basic usage, advanced scenarios, and edge case handling
+- Created JSON example files showing sample inputs and expected outputs for different request types
+- Enhanced README with comprehensive NL processing section including quick examples, supported project types table, workflow recommendations matrix, and links to all documentation
+- Added detailed inline code comments explaining intent analysis logic, template system, and detection heuristics
+
+## How to Use
+
+### Accessing Documentation
+
+All documentation is organized under `projects/tac-webbuilder/docs/`:
+
+1. **Start with the README**: Read the Natural Language Processing section in `projects/tac-webbuilder/README.md` for a quick overview
+2. **API Reference**: For detailed API documentation, see `projects/tac-webbuilder/docs/api/nl-processing.md`
+3. **Usage Guide**: For step-by-step instructions, see `projects/tac-webbuilder/docs/guides/nl-processing-guide.md`
+4. **Architecture**: To understand system design, see `projects/tac-webbuilder/docs/architecture/nl-processing-architecture.md`
+5. **Examples**: For working code, explore `projects/tac-webbuilder/examples/nl-processing/`
+
+### Running Examples
+
+```bash
+cd projects/tac-webbuilder/examples/nl-processing
+export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx"
+
+# Run basic example
+python basic_usage.py
+
+# Run advanced example
+python advanced_usage.py
+
+# Run edge cases example
+python edge_cases.py
+```
+
+### Reading Documentation Flow
+
+For new developers:
+1. Start with README's NL Processing section for high-level overview
+2. Read the Usage Guide for practical step-by-step instructions
+3. Review the Architecture documentation to understand system design
+4. Explore the API Reference for detailed method documentation
+5. Try the Examples to see working code
+
+For specific tasks:
+- Adding new functionality: Read Architecture + API Reference
+- Troubleshooting issues: Read Troubleshooting section in Usage Guide
+- Understanding a specific module: Read relevant API Reference section
+- Learning best practices: Read Best Practices in Usage Guide
+
+## Configuration
+
+No additional configuration required. The documentation is in standard markdown format and can be viewed in any markdown viewer or directly on GitHub.
+
+## Testing
+
+The documentation was validated by:
+- Creating all required files as specified in the chore
+- Ensuring all markdown files are properly formatted
+- Validating that example Python scripts are syntactically correct
+- Verifying JSON files have valid syntax
+- Confirming all cross-references and links work correctly
+- Running all existing tests to ensure zero regressions (all tests passing)
+
+## Notes
+
+### Documentation Coverage
+
+The documentation covers:
+- All public APIs in nl_processor, issue_formatter, project_detector, github_poster, and data_models modules
+- Complete workflow from natural language input to GitHub issue creation
+- Configuration and setup requirements
+- Error handling and troubleshooting
+- Best practices for writing effective natural language requests
+- Examples for common use cases and edge cases
+
+### Mermaid Diagrams
+
+The architecture documentation includes several mermaid diagrams:
+- Component diagram showing module relationships
+- Data flow diagram showing the complete pipeline
+- Integration diagram showing external dependencies (Claude API, GitHub CLI)
+
+### Example Code Quality
+
+All example Python scripts:
+- Are executable and include proper imports
+- Use realistic scenarios (not placeholder foo/bar examples)
+- Include comprehensive error handling
+- Have detailed comments explaining each step
+- Demonstrate both successful and error cases
+
+### Total Lines Added
+
+This chore added over 8,300 lines of documentation, examples, templates, and scripts:
+- Documentation: ~4,800 lines
+- Examples: ~1,600 lines
+- Templates: ~1,300 lines
+- Scripts: ~745 lines
+- README updates: ~118 lines
+
+### Future Enhancements
+
+Potential documentation improvements:
+- Add video tutorials or animated GIFs demonstrating the workflow
+- Create Jupyter notebooks for interactive exploration
+- Add integration guides for specific frameworks beyond what's covered
+- Create API client libraries for other languages (TypeScript, Go, etc.)
+- Add performance benchmarking documentation

playwright-mcp-config.json

@@ -6,7 +6,7 @@
     },
     "contextOptions": {
       "recordVideo": {
-        "dir": "./videos",
+        "dir": "/Users/Warmonger0/tac/tac-7/trees/5e6a13af/videos",
         "size": {
           "width": 1920,
           "height": 1080

projects/tac-webbuilder/.mcp.json.sample

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@latest",
+        "--isolated",
+        "--config",
+        "./playwright-mcp-config.json"
+      ]
+    }
+  }
+}