docs: add AI development playbook and architecture documentation

docs/ai-development-playbook.md

@@ -0,0 +1,202 @@
+# cd-browser AI Development Playbook
+
+Author: Saky\
+Purpose: Reusable methodology for building software with AI coding
+agents.
+
+------------------------------------------------------------------------
+
+# 1. Philosophy
+
+This playbook documents a repeatable workflow for building software with
+AI agents such as:
+
+-   OpenCode
+-   Codex‑style coding agents
+-   LLM programming assistants
+
+Goal:
+
+Maintain **architectural control and code quality** while benefiting
+from AI‑accelerated development.
+
+Core principle:
+
+AI is used as an **implementation engine**, not as an architect.
+
+The human defines:
+
+-   architecture
+-   boundaries
+-   specifications
+-   validation rules
+
+------------------------------------------------------------------------
+
+# 2. The AI Development Workflow
+
+The method used in the `cd-browser` project follows this sequence:
+
+Specification → Architecture → Module Scaffolding → Implementation →
+Validation → Integration → Release
+
+Each step uses **focused prompts with limited scope**.
+
+------------------------------------------------------------------------
+
+# 3. Repository Preparation
+
+Before using an AI coding agent, the repository must define:
+
+## Tooling
+
+black -- formatting\
+ruff -- linting\
+mypy -- type checking\
+pytest -- testing\
+pre-commit -- commit validation
+
+## Folder structure
+
+src/ tests/ specs/ scripts/ docs/
+
+## AI agent rules
+
+Defined in:
+
+instructions-agent.md
+
+The file instructs the agent to:
+
+-   read specifications first
+-   reuse modules
+-   keep changes minimal
+-   run validation workflows
+
+------------------------------------------------------------------------
+
+# 4. Prompt Design Principles
+
+Effective prompts follow three rules:
+
+### 1. Limit scope
+
+Always define affected files.
+
+Example:
+
+Scope: - src/app/navigator.py - tests/test_navigator.py
+
+### 2. Define constraints
+
+Example:
+
+Do not implement UI yet.
+
+### 3. Require validation
+
+Example:
+
+Run:
+
+make fix\
+make quality
+
+------------------------------------------------------------------------
+
+# 5. Example Prompt --- Module Implementation
+
+Example used in the project:
+
+Implement navigator state model.
+
+Scope: - src/app/navigator.py - tests related to navigator behavior
+
+Requirements: - track current path - manage selection - support
+expansion and collapse - integrate history module - add pytest coverage
+
+Validation: - make fix - make quality
+
+Output: - files changed - summary of implementation
+
+------------------------------------------------------------------------
+
+# 6. Example Prompt --- Debugging
+
+Example debugging prompt used:
+
+We discovered a terminal integration issue.
+
+Problem: The shell wrapper captures stdout using command substitution.
+The curses UI fails when stdout is captured.
+
+Requirements: - attach UI to /dev/tty - ensure stdout prints only final
+path - move logs to stderr
+
+------------------------------------------------------------------------
+
+# 7. Prompt Template
+
+Reusable template:
+
+Scope: (list files)
+
+Requirements: (describe expected behaviour)
+
+Constraints: (limit unwanted features)
+
+Validation: (run project tooling)
+
+Output: (files changed + summary)
+
+------------------------------------------------------------------------
+
+# 8. Validation Loop
+
+Every change follows the validation loop:
+
+1.  Agent implements change
+2.  Run:
+
+make fix make quality
+
+3.  Review output
+4.  Commit if successful
+
+This guarantees stable incremental development.
+
+------------------------------------------------------------------------
+
+# 9. Best Practices
+
+✔ Keep prompts small\
+✔ Implement one module at a time\
+✔ Always request tests\
+✔ Run automated checks\
+✔ Separate specification from implementation
+
+------------------------------------------------------------------------
+
+# 10. Anti‑Patterns
+
+Avoid:
+
+❌ large prompts implementing entire applications\
+❌ vague requirements\
+❌ skipping validation steps\
+❌ allowing the AI to define architecture
+
+------------------------------------------------------------------------
+
+# 11. Benefits
+
+Using this workflow:
+
+-   reduces implementation time
+-   preserves architectural control
+-   ensures consistent code quality
+-   enables reproducible development
+
+------------------------------------------------------------------------
+
+# End