Agent Workflow

This repository is intended for beginner-friendly collaboration. Agents and assistants must use the project sync workflow instead of relying on memory or manual Git habits.

Required Order

1. Before starting any task, run:

bash scripts/sync_workflow.sh pull

2. Do the requested work.

3. Record the conversation outcome as a topic note under docs/runs/.

4. Before the final response, upload repository changes:

bash scripts/sync_workflow.sh upload "sync: describe this task"

5. When the task can be expressed as a shell command, prefer the wrapped form:

bash scripts/sync_workflow.sh run "sync: describe this task" -- <command> [args...]

The run action pulls first, executes the command, then commits and pushes any committable repository changes.

Document Output Preference

User preference recorded on 2026-06-12:

• For this project, user-facing analysis documents, reports, summaries, process notes, and delivery artifacts should be presented as HTML and/or Excel by default.
• Every analysis report delivery must be placed in its own final-result folder under docs/final-results/, for example docs/final-results/YYYYMMDD-short-topic/.
• A final-result folder is the user's review surface. Put only final HTML, Excel, images, and directly needed attachments there. Do not put analysis process notes, scratch files, code, raw data, intermediate exports, or drafting material in that folder.
• Prefer index.html as the main report inside each final-result folder, and keep any linked Excel workbook or attachments in the same folder so the folder can be opened and shared as one result package.
• Every final HTML report should have a same-folder Excel workbook whenever the content contains analysis tables, rankings, checklists, or action lists. The Excel version should preserve the final report content as usable sheets, not screenshots, so users can filter, copy, and continue analysis in Excel.
• Do not use Markdown as the primary presentation format for future project deliverables.
• All project HTML output must use the project-local taste skill for UI polish: read skills/taste-skill/SKILL.md before creating or revising any HTML file, apply its design-read and pre-flight checks, and avoid shipping bare or default-looking HTML.
• When a note is required under docs/runs/, prefer an .html topic note instead of a .md note.
• Markdown is allowed only for repository control surfaces that conventionally require it, such as AGENTS.md, README.md, prompt source files, project-local skill files, or when the user explicitly asks for Markdown.

Conversation Notes

Every Codex interaction should leave a compact, reusable project note so the repository becomes a future skill and knowledge-base source.

Create or update one topic file in docs/runs/ for each meaningful topic:

docs/runs/YYYYMMDD-short-topic.html

Each note should contain:

• User goal.
• Final answer or decision.
• Files changed or generated.
• Commands run and validation result.
• Reusable patterns that may become a future Skill.
• Next action, if any.

If a topic file already exists, append the new turn instead of creating a near duplicate. Keep raw private data out of the notes; summarize sensitive tender data instead of copying it.

Safety Rules

• Do not use git reset --hard, force push, or delete user data unless the user explicitly asks for that operation.
• Do not commit ignored raw or processed data from data/raw/ or data/processed/; those directories are intentionally local by default.
• If pull, commit, or push fails because of authentication, permissions, or merge conflicts, stop and report the exact blocking step.
• Use clear commit messages, for example sync: update analysis workflow.