AgentWorks

AgentWorks documentation

Learning Architecture

This document describes the current workflow architecture as implemented now.

The older model in this repo treated learning as part of a larger learning-plus-validation architecture with LLM validation modes, per-step learning files, and exploration/exploitation prompt strategies. That is no longer the right mental model.

Current Reality

Today the learning side of workflow runtime is built around two simpler ideas:

If you remember the older architecture, these are the most important updates:

Learning

What learning writes now

The main learning destination is the global skill:

SKILL.md should stay lean. Treat it as the index and overview for the workflow runbook, not the place for detailed accumulated guidance. Keep it under roughly 80-100 lines, with links to focused references/<topic>.md files. Detailed selectors, auth flows, API quirks, timing/wait rules, file-format notes, retry patterns, and step-specific HOW guidance should live in those reference files.

The learning agent prompt in learning_agent.go is explicit:

The controller also hardwires global learning mode in controller_learning.go:

Step-specific learnings still exist, but differently

There are still step-specific artifacts, but they are no longer the main prose-learning model:

So the current split is:

Learning objective

The current system expects a workflow-level objective for the global skill:

This tells the learning agent what kind of reusable knowledge should be accumulated, for example:

This is a better description of the current design than the older “extract learnings per step until stable” framing.

Learning lifecycle

Success learning

After a successful step:

This happens in controller_learning.go.

Important current details:

Learning metadata

Runtime learning metadata is observational. It gives the workflow builder and review tools evidence for deciding whether a step's learning writes are still useful, but it does not mutate lock_learnings.

Current metadata logic in controller_learning_detection.go:

Editing the step description resets the description-hash run counter. This is review evidence only; runtime execution does not auto-lock or auto-unlock learning.

Manual lock lifecycle

lock_learnings is owned by the builder/user. Set it when the workflow should keep reading the current global skill but stop accepting automatic SKILL.md writes from that step. Clear it explicitly after a material description change or when the builder/user wants that step to learn again.

Locking and disabling learning

The important current controls on AgentConfigs:

Auto-migration for legacy configs (runtime-only, no file rewrites): if learnings_access is unset, learning_objective non-empty infers "read-write"; empty infers "read".

Recommended usage:

Failure learning

The older docs described a full failure-learning architecture. That is not a good description of the current codebase.

What still exists:

What matters operationally now:

Until failure-learning behavior is re-established as a first-class runtime path, docs should not present it as a central architecture pillar.

Scripted code steps

For learn_code steps, learning and execution are intentionally split:

That means learning for scripted steps is not just “write prose notes.” It is:

See learn_code_flow.md.

Current file layout

Global

learnings/
  _global/
    SKILL.md
    references/
    scripts/

Step-specific

learnings/
  <step-id>/
    .learning_metadata.json
    SKILL.md                # optional supporting notes
    main.py                 # scripted steps
    scripts/
    diffs/

Not every step uses every file. The important distinction is:

What to update in other docs

When editing related workflow docs, keep these rules consistent:

Code references

Related docs