saky/cd-browser
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: finalize AI logging format system

Browse Source 
- align ai-worklog and ai-prompts with the current logging framework
- require timestamped structured log entries
- finalize logging rules in instructions-agent.md
This commit is contained in:
Saky
2026-03-16 01:33:02 +01:00
parent 7c87d6f1f0
commit 6849631cc1
3 changed files with 344 additions and 125 deletions
Download Patch File Download Diff File Expand all files Collapse all files

156
docs/ai-prompts.md
View File

@@ -1,43 +1,155 @@
# AI Prompts Log # AI Prompts Log
This file stores relevant prompts used during AI-assisted development. This file stores the prompts that triggered significant AI-driven development tasks.
Only store prompts that: The goal is to preserve traceability between:
- the prompt given to the AI
- the scope of the change
- the resulting work recorded in `ai-worklog.md`
Each entry must include:
- Date (YYYY-MM-DD HH:MM)
- Task ID
- Agent
- Task type (plan/build)
- Scope
- Prompt summary
- Result summary
Only record prompts that:
- change architecture - change architecture
- introduce new behavior - introduce new behavior
- modify important logic - modify important logic
- affect project structure - affect project structure
- debug complex issues - debug complex issues
Do not store internal chain-of-thought reasoning. Do not store chain-of-thought reasoning. Only store the prompt intent and a concise result summary.
Store only the user prompt and a short result summary.
## 2026-03-15 ---
- prompt summary: Implement a dedicated history mode in `src/app/ui.py` so pressing `h` hides the tree, shows only history entries, supports Up/Down navigation, and uses Enter to select a history entry and return to the normal tree view. ### BUILD PROMPT ENTRY
- result summary: Added a dedicated history mode with its own selection state, removed the temporary overlay behavior, preserved existing `b`/`f` and normal tree navigation behavior, and added focused UI tests. Date: 2026-03-15 18:05
Task ID: BUILD-20260315-001
Agent: OpenCode
Task: build
## 2026-03-15 Scope:
- src/app/ui.py
- tests/test_ui.py
- prompt summary: Introduce a mandatory AI logging system by updating `instructions-agent.md` and adding repository logs for AI work entries and prompt summaries. Prompt Summary:
- result summary: Added enforceable AI logging rules to `instructions-agent.md`, created `docs/ai-worklog.md` and `docs/ai-prompts.md`, and established a traceable workflow for recording significant AI-assisted tasks. Implement a dedicated history mode in `src/app/ui.py` so pressing `h` hides the tree, shows only history entries, supports Up/Down navigation, and uses Enter to select a history entry and return to the normal tree view.
## 2026-03-15 Result Summary:
Added a dedicated history mode with its own selection state, removed the temporary overlay behavior, preserved existing `b`/`f` and normal tree navigation behavior, and added focused UI tests.
- prompt summary: Introduce a standard AI log entry format in `instructions-agent.md` and record the change in the repository AI logs. ---
- result summary: Added a standardized `AI BUILD ENTRY` and `AI PLAN ENTRY` format, improved consistency expectations for AI logs, and updated the log files to reflect the new format.
## 2026-03-15 ### BUILD PROMPT ENTRY
Date: 2026-03-15 19:25
Task ID: BUILD-20260315-002
Agent: OpenCode
Task: build
- prompt summary: Improve keyboard navigation in `src/app/ui.py` so Right expands or enters, Left collapses or goes to the parent, Enter confirms the selected destination, and ESC cancels back to the starting directory. Scope:
- result summary: Updated the tree-mode key handling in the terminal UI, preserved history mode behavior, and added focused UI tests for the new navigation rules. - instructions-agent.md
- docs/ai-worklog.md
- docs/ai-prompts.md
## 2026-03-15 Prompt Summary:
Introduce a mandatory AI logging system by updating `instructions-agent.md` and adding repository logs for AI work entries and prompt summaries.
- prompt summary: Improve vertical scrolling in `src/app/ui.py` so the selected entry always remains visible in tree mode and history mode when the list is taller than the screen. Result Summary:
- result summary: Added UI scroll offset handling for tree and history views, kept existing navigation behavior unchanged, and added focused tests for the scroll helper logic. Added enforceable AI logging rules to `instructions-agent.md`, created `docs/ai-worklog.md` and `docs/ai-prompts.md`, and established a traceable workflow for recording significant AI-assisted tasks.
## 2026-03-16 00:27 ---
- prompt summary: Improve terminal UI navigation by refining tree and history keyboard behavior, adding scrolling continuity so selection stays visible, and preserving confirmation, cancellation, and history mode behavior. ### BUILD PROMPT ENTRY
- result summary: Updated `src/app/ui.py` and `tests/test_ui.py` to support dedicated history selection, improved Right/Left/Enter/ESC behavior, and vertical scrolling for both tree and history views while keeping the AI logs current. Date: 2026-03-15 20:00
Task ID: BUILD-20260315-003
Agent: OpenCode
Task: build
Scope:
- instructions-agent.md
- docs/ai-worklog.md
- docs/ai-prompts.md
Prompt Summary:
Introduce a standard AI log entry format in `instructions-agent.md` and record the change in the repository AI logs.
Result Summary:
Added standardized `AI BUILD ENTRY` and `AI PLAN ENTRY` formats, improving consistency and long-term traceability of AI-assisted development.
---
### BUILD PROMPT ENTRY
Date: 2026-03-15 21:35
Task ID: BUILD-20260315-004
Agent: OpenCode
Task: build
Scope:
- src/app/ui.py
- tests/test_ui.py
Prompt Summary:
Improve keyboard navigation in `src/app/ui.py` so Right expands or enters, Left collapses or goes to the parent, Enter confirms the selected destination, and ESC cancels back to the starting directory.
Result Summary:
Updated the tree-mode key handling in the terminal UI, preserved history mode behavior, and added focused UI tests for the new navigation rules.
---
### BUILD PROMPT ENTRY
Date: 2026-03-15 22:20
Task ID: BUILD-20260315-005
Agent: OpenCode
Task: build
Scope:
- src/app/ui.py
- tests/test_ui.py
Prompt Summary:
Improve vertical scrolling in `src/app/ui.py` so the selected entry always remains visible in tree mode and history mode when the list is taller than the screen.
Result Summary:
Added UI scroll offset handling for tree and history views, kept existing navigation behavior unchanged, and added focused tests for the scroll helper logic.
---
### BUILD PROMPT ENTRY
Date: 2026-03-16 00:27
Task ID: BUILD-20260316-001
Agent: OpenCode
Task: build
Scope:
- src/app/ui.py
- tests/test_ui.py
Prompt Summary:
Refine terminal UI navigation, maintain dedicated history mode, and ensure scrolling continuity so selections remain visible.
Result Summary:
Updated terminal UI behavior, consolidated navigation improvements, and ensured consistent scrolling and selection visibility across tree and history modes.
---
### BUILD PROMPT ENTRY
Date: 2026-03-16 01:26
Task ID: BUILD-20260316-002
Agent: OpenCode
Task: build
Scope:
- instructions-agent.md
- docs/ai-worklog.md
- docs/ai-prompts.md
Prompt Summary:
Finalize the AI logging format system by requiring timestamped structured log entries and aligning the repository worklog and prompt log with the current logging framework.
Result Summary:
Updated the logging instructions, normalized the prompt log to the structured entry format, and added matching repository log entries for the finalized AI logging system.

