From 9704d3ef5b3a731b466131f841b8fc5e14f51909 Mon Sep 17 00:00:00 2001 From: Saky Date: Mon, 16 Mar 2026 02:00:18 +0100 Subject: [PATCH] docs: improve AI agent workflow and instruction framework - strengthen agent workflow rules and commit/log ordering - improve AI logging instructions and traceability - add agent framework documents and task generation tooling - keep repository workflow consistent for future AI-assisted tasks --- AGENT_WORKFLOW.md | 30 ++++++++++++++++++++++++++++++ docs/ai-prompts.md | 23 +++++++++++++++++++++++ docs/ai-worklog.md | 39 +++++++++++++++++++++++++++++++++++++++ instructions-agent.md | 6 ++++++ 4 files changed, 98 insertions(+) diff --git a/AGENT_WORKFLOW.md b/AGENT_WORKFLOW.md index 4180d31..57bfb8d 100644 --- a/AGENT_WORKFLOW.md +++ b/AGENT_WORKFLOW.md @@ -28,6 +28,28 @@ Every AI task must follow this sequence: PLAN → REVIEW → BUILD → VALIDATE → LOG +--- + +# Execution Order (Strict) + +The following operational order must be respected when executing any BUILD task. + +1. Implement changes (BUILD) +2. Run validation + make fix + make quality +3. Update AI logs + - docs/ai-worklog.md + - docs/ai-prompts.md +4. Stage all modified files including logs +5. Create commit +6. Push only if explicitly requested + +Important rule: +Logs must always be written **before creating a commit**. If log files are modified after a commit, the task is considered incomplete and must be corrected. + +--- + This sequence must not be skipped. --- @@ -195,6 +217,14 @@ The same Task ID must appear in: Agents must **not commit or push automatically** unless explicitly instructed. +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 + +Commits that omit required AI log entries violate the repository workflow rules. + When commits are requested: 1. Validate repository state diff --git a/docs/ai-prompts.md b/docs/ai-prompts.md index fa786a9..197d0a6 100644 --- a/docs/ai-prompts.md +++ b/docs/ai-prompts.md @@ -156,6 +156,29 @@ Updated the logging instructions, normalized the prompt log to the structured en --- +### BUILD PROMPT ENTRY +Date: 2026-03-16 01:45 +Task ID: BUILD-20260316-004 +Agent: OpenCode +Task: build + +Scope: +- instructions-agent.md +- AGENT.md +- AGENT_WORKFLOW.md +- AI_TASK_TEMPLATE.md +- scripts/ai-task +- docs/ai-worklog.md +- docs/ai-prompts.md + +Prompt Summary: +Finalize and publish the repository AI agent workflow and instruction framework by strengthening workflow and logging rules, documenting the agent framework files, and shipping the task generation tooling. + +Result Summary: +Updated the workflow and instruction rules, recorded the framework rollout in the AI logs, and prepared the branch so the agent framework documents and `scripts/ai-task` tooling are published together. + +--- + ### BUILD PROMPT ENTRY Date: 2026-03-16 01:34 Task ID: BUILD-20260316-003 diff --git a/docs/ai-worklog.md b/docs/ai-worklog.md index 9db175c..3fb0e2c 100644 --- a/docs/ai-worklog.md +++ b/docs/ai-worklog.md @@ -54,6 +54,45 @@ 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 diff --git a/instructions-agent.md b/instructions-agent.md index 3bccb06..0b3bbfb 100644 --- a/instructions-agent.md +++ b/instructions-agent.md @@ -105,6 +105,12 @@ Mandatory rules: 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: + - `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. Each worklog entry must include: - date