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

docs/architecture.md

@@ -0,0 +1,191 @@
+# cd-browser Architecture
+
+Author: Saky
+
+This document describes the architecture of the `cd-browser` terminal
+navigation tool.
+
+------------------------------------------------------------------------
+
+# 1. Purpose
+
+`cd-browser` provides a keyboard‑driven terminal interface to explore
+directories and return a selected path to the shell.
+
+It solves a limitation of shells:
+
+A program cannot directly change the parent shell directory.
+
+Instead:
+
+1.  The application returns a path
+2.  A shell wrapper performs `cd`
+
+------------------------------------------------------------------------
+
+# 2. High Level Architecture
+
+The project follows a layered architecture:
+
+CLI Layer ↓ UI Layer ↓ Navigator Layer ↓ Filesystem Layer
+
+History is used by the navigator.
+
+------------------------------------------------------------------------
+
+# 3. Modules
+
+## filesystem.py
+
+Responsibilities:
+
+-   inspect filesystem
+-   list directories
+-   detect children directories
+
+Core structures:
+
+DirectoryEntry
+
+Functions:
+
+list_directories() has_subdirectories()
+
+------------------------------------------------------------------------
+
+## history.py
+
+Handles navigation history.
+
+Features:
+
+-   visit(path)
+-   back()
+-   forward()
+-   select()
+
+Used by navigator.
+
+------------------------------------------------------------------------
+
+## navigator.py
+
+Core state machine of the application.
+
+Tracks:
+
+-   current_path
+-   visible directory entries
+-   selected index
+-   expanded nodes
+
+Handles:
+
+-   entering directories
+-   parent navigation
+-   tree expansion
+-   history integration
+
+------------------------------------------------------------------------
+
+## ui.py
+
+Terminal interface using curses.
+
+Responsibilities:
+
+-   render directory list
+-   highlight selection
+-   process keyboard input
+
+Keys used:
+
+↑ ↓ navigation → expand ← collapse ESC exit
+
+------------------------------------------------------------------------
+
+## cli.py
+
+Application orchestrator.
+
+Responsibilities:
+
+-   create navigator
+-   start terminal UI
+-   capture resulting path
+
+------------------------------------------------------------------------
+
+## main.py
+
+Entrypoint.
+
+Responsibilities:
+
+-   initialize logging
+-   start CLI flow
+-   print final path
+
+------------------------------------------------------------------------
+
+# 4. Shell Integration
+
+Shell wrapper function:
+
+cd\_() { local target target="$(cd_browser)"
+  if [ -n "$target" \] && \[ -d "$target" ]; then
+    cd "$target" fi }
+
+This enables:
+
+cd\_
+
+to change the working directory.
+
+------------------------------------------------------------------------
+
+# 5. Terminal Handling
+
+The application attaches its UI to:
+
+/dev/tty
+
+This allows the UI to function even when stdout is captured by shell
+substitution.
+
+stdout is reserved for:
+
+final directory path
+
+stderr is used for logging.
+
+------------------------------------------------------------------------
+
+# 6. Validation
+
+Quality tools ensure correctness:
+
+black -- formatting\
+ruff -- linting\
+mypy -- type checking\
+pytest -- testing
+
+Commands:
+
+make fix make quality make ci
+
+------------------------------------------------------------------------
+
+# 7. Extensibility
+
+Future improvements:
+
+-   enhanced navigation model
+-   fuzzy search
+-   bookmark directories
+-   persistent history
+-   configuration file
+
+------------------------------------------------------------------------
+
+# End

docs/development-journey.md

