Activities - Bootstrap Project

#	Name	Abbrev.	Guidance	Actions
Elaboration 8
1	Verify & Install Prerequisites	BSP-1	Verify & Install Prerequisites Objective Read the Technology Stack Table from docs/architecture/SAO.md, check each tool …	Read the 'BSP-1 Verify & Install Prerequisites' activity from playbook 'Junior Edda' (workflow 'Bootstrap Project'). Follow its guidance when assisting me. # Verify & Install Prerequisites ## Objective Read the Technology Stack Table from `docs/architecture/SAO.md`, check each tool on the developer's machine, install missing tools, and verify all versions meet minimum requirements. Must be idempotent — safe to run repeatedly. --- ## Process ### 1. Detect OS & Package Manager ```bash # Detect OS OS=$(uname -s) # Darwin or Linux # Detect package manager if [[ "$OS" == "Darwin" ]]; then PKG_MGR="brew" # Verify Homebrew is installed command -v brew >/dev/null 2>&1 \|\| { echo "ERROR: Homebrew not found. Install from https://brew.sh" exit 1 } elif [[ -f /etc/debian_version ]]; then PKG_MGR="apt" elif [[ -f /etc/redhat-release ]]; then PKG_MGR="dnf" else echo "ERROR: Unsupported OS. Requires macOS (Homebrew) or Linux (apt/dnf)." exit 1 fi ``` ### 2. Read Technology Stack Table Parse the Technology Stack Table from SAO.md. For each row: 1. Run the Verify Command 2. Compare installed version against Version requirement 3. If missing or below minimum: run the Install Command for the detected OS 4. If already installed and meets minimum: skip with ✅ message ### 3. Install Logic (Idempotent) For each tool in the stack table: ```bash check_and_install() { local tool="$1" local min_version="$2" local verify_cmd="$3" local install_cmd="$4" if eval "$verify_cmd" >/dev/null 2>&1; then local current_version=$(eval "$verify_cmd" 2>&1 \| grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?') echo "✅ $tool $current_version (required: $min_version)" else echo "📦 Installing $tool..." eval "$install_cmd" if eval "$verify_cmd" >/dev/null 2>&1; then echo "✅ $tool installed successfully" else echo "❌ Failed to install $tool" exit 1 fi fi } ``` ### 4. Post-Install Verification After all tools are installed, run a summary check: ``` Prerequisites Check Summary: Python 3.12.4 ✅ (required: 3.12+) Django 5.1.2 ✅ (required: 5.1+) Node.js 20.11.0 ✅ (required: 20+) npm 10.2.4 ✅ (required: 10+) git 2.43.0 ✅ (required: 2.x) make 4.4.1 ✅ (required: 4+) ruff 0.6.3 ✅ (required: 0.6+) pytest 8.3.1 ✅ (required: 8+) ... All prerequisites satisfied. ✅ ``` ### 5. Handle Edge Cases - Homebrew not installed: Error with install instructions, do not auto-install Homebrew - Permission errors: Suggest `sudo` for system-level packages on Linux - Version conflicts: Warn if installed version is newer than specified (should be fine) or if it's a different major version - Python virtual environment: Do NOT create venv here — that's BSP-04's job - npm global packages: Prefer local (npx) over global installs where possible --- ## Deliverables - ✅ OS & package manager detected - ✅ All tools from Technology Stack Table verified or installed - ✅ Version requirements met for all tools - ✅ Summary report printed - ✅ Idempotent — safe to re-run
2	Initialize Repository	BSP-2	Initialize Repository Objective Create a new Git repository with essential root-level files: .gitignore, README.md, LICENSE, …	Read the 'BSP-2 Initialize Repository' activity from playbook 'Junior Edda' (workflow 'Bootstrap Project'). Follow its guidance when assisting me. # Initialize Repository ## Objective Create a new Git repository with essential root-level files: `.gitignore`, `README.md`, `LICENSE`, and initial commit. --- ## Process ### 1. Initialize Git ```bash git init git branch -M main ``` ### 2. Create .gitignore Generate a `.gitignore` tailored to the technology stack from SAO.md. Include patterns for: ```gitignore # Python __pycache__/ .py[cod] $py.class .egg-info/ dist/ build/ .venv/ venv/ .egg # Node.js node_modules/ npm-debug.log* # IDE .vscode/ .idea/ .swp .swo ~ # OS .DS_Store Thumbs.db # Environment .env .env.local .env..local # Database .sqlite3 db.sqlite3 # Logs logs/ .log # Coverage htmlcov/ .coverage .coverage.* coverage.xml # Build artifacts staticfiles/ media/ ``` Adapt based on actual stack decisions in SAO.md. ### 3. Create README.md ```markdown # {Project Name} {One-sentence description from ESM user journey} ## Quick Start \`\`\`bash make provision # Install prerequisites & dependencies make run # Start development server \`\`\` Then open http://localhost:8000 in your browser. ## Development \| Command \| Description \| \|------------------\|--------------------------------\| \| `make provision` \| Install all prerequisites \| \| `make run` \| Start development server \| \| `make test` \| Run all tests \| \| `make lint` \| Run linter \| \| `make format` \| Auto-format code \| \| `make clean` \| Remove build artifacts \| \| `make help` \| Show all available targets \| ## Documentation - [System Architecture Overview](docs/architecture/SAO.md) - [Modus Operandi](docs/process/MODUS_OPERANDI.md) ``` ### 4. Create LICENSE Choose license based on project requirements. Default to MIT unless SAO.md specifies otherwise. ### 5. Initial Commit ```bash git add . git commit -m "chore(init): initialize repository with .gitignore, README, LICENSE" ``` --- ## Deliverables - ✅ Git repository initialized on `main` branch - ✅ .gitignore created for project stack - ✅ README.md with Quick Start and Makefile target table - ✅ LICENSE file created - ✅ Initial commit made ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - Makefile Template (Code, Required) — produced by Create Makefile (#93).
3	Scaffold Project Structure	BSP-3	Scaffold Project Structure Objective Create the directory tree as defined in DTA-04 (Code Organization). This …	Read the 'BSP-3 Scaffold Project Structure' activity from playbook 'Junior Edda' (workflow 'Bootstrap Project'). Follow its guidance when assisting me. # Scaffold Project Structure ## Objective Create the directory tree as defined in DTA-04 (Code Organization). This includes all top-level directories, app directories, placeholder files, and `__init__.py` files where needed. --- ## Process ### 1. Read DTA-04 Decisions From SAO.md § Code Organization, extract: - Repository strategy (monorepo/polyrepo) - Directory structure with layer separation - App/module names from DTA-02 (Application Blocks) ### 2. Create Directory Tree Example for a Django project: ```bash mkdir -p {app_name}/{models,services,views,templates/{app_name}} mkdir -p tests/{unit,integration,e2e} mkdir -p docs/{architecture,process,features,ux,runbooks} mkdir -p logs mkdir -p static/{css,js,img} mkdir -p scripts ``` ### 3. Create Placeholder Files For each directory, create the minimum files needed so the structure is functional: ```bash # Python packages need __init__.py touch {app_name}/__init__.py touch {app_name}/models/__init__.py touch {app_name}/services/__init__.py touch {app_name}/views/__init__.py touch tests/__init__.py touch tests/unit/__init__.py touch tests/integration/__init__.py touch tests/e2e/__init__.py # Keep empty directories in Git touch logs/.gitkeep touch static/css/.gitkeep touch static/js/.gitkeep touch static/img/.gitkeep touch docs/runbooks/.gitkeep ``` ### 4. Create docs/ Placeholder Structure ```bash # Architecture docs (from DTA) touch docs/architecture/.gitkeep # Process docs (from DSP) touch docs/process/.gitkeep # Feature files (from ESM) touch docs/features/.gitkeep # UX artifacts (from ESM) touch docs/ux/.gitkeep ``` ### 5. Commit Scaffold ```bash git add . git commit -m "chore(scaffold): create project directory structure per DTA-04" ``` --- ## Deliverables - ✅ Directory tree created per DTA-04 decisions - ✅ App packages initialized with `__init__.py` - ✅ Test directory structure created (unit/integration/e2e) - ✅ Docs directory structure created - ✅ Static assets directories created - ✅ Scaffold committed ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - IA Guidelines (Document, Required) — produced by Define Information Architecture (#37). - System Architecture Overview Template (Template, Required) — produced by Write SAO.md (#59). - Makefile Template (Code, Required) — produced by Create Makefile (#93).
4	Initialize Runtimes & Dependencies	BSP-4	Initialize Runtimes & Dependencies Objective Set up language runtimes (Python venv, Node.js) and install project …	Read the 'BSP-4 Initialize Runtimes & Dependencies' activity from playbook 'Junior Edda' (workflow 'Bootstrap Project'). Follow its guidance when assisting me. # Initialize Runtimes & Dependencies ## Objective Set up language runtimes (Python venv, Node.js) and install project dependencies via their respective package managers. Create dependency manifest files (`requirements.txt`, `package.json`) with pinned versions from the SAO.md Technology Stack Table. --- ## Process ### 1. Python Runtime ```bash # Create virtual environment python3 -m venv .venv # Activate (for current session) source .venv/bin/activate # Upgrade pip pip install --upgrade pip # Create requirements.txt from SAO.md Technology Stack Table cat > requirements.txt << 'EOF' # Core framework django>=5.1,<6.0 # Testing pytest>=8.0 pytest-django>=4.8 # Code quality ruff>=0.6 # Logging # (add based on DTA-12 Observability decisions) # Add all Python dependencies from SAO.md stack table here EOF # Install pip install -r requirements.txt ``` ### 2. Django Project Initialization (if Django is chosen) ```bash # Create Django project (only if manage.py doesn't exist) django-admin startproject config . # This creates: # config/ # ├── __init__.py # ├── settings.py # ├── urls.py # ├── asgi.py # └── wsgi.py # manage.py ``` Adjust `config/settings.py`: - Set `ALLOWED_HOSTS` - Configure `DATABASES` per DTA-05 decisions - Configure `STATIC_URL`, `STATICFILES_DIRS` - Configure logging per DTA-12 decisions - Set `SECRET_KEY` handling per DTA-13 decisions ### 3. Node.js Runtime (if applicable) ```bash # Initialize package.json npm init -y # Install frontend dependencies from SAO.md npm install --save-dev \ playwright \ # Add based on stack decisions # Create .nvmrc for Node version pinning echo "20" > .nvmrc ``` ### 4. Pytest Configuration Create `pytest.ini` or add to `pyproject.toml`: ```ini [tool.pytest.ini_options] DJANGO_SETTINGS_MODULE = "config.settings" python_files = ["tests.py", "test_.py", "_tests.py"] python_paths = ["."] addopts = "-v --tb=short" log_cli = true log_file = "tests.log" log_file_level = "INFO" ``` ### 5. Create pyproject.toml (if not exists) Consolidate Python tool configuration: ```toml [project] name = "{project-name}" version = "0.1.0" requires-python = ">=3.12" [tool.ruff] line-length = 120 target-version = "py312" [tool.ruff.lint] select = ["E", "F", "I", "N", "W"] [tool.pytest.ini_options] DJANGO_SETTINGS_MODULE = "config.settings" addopts = "-v --tb=short" log_file = "tests.log" ``` ### 6. Commit Dependencies ```bash git add . git commit -m "chore(deps): initialize Python venv, requirements.txt, Django project, pytest config" ``` --- ## Deliverables - ✅ Python venv created at `.venv/` - ✅ requirements.txt created with pinned versions from SAO.md - ✅ Django project initialized (if applicable) - ✅ package.json created (if Node.js in stack) - ✅ pyproject.toml created with tool configuration - ✅ All dependencies installed and verified - ✅ Dependencies committed ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - System Architecture Overview Template (Template, Required) — produced by Write SAO.md (#59). - Makefile Template (Code, Required) — produced by Create Makefile (#93).
5	Configure Dev Tooling	BSP-5	Configure Dev Tooling Objective Set up linters, formatters, pre-commit hooks, IDE settings, and debug configurations …	Read the 'BSP-5 Configure Dev Tooling' activity from playbook 'Junior Edda' (workflow 'Bootstrap Project'). Follow its guidance when assisting me. # Configure Dev Tooling ## Objective Set up linters, formatters, pre-commit hooks, IDE settings, and debug configurations as defined in DTA-16 (Developer Experience). --- ## Process ### 1. Pre-commit Hooks ```bash # Install pre-commit pip install pre-commit # Create .pre-commit-config.yaml cat > .pre-commit-config.yaml << 'EOF' repos: - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.6.0 hooks: - id: ruff args: [--fix] - id: ruff-format - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.6.0 hooks: - id: trailing-whitespace - id: end-of-file-fixer - id: check-yaml - id: check-added-large-files - id: check-merge-conflict EOF # Install hooks pre-commit install ``` ### 2. IDE Settings (VS Code / Windsurf / Cursor) ```bash mkdir -p .vscode # Settings cat > .vscode/settings.json << 'EOF' { "python.defaultInterpreterPath": ".venv/bin/python", "python.analysis.typeCheckingMode": "basic", "[python]": { "editor.defaultFormatter": "charliermarsh.ruff", "editor.formatOnSave": true, "editor.codeActionsOnSave": { "source.fixAll": "explicit", "source.organizeImports": "explicit" } }, "files.exclude": { "/__pycache__": true, "/.pyc": true, ".venv": true, "node_modules": true }, "editor.rulers": [120] } EOF # Extensions recommendations cat > .vscode/extensions.json << 'EOF' { "recommendations": [ "charliermarsh.ruff", "ms-python.python", "ms-python.debugpy", "batisteo.vscode-django", "firefox-devtools.vscode-firefox-debug" ] } EOF ``` ### 3. Debug Configurations ```bash cat > .vscode/launch.json << 'EOF' { "version": "0.2.0", "configurations": [ { "name": "Django: Run Server", "type": "debugpy", "request": "launch", "program": "${workspaceFolder}/manage.py", "args": ["runserver", "0.0.0.0:8000"], "django": true, "justMyCode": false }, { "name": "Pytest: Current File", "type": "debugpy", "request": "launch", "module": "pytest", "args": ["${file}", "-v", "--tb=short"], "justMyCode": false }, { "name": "Pytest: All Tests", "type": "debugpy", "request": "launch", "module": "pytest", "args": ["tests/", "-v", "--tb=short"], "justMyCode": false } ] } EOF ``` ### 4. EditorConfig ```bash cat > .editorconfig << 'EOF' root = true [] indent_style = space indent_size = 4 end_of_line = lf charset = utf-8 trim_trailing_whitespace = true insert_final_newline = true [.{js,jsx,ts,tsx,json,yml,yaml,html,css}] indent_size = 2 [Makefile] indent_style = tab EOF ``` ### 5. Commit Tooling Config ```bash git add . git commit -m "chore(tooling): configure linter, formatter, pre-commit, IDE settings, debug configs" ``` --- ## Deliverables - ✅ Pre-commit hooks* installed and configured - ✅ VS Code settings configured (formatter, linter, interpreter) - ✅ Debug configurations created (Django server, pytest) - ✅ EditorConfig created for consistent formatting - ✅ IDE extension recommendations added - ✅ Tooling committed ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - System Architecture Overview Template (Template, Required) — produced by Write SAO.md (#59). - Makefile Template (Code, Required) — produced by Create Makefile (#93).
6	Create Makefile	BSP-6	Create Makefile Objective Create a comprehensive Makefile that serves as the single orchestration layer for …	Read the 'BSP-6 Create Makefile' activity from playbook 'Junior Edda' (workflow 'Bootstrap Project'). Follow its guidance when assisting me. # Create Makefile ## Objective Create a comprehensive Makefile that serves as the single orchestration layer for all development, infrastructure, and deployment operations. CI/CD pipelines call these targets — no business logic lives in GitHub Actions. The Makefile template is in `BSP/artifacts/makefile_template.mk`. Copy it, adapt variables to your stack, and verify all targets work. --- ## Process ### 1. Copy Makefile Template Copy `BSP/artifacts/makefile_template.mk` to your project root as `Makefile`. The template includes: - Base sections: General, Provision, Development, Testing, Code Quality, Database, Cleanup - Extension points: `##@ Infrastructure` and `##@ Deployment` sections (commented out, added by DCI/DCD workflows later) - Commented variable blocks for infra and deployment (uncommented during DCI/DCD) See the full template: [`BSP/artifacts/makefile_template.mk`](artifacts/makefile_template.mk) ### 2. Adapt to Stack - Read SAO.md Technology Stack Table for tool paths and versions - If no Node.js in stack: remove `_npm-install` and `package.json` check - If no Django: replace `manage.py` commands with framework equivalents - If additional tools (e.g., Docker): add `docker-up`, `docker-down` targets - All targets should follow the pattern: verb-noun (e.g., `test-unit`, `db-init`) - Do NOT uncomment `##@ Infrastructure` or `##@ Deployment` sections yet — those are added by DCI and DCD workflows respectively ### 3. Verify All Targets Run each target and verify it works: ```bash make help # Should show formatted help make provision # Should complete without errors make lint # Should run (may report issues — that's OK) make format # Should run make test # Should run (may have 0 tests — that's OK) make clean # Should clean up ``` ### 4. Commit Makefile ```bash git add Makefile git commit -m "chore(make): create Makefile with provision, run, test, lint, format, clean targets" ``` --- ## Deliverables - ✅ Makefile created with all standard targets - ✅ `make help` shows all targets with descriptions - ✅ `make provision` installs everything from scratch - ✅ All targets verified as functional - ✅ Makefile committed
7	Create Welcome Page & Verify	BSP-7	Create Welcome Page & Verify Objective Create a basic health-check welcome page that displays application …	Read the 'BSP-7 Create Welcome Page & Verify' activity from playbook 'Junior Edda' (workflow 'Bootstrap Project'). Follow its guidance when assisting me. # Create Welcome Page & Verify ## Objective Create a basic health-check welcome page that displays application health status, verify `make provision` works end-to-end, and confirm F5 (debug launch) shows the welcome page in the browser. --- ## Process ### 1. Create Health Check View Create a simple view that shows system health: ```python # {app}/views/health.py import sys import django import platform from datetime import datetime from django.http import JsonResponse from django.shortcuts import render def health_json(request): """JSON health endpoint for monitoring.""" return JsonResponse({ "status": "healthy", "timestamp": datetime.utcnow().isoformat(), "python_version": sys.version, "django_version": django.__version__, "platform": platform.platform(), }) def welcome(request): """Welcome page showing app health dashboard.""" context = { "status": "healthy", "timestamp": datetime.now(), "python_version": sys.version.split()[0], "django_version": django.__version__, "platform": platform.platform(), "checks": _run_health_checks(), } return render(request, "welcome.html", context) def _run_health_checks(): """Run basic health checks and return results.""" checks = [] # Database check try: from django.db import connection connection.ensure_connection() checks.append({"name": "Database", "status": "✅", "detail": "Connected"}) except Exception as e: checks.append({"name": "Database", "status": "❌", "detail": str(e)}) # Static files check import os static_dir = os.path.join(os.path.dirname(os.path.dirname(__file__)), "static") if os.path.isdir(static_dir): checks.append({"name": "Static Files", "status": "✅", "detail": "Directory exists"}) else: checks.append({"name": "Static Files", "status": "⚠️", "detail": "Directory missing"}) # Logging check log_dir = os.path.join(os.path.dirname(os.path.dirname(__file__)), "logs") if os.path.isdir(log_dir): checks.append({"name": "Logging", "status": "✅", "detail": "Log directory exists"}) else: checks.append({"name": "Logging", "status": "⚠️", "detail": "Log directory missing"}) return checks ``` ### 2. Create Welcome Template ```html <!-- templates/welcome.html --> <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>{{ project_name }} — Welcome</title> <style> /* Minimal inline CSS — no external dependencies needed at bootstrap / body { font-family: -apple-system, system-ui, sans-serif; max-width: 800px; margin: 40px auto; padding: 0 20px; color: #333; } h1 { color: #2563eb; } .status { display: inline-block; padding: 4px 12px; border-radius: 12px; font-size: 14px; font-weight: 600; } .status.healthy { background: #dcfce7; color: #166534; } .checks { margin-top: 20px; } .check { display: flex; justify-content: space-between; padding: 8px 0; border-bottom: 1px solid #e5e7eb; } .meta { color: #6b7280; font-size: 14px; margin-top: 20px; } table { width: 100%; border-collapse: collapse; margin-top: 12px; } td, th { text-align: left; padding: 8px; border-bottom: 1px solid #e5e7eb; } </style> </head> <body> <h1>🚀 {{ project_name }}</h1> <p>Application is running. <span class="status healthy">{{ status }}</span></p> <h2>Health Checks</h2> <table> <tr><th>Component</th><th>Status</th><th>Detail</th></tr> {% for check in checks %} <tr> <td>{{ check.name }}</td> <td>{{ check.status }}</td> <td>{{ check.detail }}</td> </tr> {% endfor %} </table> <div class="meta"> <p>Python {{ python_version }} · Django {{ django_version }}</p> <p>{{ platform }}</p> <p>{{ timestamp }}</p> </div> </body> </html> ``` ### 3. Wire Up URLs ```python # config/urls.py from django.urls import path from {app}.views.health import welcome, health_json urlpatterns = [ path("", welcome, name="welcome"), path("health/", health_json, name="health-json"), ] ``` ### 4. End-to-End Verification Run the full bootstrap sequence and verify: ```bash # 1. Provision from scratch make provision # Expected: all dependencies installed, DB migrated, no errors # 2. Run the server make run # Expected: Django dev server starts on http://localhost:8000 # 3. Verify welcome page # Open http://localhost:8000 in browser # Expected: Welcome page showing "healthy" status with all checks ✅ # 4. Verify health JSON endpoint curl http://localhost:8000/health/ # Expected: {"status": "healthy", "python_version": "...", ...} # 5. Verify F5 debug launch # Press F5 in IDE → Django server starts under debugger # Breakpoints work, can inspect variables # 6. Run tests (should pass even if 0 tests) make test # Expected: no failures # 7. Run linter make lint # Expected: clean or only style warnings ``` ### 5. Final Commit ```bash git add . git commit -m "feat(bootstrap): add welcome page with health checks, wire up URLs Bootstrap verification complete: - make provision ✅ - make run ✅ - F5 debug launch ✅ - Welcome page at / with health dashboard - JSON health endpoint at /health/" ``` --- ## Deliverables - ✅ Welcome page* showing app health status at `/` - ✅ Health JSON endpoint at `/health/` - ✅ `make provision` completes without errors - ✅ `make run` starts server, welcome page visible - ✅ F5 debug launch works in IDE - ✅ `make test` runs without failures - ✅ `make lint` runs cleanly - ✅ Final commit with verification results
8	Configure Observability & Logging	BSP-8	Configure Observability & Logging Objective Set up three-tier logging infrastructure for backend operations (logs/app.log), frontend …	Read the 'BSP-8 Configure Observability & Logging' activity from playbook 'Junior Edda' (workflow 'Bootstrap Project'). Follow its guidance when assisting me. # Configure Observability & Logging ## Objective Set up three-tier logging infrastructure for backend operations (`logs/app.log`), frontend interactions (`logs/gui.log`), and AI token consumption (`logs/consumption.log`). This provides observability from day one and enables EST workflow token tracking for estimate calibration. --- ## Prerequisites - BSP-07 complete (welcome page verified) - Project structure exists - Django settings configured - Static files directory exists --- ## Goals ### Goal 1: Backend Operation Logging What: All backend operations log to `logs/app.log` with informative context Why: Enable troubleshooting without reproduction by logging who, what, where, when, and why for every significant operation Success Criteria: - [ ] Django LOGGING configuration added to settings - [ ] RotatingFileHandler configured (10MB, 5 backups) - [ ] Log format includes module, function, line number, and context - [ ] All service methods log entry, exit, and errors - [ ] Log messages follow informative logging pattern (who, what, where, when, why) Implementation: See Skill Django Logging Setup --- ### Goal 2: Frontend Interaction Logging What: All HTMX interactions and user actions log to `logs/gui.log` Why: Track user behavior, debug frontend issues, and understand interaction patterns Success Criteria: - [ ] JavaScript Logger class created in `static/js/logger.js` - [ ] HTMX event listeners configured (beforeRequest, afterRequest, responseError) - [ ] Django backend endpoint created (`/api/log/gui/`) - [ ] Frontend logs sent to backend for persistence - [ ] Console integration for development debugging Implementation: See Skill HTMX Frontend Logging --- ### Goal 3: Token Consumption Tracking What: AI token usage logged to `logs/consumption.log` in JSON format Why: Enable EST workflow sprint-by-sprint calibration via velocity factor calculation and K-token baseline updates Success Criteria: - [ ] TokenTracker utility class created - [ ] Scenario-level token tracking implemented - [ ] JSON log format compatible with EST-08 Sprint Close & Rebaseline - [ ] Consumption logger configured with JSON formatter - [ ] Sprint report generation utility available Implementation: See Skill Claude Token Tracking --- ## Implementation Steps ### Step 1: Create Logs Directory Structure ```bash mkdir -p logs touch logs/.gitkeep # Add logs to .gitignore (keep structure, ignore content) cat >> .gitignore << 'EOF' # Logs logs/.log !logs/.gitkeep EOF ``` Deliverable: `logs/` directory with `.gitkeep`, `.gitignore` updated --- ### Step 2: Configure Backend Logging Objective: Add Django LOGGING configuration for three log files Tasks: 1. Add LOGGING dictionary to `{project_name}/settings.py` 2. Configure formatters (verbose, simple, json) 3. Configure handlers (app_file, gui_file, consumption_file, console) 4. Configure loggers (django, {project_name}, gui, consumption) 5. Add informative logging to service methods Reference: See Skill Django Logging Setup* for: - Complete LOGGING configuration - RotatingFileHandler setup - Logger usage patterns in services, views, models - Informative logging message format - Testing logging configuration Deliverable: Django LOGGING configured, backend operations logging to `app.log` --- ### Step 3: Configure Frontend Logging Objective: Create JavaScript logger and backend endpoint for GUI events Tasks: 1. Create `static/js/logger.js` with Logger class 2. Add HTMX event listeners (beforeRequest, afterRequest, responseError, etc.) 3. Create Django view `{app_name}/views/logging_views.py::log_gui_event` 4. Add URL route `/api/log/gui/` 5. Include logger in `templates/base.html` 6. Test frontend logging in browser console Reference: See Skill HTMX Frontend Logging for: - JavaScript Logger class implementation - HTMX event logging patterns - Django backend endpoint - User action logging - JavaScript error catching - Performance considerations (throttling, batching) Deliverable: Frontend interactions logging to `gui.log` --- ### Step 4: Configure Token Consumption Tracking Objective: Create TokenTracker utility for EST workflow integration Tasks: 1. Create `{app_name}/utils/token_tracker.py` with TokenTracker class 2. Add consumption logger to Django settings (JSON formatter) 3. Create utility functions for parsing consumption.log 4. Create Django management command for sprint reports 5. Document integration with BPE workflow Reference: See Skill Claude Token Tracking for: - TokenTracker class implementation - JSON log format for EST-08 - Parsing and aggregation utilities - Sprint report generation - Integration with Claude API - Velocity factor calculation Deliverable: Token consumption logging to `consumption.log` in EST-compatible format --- ### Step 5: Verify All Logs Are Working Verification Checklist: 1. Backend Logging: ```bash # Start Django server python manage.py runserver # Trigger some operations (create, read, update) # Check logs/app.log for entries tail -f logs/app.log ``` 2. Frontend Logging: ```bash # Open browser to http://localhost:8000 # Open browser console (F12) # Click buttons, submit forms # Verify console shows log messages # Check logs/gui.log for persisted entries tail -f logs/gui.log ``` 3. Token Consumption: ```python # In Django shell from {app_name}.utils.token_tracker import log_token_consumption log_token_consumption( scenario_id="TEST-01", user_id=1, tokens_used=1000, model="claude-3-5-sonnet-20241022", sprint=1 ) ``` ```bash # Check logs/consumption.log cat logs/consumption.log # Should show JSON entry ``` 4. Log Rotation: ```bash # Verify file size limits ls -lh logs/ # Should show maxBytes=10MB configured ``` Deliverable: All three logs verified and working --- ### Step 6: Commit Logging Infrastructure ```bash git add logs/.gitkeep .gitignore git add {project_name}/settings.py git add static/js/logger.js git add {app_name}/views/logging_views.py git add {app_name}/utils/token_tracker.py git add {app_name}/urls.py git add templates/base.html git commit -m "feat(observability): configure three-tier logging infrastructure Add comprehensive logging for backend operations, frontend interactions, and AI token consumption: Backend (logs/app.log): - Django LOGGING configuration with RotatingFileHandler - Informative logging pattern (module:function:line + context) - Logs for services, views, models, and signals Frontend (logs/gui.log): - JavaScript Logger class with console and backend integration - HTMX event listeners for all interactions - Django endpoint for GUI log collection - User action and error logging Token Consumption (logs/consumption.log): - TokenTracker utility for scenario-level tracking - JSON format compatible with EST-08 Sprint Close workflow - Parsing and aggregation utilities - Sprint report generation command Enables: - Troubleshooting without reproduction - User behavior analysis - EST workflow token calibration Refs: Activity EST-08 (Sprint Close and Rebaseline)" ``` Deliverable: Logging infrastructure committed to repository --- ## Success Criteria - [x] Logs directory created with `.gitkeep` - [x] `.gitignore` updated to exclude `logs/.log` - [x] Backend logging* configured in Django settings - [x] app.log receiving backend operation logs - [x] gui.log receiving frontend interaction logs - [x] consumption.log receiving token consumption in JSON format - [x] Log rotation configured (10MB, 5 backups) - [x] Informative logging pattern followed (module:function:line + context) - [x] JavaScript Logger created and included in base template - [x] HTMX events automatically logged - [x] TokenTracker utility created - [x] All logs verified and working - [x] Infrastructure committed to repository --- ## Inputs Read these before starting this activity. They are produced earlier in the playbook and are authoritative — raise a drift event instead of deviating. - System Architecture Overview Template (Template, Required) — produced by Write SAO.md (#59). - Makefile Template (Code, Required) — produced by Create Makefile (#93). ## Construction Handoff BSP is the final Elaboration workflow. Before starting Construction, verify all four gates: \| Gate \| Artifact \| Workflow if missing \| \|------\|----------\|---------------------\| \| ESM \| `docs/features/user_journey.md` + `.feature` files in `docs/features/act-/` \| ESM — Envision the System \| \| DTA \| `docs/architecture/SAO.md` \| DTA — Define Architecture \| \| DSP \| `CLAUDE.md` \| DSP — Deploy Software Process \| \| BSP \| `Makefile` + `requirements.txt` \| this workflow (BSP) \| \| SAO §17 (if applicable) \| `tests/support/agent_story.py` \| TFK-02 — Bootstrap Test Harness \| If any gate fails, run that workflow and return here. When all gates pass, choose your Construction mode: Option A — Feature-by-feature (BPE)* Use when: scope is still fuzzy, building one feature at a time, or human review on every plan is preferred. → Run BPE on a single `.feature` spec. Option B — Dark factory (PIN → MIN) Use when: a full act is defined with multiple ready scenarios and autonomous milestone execution is wanted. → Run PIN with a goal sentence (e.g. "we aim to complete act-1"). After PIN-05 human GO, say `Work on Milestone #N` to activate MIN. Heuristic: Run BPE for your first feature to validate the setup end-to-end. Once the pattern is confirmed, switch to PIN → MIN for subsequent acts. BPE is the build engine in both modes — PIN-03 runs BPE-01 per scenario; MIN-04 runs BPE-02–05. Do not run BPE in a manual loop to approximate Option B. DCD (Design & Deploy CI/CD) is not required to start building. Deploy when 0.1 is ready.

Activities in Bootstrap Project