Agentic-Loop-Notation

Agentic Loop Notation (ALN) v0.3

Agentic Loop Notation is a small, readable notation for describing verified AI-agent loops.

Many practical loop examples now exist: documentation sweeps, repair loops, UI scoring loops, eval loops, migration loops, optimization tournaments, and recurring operational checks. Most of them are still written as prose prompts. Prose is useful, but it hides the structure that makes a loop controllable.

ALN makes that structure visible:

• goal: what success means
• context: what the agent must inspect first
• authority: what the agent may and may not change
• cycle: observe, act, verify, decide
• verifier: the fixed check that turns repetition into control flow
• stop: success, reject, no-op, stall, budget, and blocked rules
• return: the evidence and artifacts the agent must hand back

ALN is not a runtime, safety system, or authorization layer. It is a notation for making agent loops easier to teach, compare, audit, repair, and export into tools such as Codex goals, Claude Code tasks, skills, worktrees, subagents, automations, AGENTS.md and CLAUDE.md guidance, and hooks.

Use It Now

1. Read the spec: docs/ALN-v0.3.md. It is short.
2. Install the ALN Loop Designer skill, or paste the spec into your agent's context. Claude Code install steps are in docs/claude-code-mapping.md.
3. Ask the agent to translate one of your own prose prompts into an ALN loop, then run Loop Doctor on the result.

Why ALN

The first wave of AI coding was mostly linear prompting:

prompt -> output -> correction -> output -> correction

Agentic work changes shape when the human defines a loop:

goal -> observe -> act -> verify -> decide -> repeat/stop

The key is the verifier. Without a verifier, a loop is just repetition. With a verifier, the check becomes the branch condition: keep, revert, escalate, or stop.

ALN v0.3 Skeleton

loop <Name>(target):
  goal:       what success means
  context:    what the agent must inspect first
  authority:  what it may and may not change
  cycle:
    observe:  inspect current state
    act:      make one bounded change
    verify:   run the fixed check
    decide:
      keep if:     evidence improves
      revert if:   evidence regresses
      escalate if: judgment, access, safety, or authority is missing
  stop:
    success if:    completion condition is met
    reject if:     evidence shows the goal cannot or should not be met as stated
    no_op if:      nothing actionable exists
    stall if:      no improvement after N rounds
    budget if:     time, token, or iteration limit is reached
    blocked if:    required input or permission is missing
  return: evidence, diff, log, and next action

See docs/ALN-v0.3.md for the notation and docs/examples.md for examples.

Examples

This repository includes seven examples:

• DocsSweep: repair documentation drift one bounded section at a time.
• CompletionContract: require proof before declaring work complete.
• UXScoreRepair: improve a user flow against a repeated rubric.
• QueryOptimizationTournament: test competing strategies in isolation and select by evidence.
• ReadmeDemoRecipe: keep a README quickstart recipe accurate and reproducible for a new reader.
• DocsReleasePass: run existing loops as ordered stages with one end-to-end check.
• RepoAuditPanel: audit surfaces in parallel and merge the findings into one verified report.

Loop Doctor

Loop Doctor is a review checklist for ALN loops. It flags common failures:

• no fixed verifier
• vague success condition
• unsafe authority
• no rollback rule
• no evidence artifact
• no blocked/stall/no-op distinction
• excessive scope
• gameable proxy verifier
• self-reported verification
• absorbed escalation
• unverified composite
• inner grant exceeds outer
• zombie schedule

See docs/loop-doctor.md.

Runtime Mappings

ALN is tool-agnostic. The same loop structure maps onto native primitives in more than one runtime, and the analogies are shared on purpose so the mappings read in parallel:

Codex         Claude Code                shared analogy
Prompt        Prompt                  -> statement
Skill         Skill                   -> function or macro
/goal         Scoped task / plan run  -> loop
Verifier      Verifier                -> branch condition
Worktree      Git worktree            -> transaction
Subagent      Subagent                -> fork
Automation    Scheduled task          -> daemon
AGENTS.md     CLAUDE.md               -> persistent policy memory
Hook          Hook                    -> interrupt or guardrail
—             Permission rules        -> enforced authority boundary

See docs/codex-mapping.md, docs/claude-code-mapping.md, and skills/aln-loop-designer/SKILL.md.

Acknowledgements

ALN v0.1 was motivated in part by the growing body of practical loop examples in the Forward Future Loop Library, which collects repeatable AI-agent workflows with checks and stopping conditions.

Several examples in this repository are ALN translations or adaptations of Loop Library examples. See docs/examples.md for lineage and acknowledgements.

Citation

If you use ALN in writing, tooling, research, videos, or examples, please cite this repository. See CITATION.cff and NOTICE.md.

Contributing Examples

Good ALN examples should be small, inspectable, and honest about authority. Prefer one clear target, one fixed verifier, explicit stop rules, and concrete return artifacts.

When adding an example, include:

1. The loop name and target.
2. The verifier.
3. The authority boundary.
4. The success and stop rules.
5. The evidence returned to the human.

See CONTRIBUTING.md for the contribution checklist.

Safety Note

ALN describes control flow. It does not grant permission.

An ALN loop must not be treated as authorization to deploy, delete, spend money, contact third parties, expose private data, alter production systems, or override repository rules. Human gates, sandboxing, approvals, and local policies still apply.

To report unsafe loop wording or examples, see SECURITY.md.

License

ALN is licensed under Creative Commons Attribution 4.0 International. You can share and adapt it freely, including for commercial use, as long as you credit the project and link back when reasonably possible.

If ALN is useful to you, please consider starring the repository so others can find it. Starring is appreciated, not required by the license.