280
docs/ai-worklog.md
View File

@@ -1,27 +1,40 @@
# AI Worklog # AI Worklog
This file records important AI-assisted development actions. This file records important AI‑assisted development actions.
Each entry should include: The log is designed for long‑term traceability of AI‑driven development.
- date
- task type (plan/build)
- objective
- files inspected or modified
- key decisions
- validation commands executed
- result
- open issues (if any)
Entries must be concise and chronological. Each entry must include:
- Date (YYYY-MM-DD HH:MM)
- Task ID
- Agent
- Task type (plan/build)
- Objective
- Scope
- Files Modified / Files Inspected
- Key Decisions or Proposed Changes
- Validation
- Result
- Open Issues
Entries must remain chronological.
---
### AI BUILD ENTRY ### AI BUILD ENTRY
Date: 2026-03-15 Date: 2026-03-15 18:10
Task ID: BUILD-20260315-001
Agent: OpenCode
Task: build Task: build
Objective: Replace the temporary history debug overlay with a dedicated history mode in the terminal UI. Objective: Replace the temporary history debug overlay with a dedicated history mode in the terminal UI.
Scope:
- src/app/ui.py
- tests/test_ui.py
Files Modified: Files Modified:
- `src/app/ui.py` - src/app/ui.py
- `tests/test_ui.py` - tests/test_ui.py
Key Decisions: Key Decisions:
- Keep `b` and `f` unchanged. - Keep `b` and `f` unchanged.
@@ -34,131 +47,208 @@ Validation:
- make quality - make quality
Result: Result:
- History mode now shows only the history list, supports Up/Down selection, allows Enter to jump to a prior directory, and exits cleanly back to normal navigation. - History mode now shows only the history list and allows navigation and selection of past directories.
Open Issues: Open Issues:
- None. - None
---
### AI BUILD ENTRY ### AI BUILD ENTRY
Date: 2026-03-16 00:27 Date: 2026-03-15 19:30
Task ID: BUILD-20260315-002
Agent: OpenCode
Task: build Task: build
Objective: Consolidate recent terminal UI navigation improvements and document the updated interaction behavior. Objective: Introduce mandatory AI logging rules and repository logging workflow.
Scope:
- instructions-agent.md
- docs/ai-worklog.md
- docs/ai-prompts.md
Files Modified: Files Modified:
- `src/app/ui.py` - instructions-agent.md
- `tests/test_ui.py` - docs/ai-worklog.md
- `docs/ai-worklog.md` - docs/ai-prompts.md
- `docs/ai-prompts.md`
Key Decisions: Key Decisions:
- Keep dedicated history mode while refining tree-mode keyboard behavior for Right, Left, Enter, and ESC. - Require AI agents to log plan and build tasks.
- Add scroll continuity for both tree and history views so the selected row remains visible on long lists. - Separate logs for work results and prompts.
- Cover the UI-focused behavior with helper-level tests instead of changing navigator or filesystem logic. - Keep entries concise and user‑focused.
Validation:
- make fix (passed)
- make quality (passed)
Result:
- The terminal UI now combines dedicated history mode, clearer confirmation and cancellation behavior, improved tree navigation semantics, and vertical scrolling that keeps the current selection visible in both tree and history views.
Open Issues:
- None.
### AI BUILD ENTRY
Date: 2026-03-15
Task: build
Objective: Introduce mandatory AI logging rules and document the repository logging workflow.
Files Modified:
- `instructions-agent.md`
- `docs/ai-worklog.md`
- `docs/ai-prompts.md`
Key Decisions:
- Require AI agents to log significant plan and build tasks.
- Preserve separate logs for work performed and prompts received.
- Keep entries concise and user-facing.
Validation: Validation:
- not run - not run
Result: Result:
- The repository now defines mandatory AI logging in `instructions-agent.md` and includes dedicated log files for AI work history and prompt summaries. - Repository now enforces AI logging via instructions-agent.md.
Open Issues: Open Issues:
- None. - None
---
### AI BUILD ENTRY ### AI BUILD ENTRY
Date: 2026-03-15 Date: 2026-03-15 20:05
Task ID: BUILD-20260315-003
Agent: OpenCode
Task: build Task: build
Objective: Record the introduction of the standard AI log entry format and improve AI logging consistency. Objective: Introduce the standard AI log entry format and improve logging consistency.
Scope:
- instructions-agent.md
- docs/ai-worklog.md
- docs/ai-prompts.md
Files Modified: Files Modified:
- `instructions-agent.md` - instructions-agent.md
- `docs/ai-worklog.md` - docs/ai-worklog.md
- `docs/ai-prompts.md` - docs/ai-prompts.md
Key Decisions: Key Decisions:
- Add a dedicated "Standard AI Log Entry Format" section to define `AI BUILD ENTRY` and `AI PLAN ENTRY` blocks. - Define AI BUILD ENTRY and AI PLAN ENTRY blocks.
- Use the new standardized format for this worklog update to establish the pattern in the repository logs. - Standardize structure for long‑term repository traceability.
Validation: Validation:
- make fix (passed) - make fix (passed)
- make quality (passed) - make quality (passed)
Result: Result:
- The repository now documents a standard AI log entry format and uses it to improve consistency of AI-assisted development logs. - Repository now uses a standardized AI logging format.
Open Issues: Open Issues:
- None. - None
---
### AI BUILD ENTRY ### AI BUILD ENTRY
Date: 2026-03-15 Date: 2026-03-15 21:40
Task: build Task ID: BUILD-20260315-004
Objective: Improve vertical scrolling in the terminal UI so the selected row remains visible in tree mode and history mode. Agent: OpenCode
Files Modified:
- `src/app/ui.py`
- `tests/test_ui.py`
- `docs/ai-worklog.md`
- `docs/ai-prompts.md`
Key Decisions:
- Add separate scroll offsets for tree mode and history mode inside the UI state.
- Introduce a small helper to clamp scroll offsets so the selected row always stays within the visible window.
- Keep all existing navigation semantics unchanged while limiting the change to UI rendering behavior.
Validation:
- make fix (passed)
- make quality (passed)
Result:
- The terminal UI now scrolls vertically in both tree mode and history mode to keep the current selection visible when the list is taller than the screen.
Open Issues:
- None.
### AI BUILD ENTRY
Date: 2026-03-15
Task: build Task: build
Objective: Improve keyboard navigation behavior in the terminal UI for tree mode. Objective: Improve keyboard navigation behavior in the terminal UI for tree mode.
Scope:
- src/app/ui.py
- tests/test_ui.py
Files Modified: Files Modified:
- `src/app/ui.py` - src/app/ui.py
- `tests/test_ui.py` - tests/test_ui.py
Key Decisions: Key Decisions:
- Make Right expand collapsed directories and enter already expanded directories. - Right expands collapsed directories and enters expanded directories.
- Make Left collapse expanded directories and otherwise navigate to the parent directory. - Left collapses expanded directories or navigates to the parent directory.
- Make Enter confirm the selected path as the final destination and make ESC return the original starting directory. - Enter confirms the selected path.
- ESC cancels and returns to the original directory.
Validation: Validation:
- make fix (passed) - make fix (passed)
- make quality (passed) - make quality (passed)
Result: Result:
- Tree-mode keyboard navigation now supports expand-or-enter on Right, collapse-or-parent on Left, explicit selection confirmation on Enter, and cancel-to-start behavior on ESC. - Tree navigation semantics improved with clearer expand, enter, and cancel behavior.
Open Issues: Open Issues:
- None. - None
---
### AI BUILD ENTRY
Date: 2026-03-15 22:25
Task ID: BUILD-20260315-005
Agent: OpenCode
Task: build
Objective: Implement vertical scrolling so the selected entry always remains visible.
Scope:
- src/app/ui.py
- tests/test_ui.py
Files Modified:
- src/app/ui.py
- tests/test_ui.py
Key Decisions:
- Introduce scroll offsets in the UI state.
- Clamp offsets to keep the selected row visible.
- Apply the same mechanism to history mode.
Validation:
- make fix (passed)
- make quality (passed)
Result:
- Tree and history views now scroll when navigating beyond the visible screen area.
Open Issues:
- None
---
### AI BUILD ENTRY
Date: 2026-03-16 00:27
Task ID: BUILD-20260316-001
Agent: OpenCode
Task: build
Objective: Consolidate terminal UI navigation improvements and document updated behavior.
Scope:
- src/app/ui.py
- tests/test_ui.py
- docs/ai-worklog.md
- docs/ai-prompts.md
Files Modified:
- src/app/ui.py
- tests/test_ui.py
- docs/ai-worklog.md
- docs/ai-prompts.md
Key Decisions:
- Maintain dedicated history mode.
- Refine tree-mode keyboard behavior.
- Keep UI logic isolated from navigator logic.
Validation:
- make fix (passed)
- make quality (passed)
Result:
- Terminal UI now includes history mode, improved navigation semantics, and reliable vertical scrolling.
Open Issues:
- None
---
### AI BUILD ENTRY
Date: 2026-03-16 01:26
Task ID: BUILD-20260316-002
Agent: OpenCode
Task: build
Objective: Finalize the AI logging format system and align repository log files with the structured logging framework.
Scope:
- instructions-agent.md
- docs/ai-worklog.md
- docs/ai-prompts.md
Files Modified:
- instructions-agent.md
- docs/ai-worklog.md
- docs/ai-prompts.md
Key Decisions:
- Require timestamped log entries with date and time, Task ID, Agent, and Scope fields.
- Keep the worklog and prompt log aligned with the current structured logging framework.
- Normalize prompt logging into a single consistent `BUILD PROMPT ENTRY` format.
Validation:
- make fix (passed)
- make quality (passed)
Result:
- The AI logging system now uses consistent structured entries across repository instructions, worklog history, and prompt history.
Open Issues:
- None

