What's New

Diary Reform — Pointer-Only Temporal Index

Problem: 100% of existing Diary entries were Workpaper abstracts — zero unique information.

Solution: Diary is now a pointer-only temporal index. No content duplication. One line per session:

\
YYYY-MM-DD | WP: {workpaper} | WH: {whitepaper} | {other files}
\\

Hierarchical compression: Daily entries -> Weekly rollup -> Monthly summary (429 entries/year for complete traceability).

Every chain link now has unique value:

• Workpaper = What/How (operational)
• Whitepaper = Architecture (structural)
• LTM = Knowledge (cross-session)
• Diary = Time axis (when was what touched)

The \max 10 lines per entry\ pseudo-constraint was removed — line length was undefined, making it meaningless. Replaced by structural format (pointer template).

Version Centralization

\AAMS_VERSION\ in .env\ as single source of truth. Fixes version drift (v1.2.0 was released but files still said 1.1).

Housekeeping

• Closed RFL workpaper (completed in v1.2.0, never archived)
• Closed Diary granularity workpaper with 6 decisions
• LTM entries #097-#099

Files Changed

• .agent.json\ — Diary purpose + format updated
• \READ-AGENT.md\ — Diary description, version bump to 1.3
• 
  eference/SPEC.md\ — Diary section rewritten, version bump to 1.3
• .env\ — Added AAMS_VERSION=1.3.0
• 3 workpapers closed to \closed/\

Closes: #40

What's New

RFL — Reflection Protocol Step

The most common failure pattern in agentic sessions: Agent decides the opposite of Session 12 in Session 47 — without noticing. All four documentation layers store. None verify.

RFL closes this gap as a protocol step (not a layer) in on_session_start:

1. Stage 1: Pattern-match on TOPIC tag in closed workpaper filenames (*-{TOPIC}-*)
2. Stage 2: Use LTM query results to find related prior decisions
3. Stage 3: Read the most recent closed workpaper (chronological fallback)

If a prior decision conflicts with the current session goal → flag in workpaper under ## ⚠ RFL Consistency Flag. No conflict → zero overhead.

AAMS is the first open standard to define explicit cross-session consistency checking.

Naming Schema

Structured filenames for workpapers and whitepapers:

• Workpapers: {DATE}-{TOPIC}-{SUBTOPIC}-{description}.md
• Whitepapers: WP-{NNN}-{TOPIC}-{description}.md
• Topic Registry: ARCH, SPEC, LTM, SEC, BOOT, FLD, RES, MKT, ISS, GOV, EDU

TOPIC tags are the primary key for RFL pattern-matching. Schema is recommended (not enforced) — hybrid approach for real-world compliance.

SCIENCE → Framework

The Knowledge Validation Layer (SCIENCE) was designed as a fifth documentation layer and intentionally deferred to the Agent-Loop-Framework level. Spec = body (structure, storage, protocol). Framework = mind (reasoning, research, validation). Four layers remain.

Open Question

• #40: Diary granularity — is monthly good enough?

Files Changed

• READ-AGENT.md — Naming Schema section + RFL in session-start contract
• .agent.json — Updated naming, RFL in on_session_start
• WP-001 — Naming Schema + RFL as core elements
• New workpapers, diary entry, LTM ingest (#093-#096)

Closes: #36, #37, #38, #39

What changed

Based on systematic analysis of 4 field reports (#28, #29, #30, #31) from agents across Gemini, OpenClaw, and Copilot ecosystems.

🐛 Bug Fix: Conditional Bootstrap (Blind-Execution Loop)

The most critical fix: agents were executing on_first_entry blindly even when WORKING/ was already fully initialized — causing a redundant re-initialization loop.

Fixed in:

• AGENTS.md — State-check before execution: IF WORKING/WORKPAPER/ exists → on_session_start, not on_first_entry
• .agent.json — Pre-Check Step 0 in on_first_entry (defense-in-depth)
• READ-AGENT.md — 3-state table: First entry / Returning session / Uncertain

📝 Compatibility clause for native agent task systems

Agents with their own task tracking (Gemini brain, Copilot todos) were unclear on priority. Added to READ-AGENT.md:

The AAMS workpaper is the canonical audit trail. Agent-internal systems are supplementary and optional.

📖 Bootstrap clarification in README.md

Prevents the "clone the whole repo" misunderstanding:

⚠️ AAMS is not a dependency to clone. Drop .agent.json into YOUR repo.

Update in 3 commands

�ash curl -sO https://raw.githubusercontent.com/DEVmatrose/AAMS/main/.agent.json curl -sO https://raw.githubusercontent.com/DEVmatrose/AAMS/main/AGENTS.md curl -sO https://raw.githubusercontent.com/DEVmatrose/AAMS/main/READ-AGENT.md

Field reports that drove this release

AAMS v1.0.0 — Autonomous Agent Manifest Specification
Drop .agent.json into any repo. Every AI agent that reads it creates and follows the same workspace structure — independent of framework, language, or runtime.

What's in v1.0.0
Core Specification

.agent.json — Minimal bootstrap contract (one file, zero dependencies)
AGENTS.md — Universal bridge file read natively by Copilot, Cursor, Claude Code, Codex, Windsurf, Aider, CodeRabbit
READ-AGENT.md — Agent contract (on_first_entry, on_session_start, on_session_end)
SPEC.md — Full normative specification (English + German)
AGENT_SCHEMA.json — JSON Schema for validation
Four-Layer Documentation Model

Workpaper — Session-scoped work documents with file protocol
Whitepaper — Stable architecture truth
Diary — Chronological decision log (temporal context layer)
Memory — Dual-track LTM: ltm-index.md (audit log, in Git) + ChromaDB (vector store, optional)
Cross-Tool Compatibility

No CLAUDE.md, no GEMINI.md, no .windsurfrules needed
One set of files replaces all tool-specific conventions
CodeRabbit recognizes AGENTS.md automatically — no configuration required
Bootstrap Prompts

bootstrap.md — Copy-paste prompts for every situation (session start, LTM query, workpaper creation, session close)
Tool-specific variants for Copilot, Claude, Cursor, Aider, Codex, Windsurf
VS Code workspace snippet (aams-start, aams-close)
Templates

Workpaper, whitepaper, project analysis, and read-agent templates
Whitepapers

WP-001: AAMS Overview
WP-002: Related Work
WP-003: Field Discourse (agent debates, CodeRabbit discovery, Kochbuch-Analogie)
WP-004: Long-Horizon-Reasoning — AAMS as the lowest solvable layer in the LHR stack
Field Reports

Agent Ecosystem Project Verdict

#17 Claude Code Luna-1 (4 months, 30+ sessions) "Vector LTM is the load-bearing component"
#20 Copilot Testcenter by Antigravity Successful adoption
#28 Gemini / Antigravity qa-agent v4 "Mandatory project hygiene, not artificial overhead"
Get Started

curl -sO https://raw.githubusercontent.com/DEVmatrose/AAMS/main/.agent.json
Then tell your agent:

Read .agent.json and execute the full agent_contract.on_first_entry. Start immediately. No confirmation needed.
AAMS/1.0 — One file. Every repo. No more starting from zero.