Skip to content

AGENTS.md

Latest commit

 

History

History
79 lines (53 loc) · 3.04 KB

AGENTS.md

File metadata and controls

79 lines (53 loc) · 3.04 KB
Raw

A3L Codex Integration

This workspace includes A3L, a compact non-JSON presentation language that compiles to single-file HTML artifacts.

A3L Presentation Adapter

When a response would otherwise become a long Markdown status report, plan, comparison, flow, release note, or result summary, prefer an A3L presentation artifact.

Do not use A3L for tiny answers, code snippets, direct command output, or errors where plain text is clearer.

One-Minute Workflow

  1. Create .a3/out/<topic>.a3 using one capsule from agent-adapter/A3_AGENT_RULES.md.
  2. Compile it:
node bin/a3present.js .a3/out/<topic>.a3 -o dist/present/<topic>.html
  1. In the final answer, link the generated HTML artifact and include a concise text fallback summary.

Preferred Presentation Capsules

!brief#app"Title"[lead="Short summary" a=Changed av="What changed" b=Evidence bv="What passed" c=Next cv="Next action"]
!status#app"Verification"[state=Passed ok=7 warn=0 fail=0 next="Ready"]
!plan#app"Plan"[a="Inspect" b="Implement" c="Verify" d="Report"]
!compare#app"A vs B"[l=A3L r=Markdown a=Scanning av=Visual aw=Text b=Structure bv=Typed bw=Loose c=Output cv=HTML cw=Plain]
!flow#app"Workflow"[a=Input b=Transform c=Verify d=Present]

Quote values that contain spaces. Keep values short.

Verification Commands

Use these when changing the adapter or compiler:

npm test
npm run agent:smoke
npm run bench:coverage

Run npm run verify:prod for the full gate, including the slower Codex AI smoke test.

A3L Web UI Adjustment Protocol

When the user asks to adjust an A3L-generated web page, edit the A3L source first and regenerate the single HTML artifact. Do not hand-edit generated dist/**/index.html unless the user explicitly asks for a one-off generated artifact patch.

Use this order:

  1. Capsule parameters first. Change the compact capsule line for common content and variant changes.
  2. Lower-layer A3L patches second. Append explicit HTML/CSS/state/event forms only for one-off layout, styling, or behavior refinements that the capsule does not expose yet.
  3. Upgrade the capsule third. If the same lower-layer patch is likely to recur, add a capsule parameter and cover it with tests and token benchmarks.

For complex login pages, prefer loginx / authx / signin:

!loginx#auth"Secure Portal"[brand=Northstar badge="SOC2 ready" primary="Continue securely" lead="Access the command center with adaptive protection."]

Common loginx adjustments:

  • Title: the quoted capsule title.
  • Brand: brand=...
  • Security badge: badge=...
  • Primary button: primary=...
  • Hero/body copy: lead="..."
  • Visual refinements: append CSS rules such as .a3-authx-submit{bg:#0f766e}.

After adjustments, regenerate and verify:

node bin/a3c.js examples/capsule-loginx.a3 -o dist/complex-login
npm test
npm run bench:coverage

a3c prints compression stats after every compile. Default output is one HTML file with inline CSS and JS; use --bundle only when a three-file index.html + styles.css + app.js bundle is explicitly required.