17
instructions-agent.md
View File

@@ -144,9 +144,15 @@ Example for build tasks:
### AI BUILD ENTRY ### AI BUILD ENTRY
Date: YYYY-MM-DD HH:MM Date: YYYY-MM-DD HH:MM
Task ID: BUILD-YYYYMMDD-XXX
Agent: OpenCode
Task: build Task: build
Objective: short description of the task Objective: short description of the task
Scope:
- src/app/module.py
- tests/test_module.py
Files Modified: Files Modified:
- file/path/example.py - file/path/example.py
- another/file.md - another/file.md
@@ -168,9 +174,15 @@ Example for plan tasks:
### AI PLAN ENTRY ### AI PLAN ENTRY
Date: YYYY-MM-DD HH:MM Date: YYYY-MM-DD HH:MM
Task ID: PLAN-YYYYMMDD-XXX
Agent: OpenCode
Task: plan Task: plan
Objective: short description of planning objective Objective: short description of planning objective
Scope:
- src/app/module.py
- specs/module_spec.md
Files Inspected: Files Inspected:
- src/app/example.py - src/app/example.py
- specs/example_spec.md - specs/example_spec.md
@@ -188,3 +200,8 @@ Rules:
- Use bullet points when possible. - Use bullet points when possible.
- This format must be used when updating `docs/ai-worklog.md`. - This format must be used when updating `docs/ai-worklog.md`.
- The Date field must include both date and time using the format YYYY-MM-DD HH:MM. - The Date field must include both date and time using the format YYYY-MM-DD HH:MM.
- Every log entry must include a `Task ID`.
- `Task ID` format must be `BUILD-YYYYMMDD-XXX` or `PLAN-YYYYMMDD-XXX`.
- `Agent` must identify the tool or AI system performing the task (e.g., OpenCode).
- `Scope` must describe the main files or project areas affected.
- These fields make the AI worklog suitable for long-term traceability and large histories.