WORKFLOW.md

WORKFLOW.md

AGENT_WORKFLOW uses nine gates. A task cannot be considered done unless each gate is completed or explicitly justified.

Gate 1 — Understand

• Define the goal.
• Define non-goals.
• Define expected output.
• Identify project and task ID.
• Confirm constraints, data sensitivity and deployment target.

Gate 2 — Search Existing Code

Use rg, find, ls, tree or equivalent commands.

Search for:

• existing functions
• schemas
• tests
• conventions
• configs
• scripts
• similar reports or ADRs

Document commands used and files found.

Gate 3 — Reuse Decision

Choose exactly one:

• Reuse existing function.
• Modify existing function.
• Build small module.
• Stop because unnecessary.

The decision must include a reason. Building is allowed only when reuse or modification is not appropriate.

Gate 4 — Minimal Design

Write a short design:

• files allowed to edit
• behavior change
• tests to run
• known risks
• rollback path if relevant

No global refactor without explicit task scope.

Gate 5 — Implement Only Assigned Files

• Keep strict scope.
• Do not edit unrelated files.
• Do not perform global formatting unless requested.
• Do not rename public APIs unless the task requires it.
• Keep modules small and readable.

Gate 6 — Tests

Run relevant tests:

• unit tests
• integration tests
• smoke tests
• lint/type checks when available

Document exact commands. If tests cannot run, explain why and what should be run next.

Gate 7 — Anti-Leakage / Security Check

For temporal data:

• verify available_at <= prediction_time
• verify no future data enters features
• verify labels are not used as prediction features
• verify train/test split is temporal when needed
• verify backtests are walk-forward

For security:

• no secrets
• no tokens in logs
• no .env committed
• no direct port exposure unless justified
• no complete article/content storage without validation

Block the task if leakage or secret exposure is detected.

Gate 8 — Task Report + Context Compression

Write reports/task_reports/TASK_ID.md with:

• goal
• non-goals
• summary
• files changed
• commands run
• tests
• reuse decision
• risks
• security/leakage check
• remaining work
• next recommended task

Update PROJECT_STATE.md with only durable information: decisions, changed files, current risks, next tasks and recent reports.

Gate 9 — Review + Merge

Reviewer checklist:

• scope respected
• reuse decision documented
• tests pass or failure is understood
• no secrets
• no leakage
• docs updated
• task report complete
• project state updated

Merge is blocked if tests, leakage, security or scope checks fail.

Mermaid Workflow

flowchart TD
    A[Gate 1 Understand] --> B[Gate 2 Search Existing Code]
    B --> C[Gate 3 Reuse Decision]
    C -->|reuse| D[Gate 4 Minimal Design]
    C -->|modify| D
    C -->|build small module| D
    C -->|stop unnecessary| R[Report Stop Decision]
    D --> E[Gate 5 Implement Assigned Files]
    E --> F[Gate 6 Tests]
    F --> G[Gate 7 Leakage and Security Check]
    G -->|pass| H[Gate 8 Task Report and Context Compression]
    G -->|fail| X[Block and Fix]
    X --> E
    H --> I[Gate 9 Review and Merge]
    I -->|approved| J[Merge]
    I -->|changes requested| E