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

feat: finalize AI logging framework and workflow

Browse Source 
- align instructions, workflow rules, and task template with three-level logging
- extend ai-task generation to support execution-log requirements
- update worklog, prompt log, and execution log for the finalized framework
- validate the framework with generator and project quality checks
This commit is contained in:
Saky
2026-03-16 03:00:39 +01:00
parent 9704d3ef5b
commit 4273fb65cb
7 changed files with 449 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
AGENT_WORKFLOW.md
View File

@@ -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.

36
AI_TASK_TEMPLATE.md
View File

@@ -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

219
docs/ai-execution-log.md Normal file
View File

@@ -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
<full prompt text>
---
### Agent Todos
# Todos
[ ] item 1
[ ] item 2
---
### Agent Execution Report
<final report returned by the agent>
```
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.

33
docs/ai-prompts.md
View File

@@ -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.

123
docs/ai-worklog.md
View File

@@ -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
---

28
instructions-agent.md
View File

@@ -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.

37
scripts/ai-task
View File

@@ -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