Update framework configuration and clean up obsolete specs

Configuration updates: - Added .env.example template for environment variables - Updated README.md with better setup instructions (.env usage) - Enhanced .claude/settings.local.json with additional Bash permissions - Added .claude/CLAUDE.md framework documentation Spec cleanup: - Removed obsolete spec files (language_selection, mistral_extensible, template, theme_customization) - Consolidated app_spec.txt (Claude Clone example) - Added app_spec_model.txt as reference template - Added app_spec_library_rag_types_docs.txt - Added coding_prompt_library.md Framework improvements: - Updated agent.py, autonomous_agent_demo.py, client.py with minor fixes - Enhanced dockerize_my_project.py - Updated prompts (initializer, initializer_bis) with better guidance - Added docker-compose.my_project.yml example This commit consolidates improvements made during development sessions. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2025-12-25 12:53:14 +01:00
parent bf790b63a0
commit 2e33637dae
27 changed files with 3862 additions and 2378 deletions
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -0,0 +1,234 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+This is an autonomous coding agent framework that uses Claude Agent SDK with Linear integration for project management. The framework enables long-running autonomous development sessions where agents create complete applications from XML specifications.
+
+**Key Architecture**: Two-agent pattern (Initializer + Coding Agent) with Linear as the single source of truth for project state and progress tracking.
+
+## Common Commands
+
+### Running the Agent
+
+```bash
+# Fresh project initialization
+python autonomous_agent_demo.py --project-dir ./my_project
+
+# Continue existing project
+python autonomous_agent_demo.py --project-dir ./my_project
+
+# Add new features to existing project (Initializer Bis)
+python autonomous_agent_demo.py --project-dir ./my_project --new-spec app_spec_theme_customization.txt
+
+# Limit iterations for testing
+python autonomous_agent_demo.py --project-dir ./my_project --max-iterations 3
+```
+
+### Testing
+
+```bash
+# Run security hook tests
+python test_security.py
+
+# Test mypy type checking (for library projects)
+mypy path/to/module.py
+```
+
+### Environment Setup
+
+```bash
+# Generate Claude Code OAuth token
+claude setup-token
+
+# Install dependencies
+pip install -r requirements.txt
+```
+
+## High-Level Architecture
+
+### Core Agent Flow
+
+1. **First Run (Initializer Agent)**:
+   - Reads `prompts/app_spec.txt` specification
+   - Creates Linear project and ~50 issues (one per `<feature_X>` tag)
+   - Creates META issue for session tracking
+   - Initializes project structure with `init.sh`
+   - Writes `.linear_project.json` marker file
+
+2. **Subsequent Runs (Coding Agent)**:
+   - Queries Linear for highest-priority Todo issue
+   - Updates issue status to "In Progress"
+   - Implements feature using SDK tools
+   - Tests implementation (Puppeteer for web apps, pytest/mypy for libraries)
+   - Adds comment to Linear issue with implementation notes
+   - Marks issue as "Done"
+   - Updates META issue with session summary
+
+3. **Initializer Bis (Add Features)**:
+   - Triggered by `--new-spec` flag on existing projects
+   - Reads new spec file from `prompts/`
+   - Creates additional Linear issues for new features
+   - Updates existing project without re-initializing
+
+### Key Design Patterns
+
+**Session Handoff via Linear**: Agents don't use local state files for coordination. All session context, implementation notes, and progress tracking happens through Linear issues and comments. This provides:
+- Real-time visibility in Linear workspace
+- Persistent history across sessions
+- Easy debugging via issue comments
+
+**Defense-in-Depth Security** (see `security.py` and `client.py`):
+1. OS-level sandbox for bash command isolation
+2. Filesystem restrictions (operations limited to project directory)
+3. Bash command allowlist with pre-tool-use hooks
+4. Explicit MCP tool permissions
+
+**Project Type Detection** (`agent.py:is_library_project`):
+- Detects library/type-safety projects vs full-stack web apps
+- Uses different coding prompts (`coding_prompt_library.md` vs `coding_prompt.md`)
+- Keywords: "type safety", "docstrings", "mypy", "library rag"
+
+### Module Responsibilities
+
+- **`autonomous_agent_demo.py`**: Entry point, argument parsing, environment validation
+- **`agent.py`**: Core agent loop, session orchestration, project type detection
+- **`client.py`**: Claude SDK client configuration, MCP server setup (Linear + Puppeteer)
+- **`security.py`**: Bash command validation with allowlist, pre-tool-use hooks
+- **`prompts.py`**: Prompt loading utilities, spec file copying
+- **`progress.py`**: Progress tracking via `.linear_project.json` marker
+- **`linear_config.py`**: Linear API configuration constants
+
+### MCP Servers
+
+**Linear** (HTTP transport at `mcp.linear.app/mcp`):
+- Project/team management
+- Issue CRUD operations
+- Comments and status updates
+- Requires `LINEAR_API_KEY` in `.env`
+
+**Puppeteer** (stdio transport):
+- Browser automation for UI testing
+- Navigate, screenshot, click, fill, evaluate
+- Used by web app projects, not library projects
+
+## Application Specification Format
+
+Specifications use XML format in `prompts/app_spec.txt`:
+
+```xml
+<project_specification>
+  <project_name>Your App Name</project_name>
+  <overview>Detailed description...</overview>
+
+  <technology_stack>
+    <frontend>...</frontend>
+    <backend>...</backend>
+  </technology_stack>
+
+  <core_features>
+    <feature_1>
+      <title>Feature title</title>
+      <description>Detailed description</description>
+      <priority>1-4 (1=urgent, 4=low)</priority>
+      <category>frontend|backend|auth|etc</category>
+      <test_steps>
+        1. Step one
+        2. Step two
+      </test_steps>
+    </feature_1>
+    <!-- More features... -->
+  </core_features>
+</project_specification>
+```
+
+**Important**: Each `<feature_X>` tag becomes a separate Linear issue. The initializer creates exactly one issue per feature tag.
+
+## Environment Configuration
+
+All configuration via `.env` file (copy from `.env.example`):
+
+```bash
+CLAUDE_CODE_OAUTH_TOKEN='your-oauth-token'  # From: claude setup-token
+LINEAR_API_KEY='lin_api_xxxxx'              # From: linear.app/settings/api
+LINEAR_TEAM_ID='team-id'                    # Optional, agent prompts if missing
+```
+
+## Security Model
+
+### Allowed Commands (`security.py:ALLOWED_COMMANDS`)
+
+File operations: `ls`, `cat`, `head`, `tail`, `wc`, `grep`, `cp`, `mkdir`, `chmod`
+Development: `npm`, `node`, `python`, `python3`, `mypy`, `pytest`
+Version control: `git`
+Process management: `ps`, `lsof`, `sleep`, `pkill`
+Scripts: `init.sh`
+
+### Additional Validation
+
+- **`pkill`**: Only allowed for dev processes (node, npm, vite, next)
+- **`chmod`**: Only `+x` mode permitted (making scripts executable)
+- **`init.sh`**: Must be `./init.sh` or end with `/init.sh`
+
+### Adding New Commands
+
+Edit `security.py:ALLOWED_COMMANDS` and optionally add validation logic to `bash_security_hook`.
+
+## Generated Project Structure
+
+After initialization, projects contain:
+
+```
+my_project/
+├── .linear_project.json      # Linear state marker (project_id, total_issues, meta_issue_id)
+├── .claude_settings.json     # Security settings (auto-generated)
+├── app_spec.txt              # Original specification (copied from prompts/)
+├── init.sh                   # Environment setup script (executable)
+└── [generated code]          # Application files created by agent
+```
+
+## Creating New Applications
+
+1. Create `prompts/app_spec.txt` with your XML specification
+2. Use existing spec files as templates (see `prompts/app_spec.txt` for Claude Clone example)
+3. Run: `python autonomous_agent_demo.py --project-dir ./new_app`
+4. Monitor progress in Linear workspace
+
+See `GUIDE_NEW_APP.md` for detailed guide (French).
+
+## Prompt Templates
+
+Located in `prompts/`:
+
+- **`initializer_prompt.md`**: First session prompt (creates Linear project/issues)
+- **`initializer_bis_prompt.md`**: Add features prompt (extends existing project)
+- **`coding_prompt.md`**: Standard coding session (web apps with Puppeteer testing)
+- **`coding_prompt_library.md`**: Library coding session (focuses on types/docs, uses pytest/mypy)
+
+The framework automatically selects the appropriate prompt based on session type and project detection.
+
+## Important Implementation Notes
+
+### Linear Integration
+
+- All work tracked as Linear issues, not local files
+- Session handoff via Linear comments on META issue
+- Status workflow: Todo → In Progress → Done
+- Early termination: Agent stops when detecting "feature-complete" in responses
+
+### Auto-Continue Behavior
+
+Agent auto-continues with 3-second delay between sessions (`agent.py:AUTO_CONTINUE_DELAY_SECONDS`). Stops when:
+- `--max-iterations` limit reached
+- Response contains "feature-complete" or "all issues completed"
+- Fatal error occurs
+
+### Project Directory Handling
+
+Relative paths automatically placed under `generations/` directory unless absolute path provided.
+
+### Model Selection
+
+Default: `claude-opus-4-5-20251101` (Opus 4.5 for best coding performance)
+Override with: `--model claude-sonnet-4-5-20250929`
--- a/.claude/settings.local.json
+++ b/.claude/settings.local.json
@@ -3,7 +3,41 @@
    "allow": [
      "Bash(test:*)",
      "Bash(cat:*)",
-      "Bash(netstat:*)"
+      "Bash(netstat:*)",
+      "Bash(docker-compose:*)",
+      "Bash(ls:*)",
+      "Bash(rm:*)",
+      "Bash(python autonomous_agent_demo.py:*)",
+      "Bash(dir C:GitHublinear_coding_philosophia_raggenerationslibrary_rag*.py)",
+      "Bash(git add:*)",
+      "Bash(git commit -m \"$\\(cat <<''EOF''\nFix import error: rename delete_document_passages to delete_document_chunks\n\nThe function was renamed in weaviate_ingest.py but the import in __init__.py\nwas not updated, causing ImportError when using the library.\n\nChanges:\n- Updated import statement in utils/__init__.py\n- Updated __all__ export list to use correct function name\nEOF\n\\)\")",
+      "Bash(dir \"C:\\\\GitHub\\\\linear_coding_philosophia_rag\\\\generations\\\\library_rag\\\\.env\")",
+      "Bash(git commit:*)",
+      "Bash(tasklist:*)",
+      "Bash(findstr:*)",
+      "Bash(wmic process:*)",
+      "Bash(powershell -Command \"Get-Process python | Select-Object Id,Path,StartTime | Format-Table -AutoSize\")",
+      "Bash(powershell -Command \"Get-WmiObject Win32_Process -Filter \"\"name = ''python.exe''\"\" | Select-Object ProcessId, CommandLine | Format-List\")",
+      "Bash(timeout:*)",
+      "Bash(powershell -Command:*)",
+      "Bash(python:*)",
+      "Bash(dir \"C:\\\\GitHub\\\\linear_coding_library_rag\\\\generations\\\\library_rag\")",
+      "Bash(docker ps:*)",
+      "Bash(curl:*)",
+      "Bash(dir:*)",
+      "Bash(grep:*)",
+      "Bash(git push:*)",
+      "Bash(mypy:*)",
+      "WebSearch",
+      "Bash(nvidia-smi:*)",
+      "WebFetch(domain:cr.weaviate.io)",
+      "Bash(git restore:*)",
+      "Bash(git log:*)",
+      "Bash(done)",
+      "Bash(git remote set-url:*)",
+      "Bash(docker compose:*)",
+      "Bash(pytest:*)",
+      "Bash(git pull:*)"
    ]
  }
 }