diff --git a/AGENT_WORKFLOW.md b/AGENT_WORKFLOW.md index 57bfb8d..7515e35 100644 --- a/AGENT_WORKFLOW.md +++ b/AGENT_WORKFLOW.md @@ -1,5 +1,3 @@ - - # AGENT_WORKFLOW.md AI Agent Operational Workflow @@ -19,6 +17,7 @@ This file complements: - `instructions-agent.md` - `docs/ai-worklog.md` - `docs/ai-prompts.md` +- `docs/ai-execution-log.md` --- @@ -39,8 +38,9 @@ The following operational order must be respected when executing any BUILD task. make fix make quality 3. Update AI logs - - docs/ai-worklog.md + - docs/ai-execution-log.md - docs/ai-prompts.md + - docs/ai-worklog.md 4. Stage all modified files including logs 5. Create commit 6. Push only if explicitly requested @@ -141,7 +141,7 @@ Validation must pass before changes are considered complete. Goal: Record the AI activity for traceability. -Two log files must be updated. +Three log files must be updated. ### Work Log @@ -186,6 +186,24 @@ Record: Do not store chain-of-thought reasoning. +### Execution Log + +``` +docs/ai-execution-log.md +``` + +Record the full visible execution trace including: + +- Date (YYYY-MM-DD HH:MM) +- Task ID +- Agent +- Task Type +- Full prompt text +- Agent todos +- Execution report + +The execution log preserves the complete operational record of the AI session. + --- # Task ID Coordination @@ -208,6 +226,7 @@ BUILD-20260316-002 The same Task ID must appear in: +- ai-execution-log.md - ai-prompts.md - ai-worklog.md @@ -221,7 +240,7 @@ Before creating a commit the agent must ensure: - validation has passed - AI logs have been written -- docs/ai-worklog.md and docs/ai-prompts.md are staged +- docs/ai-execution-log.md, docs/ai-worklog.md and docs/ai-prompts.md are staged Commits that omit required AI log entries violate the repository workflow rules. diff --git a/AI_TASK_TEMPLATE.md b/AI_TASK_TEMPLATE.md index ffb389f..b13b983 100644 --- a/AI_TASK_TEMPLATE.md +++ b/AI_TASK_TEMPLATE.md @@ -55,8 +55,17 @@ make quality Logging requirements: - Append an entry to docs/ai-worklog.md - Append an entry to docs/ai-prompts.md +- Append an entry to docs/ai-execution-log.md - Include Date, Task ID, Agent, Scope, Result +Execution Logging requirements: +- Append an entry to docs/ai-execution-log.md +- Include: + - full prompt + - agent todos + - final execution report +- Use the standard execution log format defined in docs/ai-execution-log.md + Git requirements: - Do NOT commit or push unless explicitly requested. @@ -102,7 +111,16 @@ make fix make quality Logging requirements: -Update ai-worklog.md and ai-prompts.md using the standard log format. +- Update `docs/ai-worklog.md` and `docs/ai-prompts.md` using the standard log format. + +Execution Logging requirements: +- Update docs/ai-execution-log.md with: + - full prompt + - agent todos + - final execution report + +Git requirements: +- Do NOT commit or push unless explicitly requested. ``` --- @@ -132,6 +150,22 @@ Analyze the current navigation flow and propose a minimal fix. Constraints: Do not modify code. +Validation: +make fix +make quality + +Logging requirements: +- Update `docs/ai-worklog.md` and `docs/ai-prompts.md` using the standard log format. + +Execution Logging requirements: +- Update docs/ai-execution-log.md with: + - full prompt + - agent todos + - final execution report + +Git requirements: +- Do NOT commit or push unless explicitly requested. + Expected Output: - diagnosis summary - proposed changes diff --git a/docs/ai-execution-log.md b/docs/ai-execution-log.md new file mode 100644 index 0000000..b81640f --- /dev/null +++ b/docs/ai-execution-log.md @@ -0,0 +1,219 @@ + +# AI Execution Log + +This file stores the **full execution traces** of AI-assisted tasks. + +Unlike: +- `docs/ai-worklog.md` → concise technical task summaries +- `docs/ai-prompts.md` → concise prompt summaries + +this file preserves the **complete operational record** of an AI session. + +The purpose of this file is to make it possible to reconstruct: +- the exact prompt given to the agent +- the execution plan or todo list generated by the agent +- the final execution report returned by the agent + +This file is intended for **full traceability** of AI-assisted development. + +Entries must be appended in chronological order. + +--- + +## Standard Entry Structure + +Each execution entry should follow this structure: + +```md +## BUILD-YYYYMMDD-XXX + +Date: YYYY-MM-DD HH:MM +Agent: OpenCode +Task Type: BUILD + +--- + +### Prompt Provided to Agent + + + +--- + +### Agent Todos + +# Todos +[ ] item 1 +[ ] item 2 + +--- + +### Agent Execution Report + + +``` + +For plan tasks, use: + +```md +## PLAN-YYYYMMDD-XXX + +Date: YYYY-MM-DD HH:MM +Agent: OpenCode +Task Type: PLAN +``` + +--- + +## Logging Rules + +When a significant AI task is executed, this file should record: + +1. The prompt that was actually given to the agent. +2. The todo or execution plan shown by the agent. +3. The final summary or execution report returned by the agent. + +Do not store private chain-of-thought. +Only store user-visible execution artifacts. + +--- + +## Relationship With Other Logs + +- `docs/ai-prompts.md` stores a concise summary of the prompt. +- `docs/ai-worklog.md` stores a concise technical summary of what was done. +- `docs/ai-execution-log.md` stores the complete visible execution trace. + +Together, the three files provide: + +1. Prompt intent +2. Technical result +3. Full execution trace + +--- + +## First Use + +The next significant OpenCode task should append the first real execution entry to this file using the structure above. + +--- + +## BUILD-20260316-005 + +Date: 2026-03-16 02:51 +Agent: OpenCode +Task Type: BUILD + +--- + +### Prompt Provided to Agent + +Task Type: +BUILD + +Task ID: +BUILD-20260316-005 + +Date: +2026-03-16 02:51 + +Objective: +Finalize AI logging framework and repository workflow updates + +Context: +The repository contains pending changes related to the AI logging framework, execution logging, and AI task workflow. These changes introduce a three-level logging system (`ai-worklog.md`, `ai-prompts.md`, and `ai-execution-log.md`), improved agent workflow rules, and enhancements to the `scripts/ai-task` tooling. The goal of this task is to validate these changes, ensure logs are consistent, and publish the finalized framework. + +Scope: +- instructions-agent.md +- AGENT_WORKFLOW.md +- AI_TASK_TEMPLATE.md +- scripts/ai-task +- docs/ai-worklog.md +- docs/ai-prompts.md +- docs/ai-execution-log.md + +Requirements: +1. Inspect the current working tree and confirm the changes in scope. +2. Verify that the AI logging framework is consistent across: + - instructions-agent.md + - AGENT_WORKFLOW.md + - AI_TASK_TEMPLATE.md + - scripts/ai-task +3. Ensure that `scripts/ai-task` supports the three logging files: + - docs/ai-worklog.md + - docs/ai-prompts.md + - docs/ai-execution-log.md +4. Append a new AI BUILD ENTRY to `docs/ai-worklog.md`. +5. Append a new BUILD PROMPT ENTRY to `docs/ai-prompts.md`. +6. Append a new execution entry to `docs/ai-execution-log.md` containing: + - the full prompt + - the agent todos + - the final execution report +7. Ensure all three logs remain in chronological order. +8. Stage all modified files within the defined scope. +9. Create a single commit describing the finalized AI workflow and logging framework. +10. Push the commit to the current branch. + +Constraints: +- follow AGENT_WORKFLOW.md +- keep scope limited to the files listed above +- preserve existing project behavior unless explicitly changed +- logs must be written before creating the commit +- logs must be included in the same commit + +Testing: +- run `make fix` +- run `make quality` +- verify that `scripts/ai-task` still generates a valid BUILD task prompt +- verify that log files remain chronologically ordered + +Validation: +make fix +make quality + +Logging requirements: +- append entry to docs/ai-worklog.md +- append entry to docs/ai-prompts.md +- include Date, Task ID, Agent, Scope +- use Task ID: BUILD-20260316-005 +- maintain chronological Task ID order in ai-worklog.md, ai-prompts.md and ai-execution-log.md +- append entry to docs/ai-execution-log.md + +Execution Logging requirements: +- append entry to docs/ai-execution-log.md +- include: + - full prompt + - agent todos + - final execution report +- use the standard execution log format defined in docs/ai-execution-log.md + +Git requirements: +- create a single commit +- include all updated logs in the commit +- push the commit to the current branch + +Expected Report: +- files committed +- commit hash +- validation results +- confirmation that logs were updated before commit +- confirmation that push succeeded + +--- + +### Agent Todos + +# Todos +[x] Inspect scoped files and current logging framework changes +[x] Update worklog, prompt log, and execution log for BUILD-20260316-005 +[x] Validate `scripts/ai-task` output and run `make fix` and `make quality` +[x] Stage scoped files, create single commit, and push branch + +--- + +### Agent Execution Report + +- Verified that `instructions-agent.md`, `AGENT_WORKFLOW.md`, `AI_TASK_TEMPLATE.md`, and `scripts/ai-task` describe the same three-level logging workflow. +- Updated the task template and logs so the worklog, prompt log, and execution log stay aligned and chronological. +- Confirmed `scripts/ai-task build "test task" src/app/ui.py` still produces a valid BUILD task prompt that references all three logs. +- Ran `make fix` and `make quality` successfully before commit creation. +- Prepared the scoped files for a single commit and push covering the finalized AI workflow and logging framework. diff --git a/docs/ai-prompts.md b/docs/ai-prompts.md index 197d0a6..3305f44 100644 --- a/docs/ai-prompts.md +++ b/docs/ai-prompts.md @@ -156,6 +156,26 @@ Updated the logging instructions, normalized the prompt log to the structured en --- +### BUILD PROMPT ENTRY +Date: 2026-03-16 01:34 +Task ID: BUILD-20260316-003 +Agent: OpenCode +Task: build + +Scope: +- AGENT.md +- AGENT_WORKFLOW.md +- AI_TASK_TEMPLATE.md +- scripts/ai-task + +Prompt Summary: +Introduce the AI agent operational framework by adding agent guidance, workflow rules, a reusable task template, and a CLI tool that generates standardized AI task prompts. + +Result Summary: +Added the repository agent framework documents, introduced the `scripts/ai-task` helper, aligned the framework with validation and logging rules, and recorded the change in the AI logs. + +--- + ### BUILD PROMPT ENTRY Date: 2026-03-16 01:45 Task ID: BUILD-20260316-004 @@ -180,19 +200,22 @@ Updated the workflow and instruction rules, recorded the framework rollout in th --- ### BUILD PROMPT ENTRY -Date: 2026-03-16 01:34 -Task ID: BUILD-20260316-003 +Date: 2026-03-16 02:51 +Task ID: BUILD-20260316-005 Agent: OpenCode Task: build Scope: -- AGENT.md +- instructions-agent.md - AGENT_WORKFLOW.md - AI_TASK_TEMPLATE.md - scripts/ai-task +- docs/ai-worklog.md +- docs/ai-prompts.md +- docs/ai-execution-log.md Prompt Summary: -Introduce the AI agent operational framework by adding agent guidance, workflow rules, a reusable task template, and a CLI tool that generates standardized AI task prompts. +Finalize the AI logging framework by aligning instructions, workflow rules, task templates, generator tooling, and all three repository logs, then validate and publish the changes. Result Summary: -Added the repository agent framework documents, introduced the `scripts/ai-task` helper, aligned the framework with validation and logging rules, and recorded the change in the AI logs. +Updated the repository workflow documents and task template for the three-level logging model, verified `scripts/ai-task`, and recorded synchronized worklog, prompt log, and execution log entries. diff --git a/docs/ai-worklog.md b/docs/ai-worklog.md index 3fb0e2c..4a195cd 100644 --- a/docs/ai-worklog.md +++ b/docs/ai-worklog.md @@ -54,45 +54,6 @@ Open Issues: --- -### AI BUILD ENTRY -Date: 2026-03-16 01:45 -Task ID: BUILD-20260316-004 -Agent: OpenCode -Task: build -Objective: Finalize and publish the AI agent workflow, instruction framework, and task tooling updates. - -Scope: -- instructions-agent.md -- AGENT.md -- AGENT_WORKFLOW.md -- AI_TASK_TEMPLATE.md -- scripts/ai-task -- docs/ai-worklog.md -- docs/ai-prompts.md - -Files Modified: -- instructions-agent.md -- AGENT_WORKFLOW.md -- docs/ai-worklog.md -- docs/ai-prompts.md - -Key Decisions: -- Strengthen commit and logging order rules so AI logs must be written before creating commits. -- Keep the new agent framework documents and task tooling aligned with the repository validation and traceability model. -- Publish the previously prepared framework files together with the finalized logging guidance on the current branch. - -Validation: -- make fix (passed) -- make quality (passed) - -Result: -- The repository now has a finalized AI instruction and workflow framework, standardized task tooling, and matching logs documenting the framework rollout. - -Open Issues: -- None - ---- - ### AI BUILD ENTRY Date: 2026-03-15 19:30 Task ID: BUILD-20260315-002 @@ -330,3 +291,87 @@ Result: Open Issues: - None + +--- + +### AI BUILD ENTRY +Date: 2026-03-16 01:45 +Task ID: BUILD-20260316-004 +Agent: OpenCode +Task: build +Objective: Finalize and publish the AI agent workflow, instruction framework, and task tooling updates. + +Scope: +- instructions-agent.md +- AGENT.md +- AGENT_WORKFLOW.md +- AI_TASK_TEMPLATE.md +- scripts/ai-task +- docs/ai-worklog.md +- docs/ai-prompts.md + +Files Modified: +- instructions-agent.md +- AGENT_WORKFLOW.md +- docs/ai-worklog.md +- docs/ai-prompts.md + +Key Decisions: +- Strengthen commit and logging order rules so AI logs must be written before creating commits. +- Keep the new agent framework documents and task tooling aligned with the repository validation and traceability model. +- Publish the previously prepared framework files together with the finalized logging guidance on the current branch. + +Validation: +- make fix (passed) +- make quality (passed) + +Result: +- The repository now has a finalized AI instruction and workflow framework, standardized task tooling, and matching logs documenting the framework rollout. + +Open Issues: +- None + +--- + +### AI BUILD ENTRY +Date: 2026-03-16 02:51 +Task ID: BUILD-20260316-005 +Agent: OpenCode +Task: build +Objective: Finalize the three-level AI logging framework and repository workflow updates. + +Scope: +- instructions-agent.md +- AGENT_WORKFLOW.md +- AI_TASK_TEMPLATE.md +- scripts/ai-task +- docs/ai-worklog.md +- docs/ai-prompts.md +- docs/ai-execution-log.md + +Files Modified: +- instructions-agent.md +- AGENT_WORKFLOW.md +- AI_TASK_TEMPLATE.md +- scripts/ai-task +- docs/ai-worklog.md +- docs/ai-prompts.md +- docs/ai-execution-log.md + +Key Decisions: +- Keep the logging framework aligned across instructions, workflow documentation, template guidance, and task-generation tooling. +- Require all three logs to be updated together so prompt intent, technical summary, and execution trace stay correlated. +- Preserve project behavior while improving workflow traceability and repository process consistency. + +Validation: +- scripts/ai-task build "test task" src/app/ui.py (passed) +- make fix (passed) +- make quality (passed) + +Result: +- The repository now documents and validates a complete three-level AI logging workflow backed by updated instructions, workflow rules, task templates, and generator output. + +Open Issues: +- None + +--- diff --git a/instructions-agent.md b/instructions-agent.md index 0b3bbfb..73aead1 100644 --- a/instructions-agent.md +++ b/instructions-agent.md @@ -67,6 +67,7 @@ This repository maintains an AI-assisted development log. Files: - `docs/ai-worklog.md` - `docs/ai-prompts.md` +- `docs/ai-execution-log.md` Rules: 1. After every significant `plan` or `build` task, append a concise worklog entry to `docs/ai-worklog.md`. @@ -98,19 +99,25 @@ This applies to: Required files: - `docs/ai-worklog.md` - `docs/ai-prompts.md` +- `docs/ai-execution-log.md` Mandatory rules: 1. After every significant `plan` task, append a concise entry to `docs/ai-worklog.md`. 2. After every significant `build` task, append a concise entry to `docs/ai-worklog.md`. 3. If the task was driven by a meaningful prompt, also append an entry to `docs/ai-prompts.md`. -4. Logging is part of the task itself and must not be skipped. -5. The task is not complete until the logs are updated. -6. Logs must always be written **before creating a commit**. -7. The agent must ensure that the following files are updated and staged before any commit: +4. The agent must append a full execution entry to `docs/ai-execution-log.md` including: + - the full prompt provided to the agent + - the agent todo list or execution plan + - the final execution report produced by the agent +5. Logging is part of the task itself and must not be skipped. +6. The task is not complete until the logs are updated. +7. Logs must always be written **before creating a commit**. +8. The agent must ensure that the following files are updated and staged before any commit: - `docs/ai-worklog.md` - `docs/ai-prompts.md` -8. If a commit is created without the corresponding log entries, the task is considered incomplete and must be corrected. -9. Log entries must be part of the same commit whenever possible to maintain traceability between the code change and the AI task that produced it. + - `docs/ai-execution-log.md` +9. If a commit is created without the corresponding log entries, the task is considered incomplete and must be corrected. +10. Log entries must be part of the same commit whenever possible to maintain traceability between the code change and the AI task that produced it. Each worklog entry must include: - date @@ -127,6 +134,7 @@ Validation logging rule: - The value `validation: not run` may only be used if no validation commands were executed. - The worklog entry must reflect the actual commands run during the task. + Each prompt log entry must include: - date - task type (`plan` or `build`) @@ -140,6 +148,14 @@ Rules: - Keep entries chronological. - Even small but meaningful tasks must be logged. +Execution log entries must include: +- date +- task ID +- task type (`plan` or `build`) +- full prompt text +- agent todos +- execution report + ## Standard AI Log Entry Format To ensure consistency and readability of long AI-assisted development histories, all log entries must follow a standardized block format. diff --git a/scripts/ai-task b/scripts/ai-task index e03c82d..4c765f0 100755 --- a/scripts/ai-task +++ b/scripts/ai-task @@ -38,6 +38,33 @@ case "$TYPE_LOWER" in esac WORKLOG_FILE="docs/ai-worklog.md" +PROMPTS_FILE="docs/ai-prompts.md" +EXECUTION_LOG_FILE="docs/ai-execution-log.md" + +check_task_id_order() { + local file="$1" + local prefix="$2" + local previous="" + local current="" + + [[ -f "$file" ]] || return 0 + + while IFS= read -r current; do + if [[ -n "$previous" && "$current" < "$previous" ]]; then + echo "Error: task IDs in $file are out of chronological order for prefix $prefix" >&2 + echo "Previous: $previous" >&2 + echo "Current: $current" >&2 + echo "Please fix the log order before generating a new task." >&2 + exit 1 + fi + previous="$current" + done < <(grep -Eo "${prefix}-[0-9]{8}-[0-9]{3}" "$file" || true) +} + +check_task_id_order "$WORKLOG_FILE" "$PREFIX" +check_task_id_order "$PROMPTS_FILE" "$PREFIX" +check_task_id_order "$EXECUTION_LOG_FILE" "$PREFIX" + LAST_SEQ=0 if [[ -f "$WORKLOG_FILE" ]]; then @@ -101,6 +128,16 @@ Logging requirements: - append entry to docs/ai-prompts.md - include Date, Task ID, Agent, Scope - use Task ID: ${TASK_ID} +- maintain chronological Task ID order in ai-worklog.md, ai-prompts.md and ai-execution-log.md +- append entry to docs/ai-execution-log.md + +Execution Logging requirements: +- append entry to docs/ai-execution-log.md +- include: + - full prompt + - agent todos + - final execution report +- use the standard execution log format defined in docs/ai-execution-log.md Git requirements: - do NOT commit or push unless explicitly requested