@@ -0,0 +1,453 @@
+# cd-browser -- Development Journey (Reconstructed from Chat Session)
+
+Author: Saky\
+Method: AI‑assisted development with OpenCode + ChatGPT\
+Environment: macOS, Python 3.11, zsh terminal
+
+------------------------------------------------------------------------
+
+# Overview
+
+This document reconstructs the full development process of
+**cd-browser**, a terminal directory navigator, built step‑by‑step
+using:
+
+-   a reusable Python development template
+-   OpenCode as an autonomous coding agent
+-   ChatGPT as architectural guidance
+
+The workflow followed a structured pattern:
+
+Specification → Plan → Implementation → Validation → Integration →
+Release
+
+------------------------------------------------------------------------
+
+# Phase 1 --- Creating the Python AI Development Template
+
+## Objective
+
+Create a reusable repository template for AI‑assisted Python projects
+with:
+
+-   clean structure
+-   automated formatting
+-   static analysis
+-   testing
+-   reproducible workflows
+
+## Key decisions
+
+-   Python ≥ 3.11
+-   virtual environment `.venv`
+-   tooling:
+
+  Tool         Purpose
+  ------------ ------------------
+  black        formatting
+  ruff         linting
+  mypy         type checking
+  pytest       testing
+  pre-commit   automated checks
+  make         task automation
+
+## Repository structure
+
+src/ tests/ specs/ scripts/ Makefile pyproject.toml
+instructions-agent.md
+
+## Important file
+
+### instructions-agent.md
+
+Defines how OpenCode should behave:
+
+-   read specs before implementing
+-   keep changes minimal
+-   reuse modules
+-   run validation after changes
+
+This file becomes the AI contract for the repository.
+
+------------------------------------------------------------------------
+
+# Phase 2 --- Creating the Project
+
+## Project Name
+
+cd-browser
+
+Goal:
+
+A terminal directory browser that allows fast navigation and returns a
+directory path to the shell.
+
+------------------------------------------------------------------------
+
+# Phase 3 --- Application Specification
+
+Specification stored in:
+
+specs/cd_browser_spec.md
+
+Key behavior defined:
+
+-   browse directories in terminal
+-   arrow navigation
+-   expandable tree
+-   history support
+-   return selected path to shell
+
+------------------------------------------------------------------------
+
+# Phase 4 --- Preparing the Codebase
+
+Created modules:
+
+src/app/
+
+cli.py\
+filesystem.py\
+history.py\
+navigator.py\
+ui.py\
+main.py
+
+Purpose of each module:
+
+  Module       Responsibility
+  ------------ -----------------------
+  filesystem   filesystem inspection
+  history      navigation history
+  navigator    state machine
+  ui           terminal rendering
+  cli          orchestration
+  main         entrypoint
+
+------------------------------------------------------------------------
+
+# Phase 5 --- Implementation via OpenCode
+
+OpenCode was instructed to implement modules step‑by‑step.
+
+## Step 1 --- Filesystem layer
+
+Prompt summary:
+
+Implement filesystem helpers: - list directories - detect
+subdirectories - return structured entries
+
+### Result
+
+filesystem.py implemented:
+
+-   DirectoryEntry
+-   list_directories()
+-   has_subdirectories()
+
+### Tests added
+
+tests/test_filesystem.py
+
+Validation:
+
+pytest\
+black\
+ruff\
+mypy
+
+All passed.
+
+------------------------------------------------------------------------
+
+# Step 2 --- History module
+
+Prompt summary:
+
+Implement session history manager.
+
+### Result
+
+history.py:
+
+-   visit()
+-   back()
+-   forward()
+-   select()
+
+### Tests
+
+tests/test_history.py
+
+Validation: success.
+
+------------------------------------------------------------------------
+
+# Step 3 --- Navigator (core logic)
+
+Prompt summary:
+
+Implement navigator state model using filesystem + history. Do not
+implement UI yet.
+
+### Result
+
+navigator.py manages:
+
+-   current_path
+-   visible entries
+-   selection index
+-   expand/collapse
+-   parent navigation
+-   history integration
+
+### Tests
+
+tests/test_navigator.py
+
+22 tests passed.
+
+------------------------------------------------------------------------
+
+# Step 4 --- Terminal UI
+
+Prompt summary:
+
+Implement minimal curses UI.
+
+### Result
+
+ui.py:
+
+-   curses interface
+-   path display
+-   selection highlighting
+-   arrow navigation
+-   ESC exit
+
+### Tests
+
+UI-independent logic tested.
+
+------------------------------------------------------------------------
+
+# Step 5 --- CLI integration
+
+Prompt summary:
+
+Create CLI orchestration.
+
+### Result
+
+cli.py
+
+-   initializes navigator
+-   launches UI
+-   returns final path
+
+main.py
+
+-   entrypoint
+-   prints selected path
+
+Validation:
+
+27 tests passed
+
+------------------------------------------------------------------------
+
+# Phase 6 --- Shell Integration
+
+Problem:
+
+A program cannot change the parent shell directory.
+
+Solution:
+
+Create shell wrapper:
+
+cd\_() { local target target="$(cd_browser)"
+  if [ -n "$target" \] && \[ -d "$target" ]; then
+    cd "$target" fi }
+
+Added to:
+
+\~/.zshrc
+
+Now command:
+
+cd\_
+
+opens the navigator and changes directory.
+
+------------------------------------------------------------------------
+
+# Phase 7 --- Critical Bug Encountered
+
+## Issue
+
+Using command substitution:
+
+target="\$(cd_browser)"
+
+broke the curses UI.
+
+Observed behavior:
+
+-   UI not rendering
+-   logging printed to stdout
+
+Example output:
+
+INFO app.main Starting application
+
+### Root cause
+
+-   stdout captured by shell
+-   curses requires real terminal
+-   logging polluted stdout
+
+------------------------------------------------------------------------
+
+# Resolution
+
+Prompt given to OpenCode:
+
+Fix integration so UI uses real terminal while stdout remains clean.
+
+### Fix implemented
+
+1.  UI attached to /dev/tty
+2.  logging redirected to stderr
+3.  stdout reserved for final path
+
+### Files modified
+
+ui.py\
+main.py\
+logging_config.py\
+tests
+
+Validation:
+
+28 tests passed
+
+Problem resolved.
+
+------------------------------------------------------------------------
+
+# Phase 8 --- Packaging
+
+Added console entrypoint in pyproject.toml:
+
+\[project.scripts\] cd_browser = "app.main:main"
+
+Now installable via:
+
+pip install .
+
+Command available:
+
+cd_browser
+
+------------------------------------------------------------------------
+
+# Phase 9 --- Documentation Refactor
+
+Problem:
+
+README from template conflicted with project README.
+
+Solution:
+
+README.md\
+README_TEMPLATE.md
+
+README.md → project documentation\
+README_TEMPLATE.md → original template documentation preserved
+
+------------------------------------------------------------------------
+
+# Phase 10 --- Repository Release Preparation
+
+Checklist performed:
+
+-   formatting
+-   linting
+-   type checking
+-   tests
+
+Commands:
+
+make fix\
+make quality\
+make ci
+
+All passed.
+
+------------------------------------------------------------------------
+
+# Phase 11 --- Final Repository Initialization
+
+Repository prepared for first release.
+
+git add .\
+git commit -m "Initial release: cd-browser v0.1.0"
+
+Then:
+
+git push -u origin main\
+git tag v0.1.0\
+git push origin v0.1.0
+
+------------------------------------------------------------------------
+
+# Current Features
+
+cd-browser provides:
+
+-   interactive terminal directory browsing
+-   expandable directory tree
+-   keyboard navigation
+-   directory history
+-   shell integration
+-   installation via pip
+-   automated testing and quality checks
+
+------------------------------------------------------------------------
+
+# Future Improvements
+
+Planned navigation redesign:
+
+Key model:
+
+→ expand / enter\
+← collapse / go up\
+Enter confirm directory\
+ESC cancel
+
+------------------------------------------------------------------------
+
+# Lessons Learned
+
+AI‑assisted development works best with:
+
+1.  clear specifications
+2.  modular architecture
+3.  strict validation loops
+4.  minimal prompts with clear scope
+
+Critical discovery:
+
+Terminal applications must handle:
+
+stdout\
+stderr\
+/dev/tty
+
+correctly when used inside shell substitution.
+
+------------------------------------------------------------------------
+
+End of document.